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

1.1.4. Per-atom properties

This section documents the following functions:

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

Get data type of a LAMMPS per-atom property

Added in version 18Sep2020.

This function returns an integer that encodes the data type of the per-atom property with the specified name. See _LMP_DATATYPE_CONST for valid values. Callers of lammps_extract_atom() can use this information to decide how to cast the void * pointer and access the data. In addition, lammps_extract_atom_size() can be used to get information about the vector or array dimensions.

Parameters:

  • handle – pointer to a previously created LAMMPS instance

  • name – string with the name of the extracted property

Returns:

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

int lammps_extract_atom_size(void *handle, const char *name, int type)

Get dimension info of a LAMMPS per-atom property

Added in version 19Nov2024.

This function returns an integer with the size of the per-atom property with the specified name. This allows to accurately determine the size of the per-atom data vectors or arrays. For per-atom arrays, the type argument is required to return either the number of rows or the number of columns. It is ignored for per-atom vectors.

Callers of lammps_extract_atom() can use this information in combination with the result from lammps_extract_atom_datatype() to decide how to cast the void * pointer and access the data.

Parameters:

  • handle – pointer to a previously created LAMMPS instance

  • name – string with the name of the extracted property

  • type – either LMP_SIZE_ROWS or LMP_SIZE_COLS if name refers to a per-atom array otherwise ignored

Returns:

integer with the size of the vector or array dimension or -1

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

Get pointer to a LAMMPS per-atom property.

This function returns a pointer to the location of per-atom properties (and per-atom-type properties in the case of the ‘mass’ keyword). Per-atom data is distributed across sub-domains and thus MPI ranks. The returned pointer is cast to void * and needs to be cast to a pointer of data type that the entity represents. You can use the functions lammps_extract_atom_datatype() and lammps_extract_atom_size() to determine data type, dimensions and sizes of the storage pointed to by the returned pointer.

A table with supported keywords is included in the documentation of the Atom::extract() function.

Changed in version 4Jul2026.

When using the KOKKOS package with a device backend, per-atom data is now synchronized from the device to the host before the pointer is returned. Previously the host copy could be out-of-date for calls not aligned with an output or end-of-run step.

Note

When running with the KOKKOS package and per-atom data residing on an accelerator device (e.g. a GPU), the requested data is synchronized from the device to the host before the pointer is returned, so that the host data accessed through it is current even when this function is called between output steps (for example from the LAMMPS GUI or a Python script while a run is in progress).

Warning

The pointers returned by this function are generally not persistent since per-atom data may be re-distributed, re-allocated, and re-ordered at every re-neighboring operation.

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 data or NULL if not found.