1.1.4. Per-atom properties — LAMMPS documentation

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

# 1.1.4. Per-atom properties

This section documents the following functions:

- `lammps_extract_atom_datatype()`

- `lammps_extract_atom_size()`

- `lammps_extract_atom()`

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.

  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.