1. LAMMPS Library Interfaces — LAMMPS documentation

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

# 1. LAMMPS Library Interfaces

As described on the library interface to LAMMPS page, LAMMPS can be built as a library (static or shared), so that it can be called by another code, used in a coupled manner with other codes, or driven through a Python script. The LAMMPS standalone executable itself is essentially a thin wrapper on top of the LAMMPS library, which creates a LAMMPS instance, passes the input for processing to that instance, and then exits.

Most of the APIs described below are based on C language wrapper functions in the files `src/library.h` and `src/library.cpp`, but it is also possible to use C++ directly. The basic procedure is always the same: you create one or more instances of `LAMMPS`, pass commands as strings or from files to that LAMMPS instance to execute calculations, and/or call functions that read, manipulate, and update data from the active class instances inside LAMMPS to do analysis or perform operations that are not possible with existing input script commands.

Thread-safety

LAMMPS was initially not conceived as a thread-safe program, but over the years changes have been applied to replace operations that collide with creating multiple LAMMPS instances from multiple-threads of the same process with thread-safe alternatives. This primarily applies to the core LAMMPS code and less so on add-on packages, especially when those packages require additional code in the lib folder, interface LAMMPS to Fortran libraries, or the code uses static variables (like the COLVARS package).

Another major issue to deal with is to correctly handle MPI. Creating a LAMMPS instance requires passing an MPI communicator, or it assumes the `MPI_COMM_WORLD` communicator, which spans all MPI processor ranks. When creating multiple LAMMPS object instances from different threads, this communicator has to be different for each thread or else collisions can happen. Or it has to be guaranteed, that only one thread at a time is active. MPI communicators, however, are not a problem, if LAMMPS is compiled with the MPI STUBS library, which implies that there is no MPI communication and only 1 MPI rank.

## 1.1. LAMMPS C Library API

The C library interface is the most commonly used path to manage LAMMPS instances from a compiled code and it is the basis for the Python and Fortran modules. Almost all functions of the C language API require an argument containing a “handle” in the form of a `void *` type variable, which points to the location of a LAMMPS class instance.

The `library.h` header file by default does not include the `mpi.h` header file and thus hides the `lammps_open()` function which requires the declaration of the `MPI_comm` data type. This is only a problem when the communicator that would be passed is different from `MPI_COMM_WORLD`. Otherwise calling `lammps_open_no_mpi()` will work just as well. To make `lammps_open()` available, you need to compile the code with `-DLAMMPS_LIB_MPI` or add the line `#define LAMMPS_LIB_MPI` before `#include "library.h"`.

Please note the `mpi.h` file must usually be the same (and thus the MPI library in use) for the LAMMPS code and library and the calling code. The exception is when LAMMPS was compiled in serial mode using the `STUBS` MPI library. In that case the calling code may be compiled with a different MPI library so long as `lammps_open_no_mpi()` is called to create a LAMMPS instance. In that case each MPI rank will run LAMMPS in serial mode.

Errors versus exceptions

If the LAMMPS executable encounters an error condition, it will abort after printing an error message. It does so by catching the exceptions that LAMMPS could throw. For a C library interface this is usually not desirable since the calling code might lack the ability to catch such exceptions. Thus, the library functions will catch those exceptions and return from the affected functions. The error status `can be queried` and an `error message retrieved`. This is, for example used by the LAMMPS python module and then a suitable Python exception is thrown.

Using the C library interface as a plugin

Rather than including the C library interface directly using the `library.h` header file and link to the LAMMPS (static or shared) library at compile time, you can use the `liblammpsplugin.h` header file and the `liblammpsplugin.c` C code in the `examples/COUPLE/plugin` folder for an interface to LAMMPS that is largely identical to the regular library interface, only that it will load a LAMMPS shared library file at runtime. This can be useful for applications where the interface to LAMMPS would be an optional feature or where you would like to load different version of the LAMMPS library (e.g. an updated one) without replacing the executable. The LAMMPS-GUI is an example for such a program. It has its own wrapper that supports both modes and they can be changed at compile time.

Warning

No checks are made on the arguments of the function calls of the C library interface. All function arguments must be non-NULL unless explicitly allowed, and must point to consistent and valid data. Buffers for storing returned data must be allocated to a suitable size. Passing invalid or unsuitable information will likely cause crashes or corrupt data.

- 1.1.1. Creating or deleting a LAMMPS object
- 1.1.2. Executing commands
- 1.1.3. System properties
- 1.1.4. Per-atom properties
- 1.1.5. Computes, fixes, variables
- 1.1.6. Scatter/gather operations
- 1.1.7. Neighbor list access
- 1.1.8. Configuration information
- 1.1.9. Utility functions
- 1.1.10. Extending the C API

## 1.2. LAMMPS Python API

The LAMMPS Python module enables calling the LAMMPS C library API from Python by dynamically loading functions in the LAMMPS shared library through the Python ctypes module. Because of the dynamic loading, it is required that LAMMPS is compiled in “shared” mode. The Python interface is object-oriented, but otherwise tries to be very similar to the C library API. More information on this is in the Use Python with LAMMPS section of the manual. Use of the LAMMPS Python module is described in The lammps Python module.

## 1.3. LAMMPS Fortran API

The LAMMPS Fortran module is a wrapper around calling functions from the LAMMPS C library API. This is done using the ISO_C_BINDING feature in Fortran 2003. The interface is object-oriented but otherwise tries to be very similar to the C library API and the basic Python module.

- 1.3.1. The `LIBLAMMPS` Fortran Module
- 1.3.2. Creating or deleting a LAMMPS object
- 1.3.3. Executing LAMMPS commands
- 1.3.4. Accessing system properties
- 1.3.5. The `LIBLAMMPS` module API

## 1.4. LAMMPS C++ API

It is also possible to invoke the LAMMPS C++ API directly in your code. It lacks some of the convenience of the C library API, but it allows more direct access to simulation data and thus more low-level manipulations. The following links provide some examples and references to the C++ API.

- 1.4.1. Using the C++ API directly
- 1.4.2. Creating or deleting a LAMMPS object
- 1.4.3. Executing LAMMPS commands