1.1.3. System properties

This section documents the following functions:

The library interface allows extraction of different kinds of information about the active simulation instance and also 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, this should be done with care. When accessing per-atom data, please note that this data is the per-processor local data and is indexed accordingly. Per-atom data can change sizes and ordering at every neighbor list rebuild or atom sort event as atoms migrate between sub-domains 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 processors. 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)

Get current value of 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.

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_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

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.

New in version 18Sep2020.

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

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.

New in version 18Sep2020.

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.

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.

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.

nthreads

Number of requested OpenMP threads 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

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.

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.

New in version 18Sep2020.

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

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

q_flag

int

1

deprecated. Use lammps_extract_setting() instead.

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