\(\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 newLAMMPS
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. Howeverargc
may be set to 0 and thenargv
may beNULL
. 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.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 thelammps_open_no_mpi()
orlammps_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 usesMPI_COMM_WORLD
.This function is a version of
lammps_open()
, that is missing the MPI communicator argument. It will useMPI_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
- 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.New 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 thelammps()
constructor of the LAMMPS Fortran module. Internally it converts the f_comm argument into a C-style MPI communicator withMPI_Comm_f2c()
and then callslammps_open()
.If for some reason the creation or initialization of the LAMMPS instance fails a null pointer is returned.
- 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 thelammps_open()
variants. It does not callMPI_Finalize()
to allow creating and deleting multiple LAMMPS instances concurrently or sequentially. Seelammps_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.
New 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 callsMPI_Init()
in case it is not.
-
void lammps_mpi_finalize()
Shut down the MPI infrastructure.
New 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.
-
void lammps_kokkos_finalize()
Shut down the Kokkos library environment.
New 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.
-
void lammps_python_finalize()
Clear the embedded Python environment
New 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.
-
void lammps_error(void *handle, int error_type, const char *error_text)
Call a LAMMPS Error class function
New 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