\(\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
line	line number (0-based) of current line in current file or buffer	pointer to int	no
imagename	file name of the last dump image file written	pointer to 0-terminated const char array	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.