ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

adjustements to atom_style doc page

Browse Source
This commit is contained in:
Steve Plimpton
2024-01-26 10:11:35 -07:00
parent 4082ca077e
commit e84adc630b
1 changed files with 149 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
doc/src/atom_style.rst
View File

@ -51,18 +51,18 @@ Description
The *atom_style* command selects which per-atom attributes are
associated with atoms in a LAMMPS simulation and thus stored and
communicated with those atoms and read from and stored in data and
restart files. Different models (e.g. :doc:`pair styles <pair_style>`)
require access to specific per-atom attributes and thus require a
specific atom style (for instance, to compute Coulomb interactions, the
atom must have a "charge" (aka "q") attribute.
communicated with those atoms as well as read from and stored in data
and restart files. Different models (e.g. :doc:`pair styles
<pair_style>`) require access to specific per-atom attributes and thus
require a specific atom style. For example, to compute Coulomb
interactions, the atom must have a "charge" (aka "q") attribute.
A number of distinct atom styles exist that combine attributes. Some
atom styles are supersets of others. Further attributes may be added to
atoms either via using a hybrid style and thus providing a union of the
attributes of the sub-styles, or via :doc:`fix property/atom
<fix_property_atom>`. The *atom_style* command must be used before a
simulation is setup via a :doc:`read_data <read_data>`,
atom styles are supersets of others. Further attributes may be added
to atoms either via using a hybrid style which provides a union of the
attributes of the sub-styles, or via the :doc:`fix property/atom
<fix_property_atom>` command. The *atom_style* command must be used
before a simulation is setup via a :doc:`read_data <read_data>`,
:doc:`read_restart <read_restart>`, or :doc:`create_box <create_box>`
command.
@ -79,33 +79,27 @@ general enough to encompass all attributes required. E.g. with atom
style *bond*, it is not possible to define angles and use angle styles.
It is OK to use a style more general than needed, though it may be
slightly inefficient and allocate and communicate additional, otherwise
unused data.
slightly inefficient because it will allocate and communicate
additional unused data.
Atom style attributes
"""""""""""""""""""""
The atom style *atomic* has the minimum subset of per-atom attributes
and is also the default setting. It encompasses the following per-atom
attributes (name of the array in the :doc:`Atom class <Classes_atom>` is
given in parenthesis): atom-ID (tag), type (type), position (x),
velocities (v), forces (f), image flags (image), group membership
(mask). Since all atom styles are supersets of *atomic* they all
include these attributes.
and is also the default setting. It encompasses the following
per-atom attributes (name of the vector or array in the :doc:`Atom
class <Classes_atom>` is given in parenthesis): atom-ID (tag), type
(type), position (x), velocities (v), forces (f), image flags (image),
group membership (mask). Since all atom styles are supersets of
*atomic* they all include these attributes.
.. note::
The atomic mass (mass) is generally indexed with the atom *type* and
**not** the atom *index*. A per-atom mass attribute (rmass) is
available for select atom styles or can be added through using
:doc:`fix property/atom <fix_property_atom>`. If both are defined
the per-atom mass takes precedence.
Below is a table with additional atom styles, which attributes they
This table lists all the available atom styles, which attributes they
provide, which :doc:`package <Packages>` is required to use them, and
what typical applications are that use them. See the :doc:`read_data
<read_data>`, :doc:`create_atoms <create_atoms>`, and :doc:`set <set>`
commands for details on how to set these various quantities.
what the typical applications are that use them. See the
:doc:`read_data <read_data>`, :doc:`create_atoms <create_atoms>`, and
:doc:`set <set>` commands for details on how to set these various
quantities. More information about many of the styles is provided in
the Additional Information section below.
.. list-table::
:header-rows: 1
@ -226,50 +220,67 @@ commands for details on how to set these various quantities.
.. note::
It is possible to add some attributes, such as a molecule ID, to atom
styles that do not have them built in using the :doc:`fix
property/atom <fix_property_atom>` command. This command also allows
new custom attributes consisting of extra integer or floating-point
values or vectors to be added to atoms. See the :doc:`fix property/atom
<fix_property_atom>` page for examples of cases where this is useful
and details on how to initialize, access, and output these custom
values.
It is possible to add some attributes, such as a molecule ID and
charge, to atom styles that do not have them built in using the
:doc:`fix property/atom <fix_property_atom>` command. This command
also allows new custom-named attributes consisting of extra integer
or floating-point values or vectors to be added to atoms. See the
:doc:`fix property/atom <fix_property_atom>` page for examples of
cases where this is useful and details on how to initialize,
access, and output these custom values.
All of the above atyle styles define point particles unless that have
the *radius* property and then define finite-size particles. See the
:doc:`Howto spherical <Howto_spherical>` page for an overview of using
finite-size particle models with LAMMPS. The *radius* property may need
to be entered as *diameter* (e.g. in :doc:`molecule files <molecule>`
or :doc:`data files <read_data>`).
----------
Unless an atom style has the *rmass* attribute, the atomic masses are
defined on a per-type basis, using the :doc:`mass <mass>` command. Atom
styles that have a per-atom mass may define it indirectly through
setting particle diameter and density on a per-particle basis. If the
*rmass* attribute is added through :doc:`fix property/atom <fix_property_atom>`
it is usually needed to define both, per-type and per-atom masses, however
the per-atom mass will usually take precedence.
Particle size and mass
""""""""""""""""""""""
For the atom style *sphere* and *bpm/sphere* styles, the particles may
be either point particles or finite-size particles. If the *radius*
attribute is > 0.0, the particle is a finite-size sphere. If the
diameter = 0.0, it is a point particle. Note that by using the *disc*
keyword with the :doc:`fix nve/sphere <fix_nve_sphere>`, :doc:`fix
nvt/sphere <fix_nvt_sphere>`, :doc:`fix nph/sphere <fix_nph_sphere>`,
:doc:`fix npt/sphere <fix_npt_sphere>` commands for the *sphere* style,
spheres can be effectively treated as 2d discs for a 2d simulation if
desired. See also the :doc:`set density/disc <set>` command. These
styles also take an optional 0 or 1 argument. A value of 0 means the
radius of each sphere is constant for the duration of the simulation
(this is the default). A value of 1 means the radii may vary
dynamically during the simulation, e.g. due to use of the :doc:`fix
adapt <fix_adapt>` command.
All of the atom styles define point particles unless they (1) define
finite-size spherical particles via the *radius* attribute, or (2)
define finite-size aspherical particles (e.g. the *body*, *ellipsoid*,
*line*, and *tri* styles). Most of these styles can also be used with
mixtures of point and finite-size particles.
For the *ellipsoid* style, the particles are ellipsoids and each
stores a flag which indicates whether it is a finite-size ellipsoid or
a point particle. If it is an ellipsoid, it also stores a shape
vector with the 3 diameters of the ellipsoid and a quaternion 4-vector
with its orientation.
Note that the *radius* property may need to be provided as a
*diameter* (e.g. in :doc:`molecule files <molecule>` or :doc:`data
files <read_data>`). See the :doc:`Howto spherical <Howto_spherical>`
page for an overview of using finite-size spherical and aspherical
particle models with LAMMPS.
Unless an atom style defines the per-atom *rmass* attribute, particle
masses are defined on a per-type basis, using the :doc:`mass <mass>`
command. This means each particle's mass is indexed by its atom
*type*.
A few styles define the per-atom *rmass* attribute which can also be
added using the :doc:`fix property/atom <fix_property_atom>` command.
In this case each particle stores its own mass. Atom styles that have
a per-atom rmass may define it indirectly through setting particle
diameter and density on a per-particle basis. If both per-type mass
and per-atom *rmass* are defined (e.g. in a hybrid style), the
per-atom mass will take precedence in any operation which which works
with both flavors of mass.
----------
Additional information about specific atom styles
"""""""""""""""""""""""""""""""""""""""""""""""""
For the *body* style, the particles are arbitrary bodies with internal
attributes defined by the "style" of the bodies, which is specified by
the *bstyle* argument. Body particles can represent complex entities,
such as surface meshes of discrete points, collections of
sub-particles, deformable objects, etc.
The :doc:`Howto body <Howto_body>` page describes the body styles
LAMMPS currently supports, and provides more details as to the kind of
body particles they represent. For all styles, each body particle
stores moments of inertia and a quaternion 4-vector, so that its
orientation and position can be time integrated due to forces and
torques.
Note that there may be additional arguments required along with the
*bstyle* specification, in the atom_style body command. These
arguments are described on the :doc:`Howto body <Howto_body>` doc page.
For the *dielectric* style, each particle can be either a physical
particle (e.g. an ion), or an interface particle representing a boundary
@ -288,28 +299,16 @@ and interface particles is only meaningful when :doc:`fix polarize
<fix_polarize>` commands are applied to the interface particles. This
style is part of the DIELECTRIC package.
For the *dipole* style, a point dipole is defined for each point
particle. Note that if you wish the particles to be finite-size spheres
as in a Stockmayer potential for a dipolar fluid, so that the particles
can rotate due to dipole-dipole interactions, then you need to use the
command `atom_style hybrid sphere dipole`, which will assign both a
diameter and dipole moment to each particle. This also requires using
an integrator with a "/sphere" suffix like :doc:`fix nve/sphere
<fix_nve_sphere>` or :doc:`fix nvt/sphere <fix_nh_sphere>` and the
"update dipole" or "update dlm" parameters to the fix commands.
For the *electron* style, the particles representing electrons are 3d
Gaussians with a specified position and bandwidth or uncertainty in
position, which is represented by the eradius = electron size.
For the *peri* style, the particles are spherical and each stores a
per-particle mass and volume.
The *oxdna* style is for coarse-grained nucleotides and stores the
3'-to-5' polarity of the nucleotide strand, which is set through
the bond topology in the data file. The first (second) atom in a
bond definition is understood to point towards the 3'-end (5'-end)
of the strand.
For the *dipole* style, a point dipole vector mu is defined for each
point particle. Note that if you wish the particles to be finite-size
spheres as in a Stockmayer potential for a dipolar fluid, so that the
particles can rotate due to dipole-dipole interactions, then you need
to use the command `atom_style hybrid sphere dipole`, which will
assign both a diameter and dipole moment to each particle. This also
requires using an integrator with a "/sphere" suffix like :doc:`fix
nve/sphere <fix_nve_sphere>` or :doc:`fix nvt/sphere <fix_nh_sphere>`
and the "update dipole" or "update dlm" parameters to the fix
commands.
The *dpd* style is for reactive dissipative particle dynamics (DPD)
particles. Note that it is part of the DPD-REACT package, and is not
@ -321,19 +320,36 @@ mechanical energy (uMech), and internal chemical energy (uChem).
The *edpd* style is for energy-conserving dissipative particle
dynamics (eDPD) particles which store a temperature (edpd_temp), and
heat capacity(edpd_cv).
heat capacity (edpd_cv).
For the *electron* style, the particles representing electrons are 3d
Gaussians with a specified position and bandwidth or uncertainty in
position, which is represented by the eradius = electron size.
For the *ellipsoid* style, particles can be ellipsoids which each
stores a shape vector with the 3 diameters of the ellipsoid and a
quaternion 4-vector with its orientation. Each particle stores a flag
in the ellipsoid vector which indicates whether it is an ellipsoid (1)
or a point particle (0).
For the *line* style, particles can be are idealized line segments
which store a per-particle mass and length and orientation (i.e. the
end points of the line segment). Each particle stores a flag in the
line vector which indicates whether it is a line segment (1) or a
point particle (0).
The *mdpd* style is for many-body dissipative particle dynamics (mDPD)
particles which store a density (rho) for considering density-dependent
many-body interactions.
The *tdpd* style is for transport dissipative particle dynamics (tDPD)
particles which store a set of chemical concentration. An integer
"cc_species" is required to specify the number of chemical species
involved in a tDPD system.
The *oxdna* style is for coarse-grained nucleotides and stores the
3'-to-5' polarity of the nucleotide strand, which is set through
the bond topology in the data file. The first (second) atom in a
bond definition is understood to point towards the 3'-end (5'-end)
of the strand.
The *sph* style is for smoothed particle hydrodynamics (SPH) particles
which store a density (rho), energy (esph), and heat capacity (cv).
For the *peri* style, the particles are spherical and each stores a
per-particle mass and volume.
The *smd* style is for Smooth Particle Mach dynamics. Both fluids and
solids can be modeled. Particles store the mass and volume of an
@ -342,22 +358,37 @@ variables (e.g. stress and deformation) and a contact radius for
calculating repulsive forces which prevent individual physical bodies
from penetrating each other.
For the *spin* style, a magnetic spin is associated to each atom.
The *sph* style is for smoothed particle hydrodynamics (SPH) particles
which store a density (rho), energy (esph), and heat capacity (cv).
For the *spin* style, a magnetic spin is associated with each atom.
Those spins have a norm (their magnetic moment) and a direction.
The *wavepacket* style is similar to *electron*, but the electrons may
consist of several Gaussian wave packets, summed up with coefficients
cs= (cs_re,cs_im). Each of the wave packets is treated as a separate
particle in LAMMPS, wave packets belonging to the same electron must
have identical *etag* values.
The *tdpd* style is for transport dissipative particle dynamics (tDPD)
particles which store a set of chemical concentration. An integer
"cc_species" is required to specify the number of chemical species
involved in a tDPD system.
For the *line* style, the particles are idealized line segments and
each stores a per-particle mass and length and orientation (i.e. the
end points of the line segment).
The *wavepacket* style is similar to the *electron* style, but the
electrons may consist of several Gaussian wave packets, summed up with
coefficients cs= (cs_re,cs_im). Each of the wave packets is treated
as a separate particle in LAMMPS, wave packets belonging to the same
electron must have identical *etag* values.
For the *tri* style, the particles are planar triangles and each
stores a per-particle mass and size and orientation (i.e. the corner
points of the triangle).
The *sphere* and *bpm/sphere* styles allow particles to be either point
particles or finite-size particles. If the *radius* attribute is >
0.0, the particle is a finite-size sphere. If the diameter = 0.0, it
is a point particle. Note that by using the *disc* keyword with the
:doc:`fix nve/sphere <fix_nve_sphere>`, :doc:`fix nvt/sphere
<fix_nvt_sphere>`, :doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix
npt/sphere <fix_npt_sphere>` commands for the *sphere* style, spheres
can be effectively treated as 2d discs for a 2d simulation if desired.
See also the :doc:`set density/disc <set>` command. These styles also
take an optional 0 or 1 argument. A value of 0 means the radius of
each sphere is constant for the duration of the simulation (this is
the default). A value of 1 means the radii may vary dynamically
during the simulation, e.g. due to use of the :doc:`fix adapt
<fix_adapt>` command.
The *template* style allows molecular topology (bonds,angles,etc) to be
defined via a molecule template using the :doc:`molecule <molecule>`
@ -387,22 +418,11 @@ showing the use of the *template* atom style versus *molecular*.
the CO2 molecule should define atom types 3 and 4 (or atom types 3
and 2 if a single oxygen type is desired), and bond type 2.
For the *body* style, the particles are arbitrary bodies with internal
attributes defined by the "style" of the bodies, which is specified by
the *bstyle* argument. Body particles can represent complex entities,
such as surface meshes of discrete points, collections of
sub-particles, deformable objects, etc.
The :doc:`Howto body <Howto_body>` page describes the body styles
LAMMPS currently supports, and provides more details as to the kind of
body particles they represent. For all styles, each body particle
stores moments of inertia and a quaternion 4-vector, so that its
orientation and position can be time integrated due to forces and
torques.
Note that there may be additional arguments required along with the
*bstyle* specification, in the atom_style body command. These
arguments are described on the :doc:`Howto body <Howto_body>` doc page.
For the *tri* style, particles can be planar triangles which each
stores a per-particle mass and size and orientation (i.e. the corner
points of the triangle). Each particle stores a flag in the tri
vector which indicates whether it is a triangle (1) or a point
particle (0).
----------
@ -454,8 +474,8 @@ Related commands
Default
"""""""
The default atom style is *atomic*. If atom_style *sphere* is used, its
default argument is 0.
The default atom style is *atomic*. If atom_style *sphere* or
*bpm/sphere* is used, its default argument is 0.
----------