1.1.3. System properties — LAMMPS documentation

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

# 1.1.3. System properties

This section documents the following functions:

- `lammps_get_natoms()`

- `lammps_get_thermo()`

- `lammps_last_thermo()`

- `lammps_extract_box()`

- `lammps_reset_box()`

- `lammps_memory_usage()`

- `lammps_get_mpi_comm()`

- `lammps_extract_setting()`

- `lammps_extract_global_datatype()`

- `lammps_extract_global()`

The library interface allows the extraction of different kinds of information about the active simulation instance and also - in some cases - to apply modifications to it. This enables combining of a LAMMPS simulation with other processing and simulation methods computed by the calling code, or by another code that is coupled to LAMMPS via the library interface. In some cases the data returned is direct reference to the original data inside LAMMPS, cast to a void pointer. In that case the data needs to be cast to a suitable pointer for the calling program to access it, and you may need to know the correct dimensions and lengths. This also means you can directly change those value(s) from the calling program (e.g., to modify atom positions). Of course, changing values should be done with care. When accessing per-atom data, please note that these data are the per-processor local data and are indexed accordingly. Per-atom data can change sizes and ordering at every neighbor list rebuild or atom sort event as atoms migrate between subdomains and processors.

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

    int main(int argc, char **argv)
    {
      void *handle;
      int i;

      handle = lammps_open_no_mpi(0, NULL, NULL);
      lammps_file(handle,"in.sysinit");
      printf("Running a simulation with %g atoms.\n",
             lammps_get_natoms(handle));

      printf(" %d local and %d ghost atoms. %d atom types\n",
             lammps_extract_setting(handle,"nlocal"),
             lammps_extract_setting(handle,"nghost"),
             lammps_extract_setting(handle,"ntypes"));

      double  *dt = (double *)lammps_extract_global(handle,"dt");
      printf("Changing timestep from %g to 0.5\n", *dt);
      *dt = 0.5;

      lammps_command(handle,"run 1000 post no");

      for (i=0; i < 10; ++i) {
        lammps_command(handle,"run 100 pre no post no");
        printf("PE = %g\nKE = %g\n",
               lammps_get_thermo(handle,"pe"),
               lammps_get_thermo(handle,"ke"));
      }
      lammps_close(handle);
      return 0;
    }

double lammps_get_natoms(void *handle)

  Return the total number of atoms in the system.

  This number may be very large when running large simulations across multiple processes. Depending on compile time choices, LAMMPS may be using either 32-bit or a 64-bit integer to store this number. For portability this function returns thus a double precision floating point number, which can represent up to a 53-bit signed integer exactly (\(\approx 10^{16}\)).

  As an alternative, you can use `lammps_extract_global()` and cast the resulting pointer to an integer pointer of the correct size and dereference it. The size of that integer (in bytes) can be queried by calling `lammps_extract_setting()` to return the size of a `bigint` integer.

  Changed in version 18Sep2020: The type of the return value was changed from `int` to `double` to accommodate reporting atom counts for larger systems that would overflow a 32-bit int without having to depend on a 64-bit bit integer type definition.

  Parameters:

    handle – pointer to a previously created LAMMPS instance

  Returns:

    total number of atoms or 0 if value is too large

double lammps_get_thermo(void *handle, const char *keyword)

  Evaluate a thermo keyword.

  This function returns the current value of a thermo keyword. Unlike `lammps_extract_global()` it does not give access to the storage of the desired data but returns its value as a `double`, so it can also return information that is computed on-the-fly. Use `lammps_last_thermo()` to get access to the cached data from the last thermo output.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - keyword – string with the name of the thermo keyword

  Returns:

    value of the requested thermo property or 0.0

void *lammps_last_thermo(void *handle, const char *what, int index)

  Access cached data from last thermo output

  New in version 15Jun2023.

  This function provides access to cached data from the last thermo output. This differs from `lammps_get_thermo()` in that it does not trigger an evaluation. Instead it provides direct access to a read-only location of the last thermo output data and the corresponding keyword strings. The how to handle the return value depends on the value of the what argument string.

  Value of what | Description of return value | Data type | Uses index
  --- | --- | --- | ---
  setup | 1 if setup is not completed and thus thermo data invalid, 0 otherwise | pointer to int | no
  step | timestep when the last thermo output was generated or -1 | pointer to bigint | no
  num | number of fields in thermo output | pointer to int | no
  keyword | column keyword for thermo output | pointer to 0-terminated const char array | yes
  type | data type of thermo output column; see `_LMP_DATATYPE_CONST` | pointer to int | yes
  data | actual field data for column | pointer to int, int64_t or double | yes

  Note

  The type property points to a static location that is reassigned with every call, so the returned pointer should be recast, dereferenced, and assigned immediately. Otherwise, its value may be changed with the next invocation of the function.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - what – string with the kind of data requested

    - index – integer with index into data arrays, ignored for scalar data

  Returns:

    pointer to location of requested data cast to void or NULL

void lammps_extract_box(void *handle, double *boxlo, double *boxhi, double *xy, double *yz, double *xz, int *pflags, int *boxflag)

  Extract simulation box parameters.

  This function (re-)initializes the simulation box and boundary information and then assign the designated data to the locations in the pointers passed as arguments. Any argument (except the first) may be a NULL pointer and then will not be assigned.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - boxlo – pointer to 3 doubles where the lower box boundary is stored

    - boxhi – pointer to 3 doubles where the upper box boundary is stored

    - xy – pointer to a double where the xy tilt factor is stored

    - yz – pointer to a double where the yz tilt factor is stored

    - xz – pointer to a double where the xz tilt factor is stored

    - pflags – pointer to 3 ints, set to 1 for periodic boundaries and 0 for non-periodic

    - boxflag – pointer to an int, which is set to 1 if the box will be changed during a simulation by a fix and 0 if not.

void lammps_reset_box(void *handle, double *boxlo, double *boxhi, double xy, double yz, double xz)

  Reset simulation box parameters.

  This function sets the simulation box dimensions (upper and lower bounds and tilt factors) from the provided data and then re-initializes the box information and all derived settings. It may only be called before atoms are created.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - boxlo – pointer to 3 doubles containing the lower box boundary

    - boxhi – pointer to 3 doubles containing the upper box boundary

    - xy – xy tilt factor

    - yz – yz tilt factor

    - xz – xz tilt factor

void lammps_memory_usage(void *handle, double *meminfo)

  Get memory usage information

  New in version 18Sep2020.

  This function will retrieve memory usage information for the current LAMMPS instance or process. The meminfo buffer will be filled with 3 different numbers (if supported by the operating system). The first is the tally (in MBytes) of all large memory allocations made by LAMMPS. This is a lower boundary of how much memory is requested and does not account for memory allocated on the stack or allocations via `new`. The second number is the current memory allocation of the current process as returned by a memory allocation reporting in the system library. The third number is the maximum amount of RAM (not swap) used by the process so far. If any of the two latter parameters is not supported by the operating system it will be set to zero.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - meminfo – buffer with space for at least 3 double to store data in.

int lammps_get_mpi_comm(void *handle)

  Return current LAMMPS world communicator as integer

  New in version 18Sep2020.

  This will take the LAMMPS “world” communicator and convert it to an integer using `MPI_Comm_c2f()`, so it is equivalent to the corresponding MPI communicator in Fortran. This way it can be safely passed around between different programming languages. To convert it to the C language representation use `MPI_Comm_f2c()`.

  If LAMMPS was compiled with MPI_STUBS, this function returns -1.

  See also

    `lammps_open_fortran()`

  Parameters:

    handle – pointer to a previously created LAMMPS instance

  Returns:

    Fortran representation of the LAMMPS world communicator

int lammps_extract_setting(void *handle, const char *keyword)

  Query LAMMPS about global settings.

  This function will retrieve or compute global properties. In contrast to `lammps_get_thermo()` this function returns an `int`. The following tables list the currently supported keyword. If a keyword is not recognized, the function returns -1. The integer sizes functions may be called without a valid LAMMPS object handle (it is ignored).

  - Integer sizes

  - Image masks

  - System status

  - System sizes

  - Atom style flags

  Integer sizes

  Keyword | Description / Return value
  --- | ---
  bigint | size of the `bigint` integer type, 4 or 8 bytes. Set at compile time.
  tagint | size of the `tagint` integer type, 4 or 8 bytes. Set at compile time.
  imageint | size of the `imageint` integer type, 4 or 8 bytes. Set at compile time.

  Image masks

  These settings are related to how LAMMPS stores and interprets periodic images. The values are used internally by the Fortran interface and are not likely to be useful to users.

  Keyword | Description / Return value
  --- | ---
  IMGMASK | Bit-mask used to convert image flags to a single integer
  IMGMAX | Maximum allowed image number for a particular atom
  IMGBITS | Bits used in image counts
  IMG2BITS | Second bitmask used in image counts

  System status

  Keyword | Description / Return value
  --- | ---
  dimension | Number of dimensions: 2 or 3. See dimension command.
  box_exist | 1 if the simulation box is defined, 0 if not. See create_box command.
  kokkos_active | 1 if the KOKKOS package is compiled in and activated, 0 if not. See KOKKOS package.
  kokkos_nthreads | Number of Kokkos threads per MPI process, 0 if Kokkos is not active. See KOKKOS package.
  kokkos_ngpus | Number of Kokkos gpus per physical node, 0 if Kokkos is not active or no GPU support. See KOKKOS package.
  nthreads | Number of requested OpenMP threads per MPI process for LAMMPS’ execution
  newton_bond | 1 if Newton’s 3rd law is applied to bonded interactions, 0 if not.
  newton_pair | 1 if Newton’s 3rd law is applied to non-bonded interactions, 0 if not.
  triclinic | 1 if the the simulation box is triclinic, 0 if orthogonal. See change_box command.
  universe_rank | MPI rank on LAMMPS’ universe communicator (0 <= universe_rank < universe_size)
  universe_size | Number of ranks on LAMMPS’ universe communicator (world_size <= universe_size)
  world_rank | MPI rank on LAMMPS’ world communicator (0 <= world_rank < world_size)
  world_size | Number of ranks on LAMMPS’ world communicator

  System sizes

  Keyword | Description / Return value
  --- | ---
  nlocal | number of “owned” atoms of the current MPI rank.
  nghost | number of “ghost” atoms of the current MPI rank.
  nall | number of all “owned” and “ghost” atoms of the current MPI rank.
  nmax | maximum of nlocal+nghost across all MPI ranks (for per-atom data array size).
  ntypes | number of atom types
  nbondtypes | number of bond types
  nangletypes | number of angle types
  ndihedraltypes | number of dihedral types
  nimpropertypes | number of improper types
  nellipsoids | number of atoms that have ellipsoid data
  nlines | number of atoms that have line data (see pair style line/lj)
  ntris | number of atoms that have triangle data (see pair style tri/lj)
  nbodies | number of atoms that have body data (see the Body particle HowTo)

  Atom style flags

  Keyword | Description / Return value
  --- | ---
  molecule_flag | 1 if the atom style includes molecular topology data. See atom_style command.
  q_flag | 1 if the atom style includes point charges. See atom_style command.
  mu_flag | 1 if the atom style includes point dipoles. See atom_style command.
  rmass_flag | 1 if the atom style includes per-atom masses, 0 if there are per-type masses. See atom_style command.
  radius_flag | 1 if the atom style includes a per-atom radius. See atom_style command.
  sphere_flag | 1 if the atom style describes extended particles that can rotate. See atom_style command.
  ellipsoid_flag | 1 if the atom style describes extended particles that may be ellipsoidal. See atom_style command.
  omega_flag | 1 if the atom style can store per-atom rotational velocities. See atom_style command.
  torque_flag | 1 if the atom style can store per-atom torques. See atom_style command.
  angmom_flag | 1 if the atom style can store per-atom angular momentum. See atom_style command.

  See also

    `lammps_extract_global()`

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - keyword – string with the name of the thermo keyword

  Returns:

    value of the queried setting or -1 if unknown

int lammps_extract_global_datatype(void *handle, const char *name)

  Get data type of internal global LAMMPS variables or arrays.

  New in version 18Sep2020.

  This function returns an integer that encodes the data type of the global property with the specified name. See `_LMP_DATATYPE_CONST` for valid values. Callers of `lammps_extract_global()` can use this information to then decide how to cast the `void *` pointer and access the data.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance (unused)

    - name – string with the name of the extracted property

  Returns:

    integer constant encoding the data type of the property or -1 if not found.

void *lammps_extract_global(void *handle, const char *name)

  Get pointer to internal global LAMMPS variables or arrays.

  This function returns a pointer to the location of some global property stored in one of the constituent classes of a LAMMPS instance. The returned pointer is cast to `void *` and needs to be cast to a pointer of the type that the entity represents. The pointers returned by this function are generally persistent; therefore it is not necessary to call the function again, unless a clear command command is issued which wipes out and recreates the contents of the `LAMMPS` class.

  Please also see `lammps_extract_setting()`, `lammps_get_thermo()`, and `lammps_extract_box()`.

  The following tables list the supported names, their data types, length of the data area, and a short description. The data type can also be queried through calling `lammps_extract_global_datatype()`. The `bigint` type may be defined to be either an `int` or an `int64_t`. This is set at compile time of the LAMMPS library and can be queried through calling `lammps_extract_setting()`. The function `lammps_extract_global_datatype()` will directly report the “native” data type. The following tables are provided:

  - Timestep settings

  - Simulation box settings

  - System property settings

  - Unit settings

  Timestep settings

  Name | Type | Length | Description
  --- | --- | --- | ---
  dt | double | 1 | length of the time step. See timestep command.
  ntimestep | bigint | 1 | current time step number. See reset_timestep command.
  atime | double | 1 | accumulated simulation time in time units.
  atimestep | bigint | 1 | the number of the timestep when “atime” was last updated.
  respa_levels | int | 1 | number of r-RESPA levels. See run_style command.
  respa_dt | double | number of r-RESPA levels | length of the time steps with r-RESPA. See run_style command.

  Simulation box settings

  Name | Type | Length | Description
  --- | --- | --- | ---
  boxlo | double | 3 | lower box boundaries. See create_box command.
  boxhi | double | 3 | upper box boundaries. See create_box command.
  boxxlo | double | 1 | lower box boundary in x-direction. See create_box command.
  boxxhi | double | 1 | upper box boundary in x-direction. See create_box command.
  boxylo | double | 1 | lower box boundary in y-direction. See create_box command.
  boxyhi | double | 1 | upper box boundary in y-direction. See create_box command.
  boxzlo | double | 1 | lower box boundary in z-direction. See create_box command.
  boxzhi | double | 1 | upper box boundary in z-direction. See create_box command.
  sublo | double | 3 | subbox lower boundaries
  subhi | double | 3 | subbox upper boundaries
  sublo_lambda | double | 3 | subbox lower boundaries in fractional coordinates (for triclinic cells)
  subhi_lambda | double | 3 | subbox upper boundaries in fractional coordinates (for triclinic cells)
  periodicity | int | 3 | 0 if non-periodic, 1 if periodic for x, y, and z; See boundary command.
  triclinic | int | 1 | 1 if the the simulation box is triclinic, 0 if orthogonal; See change_box command.
  xy | double | 1 | triclinic tilt factor. See Triclinic (non-orthogonal) simulation boxes.
  yz | double | 1 | triclinic tilt factor. See Triclinic (non-orthogonal) simulation boxes.
  xz | double | 1 | triclinic tilt factor. See Triclinic (non-orthogonal) simulation boxes.

  System property settings

  Name | Type | Length | Description
  --- | --- | --- | ---
  ntypes | int | 1 | number of atom types
  nbonds | bigint | 1 | total number of bonds in the simulation.
  nangles | bigint | 1 | total number of angles in the simulation.
  ndihedrals | bigint | 1 | total number of dihedrals in the simulation.
  nimpropers | bigint | 1 | total number of impropers in the simulation.
  natoms | bigint | 1 | total number of atoms in the simulation.
  nlocal | int | 1 | number of “owned” atoms of the current MPI rank.
  nghost | int | 1 | number of “ghost” atoms of the current MPI rank.
  nmax | int | 1 | maximum of nlocal+nghost across all MPI ranks (for per-atom data array size).
  special_lj | double | 4 | special pair weighting factors for LJ interactions (first element is always 1.0)
  special_coul | double | 4 | special pair weighting factors for Coulomb interactions (first element is always 1.0)
  q_flag | int | 1 | deprecated. Use `lammps_extract_setting()` instead.
  atom_style | char * | 1 | string with the current atom style.
  pair_style | char * | 1 | string with the current pair style.
  bond_style | char * | 1 | string with the current bond style.
  angle_style | char * | 1 | string with the current angle style.
  dihedral_style | char * | 1 | string with the current dihedral style.
  improper_style | char * | 1 | string with the current improper style.
  kspace_style | char * | 1 | string with the current KSpace style.

  Unit settings

  Name | Type | Length | Description
  --- | --- | --- | ---
  units | char * | 1 | string with the current unit style. See units command.
  boltz | double | 1 | value of the “boltz” constant. See units command.
  hplanck | double | 1 | value of the “hplanck” constant. See units command.
  mvv2e | double | 1 | factor to convert \(\frac{1}{2}mv^2\) for a particle to the current energy unit; See units command.
  ftm2v | double | 1 | (description missing) See units command.
  mv2d | double | 1 | (description missing) See units command.
  nktv2p | double | 1 | (description missing) See units command.
  qqr2e | double | 1 | factor to convert \(\frac{q_i q_j}{r}\) to energy units; See units command.
  qe2f | double | 1 | (description missing) See units command.
  vxmu2f | double | 1 | (description missing) See units command.
  xxt2kmu | double | 1 | (description missing) See units command.
  dielectric | double | 1 | value of the dielectric constant. See dielectric command.
  qqrd2e | double | 1 | (description missing) See units command.
  e_mass | double | 1 | (description missing) See units command.
  hhmrr2e | double | 1 | (description missing) See units command.
  mvh2r | double | 1 | (description missing) See units command.
  angstrom | double | 1 | constant to convert current length unit to angstroms; 1.0 for reduced (aka “lj”) units. See units command.
  femtosecond | double | 1 | constant to convert current time unit to femtoseconds; 1.0 for reduced (aka “lj”) units
  qelectron | double | 1 | (description missing) See units command.

  Warning

  Modifying the data in the location pointed to by the returned pointer may lead to inconsistent internal data and thus may cause failures or crashes or bogus simulations. In general it is thus usually better to use a LAMMPS input command that sets or changes these parameters. Those will take care of all side effects and necessary updates of settings derived from such settings. Where possible, a reference to such a command or a relevant section of the manual is given below.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - name – string with the name of the extracted property

  Returns:

    pointer (cast to `void *`) to the location of the requested property. NULL if name is not known.