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, 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.

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.

New in version 18Sep2020.

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.

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.

New in version 18Sep2020.

void lammps_mpi_finalize()

Shut down the MPI infrastructure.

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.

New in version 18Sep2020.