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

4.13.2. LAMMPS Atom and AtomVec Base Classes

class Atom : protected Pointers

Class to provide access to atom data.

The Atom class provides access to atom style related global settings and per-atom data that is stored with atoms and migrates with them from sub-domain to sub-domain as atoms move around. This includes topology data, which is stored with either one specific atom or all atoms involved depending on the settings of the newton command.

The actual per-atom data is allocated and managed by one of the various classes derived from the AtomVec class as determined by the atom_style command. The pointers in the Atom class are updated by the AtomVec class as needed.

Public Functions

Atom(class LAMMPS*)

Atom class constructor

This resets and initializes all kinds of settings, parameters, and pointer variables for per-atom arrays. This also initializes the factory for creating instances of classes derived from the AtomVec base class, which correspond to the selected atom style.

Parameters:

_lmp – pointer to the base LAMMPS class

int find_custom(const char*, int&, int&)

Find a custom per-atom property with given name.

This function returns the list index of a custom per-atom property with the name “name”, also returning by reference its data type and number of values per atom.

Parameters:
  • name – Name of the property (w/o a “i_” or “d_” or “i2_” or “d2_” prefix)

  • &flag – Returns data type of property: 0 for int, 1 for double

  • &cols – Returns number of values: 0 for a single value, 1 or more for a vector of values

Returns:

index of property in the respective list of properties

int find_custom_ghost(const char*, int&, int&, int&)

Find a custom per-atom property with given name and retrieve ghost property.

This function returns the list index of a custom per-atom property with the name “name”, also returning by reference its data type, number of values per atom, and if it is communicated to ghost particles. Classes rarely need to check on ghost communication and so find_custom is typically preferred to this function. See pair amoeba for an example where checking ghost communication is necessary.

Parameters:
  • name – Name of the property (w/o a “i_” or “d_” or “i2_” or “d2_” prefix)

  • &flag – Returns data type of property: 0 for int, 1 for double

  • &cols – Returns number of values: 0 for a single value, 1 or more for a vector of values

  • &ghost – Returns whether property is communicated to ghost atoms: 0 for no, 1 for yes

Returns:

index of property in the respective list of properties

virtual int add_custom(const char*, int, int, int ghost = 0)

Add a custom per-atom property with the given name and type and size.

This function will add a custom per-atom property with one or more values with the name “name” to the list of custom properties. This function is called, e.g. from fix property/atom.

Parameters:
  • name – Name of the property (w/o a “i_” or “d_” or “i2_” or “d2_” prefix)

  • flag – Data type of property: 0 for int, 1 for double

  • cols – Number of values: 0 for a single value, 1 or more for a vector of values

  • ghost – Whether property is communicated to ghost atoms: 0 for no, 1 for yes

Returns:

index of property in the respective list of properties

virtual void remove_custom(int, int, int)

Remove a custom per-atom property of a given type and size.

This will remove a property that was requested, e.g. by the fix property/atom command. It frees the allocated memory and sets the pointer to nullptr for the entry in the list so it can be reused. The lists of these pointers are never compacted or shrunk, so that indices to name mappings remain valid.

Parameters:
  • index – Index of property in the respective list of properties

  • flag – Data type of property: 0 for int, 1 for double

  • cols – Number of values: 0 for a single value, 1 or more for a vector of values

void *extract(const char*)

Provide access to internal data of the Atom class by keyword

This function is a way to access internal per-atom data. This data is distributed across MPI ranks and thus only the data for “local” atoms are expected to be available. Whether also data for “ghost” atoms is stored and up-to-date depends on various simulation settings.

This table lists a large part of the supported names, their data types, length of the data area, and a short description.

Name

Type

Items per atom

Description

mass

double

1

per-type mass. This array is NOT a per-atom array but of length ntypes+1, element 0 is ignored.

id

tagint

1

atom ID of the particles

type

int

1

atom type of the particles

mask

int

1

bitmask for mapping to groups. Individual bits are set to 0 or 1 for each group.

image

imageint

1

3 image flags encoded into a single integer. See lammps_encode_image_flags().

x

double

3

x-, y-, and z-coordinate of the particles

v

double

3

x-, y-, and z-component of the velocity of the particles

f

double

3

x-, y-, and z-component of the force on the particles

molecule

int

1

molecule ID of the particles

q

double

1

charge of the particles

mu

double

3

dipole moment of the particles

omega

double

3

x-, y-, and z-component of rotational velocity of the particles

angmom

double

3

x-, y-, and z-component of angular momentum of the particles

torque

double

3

x-, y-, and z-component of the torque on the particles

radius

double

1

radius of the (extended) particles

rmass

double

1

per-atom mass of the particles. nullptr if per-type masses are used. See the rmass_flag setting.

ellipsoid

int

1

1 if the particle is an ellipsoidal particle, 0 if not

line

int

1

1 if the particle is a line particle, 0 if not

tri

int

1

1 if the particle is a triangulated particle, 0 if not

body

int

1

1 if the particle is a body particle, 0 if not

quat

double

4

four quaternion components of the particles

temperature

double

1

temperature of the particles

heatflow

double

1

heatflow of the particles

i_name

int

1

single integer value defined by fix property/atom vector name

d_name

double

1

single double value defined by fix property/atom vector name

i2_name

int

N

N integer values defined by fix property/atom array name

d2_name

double

N

N double values defined by fix property/atom array name

See also

lammps_extract_atom()

See also

extract_datatype

Parameters:

name – string with the keyword of the desired property. Typically the name of the pointer variable returned

Returns:

pointer to the requested data cast to void * or nullptr

int extract_datatype(const char*)

Provide data type info about internal data of the Atom class

Added in version 18Sep2020.

See also

extract

Parameters:

name – string with the keyword of the desired property.

Returns:

data type constant for desired property or -1

struct PerAtom