\(\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 initialized 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 shrink, 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()