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

1.1.1. Creating or deleting a LAMMPS object

This section documents the following functions:

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()

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()

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()

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