1.1.1. Creating or deleting a LAMMPS object — LAMMPS documentation

\(\renewcommand{\AA}{\text{Å}}\)

# 1.1.1. Creating or deleting a LAMMPS object

This section documents the following functions:

- `lammps_open()`

- `lammps_open_no_mpi()`

- `lammps_open_fortran()`

- `lammps_close()`

- `lammps_mpi_init()`

- `lammps_mpi_finalize()`

- `lammps_kokkos_finalize()`

- `lammps_python_finalize()`

- `lammps_plugin_finalize()`

- `lammps_error()`

The `lammps_open()` and `lammps_open_no_mpi()` functions are used to create and initialize a `LAMMPS()` instance. They return a reference to this instance as a `void *` pointer to be used as the “handle” argument in subsequent function calls until that instance is destroyed by calling `lammps_close()`. Here is a simple example demonstrating its use:

    #include "library.h"
    #include <stdio.h>

    int main(int argc, char **argv)
    {
      void *handle;
      int version;
      const char *lmpargv[] = { "liblammps", "-log", "none"};
      int lmpargc = sizeof(lmpargv)/sizeof(const char *);

      /* create LAMMPS instance */
      handle = lammps_open_no_mpi(lmpargc, (char **)lmpargv, NULL);
      if (handle == NULL) {
        printf("LAMMPS initialization failed");
        lammps_mpi_finalize();
        return 1;
      }

      /* get and print numerical version code */
      version = lammps_version(handle);
      printf("LAMMPS Version: %d\n",version);

      /* delete LAMMPS instance and shut down MPI */
      lammps_close(handle);
      lammps_mpi_finalize();
      return 0;
    }

The LAMMPS library uses the MPI library it was compiled with and will either run on all processors in the `MPI_COMM_WORLD` communicator or on the set of processors in the communicator passed as the `comm` argument of `lammps_open()`. This means the calling code can run LAMMPS on all or a subset of processors. For example, a wrapper code might decide to alternate between LAMMPS and another code, allowing them both to run on all the processors. Or it might allocate part of the processors to LAMMPS and the rest to the other code by creating a custom communicator with `MPI_Comm_split()` and running both codes concurrently before syncing them up periodically. Or it might instantiate multiple instances of LAMMPS to perform different calculations and either alternate between them, run them concurrently on split communicators, or run them one after the other. The `lammps_open()` function may be called multiple times for this latter purpose.

The `lammps_close()` function is used to shut down the `LAMMPS` class pointed to by the handle passed as an argument and free all its memory. This has to be called for every instance created with one of the `lammps_open()` functions. It will, however, not call `MPI_Finalize()`, since that may only be called once. See `lammps_mpi_finalize()` for an alternative to invoking `MPI_Finalize()` explicitly from the calling program.

void *lammps_open(int argc, char **argv, MPI_Comm comm, void **ptr)

  Create instance of the LAMMPS class and return pointer to it.

  The `lammps_open()` function creates a new `LAMMPS` class instance while passing in a list of strings as if they were command-line arguments for the LAMMPS executable, and an MPI communicator for LAMMPS to run under. Since the list of arguments is exactly as when called from the command-line, the first argument would be the name of the executable and thus is otherwise ignored. However `argc` may be set to 0 and then `argv` may be `NULL`. If MPI is not yet initialized, `MPI_Init()` will be called during creation of the LAMMPS class instance.

  If for some reason the creation or initialization of the LAMMPS instance fails a null pointer is returned.

  Changed in version 18Sep2020: This function now has the pointer to the created LAMMPS class instance as return value. For backward compatibility it is still possible to provide the address of a pointer variable as final argument ptr.

  Deprecated since version 18Sep2020: The ptr argument will be removed in a future release of LAMMPS. It should be set to `NULL` instead.

  See also

    `lammps_open_no_mpi()`, `lammps_open_fortran()`

  Note

  This function is only declared when the code using the LAMMPS `library.h` include file is compiled with `-DLAMMPS_LIB_MPI`, or contains a `#define LAMMPS_LIB_MPI 1` statement before `#include "library.h"`. Otherwise you can only use the `lammps_open_no_mpi()` or `lammps_open_fortran()` functions.

  Parameters:

    - argc – number of command-line arguments

    - argv – list of command-line argument strings

    - comm – MPI communicator for this LAMMPS instance

    - ptr – pointer to a void pointer variable which serves as a handle; may be `NULL`

  Returns:

    pointer to new LAMMPS instance cast to `void *`

void *lammps_open_no_mpi(int argc, char **argv, void **ptr)

  Variant of `lammps_open()` that implicitly uses `MPI_COMM_WORLD`.

  This function is a version of `lammps_open()`, that is missing the MPI communicator argument. It will use `MPI_COMM_WORLD` instead. The type and purpose of arguments and return value are otherwise the same.

  Outside of the convenience, this function is useful, when the LAMMPS library was compiled in serial mode, but the calling code runs in parallel and the `MPI_Comm` data type of the STUBS library would not be compatible with that of the calling code.

  If for some reason the creation or initialization of the LAMMPS instance fails a null pointer is returned.

  Changed in version 18Sep2020: This function now has the pointer to the created LAMMPS class instance as return value. For backward compatibility it is still possible to provide the address of a pointer variable as final argument ptr.

  Deprecated since version 18Sep2020: The ptr argument will be removed in a future release of LAMMPS. It should be set to `NULL` instead.

  See also

    `lammps_open()`, `lammps_open_fortran()`

  Parameters:

    - argc – number of command-line arguments

    - argv – list of command-line argument strings

    - ptr – pointer to a void pointer variable which serves as a handle; may be `NULL`

  Returns:

    pointer to new LAMMPS instance cast to `void *`

void *lammps_open_fortran(int argc, char **argv, int f_comm)

  Variant of `lammps_open()` using a Fortran MPI communicator.

  Added in version 18Sep2020.

  This function is a version of `lammps_open()`, that uses an integer for the MPI communicator as the MPI Fortran interface does. It is used in the `lammps()` constructor of the LAMMPS Fortran module. Internally it converts the f_comm argument into a C-style MPI communicator with `MPI_Comm_f2c()` and then calls `lammps_open()`.

  If for some reason the creation or initialization of the LAMMPS instance fails a null pointer is returned.

  See also

    `lammps_open_fortran()`, `lammps_open_no_mpi()`

  Parameters:

    - argc – number of command-line arguments

    - argv – list of command-line argument strings

    - f_comm – Fortran style MPI communicator for this LAMMPS instance

  Returns:

    pointer to new LAMMPS instance cast to `void *`

void lammps_close(void *handle)

  Delete a LAMMPS instance created by lammps_open() or its variants.

  This function deletes the LAMMPS class instance pointed to by `handle` that was created by one of the `lammps_open()` variants. It does not call `MPI_Finalize()` to allow creating and deleting multiple LAMMPS instances concurrently or sequentially. See `lammps_mpi_finalize()` for a function performing this operation.

  Parameters:

    handle – pointer to a previously created LAMMPS instance

void lammps_mpi_init()

  Ensure the MPI environment is initialized.

  Added in version 18Sep2020.

  The MPI standard requires that any MPI application must call `MPI_Init()` exactly once before performing any other MPI function calls. This function checks, whether MPI is already initialized and calls `MPI_Init()` in case it is not.

void lammps_mpi_finalize()

  Shut down the MPI infrastructure.

  Added in version 18Sep2020.

  The MPI standard requires that any MPI application calls `MPI_Finalize()` before exiting. Even if a calling program does not do any MPI calls, MPI is still initialized internally to avoid errors accessing any MPI functions. This function should then be called right before exiting the program to wait until all (parallel) tasks are completed and then MPI is cleanly shut down. After calling this function no more MPI calls may be made.

  See also

    `lammps_kokkos_finalize()`, `lammps_python_finalize()`, `lammps_plugin_finalize()`

void lammps_kokkos_finalize()

  Shut down the Kokkos library environment.

  Added in version 2Jul2021.

  The Kokkos library may only be initialized once during the execution of a process. This is done automatically the first time Kokkos functionality is used. This requires that the Kokkos environment must be explicitly shut down after any LAMMPS instance using it is closed (to release associated resources). After calling this function no Kokkos functionality may be used.

  See also

    `lammps_mpi_finalize()`, `lammps_python_finalize()`, `lammps_plugin_finalize()`

void lammps_python_finalize()

  Clear the embedded Python environment

  Added in version 20Sep2021.

  This function resets and clears an embedded Python environment by calling the Py_Finalize() function of the embedded Python library, if enabled. This call would free up all allocated resources and release loaded shared objects.

  However, this is not done when a LAMMPS instance is deleted because a) LAMMPS may have been used through the Python module and thus the Python interpreter is external and not embedded into LAMMPS and therefore may not be reset by LAMMPS b) some Python modules and extensions, most notably NumPy, are not compatible with being initialized multiple times, which would happen if additional LAMMPS instances using Python would be created after after calling Py_Finalize().

  This function can be called to explicitly clear the Python environment in case it is safe to do so.

  See also

    `lammps_mpi_finalize()`, `lammps_kokkos_finalize()`, `lammps_plugin_finalize()`

void lammps_plugin_finalize()

  Unload all plugins and release the corresponding DSO handles

  Added in version 12Jun2025.

  This function clears the list of all loaded plugins and closes the corresponding DSO handles and releases the imported executable code.

  However, this is not done when a LAMMPS instance is deleted because plugins and their shared objects are global properties.

  This function can be called to explicitly clear out all loaded plugins in case it is safe to do so.

  See also

    `lammps_mpi_finalize()`, `lammps_kokkos_finalize()`, `lammps_python_finalize()`

void lammps_error(void *handle, int error_type, const char *error_text)

  Call a LAMMPS Error class function

  Added in version 3Nov2022.

  This function is a wrapper around functions in the `Error` to print an error message and then stop LAMMPS.

  The error_type parameter selects which function to call. It is a sum of constants from `_LMP_ERROR_CONST`. If the value does not match any valid combination of constants a warning is printed and the function returns.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - error_type – parameter to select function in the Error class

    - error_text – error message