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

update some doc pages

Browse Source
This commit is contained in:
Steve Plimpton
2023-11-09 17:58:12 -07:00
parent 612a919e93
commit e57079768f
3 changed files with 280 additions and 239 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
doc/src/Howto_triclinic.rst
View File

@ -56,9 +56,9 @@ at (xlo,ylo,zhi) and 3 edge vectors **A** = (ax,ay,az), **B** =
(bx,by,bz), **C** = (cx,cy,cz) which can be arbitrary vectors, so long
as they are non-zero, distinct, and not co-planar. In addition, they
must define a right-handed system, such that (**A** cross **B**)
points in the direction of **C**. Note that a left-handed system can
be converted to a right-handed system by simply swapping the order of
any two of the **A**, **B**, **C** vectors.
points in the direction of **C**. A left-handed system can be
converted to a right-handed system by simply swapping the order of any
pair of the **A**, **B**, **C** vectors.
The 4 commands listed above for defining orthogonal simulation boxes
have triclinic options which allow for specification of the origin and
@ -151,12 +151,12 @@ This means 4 things which are important to understand:
should be inside the general triclinic simulation box defined by the
edge vectors **A**, **B**, **C** and its origin. Likewise per-atom
velocities should be in directions consistent with the general
triclinic box orientation. I.e. a velocity vector that will be in
triclinic box orientation. E.g. a velocity vector which will be in
the +x direction once LAMMPS converts from a general to restricted
triclinic box, should be specified in the data file in the direction
of the **A** edge vector. See the :doc:`read_data <read_data>` doc
page for info on all the per-atom vector quantities this rule
affects when the data file for a general triclinic box is input.
page for info on all the per-atom vector quantities to which this
rule applies when a data file for a general triclinic box is input.
* If commands such as :doc:`write_data <write_data>` or :doc:`dump
custom <dump>` are used to output general triclinic information, it
is effectively the inverse of the operation described in the
@ -332,16 +332,18 @@ will become non-orthogonal, e.g. due to use of the :doc:`fix npt
you can use the :doc:`change_box <change_box>` command to convert a
simulation box from orthogonal to restricted triclinic and vice versa.
Highly tilted restricted triclinic simulation boxes can be
computationally inefficient. This is due to the large volume of
communication needed to acquire ghost atoms around a processor's
irregular-shaped subdomain. For extreme values of tilt, LAMMPS may
also lose atoms and generate an error.
.. note::
Highly tilted restricted triclinic simulation boxes can be
computationally inefficient. This is due to the large volume of
communication needed to acquire ghost atoms around a processor's
irregular-shaped subdomain. For extreme values of tilt, LAMMPS may
also lose atoms and generate an error.
LAMMPS will issue a warning if you define a restricted triclinic box
with a tilt factor which skews the box more than half the distance of
the parallel box length, which is the first dimension in the tilt
factor (x for xz).
factor (e.g. x for xz).
For example, if xlo = 2 and xhi = 12, then the x box length is 10 and
the xy tilt factor should be between -5 and 5 to avoid the warning.
@ -361,8 +363,8 @@ occur using the :doc:`fix deform <fix_deform>` or :doc:`fix npt
either of the commands.
One exception to box flipping is if the first dimension in the tilt
factor (x for xy) is non-periodic. In that case, the limits on the
tilt factor are not enforced, since flipping the box in that dimension
would not change the atom positions due to non-periodicity. In this
mode, if the system tilts to large angles, the simulation will simply
become inefficient, due to the highly skewed simulation box.
factor (e.g. x for xy) is non-periodic. In that case, the limits on
the tilt factor are not enforced, since flipping the box in that
dimension would not change the atom positions due to non-periodicity.
In this mode, if the system tilts to large angles, the simulation will
simply become inefficient, due to the highly skewed simulation box.

281
doc/src/fix_rigid.rst
View File

@ -169,14 +169,15 @@ Examples of large rigid bodies are a colloidal particle, or portions
of a biomolecule such as a protein.
Example of small rigid bodies are patchy nanoparticles, such as those
modeled in :ref:`this paper <Zhang1>` by Sharon Glotzer's group, clumps of
granular particles, lipid molecules consisting of one or more point
dipoles connected to other spheroids or ellipsoids, irregular
particles built from line segments (2d) or triangles (3d), and
coarse-grain models of nano or colloidal particles consisting of a
small number of constituent particles. Note that the :doc:`fix shake <fix_shake>` command can also be used to rigidify small
molecules of 2, 3, or 4 atoms, e.g. water molecules. That fix treats
the constituent atoms as point masses.
modeled in :ref:`this paper <Zhang1>` by Sharon Glotzer's group,
clumps of granular particles, lipid molecules consisting of one or
more point dipoles connected to other spheroids or ellipsoids,
irregular particles built from line segments (2d) or triangles (3d),
and coarse-grain models of nano or colloidal particles consisting of a
small number of constituent particles. Note that the :doc:`fix shake
<fix_shake>` command can also be used to rigidify small molecules of
2, 3, or 4 atoms, e.g. water molecules. That fix treats the
constituent atoms as point masses.
These fixes also update the positions and velocities of the atoms in
each rigid body via time integration, in the NVE, NVT, NPT, or NPH
@ -210,13 +211,14 @@ processors when ghost atom info is accumulated.
.. note::
To use the *rigid/small* styles the ghost atom cutoff must be
large enough to span the distance between the atom that owns the body
and every other atom in the body. This distance value is printed out
when the rigid bodies are defined. If the
:doc:`pair_style <pair_style>` cutoff plus neighbor skin does not span
this distance, then you should use the :doc:`comm_modify cutoff <comm_modify>` command with a setting epsilon larger than
the distance.
To use the *rigid/small* styles the ghost atom cutoff must be large
enough to span the distance between the atom that owns the body and
every other atom in the body. This distance value is printed out
when the rigid bodies are defined. If the :doc:`pair_style
<pair_style>` cutoff plus neighbor skin does not span this
distance, then you should use the :doc:`comm_modify cutoff
<comm_modify>` command with a setting epsilon larger than the
distance.
Which of the two variants is faster for a particular problem is hard
to predict. The best way to decide is to perform a short test run.
@ -227,49 +229,54 @@ differences may accumulate to produce divergent trajectories.
.. note::
You should not update the atoms in rigid bodies via other
time-integration fixes (e.g. :doc:`fix nve <fix_nve>`, :doc:`fix nvt <fix_nh>`, :doc:`fix npt <fix_nh>`, :doc:`fix move <fix_move>`),
or you will have conflicting updates to positions and velocities
resulting in unphysical behavior in most cases. When performing a hybrid
simulation with some atoms in rigid bodies, and some not, a separate
time integration fix like :doc:`fix nve <fix_nve>` or :doc:`fix nvt <fix_nh>` should be used for the non-rigid particles.
time-integration fixes (e.g. :doc:`fix nve <fix_nve>`, :doc:`fix
nvt <fix_nh>`, :doc:`fix npt <fix_nh>`, :doc:`fix move
<fix_move>`), or you will have conflicting updates to positions and
velocities resulting in unphysical behavior in most cases. When
performing a hybrid simulation with some atoms in rigid bodies, and
some not, a separate time integration fix like :doc:`fix nve
<fix_nve>` or :doc:`fix nvt <fix_nh>` should be used for the
non-rigid particles.
.. note::
These fixes are overkill if you simply want to hold a collection
of atoms stationary or have them move with a constant velocity. A
simpler way to hold atoms stationary is to not include those atoms in
your time integration fix. E.g. use "fix 1 mobile nve" instead of
"fix 1 all nve", where "mobile" is the group of atoms that you want to
move. You can move atoms with a constant velocity by assigning them
an initial velocity (via the :doc:`velocity <velocity>` command),
setting the force on them to 0.0 (via the :doc:`fix setforce <fix_setforce>` command), and integrating them as usual
(e.g. via the :doc:`fix nve <fix_nve>` command).
These fixes are overkill if you simply want to hold a collection of
atoms stationary or have them move with a constant velocity. A
simpler way to hold atoms stationary is to not include those atoms
in your time integration fix. E.g. use "fix 1 mobile nve" instead
of "fix 1 all nve", where "mobile" is the group of atoms that you
want to move. You can move atoms with a constant velocity by
assigning them an initial velocity (via the :doc:`velocity
<velocity>` command), setting the force on them to 0.0 (via the
:doc:`fix setforce <fix_setforce>` command), and integrating them
as usual (e.g. via the :doc:`fix nve <fix_nve>` command).
.. warning::
The aggregate properties of each rigid body are
calculated at the start of a simulation run and are maintained in
internal data structures. The properties include the position and
velocity of the center-of-mass of the body, its moments of inertia, and
its angular momentum. This is done using the properties of the
constituent atoms of the body at that point in time (or see the *infile*
keyword option). Thereafter, changing these properties of individual
atoms in the body will have no effect on a rigid body's dynamics, unless
they effect any computation of per-atom forces or torques. If the
keyword *reinit* is set to *yes* (the default), the rigid body data
structures will be recreated at the beginning of each *run* command;
if the keyword *reinit* is set to *no*, the rigid body data structures
will be built only at the very first *run* command and maintained for
as long as the rigid fix is defined. For example, you might think you
could displace the atoms in a body or add a large velocity to each atom
in a body to make it move in a desired direction before a second run is
performed, using the :doc:`set <set>` or
:doc:`displace_atoms <displace_atoms>` or :doc:`velocity <velocity>`
commands. But these commands will not affect the internal attributes
of the body unless *reinit* is set to *yes*\ . With *reinit* set to *no*
(or using the *infile* option, which implies *reinit* *no*\ ) the position
and velocity of individual atoms in the body will be reset when time
integration starts again.
The aggregate properties of each rigid body are calculated at the
start of a simulation run and are maintained in internal data
structures. The properties include the position and velocity of the
center-of-mass of the body, its moments of inertia, and its angular
momentum. This is done using the properties of the constituent
atoms of the body at that point in time (or see the *infile*
keyword option). Thereafter, changing these properties of
individual atoms in the body will have no effect on a rigid body's
dynamics, unless they effect any computation of per-atom forces or
torques. If the keyword *reinit* is set to *yes* (the default), the
rigid body data structures will be recreated at the beginning of
each *run* command; if the keyword *reinit* is set to *no*, the
rigid body data structures will be built only at the very first
*run* command and maintained for as long as the rigid fix is
defined. For example, you might think you could displace the atoms
in a body or add a large velocity to each atom in a body to make it
move in a desired direction before a second run is performed, using
the :doc:`set <set>` or :doc:`displace_atoms <displace_atoms>` or
:doc:`velocity <velocity>` commands. But these commands will not
affect the internal attributes of the body unless *reinit* is set
to *yes*\ . With *reinit* set to *no* (or using the *infile*
option, which implies *reinit* *no*\ ) the position and velocity of
individual atoms in the body will be reset when time integration
starts again.
----------
@ -314,17 +321,17 @@ to be part of rigid bodies.
.. note::
To compute the initial center-of-mass position and other
properties of each rigid body, the image flags for each atom in the
body are used to "unwrap" the atom coordinates. Thus you must ensure
that these image flags are consistent so that the unwrapping creates a
To compute the initial center-of-mass position and other properties
of each rigid body, the image flags for each atom in the body are
used to "unwrap" the atom coordinates. Thus you must ensure that
these image flags are consistent so that the unwrapping creates a
valid rigid body (one where the atoms are close together),
particularly if the atoms in a single rigid body straddle a periodic
boundary. This means the input data file or restart file must define
the image flags for each atom consistently or that you have used the
:doc:`set <set>` command to specify them correctly. If a dimension is
non-periodic then the image flag of each atom must be 0 in that
dimension, else an error is generated.
particularly if the atoms in a single rigid body straddle a
periodic boundary. This means the input data file or restart file
must define the image flags for each atom consistently or that you
have used the :doc:`set <set>` command to specify them correctly.
If a dimension is non-periodic then the image flag of each atom
must be 0 in that dimension, else an error is generated.
The *force* and *torque* keywords discussed next are only allowed for
the *rigid* styles.
@ -360,12 +367,13 @@ settings from the final keyword are used.
.. note::
For computational efficiency, you may wish to turn off pairwise
and bond interactions within each rigid body, as they no longer
contribute to the motion. The :doc:`neigh_modify exclude <neigh_modify>` and :doc:`delete_bonds <delete_bonds>`
commands are used to do this. If the rigid bodies have strongly
overlapping atoms, you may need to turn off these interactions to
avoid numerical problems due to large equal/opposite intra-body forces
For computational efficiency, you may wish to turn off pairwise and
bond interactions within each rigid body, as they no longer
contribute to the motion. The :doc:`neigh_modify exclude
<neigh_modify>` and :doc:`delete_bonds <delete_bonds>` commands are
used to do this. If the rigid bodies have strongly overlapping
atoms, you may need to turn off these interactions to avoid
numerical problems due to large equal/opposite intra-body forces
swamping the contribution of small inter-body forces.
For computational efficiency, you should typically define one fix
@ -377,7 +385,8 @@ is more expensive.
The constituent particles within a rigid body can be point particles
(the default in LAMMPS) or finite-size particles, such as spheres or
ellipsoids or line segments or triangles. See the :doc:`atom_style sphere and ellipsoid and line and tri <atom_style>` commands for more
ellipsoids or line segments or triangles. See the :doc:`atom_style
sphere and ellipsoid and line and tri <atom_style>` commands for more
details on these kinds of particles. Finite-size particles contribute
differently to the moment of inertia of a rigid body than do point
particles. Finite-size particles can also experience torque (e.g. due
@ -387,7 +396,8 @@ orientation. These contributions are accounted for by these fixes.
Forces between particles within a body do not contribute to the
external force or torque on the body. Thus for computational
efficiency, you may wish to turn off pairwise and bond interactions
between particles within each rigid body. The :doc:`neigh_modify exclude <neigh_modify>` and :doc:`delete_bonds <delete_bonds>`
between particles within each rigid body. The :doc:`neigh_modify
exclude <neigh_modify>` and :doc:`delete_bonds <delete_bonds>`
commands are used to do this. For finite-size particles this also
means the particles can be highly overlapped when creating the rigid
body.
@ -399,16 +409,17 @@ perform constant NVE time integration. They are referred to below as
the 4 NVE rigid styles. The only difference is that the *rigid* and
*rigid/small* styles use an integration technique based on Richardson
iterations. The *rigid/nve* and *rigid/small/nve* styles uses the
methods described in the paper by :ref:`Miller <Miller3>`, which are thought
to provide better energy conservation than an iterative approach.
methods described in the paper by :ref:`Miller <Miller3>`, which are
thought to provide better energy conservation than an iterative
approach.
The *rigid/nvt* and *rigid/nvt/small* styles performs constant NVT
integration using a Nose/Hoover thermostat with chains as described
originally in :ref:`(Hoover) <Hoover>` and :ref:`(Martyna) <Martyna2>`, which
thermostats both the translational and rotational degrees of freedom
of the rigid bodies. They are referred to below as the 2 NVT rigid
styles. The rigid-body algorithm used by *rigid/nvt* is described in
the paper by :ref:`Kamberaj <Kamberaj>`.
originally in :ref:`(Hoover) <Hoover>` and :ref:`(Martyna)
<Martyna2>`, which thermostats both the translational and rotational
degrees of freedom of the rigid bodies. They are referred to below as
the 2 NVT rigid styles. The rigid-body algorithm used by *rigid/nvt*
is described in the paper by :ref:`Kamberaj <Kamberaj>`.
The *rigid/npt*, *rigid/nph*, *rigid/npt/small*, and *rigid/nph/small*
styles perform constant NPT or NPH integration using a Nose/Hoover
@ -434,12 +445,12 @@ The target pressures for each of the 6 components of the stress tensor
can be specified independently via the *x*, *y*, *z* keywords, which
correspond to the 3 simulation box dimensions. For each component,
the external pressure or tensor component at each timestep is a ramped
value during the run from *Pstart* to *Pstop*\ . If a target pressure is
specified for a component, then the corresponding box dimension will
change during a simulation. For example, if the *y* keyword is used,
the y-box length will change. A box dimension will not change if that
component is not specified, although you have the option to change
that dimension via the :doc:`fix deform <fix_deform>` command.
value during the run from *Pstart* to *Pstop*\ . If a target pressure
is specified for a component, then the corresponding box dimension
will change during a simulation. For example, if the *y* keyword is
used, the y-box length will change. A box dimension will not change
if that component is not specified, although you have the option to
change that dimension via the :doc:`fix deform <fix_deform>` command.
For all barostat keywords, the *Pdamp* parameter operates like the
*Tdamp* parameter, determining the time scale on which pressure is
@ -523,11 +534,11 @@ discussed below.
The *langevin* keyword applies a Langevin thermostat to the constant
NVE time integration performed by any of the 4 NVE rigid styles:
*rigid*, *rigid/nve*, *rigid/small*, *rigid/small/nve*\ . It cannot be
used with the 2 NVT rigid styles: *rigid/nvt*, *rigid/small/nvt*\ . The
desired temperature at each timestep is a ramped value during the run
from *Tstart* to *Tstop*\ . The *Tdamp* parameter is specified in time
units and determines how rapidly the temperature is relaxed. For
*rigid*, *rigid/nve*, *rigid/small*, *rigid/small/nve*\ . It cannot
be used with the 2 NVT rigid styles: *rigid/nvt*, *rigid/small/nvt*\ .
The desired temperature at each timestep is a ramped value during the
run from *Tstart* to *Tstop*\ . The *Tdamp* parameter is specified in
time units and determines how rapidly the temperature is relaxed. For
example, a value of 100.0 means to relax the temperature in a timespan
of (roughly) 100 time units (:math:`\tau` or fs or ps - see the
:doc:`units <units>` command). The random # *seed* must be a positive
@ -562,29 +573,30 @@ used. *Tchain* is the number of thermostats in the Nose Hoover chain.
This value, along with *Tdamp* can be varied to dampen undesirable
oscillations in temperature that can occur in a simulation. As a rule
of thumb, increasing the chain length should lead to smaller
oscillations. The keyword *pchain* specifies the number of
thermostats in the chain thermostatting the barostat degrees of
freedom.
oscillations. The keyword *pchain* specifies the number of thermostats
in the chain thermostatting the barostat degrees of freedom.
.. note::
There are alternate ways to thermostat a system of rigid bodies.
You can use :doc:`fix langevin <fix_langevin>` to treat the individual
particles in the rigid bodies as effectively immersed in an implicit
solvent, e.g. a Brownian dynamics model. For hybrid systems with both
rigid bodies and solvent particles, you can thermostat only the
solvent particles that surround one or more rigid bodies by
appropriate choice of groups in the compute and fix commands for
temperature and thermostatting. The solvent interactions with the
rigid bodies should then effectively thermostat the rigid body
temperature as well without use of the Langevin or Nose/Hoover options
associated with the fix rigid commands.
You can use :doc:`fix langevin <fix_langevin>` to treat the
individual particles in the rigid bodies as effectively immersed in
an implicit solvent, e.g. a Brownian dynamics model. For hybrid
systems with both rigid bodies and solvent particles, you can
thermostat only the solvent particles that surround one or more
rigid bodies by appropriate choice of groups in the compute and fix
commands for temperature and thermostatting. The solvent
interactions with the rigid bodies should then effectively
thermostat the rigid body temperature as well without use of the
Langevin or Nose/Hoover options associated with the fix rigid
commands.
----------
The *mol* keyword can only be used with the *rigid/small* styles. It
must be used when other commands, such as :doc:`fix deposit <fix_deposit>` or :doc:`fix pour <fix_pour>`, add rigid
bodies on-the-fly during a simulation. You specify a *template-ID*
must be used when other commands, such as :doc:`fix deposit
<fix_deposit>` or :doc:`fix pour <fix_pour>`, add rigid bodies
on-the-fly during a simulation. You specify a *template-ID*
previously defined using the :doc:`molecule <molecule>` command, which
reads a file that defines the molecule. You must use the same
*template-ID* that the other fix which is adding rigid bodies uses.
@ -668,16 +680,16 @@ cross periodic boundaries during the simulation.
.. note::
If you use the *infile* or *mol* keywords and write restart
files during a simulation, then each time a restart file is written,
the fix also write an auxiliary restart file with the name
rfile.rigid, where "rfile" is the name of the restart file,
If you use the *infile* or *mol* keywords and write restart files
during a simulation, then each time a restart file is written, the
fix also write an auxiliary restart file with the name rfile.rigid,
where "rfile" is the name of the restart file,
e.g. tmp.restart.10000 and tmp.restart.10000.rigid. This auxiliary
file is in the same format described above. Thus it can be used in a
new input script that restarts the run and re-specifies a rigid fix
using an *infile* keyword and the appropriate filename. Note that the
auxiliary file will contain one line for every rigid body, even if the
original file only listed a subset of the rigid bodies.
file is in the same format described above. Thus it can be used in
a new input script that restarts the run and re-specifies a rigid
fix using an *infile* keyword and the appropriate filename. Note
that the auxiliary file will contain one line for every rigid body,
even if the original file only listed a subset of the rigid bodies.
If the system has rigid bodies with finite-size overlapping particles
and the model uses the :doc:`fix gravity <fix_gravity>` command to
@ -726,10 +738,11 @@ also accounted for by this fix.
----------
If your simulation is a hybrid model with a mixture of rigid bodies and
non-rigid particles (e.g. solvent) there are several ways these rigid
fixes can be used in tandem with :doc:`fix nve <fix_nve>`, :doc:`fix nvt
<fix_nh>`, :doc:`fix npt <fix_nh>`, and :doc:`fix nph <fix_nh>`.
If your simulation is a hybrid model with a mixture of rigid bodies
and non-rigid particles (e.g. solvent) there are several ways these
rigid fixes can be used in tandem with :doc:`fix nve <fix_nve>`,
:doc:`fix nvt <fix_nh>`, :doc:`fix npt <fix_nh>`, and :doc:`fix nph
<fix_nh>`.
If you wish to perform NVE dynamics (no thermostatting or
barostatting), use one of 4 NVE rigid styles to integrate the rigid
@ -739,14 +752,14 @@ particles.
If you wish to perform NVT dynamics (thermostatting, but no
barostatting), you can use one of the 2 NVT rigid styles for the rigid
bodies, and any thermostatting fix for the non-rigid particles
(:doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`, :doc:`fix
temp/berendsen <fix_temp_berendsen>`). You can also use one of the 4
NVE rigid styles for the rigid bodies and thermostat them using
:doc:`fix langevin <fix_langevin>` on the group that contains all the
particles in the rigid bodies. The net force added by :doc:`fix
langevin <fix_langevin>` to each rigid body effectively thermostats its
translational center-of-mass motion. Not sure how well it does at
thermostatting its rotational motion.
(:doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`,
:doc:`fix temp/berendsen <fix_temp_berendsen>`). You can also use one
of the 4 NVE rigid styles for the rigid bodies and thermostat them
using :doc:`fix langevin <fix_langevin>` on the group that contains
all the particles in the rigid bodies. The net force added by
:doc:`fix langevin <fix_langevin>` to each rigid body effectively
thermostats its translational center-of-mass motion. Not sure how
well it does at thermostatting its rotational motion.
If you wish to perform NPT or NPH dynamics (barostatting), you cannot
use both :doc:`fix npt <fix_nh>` and the NPT or NPH rigid styles. This
@ -772,12 +785,12 @@ to the global pressure and the box is scaled the same by any of the
barostatting fixes.
You could even use the second and third options for a non-hybrid
simulation consisting of only rigid bodies, assuming you give :doc:`fix
npt <fix_nh>` an empty group, though it's an odd thing to do. The
barostatting fixes (:doc:`fix npt <fix_nh>` and :doc:`fix press/berensen
<fix_press_berendsen>`) will monitor the pressure and change the box
dimensions, but not time integrate any particles. The integration of
the rigid bodies will be performed by fix rigid/nvt.
simulation consisting of only rigid bodies, assuming you give
:doc:`fix npt <fix_nh>` an empty group, though it's an odd thing to
do. The barostatting fixes (:doc:`fix npt <fix_nh>` and :doc:`fix
press/berensen <fix_press_berendsen>`) will monitor the pressure and
change the box dimensions, but not time integrate any particles. The
integration of the rigid bodies will be performed by fix rigid/nvt.
----------
@ -822,10 +835,10 @@ various :doc:`output commands <Howto_output>`. The scalar value
calculated by these fixes is "intensive". The scalar is the current
temperature of the collection of rigid bodies. This is averaged over
all rigid bodies and their translational and rotational degrees of
freedom. The translational energy of a rigid body is 1/2 m v\^2, where
m = total mass of the body and v = the velocity of its center of mass.
The rotational energy of a rigid body is 1/2 I w\^2, where I = the
moment of inertia tensor of the body and w = its angular velocity.
freedom. The translational energy of a rigid body is 1/2 m v\^2,
where m = total mass of the body and v = the velocity of its center of
mass. The rotational energy of a rigid body is 1/2 I w\^2, where I =
the moment of inertia tensor of the body and w = its angular velocity.
Degrees of freedom constrained by the *force* and *torque* keywords
are removed from this calculation, but only for the *rigid* and
*rigid/nve* fixes.

202
doc/src/read_data.rst
View File

@ -63,11 +63,16 @@ Description
Read in a data file containing information LAMMPS needs to run a
simulation. The file can be ASCII text or a gzipped text file
(detected by a .gz suffix). This is one of 3 ways to specify initial
atom coordinates; see the :doc:`read_restart <read_restart>` and
:doc:`create_atoms <create_atoms>` commands for alternative methods.
Also see the explanation of the :doc:`-restart command-line switch
<Run_options>` which can convert a restart file to a data file.
(detected by a .gz suffix).
This is one of 3 ways to specify the simulation box: see the
:doc:`create_box <create_box>` and :doc:`read_restart <read_restart>`
and commands for alternative methods. It is also one of 3 ways to
specify initial atom coordinates: see the :doc:`create_atoms
<create_atoms>` and :doc:`read_restart <read_restart>` and commands
for alternative methods. Also see the explanation of the
:doc:`-restart command-line switch <Run_options>` which can convert a
restart file to a data file.
This command can be used multiple times to add new atoms and their
properties to an existing system by using the *add*, *offset*, and
@ -133,6 +138,17 @@ keyword must be used.
will separate the atoms in the bond, which can lead to "lost" bond
atoms or bad dynamics.
.. note::
If the first read_data command defined a restricted or general
triclinic simulation box (see the sub-section below on header
keywords), then subsequent data files have restrictions. For a
restricted triclinic box, the 3 tilt factors ("xy xz yz" keyword)
must have the same values in subsequent data files. For a general
triclinic box, the avec, bvec, cvec, and "abc origin" keywords must
have the same values in subsequent data files. Also the *shift*
keyword cannot be used in subsequent read_data commands.
The three choices for the *add* argument affect how the atom IDs and
molecule IDs of atoms in the data file are treated. If *append* is
specified, atoms in the data file are added to the current system,
@ -372,8 +388,8 @@ For a restricted triclinic box, the *xy xz yz* keyword is used in
addition to the *xlo xhi*, *ylo yhi*, *zlo zhi* keywords. The three
*xy,xz,yz* values can be 0.0 or positive or negative, and are called
"tilt factors" because they are the amount of displacement applied to
faces of an orthogonal box to transform it into a restricted triclinic
parallelepiped.
edges of faces of an orthogonal box to transform it into a restricted
triclinic parallelepiped.
The :doc:`Howto_triclinic <Howto_triclinic>` doc page discusses the
tilt factors in detail and explains that the resulting edge vectors of
@ -383,11 +399,11 @@ a restricted triclinic box are:
* **B** = (xy,yhi-ylo,0)
* **C** = (xz,yz,zhi-zlo)
This restricted form of edge vectors means that **A** is along the
x-axis, **B** is in the xy plane with a y-component in the +y
direction, and **C** has a z-component in the +z direction. The
origin (lower left corner) of the restricted triclinic box is at
(xlo,ylo,zlo).
This restricted form of edge vectors requires that **A** be in the
direction of the x-axis, **B** be in the xy plane with its y-component
in the +y direction, and **C** have its z-component in the +z
direction. The origin (lower left corner) of the restricted triclinic
box is at (xlo,ylo,zlo).
For a 2d simulation, the zlo and zhi values must straddle zero. The
default zlo/zhi values do this, so that keyword is not needed in 2d.
@ -433,16 +449,19 @@ origin* keywords are used. The *xlo xhi*, *ylo yhi*, *zlo zhi*, and
*xy xz yz* keywords are not used. The first 3 keywords define the 3
edge vectors **A**, **B**, **C** of a general triclinic box. They can
be arbitrary vectors so long as they are distinct, non-zero, and not
co-planar. There is no "right-hand rule" requirement that (**A** x
**B**) point in the direction of **C**. The origin of the box (origin
of the 3 edge vectors) is set by the *abc origin* keyword.
co-planar. They must also define a right-handed system requirement
such that (**A** x **B**) points in the direction of **C**. A
left-handed system can be converted to a right-handed system by simply
swapping the order of any pair of the **A**, **B**, **C** vectors.
The origin of the box (origin of the 3 edge vectors) is set by the
*abc origin* keyword.
The default values for these 4 keywords are as follows:
* avec = (1,0,0)
* bvec = (0,1,0)
* cvec = (0,0,1)
* *abc origin = (0,0,0) for 3d, (0,0,-0.5) for 2d
* abc origin = (0,0,0) for 3d, (0,0,-0.5) for 2d
For 2d simulations, *cvec* = (0,0,1) is required, and the 3rd value of
*abc origin* must be -0.5. These are the default values, so the
@ -452,18 +471,18 @@ For 2d simulations, *cvec* = (0,0,1) is required, and the 3rd value of
LAMMPS allows specification of general triclinic simulation boxes
as a convenience for users who may be converting data from
solid-state crystallograhic representations or ftom DFT codes for
solid-state crystallograhic representations or from DFT codes for
input to LAMMPS. However, as explained on the
:doc:`Howto_triclinic <Howto_triclinic>` doc page, internally
:doc:`Howto_triclinic <Howto_triclinic>` doc page, internally,
LAMMPS only uses restricted triclinic simulation boxes. This means
the box and per-atom information (e.g. coordinates, velocities) in
the data file are converted from general to restricted triclinic
form as soon as the file is read. This means other sections of the
data file must specify their per-atom data appropriately. This
requirement is explained below for the relevant sections. The
:doc:`Howto_triclinic <Howto_triclinic>` doc page also discusses
other LAMMPS commands which can input/output general triclinic
representations of the simulation box and per-atom data.
form when the file is read. Other sections of the data file must
also list their per-atom data appropriately if vector quantities
are specified. This requirement is explained below for the relevant
sections. The :doc:`Howto_triclinic <Howto_triclinic>` doc page
also discusses other LAMMPS commands which can input/output general
triclinic representations of the simulation box and per-atom data.
The following explanations apply to all 3 kinds of simulation boxes:
orthogonal, restricted triclinic, and general triclinic.
@ -509,24 +528,25 @@ needed, so that the image flag would be zero.
.. note::
If the system is non-periodic (in a dimension), then all atoms in the
data file must have coordinates (in that dimension) that are "greater
than or equal to" the lo value and "less than or equal to" the hi
value. If the non-periodic dimension is of style "fixed" (see the
:doc:`boundary <boundary>` command), then the atom coords must be
strictly "less than" the hi value, due to the way LAMMPS assign atoms
to processors. Note that you should not make the lo/hi values
radically smaller/larger than the extent of the atoms. For example,
if your atoms extend from 0 to 50, you should not specify the box
bounds as -10000 and 10000 unless you also use the :doc:`processors
command <processors>`. This is because LAMMPS uses the specified box
size to layout the 3d grid of processors. A huge (mostly empty) box
will be sub-optimal for performance when using "fixed" boundary
conditions (see the :doc:`boundary <boundary>` command). When using
"shrink-wrap" boundary conditions (see the :doc:`boundary <boundary>`
command), a huge (mostly empty) box may cause a parallel simulation
to lose atoms when LAMMPS shrink-wraps the box around the atoms. The
read_data command will generate an error in this case.
If the system is non-periodic (in a dimension), then all atoms in
the data file must have coordinates (in that dimension) that are
"greater than or equal to" the lo value and "less than or equal to"
the hi value. If the non-periodic dimension is of style "fixed"
(see the :doc:`boundary <boundary>` command), then the atom coords
must be strictly "less than" the hi value, due to the way LAMMPS
assign atoms to processors. Note that you should not make the
lo/hi values radically smaller/larger than the extent of the atoms.
For example, if atoms extend from 0 to 50, you should not specify
the box bounds as -10000 and 10000 unless you also use the
:doc:`processors command <processors>`. This is because LAMMPS
uses the specified box size to layout the 3d grid of processors. A
huge (mostly empty) box will be sub-optimal for performance when
using "fixed" boundary conditions (see the :doc:`boundary
<boundary>` command). When using "shrink-wrap" boundary conditions
(see the :doc:`boundary <boundary>` command), a huge (mostly empty)
box may cause a parallel simulation to lose atoms when LAMMPS
shrink-wraps the box around the atoms. The read_data command will
generate an error in this case.
----------
@ -557,12 +577,12 @@ and :doc:`molecule <molecule>` doc pages for more discussion of
.. note::
All of the "extra" settings are only applied in the first data
file read and when no simulation box has yet been created; as soon as
All of the "extra" settings are only applied in the first data file
read and when no simulation box has yet been created; as soon as
the simulation box is created (and read_data implies that), these
settings are *locked* and cannot be changed anymore. Please see the
description of the *add* keyword above for reading multiple data files.
If they appear in later data files, they are ignored.
description of the *add* keyword above for reading multiple data
files. If they appear in later data files, they are ignored.
The "ellipsoids" and "lines" and "triangles" and "bodies" settings are
only used with :doc:`atom_style ellipsoid or line or tri or body
@ -575,14 +595,14 @@ below. See the discussion of bodyflag and the *Bodies* section below.
.. note::
For :doc:`atom_style template <atom_style>`, the molecular
topology (bonds,angles,etc) is contained in the molecule templates
read-in by the :doc:`molecule <molecule>` command. This means you
cannot set the *bonds*, *angles*, etc header keywords in the data
file, nor can you define *Bonds*, *Angles*, etc sections as discussed
For :doc:`atom_style template <atom_style>`, the molecular topology
(bonds,angles,etc) is contained in the molecule templates read-in
by the :doc:`molecule <molecule>` command. This means you cannot
set the *bonds*, *angles*, etc header keywords in the data file,
nor can you define *Bonds*, *Angles*, etc sections as discussed
below. You can set the *bond types*, *angle types*, etc header
keywords, though it is not necessary. If specified, they must match
the maximum values defined in any of the template molecules.
keywords, though it is not necessary. If specified, they must
match the maximum values defined in any of the template molecules.
----------
@ -780,13 +800,13 @@ of analysis.
For orthogonal and restricted and general triclinic simulation
boxes, the atom coordinates (x,y,z) listed in this section should
be inside the corresponding simulation box. For restricted
triclinic boxes that means the parallelepiped defined by the by the
*xlo xhi*, *ylo yhi*, *zlo zhi*, and *xy xz yz*, keywords. For
general triclinic boxes that means the parallelepiped defined by
the 3 edge vectors and origin specified by the *avec*, *bvec*,
*cvec*, and *abc origin* header keywords. See the discussion in
the header section above about how atom coordinates outside the
simulation box are (or are not) remapped to be inside the box.
triclinic boxes that means the parallelepiped defined by the *xlo
xhi*, *ylo yhi*, *zlo zhi*, and *xy xz yz*, keywords. For general
triclinic boxes that means the parallelepiped defined by the 3 edge
vectors and origin specified by the *avec*, *bvec*, *cvec*, and
*abc origin* header keywords. See the discussion in the header
section above about how atom coordinates outside the simulation box
are (or are not) remapped to be inside the box.
.. list-table::
@ -865,13 +885,13 @@ The per-atom values have these meanings and units, listed alphabetically:
* lineflag = 1 for line segment particles, 0 for point or spherical particles
* mass = mass of particle (mass units)
* molecule-ID = integer ID of molecule the atom belongs to
* mux,muy,muz = components of dipole moment of atom (dipole units) (see general triclinic comment below)
* mux,muy,muz = components of dipole moment of atom (dipole units) (see general triclinic note below)
* normx,normy,normz = components of dielectric dipole moment of atom (dipole
units) (see general triclinic comment below)
units) (see general triclinic note below)
* q = charge on atom (charge units)
* rho = density (need units) for SPH particles
* sp = magnitude of magnetic spin of atom (Bohr magnetons)
* spx,spy,spz = components of magnetic spin of atom (unit vector) (see general triclinic comment below)
* spx,spy,spz = components of magnetic spin of atom (unit vector) (see general triclinic note below)
* template-atom = which atom within a template molecule the atom is
* template-index = which molecule within the molecule template the atom is part of
* theta = internal temperature of a DPD particle
@ -879,29 +899,31 @@ The per-atom values have these meanings and units, listed alphabetically:
* volume = volume of Peridynamic particle (distance\^3 units)
* x,y,z = coordinates of atom (distance units)
* x0,y0,z0 = original (strain-free) coordinates of atom (distance
units) (see general triclinic comment below)
units) (see general triclinic note below)
The units for these quantities depend on the unit style; see the
:doc:`units <units>` command for details.
For 2d simulations, z must be specified as 0.0. If the data file is
created by another program, then z values for a 2d simulation can be
within epsilon of 0.0, and LAMMPS will force them to zero.
For 2d simulations, the atom coordinate z must be specified as 0.0.
If the data file is created by another program, then z values for a 2d
simulation can be within epsilon of 0.0, and LAMMPS will force them to
zero.
If the data file defines a general triclinic box, then the following
per-atom values in the list above are per-atom vectors: (mux,muy,muz),
(normx,normy,normz), (spx,spy,spz). They should be specified with
values for the rotated coordinate axes of the general triclinic box.
Likewise, (x0,y0,z0) are per-atom coordinates and should be values
inside the general triclinic box, the same as explained for (x,y,z)
above. See the :doc:`Howto triclinic <Howto_triclininc>` doc page for
more details.
.. note::
If the data file defines a general triclinic box, then each of the 3
vectors (translational velocity, angular momentum, angule velocity)
sholld be specified for the rotated coordinate axes of the general
triclinic box. See the :doc:`Howto triclinic <Howto_triclininc>` doc
page for more details.
If the data file defines a general triclinic box, then the
following per-atom values in the list above are per-atom vectors
which imply an orientation: (mux,muy,muz), (normx,normy,normz),
(spx,spy,spz). This menas they should be specified consistent with
the general triclinic box and its orientation relative to the
standard x,y,z coordinate axes. For example a dipole moment vector
which will be in the +x direction once LAMMPS converts from a
general to restricted triclinic box, should be specified in the
data file in the direction of the **A** edge vector. Likewise the
(x0,y0,z0) per-atom strain-free coordinates should be inside the
general triclinic simulation box as explained in the note above.
See the :doc:`Howto triclinic <Howto_triclininc>` doc page for more
details.
The atom-ID is used to identify the atom throughout the simulation and
in dump files. Normally, it is a unique value from 1 to Natoms for
@ -1049,9 +1071,8 @@ that use unwrapped coordinates internally are as follows:
Atom velocities and other atom quantities not defined above are set to
0.0 when the *Atoms* section is read. Velocities can be set later by
a *Velocities* section in the data file or by a
:doc:`velocity <velocity>` or :doc:`set <set>` command in the input
script.
a *Velocities* section in the data file or by a :doc:`velocity
<velocity>` or :doc:`set <set>` command in the input script.
----------
@ -1329,11 +1350,10 @@ LAMMPS normalizes each atom's quaternion in case (a,b,c) is not
specified as a unit vector.
If the data file defines a general triclinic box, then the quaternion
for each ellipsoid should be specified for its orientation in the
general triclinic system with respect to the standard xyz axes (not
the rotated coordinate axes of the general triclinic system). When
the general triclinic box is transformed to a restricted triclinic
box, the ellipsoid quaternions will be altered appropriately.
for each ellipsoid should be specified for its orientation relative to
the standard x,y,z coordinate axes. When the system is converted to a
restricted triclinic box, the ellipsoid quaternions will be altered
appropriately.
The *Ellipsoids* section must appear after the *Atoms* section.
@ -1458,6 +1478,12 @@ the line segment with a unit vector in the +z direction, gives an
I.e. normal = (c2-c1) x (0,0,1). This orientation may be important
for defining some interactions.
If the data file defines a general triclinic box, then the quaternion
for each ellipsoid should be specified for its orientation relative to
the standard x,y,z coordinate axes. When the system is converted to a
restricted triclinic box, the ellipsoid quaternions will be altered
appropriately.
If the data file defines a general triclinic box, the (x1,y1) and
(x2,y2) values should be within (or near) its parallelogram area,
i.e. near the x,y coordinates of the line segment as defined in the