4.13.2. LAMMPS Atom and AtomVec Base Classes — LAMMPS documentation

\(\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()`, `lammps_extract_atom_datatype()`, `lammps_extract_atom_size()`

    See also

    extract_datatype, extract_size

    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 extract_size

    Parameters:

      name – string with the keyword of the desired property.

    Returns:

      data type constant for desired property or -1

  int extract_size(const char*, int)

    Provide vector or array size info of internal data of the Atom class

    Added in version 19Nov2024.

    See also

    extract extract_datatype

    Parameters:

      - name – string with the keyword of the desired property.

      - type – either LMP_SIZE_ROWS or LMP_SIZE_COLS for per-atom array or ignored

    Returns:

      size of the vector or size of the array for the requested dimension or -1

  struct PerAtom