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 (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 as they are non-zero, distinct, and not co-planar. In addition, they
must define a right-handed system, such that (**A** cross **B**) must define a right-handed system, such that (**A** cross **B**)
points in the direction of **C**. Note that a left-handed system can points in the direction of **C**. A left-handed system can be
be converted to a right-handed system by simply swapping the order of converted to a right-handed system by simply swapping the order of any
any two of the **A**, **B**, **C** vectors. pair of the **A**, **B**, **C** vectors.
The 4 commands listed above for defining orthogonal simulation boxes The 4 commands listed above for defining orthogonal simulation boxes
have triclinic options which allow for specification of the origin and 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 should be inside the general triclinic simulation box defined by the
edge vectors **A**, **B**, **C** and its origin. Likewise per-atom edge vectors **A**, **B**, **C** and its origin. Likewise per-atom
velocities should be in directions consistent with the general 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 the +x direction once LAMMPS converts from a general to restricted
triclinic box, should be specified in the data file in the direction 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 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 page for info on all the per-atom vector quantities to which this
affects when the data file for a general triclinic box is input. 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 * If commands such as :doc:`write_data <write_data>` or :doc:`dump
custom <dump>` are used to output general triclinic information, it custom <dump>` are used to output general triclinic information, it
is effectively the inverse of the operation described in the 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 you can use the :doc:`change_box <change_box>` command to convert a
simulation box from orthogonal to restricted triclinic and vice versa. simulation box from orthogonal to restricted triclinic and vice versa.
Highly tilted restricted triclinic simulation boxes can be .. note::
computationally inefficient. This is due to the large volume of
communication needed to acquire ghost atoms around a processor's Highly tilted restricted triclinic simulation boxes can be
irregular-shaped subdomain. For extreme values of tilt, LAMMPS may computationally inefficient. This is due to the large volume of
also lose atoms and generate an error. 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 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 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 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 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. 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. either of the commands.
One exception to box flipping is if the first dimension in the tilt 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 factor (e.g. x for xy) is non-periodic. In that case, the limits on
tilt factor are not enforced, since flipping the box in that dimension the tilt factor are not enforced, since flipping the box in that
would not change the atom positions due to non-periodicity. In this dimension would not change the atom positions due to non-periodicity.
mode, if the system tilts to large angles, the simulation will simply In this mode, if the system tilts to large angles, the simulation will
become inefficient, due to the highly skewed simulation box. 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. of a biomolecule such as a protein.
Example of small rigid bodies are patchy nanoparticles, such as those Example of small rigid bodies are patchy nanoparticles, such as those
modeled in :ref:`this paper <Zhang1>` by Sharon Glotzer's group, clumps of modeled in :ref:`this paper <Zhang1>` by Sharon Glotzer's group,
granular particles, lipid molecules consisting of one or more point clumps of granular particles, lipid molecules consisting of one or
dipoles connected to other spheroids or ellipsoids, irregular more point dipoles connected to other spheroids or ellipsoids,
particles built from line segments (2d) or triangles (3d), and irregular particles built from line segments (2d) or triangles (3d),
coarse-grain models of nano or colloidal particles consisting of a 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 small number of constituent particles. Note that the :doc:`fix shake
molecules of 2, 3, or 4 atoms, e.g. water molecules. That fix treats <fix_shake>` command can also be used to rigidify small molecules of
the constituent atoms as point masses. 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 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 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:: .. note::
To use the *rigid/small* styles the ghost atom cutoff must be To use the *rigid/small* styles the ghost atom cutoff must be large
large enough to span the distance between the atom that owns the body enough to span the distance between the atom that owns the body and
and every other atom in the body. This distance value is printed out every other atom in the body. This distance value is printed out
when the rigid bodies are defined. If the when the rigid bodies are defined. If the :doc:`pair_style
:doc:`pair_style <pair_style>` cutoff plus neighbor skin does not span <pair_style>` cutoff plus neighbor skin does not span this
this distance, then you should use the :doc:`comm_modify cutoff <comm_modify>` command with a setting epsilon larger than distance, then you should use the :doc:`comm_modify cutoff
the distance. <comm_modify>` command with a setting epsilon larger than the
distance.
Which of the two variants is faster for a particular problem is hard 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. 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:: .. note::
You should not update the atoms in rigid bodies via other 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>`), time-integration fixes (e.g. :doc:`fix nve <fix_nve>`, :doc:`fix
or you will have conflicting updates to positions and velocities nvt <fix_nh>`, :doc:`fix npt <fix_nh>`, :doc:`fix move
resulting in unphysical behavior in most cases. When performing a hybrid <fix_move>`), or you will have conflicting updates to positions and
simulation with some atoms in rigid bodies, and some not, a separate velocities resulting in unphysical behavior in most cases. When
time integration fix like :doc:`fix nve <fix_nve>` or :doc:`fix nvt <fix_nh>` should be used for the non-rigid particles. 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:: .. note::
These fixes are overkill if you simply want to hold a collection These fixes are overkill if you simply want to hold a collection of
of atoms stationary or have them move with a constant velocity. A atoms stationary or have them move with a constant velocity. A
simpler way to hold atoms stationary is to not include those atoms in simpler way to hold atoms stationary is to not include those atoms
your time integration fix. E.g. use "fix 1 mobile nve" instead of in your time integration fix. E.g. use "fix 1 mobile nve" instead
"fix 1 all nve", where "mobile" is the group of atoms that you want to of "fix 1 all nve", where "mobile" is the group of atoms that you
move. You can move atoms with a constant velocity by assigning them want to move. You can move atoms with a constant velocity by
an initial velocity (via the :doc:`velocity <velocity>` command), assigning them an initial velocity (via the :doc:`velocity
setting the force on them to 0.0 (via the :doc:`fix setforce <fix_setforce>` command), and integrating them as usual <velocity>` command), setting the force on them to 0.0 (via the
(e.g. via the :doc:`fix nve <fix_nve>` command). :doc:`fix setforce <fix_setforce>` command), and integrating them
as usual (e.g. via the :doc:`fix nve <fix_nve>` command).
.. warning:: .. warning::
The aggregate properties of each rigid body are The aggregate properties of each rigid body are calculated at the
calculated at the start of a simulation run and are maintained in start of a simulation run and are maintained in internal data
internal data structures. The properties include the position and structures. The properties include the position and velocity of the
velocity of the center-of-mass of the body, its moments of inertia, and center-of-mass of the body, its moments of inertia, and its angular
its angular momentum. This is done using the properties of the momentum. This is done using the properties of the constituent
constituent atoms of the body at that point in time (or see the *infile* atoms of the body at that point in time (or see the *infile*
keyword option). Thereafter, changing these properties of individual keyword option). Thereafter, changing these properties of
atoms in the body will have no effect on a rigid body's dynamics, unless individual atoms in the body will have no effect on a rigid body's
they effect any computation of per-atom forces or torques. If the dynamics, unless they effect any computation of per-atom forces or
keyword *reinit* is set to *yes* (the default), the rigid body data torques. If the keyword *reinit* is set to *yes* (the default), the
structures will be recreated at the beginning of each *run* command; rigid body data structures will be recreated at the beginning of
if the keyword *reinit* is set to *no*, the rigid body data structures each *run* command; if the keyword *reinit* is set to *no*, the
will be built only at the very first *run* command and maintained for rigid body data structures will be built only at the very first
as long as the rigid fix is defined. For example, you might think you *run* command and maintained for as long as the rigid fix is
could displace the atoms in a body or add a large velocity to each atom defined. For example, you might think you could displace the atoms
in a body to make it move in a desired direction before a second run is in a body or add a large velocity to each atom in a body to make it
performed, using the :doc:`set <set>` or move in a desired direction before a second run is performed, using
:doc:`displace_atoms <displace_atoms>` or :doc:`velocity <velocity>` the :doc:`set <set>` or :doc:`displace_atoms <displace_atoms>` or
commands. But these commands will not affect the internal attributes :doc:`velocity <velocity>` commands. But these commands will not
of the body unless *reinit* is set to *yes*\ . With *reinit* set to *no* affect the internal attributes of the body unless *reinit* is set
(or using the *infile* option, which implies *reinit* *no*\ ) the position to *yes*\ . With *reinit* set to *no* (or using the *infile*
and velocity of individual atoms in the body will be reset when time option, which implies *reinit* *no*\ ) the position and velocity of
integration starts again. individual atoms in the body will be reset when time integration
starts again.
---------- ----------
@ -314,17 +321,17 @@ to be part of rigid bodies.
.. note:: .. note::
To compute the initial center-of-mass position and other To compute the initial center-of-mass position and other properties
properties of each rigid body, the image flags for each atom in the of each rigid body, the image flags for each atom in the body are
body are used to "unwrap" the atom coordinates. Thus you must ensure used to "unwrap" the atom coordinates. Thus you must ensure that
that these image flags are consistent so that the unwrapping creates a these image flags are consistent so that the unwrapping creates a
valid rigid body (one where the atoms are close together), valid rigid body (one where the atoms are close together),
particularly if the atoms in a single rigid body straddle a periodic particularly if the atoms in a single rigid body straddle a
boundary. This means the input data file or restart file must define periodic boundary. This means the input data file or restart file
the image flags for each atom consistently or that you have used the must define the image flags for each atom consistently or that you
:doc:`set <set>` command to specify them correctly. If a dimension is have used the :doc:`set <set>` command to specify them correctly.
non-periodic then the image flag of each atom must be 0 in that If a dimension is non-periodic then the image flag of each atom
dimension, else an error is generated. must be 0 in that dimension, else an error is generated.
The *force* and *torque* keywords discussed next are only allowed for The *force* and *torque* keywords discussed next are only allowed for
the *rigid* styles. the *rigid* styles.
@ -360,12 +367,13 @@ settings from the final keyword are used.
.. note:: .. note::
For computational efficiency, you may wish to turn off pairwise For computational efficiency, you may wish to turn off pairwise and
and bond interactions within each rigid body, as they no longer 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>` contribute to the motion. The :doc:`neigh_modify exclude
commands are used to do this. If the rigid bodies have strongly <neigh_modify>` and :doc:`delete_bonds <delete_bonds>` commands are
overlapping atoms, you may need to turn off these interactions to used to do this. If the rigid bodies have strongly overlapping
avoid numerical problems due to large equal/opposite intra-body forces 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. swamping the contribution of small inter-body forces.
For computational efficiency, you should typically define one fix 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 constituent particles within a rigid body can be point particles
(the default in LAMMPS) or finite-size particles, such as spheres or (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 details on these kinds of particles. Finite-size particles contribute
differently to the moment of inertia of a rigid body than do point differently to the moment of inertia of a rigid body than do point
particles. Finite-size particles can also experience torque (e.g. due 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 Forces between particles within a body do not contribute to the
external force or torque on the body. Thus for computational external force or torque on the body. Thus for computational
efficiency, you may wish to turn off pairwise and bond interactions 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 commands are used to do this. For finite-size particles this also
means the particles can be highly overlapped when creating the rigid means the particles can be highly overlapped when creating the rigid
body. 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 the 4 NVE rigid styles. The only difference is that the *rigid* and
*rigid/small* styles use an integration technique based on Richardson *rigid/small* styles use an integration technique based on Richardson
iterations. The *rigid/nve* and *rigid/small/nve* styles uses the iterations. The *rigid/nve* and *rigid/small/nve* styles uses the
methods described in the paper by :ref:`Miller <Miller3>`, which are thought methods described in the paper by :ref:`Miller <Miller3>`, which are
to provide better energy conservation than an iterative approach. thought to provide better energy conservation than an iterative
approach.
The *rigid/nvt* and *rigid/nvt/small* styles performs constant NVT The *rigid/nvt* and *rigid/nvt/small* styles performs constant NVT
integration using a Nose/Hoover thermostat with chains as described integration using a Nose/Hoover thermostat with chains as described
originally in :ref:`(Hoover) <Hoover>` and :ref:`(Martyna) <Martyna2>`, which originally in :ref:`(Hoover) <Hoover>` and :ref:`(Martyna)
thermostats both the translational and rotational degrees of freedom <Martyna2>`, which thermostats both the translational and rotational
of the rigid bodies. They are referred to below as the 2 NVT rigid degrees of freedom of the rigid bodies. They are referred to below as
styles. The rigid-body algorithm used by *rigid/nvt* is described in the 2 NVT rigid styles. The rigid-body algorithm used by *rigid/nvt*
the paper by :ref:`Kamberaj <Kamberaj>`. is described in the paper by :ref:`Kamberaj <Kamberaj>`.
The *rigid/npt*, *rigid/nph*, *rigid/npt/small*, and *rigid/nph/small* The *rigid/npt*, *rigid/nph*, *rigid/npt/small*, and *rigid/nph/small*
styles perform constant NPT or NPH integration using a Nose/Hoover 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 can be specified independently via the *x*, *y*, *z* keywords, which
correspond to the 3 simulation box dimensions. For each component, correspond to the 3 simulation box dimensions. For each component,
the external pressure or tensor component at each timestep is a ramped 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 value during the run from *Pstart* to *Pstop*\ . If a target pressure
specified for a component, then the corresponding box dimension will is specified for a component, then the corresponding box dimension
change during a simulation. For example, if the *y* keyword is used, will change during a simulation. For example, if the *y* keyword is
the y-box length will change. A box dimension will not change if that used, the y-box length will change. A box dimension will not change
component is not specified, although you have the option to change if that component is not specified, although you have the option to
that dimension via the :doc:`fix deform <fix_deform>` command. change that dimension via the :doc:`fix deform <fix_deform>` command.
For all barostat keywords, the *Pdamp* parameter operates like the For all barostat keywords, the *Pdamp* parameter operates like the
*Tdamp* parameter, determining the time scale on which pressure is *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 The *langevin* keyword applies a Langevin thermostat to the constant
NVE time integration performed by any of the 4 NVE rigid styles: NVE time integration performed by any of the 4 NVE rigid styles:
*rigid*, *rigid/nve*, *rigid/small*, *rigid/small/nve*\ . It cannot be *rigid*, *rigid/nve*, *rigid/small*, *rigid/small/nve*\ . It cannot
used with the 2 NVT rigid styles: *rigid/nvt*, *rigid/small/nvt*\ . The be used with the 2 NVT rigid styles: *rigid/nvt*, *rigid/small/nvt*\ .
desired temperature at each timestep is a ramped value during the run The desired temperature at each timestep is a ramped value during the
from *Tstart* to *Tstop*\ . The *Tdamp* parameter is specified in time run from *Tstart* to *Tstop*\ . The *Tdamp* parameter is specified in
units and determines how rapidly the temperature is relaxed. For 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 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 of (roughly) 100 time units (:math:`\tau` or fs or ps - see the
:doc:`units <units>` command). The random # *seed* must be a positive :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 This value, along with *Tdamp* can be varied to dampen undesirable
oscillations in temperature that can occur in a simulation. As a rule oscillations in temperature that can occur in a simulation. As a rule
of thumb, increasing the chain length should lead to smaller of thumb, increasing the chain length should lead to smaller
oscillations. The keyword *pchain* specifies the number of oscillations. The keyword *pchain* specifies the number of thermostats
thermostats in the chain thermostatting the barostat degrees of in the chain thermostatting the barostat degrees of freedom.
freedom.
.. note:: .. note::
There are alternate ways to thermostat a system of rigid bodies. There are alternate ways to thermostat a system of rigid bodies.
You can use :doc:`fix langevin <fix_langevin>` to treat the individual You can use :doc:`fix langevin <fix_langevin>` to treat the
particles in the rigid bodies as effectively immersed in an implicit individual particles in the rigid bodies as effectively immersed in
solvent, e.g. a Brownian dynamics model. For hybrid systems with both an implicit solvent, e.g. a Brownian dynamics model. For hybrid
rigid bodies and solvent particles, you can thermostat only the systems with both rigid bodies and solvent particles, you can
solvent particles that surround one or more rigid bodies by thermostat only the solvent particles that surround one or more
appropriate choice of groups in the compute and fix commands for rigid bodies by appropriate choice of groups in the compute and fix
temperature and thermostatting. The solvent interactions with the commands for temperature and thermostatting. The solvent
rigid bodies should then effectively thermostat the rigid body interactions with the rigid bodies should then effectively
temperature as well without use of the Langevin or Nose/Hoover options thermostat the rigid body temperature as well without use of the
associated with the fix rigid commands. Langevin or Nose/Hoover options associated with the fix rigid
commands.
---------- ----------
The *mol* keyword can only be used with the *rigid/small* styles. It 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 must be used when other commands, such as :doc:`fix deposit
bodies on-the-fly during a simulation. You specify a *template-ID* <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 previously defined using the :doc:`molecule <molecule>` command, which
reads a file that defines the molecule. You must use the same reads a file that defines the molecule. You must use the same
*template-ID* that the other fix which is adding rigid bodies uses. *template-ID* that the other fix which is adding rigid bodies uses.
@ -668,16 +680,16 @@ cross periodic boundaries during the simulation.
.. note:: .. note::
If you use the *infile* or *mol* keywords and write restart If you use the *infile* or *mol* keywords and write restart files
files during a simulation, then each time a restart file is written, during a simulation, then each time a restart file is written, the
the fix also write an auxiliary restart file with the name fix also write an auxiliary restart file with the name rfile.rigid,
rfile.rigid, where "rfile" is the name of the restart file, where "rfile" is the name of the restart file,
e.g. tmp.restart.10000 and tmp.restart.10000.rigid. This auxiliary 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 file is in the same format described above. Thus it can be used in
new input script that restarts the run and re-specifies a rigid fix a new input script that restarts the run and re-specifies a rigid
using an *infile* keyword and the appropriate filename. Note that the fix using an *infile* keyword and the appropriate filename. Note
auxiliary file will contain one line for every rigid body, even if the that the auxiliary file will contain one line for every rigid body,
original file only listed a subset of the rigid bodies. even if the original file only listed a subset of the rigid bodies.
If the system has rigid bodies with finite-size overlapping particles If the system has rigid bodies with finite-size overlapping particles
and the model uses the :doc:`fix gravity <fix_gravity>` command to 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 If your simulation is a hybrid model with a mixture of rigid bodies
non-rigid particles (e.g. solvent) there are several ways these rigid and non-rigid particles (e.g. solvent) there are several ways these
fixes can be used in tandem with :doc:`fix nve <fix_nve>`, :doc:`fix nvt rigid fixes can be used in tandem with :doc:`fix nve <fix_nve>`,
<fix_nh>`, :doc:`fix npt <fix_nh>`, and :doc:`fix nph <fix_nh>`. :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 If you wish to perform NVE dynamics (no thermostatting or
barostatting), use one of 4 NVE rigid styles to integrate the rigid 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 If you wish to perform NVT dynamics (thermostatting, but no
barostatting), you can use one of the 2 NVT rigid styles for the rigid barostatting), you can use one of the 2 NVT rigid styles for the rigid
bodies, and any thermostatting fix for the non-rigid particles bodies, and any thermostatting fix for the non-rigid particles
(:doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`, :doc:`fix (:doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`,
temp/berendsen <fix_temp_berendsen>`). You can also use one of the 4 :doc:`fix temp/berendsen <fix_temp_berendsen>`). You can also use one
NVE rigid styles for the rigid bodies and thermostat them using of the 4 NVE rigid styles for the rigid bodies and thermostat them
:doc:`fix langevin <fix_langevin>` on the group that contains all the using :doc:`fix langevin <fix_langevin>` on the group that contains
particles in the rigid bodies. The net force added by :doc:`fix all the particles in the rigid bodies. The net force added by
langevin <fix_langevin>` to each rigid body effectively thermostats its :doc:`fix langevin <fix_langevin>` to each rigid body effectively
translational center-of-mass motion. Not sure how well it does at thermostats its translational center-of-mass motion. Not sure how
thermostatting its rotational motion. well it does at thermostatting its rotational motion.
If you wish to perform NPT or NPH dynamics (barostatting), you cannot 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 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. barostatting fixes.
You could even use the second and third options for a non-hybrid You could even use the second and third options for a non-hybrid
simulation consisting of only rigid bodies, assuming you give :doc:`fix simulation consisting of only rigid bodies, assuming you give
npt <fix_nh>` an empty group, though it's an odd thing to do. The :doc:`fix npt <fix_nh>` an empty group, though it's an odd thing to
barostatting fixes (:doc:`fix npt <fix_nh>` and :doc:`fix press/berensen do. The barostatting fixes (:doc:`fix npt <fix_nh>` and :doc:`fix
<fix_press_berendsen>`) will monitor the pressure and change the box press/berensen <fix_press_berendsen>`) will monitor the pressure and
dimensions, but not time integrate any particles. The integration of change the box dimensions, but not time integrate any particles. The
the rigid bodies will be performed by fix rigid/nvt. 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 calculated by these fixes is "intensive". The scalar is the current
temperature of the collection of rigid bodies. This is averaged over temperature of the collection of rigid bodies. This is averaged over
all rigid bodies and their translational and rotational degrees of 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 freedom. The translational energy of a rigid body is 1/2 m v\^2,
m = total mass of the body and v = the velocity of its center of mass. where m = total mass of the body and v = the velocity of its center of
The rotational energy of a rigid body is 1/2 I w\^2, where I = the mass. The rotational energy of a rigid body is 1/2 I w\^2, where I =
moment of inertia tensor of the body and w = its angular velocity. the moment of inertia tensor of the body and w = its angular velocity.
Degrees of freedom constrained by the *force* and *torque* keywords Degrees of freedom constrained by the *force* and *torque* keywords
are removed from this calculation, but only for the *rigid* and are removed from this calculation, but only for the *rigid* and
*rigid/nve* fixes. *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 Read in a data file containing information LAMMPS needs to run a
simulation. The file can be ASCII text or a gzipped text file 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 (detected by a .gz suffix).
atom coordinates; see the :doc:`read_restart <read_restart>` and
:doc:`create_atoms <create_atoms>` commands for alternative methods. This is one of 3 ways to specify the simulation box: see the
Also see the explanation of the :doc:`-restart command-line switch :doc:`create_box <create_box>` and :doc:`read_restart <read_restart>`
<Run_options>` which can convert a restart file to a data file. 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 This command can be used multiple times to add new atoms and their
properties to an existing system by using the *add*, *offset*, and 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 will separate the atoms in the bond, which can lead to "lost" bond
atoms or bad dynamics. 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 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 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, 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 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 *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 "tilt factors" because they are the amount of displacement applied to
faces of an orthogonal box to transform it into a restricted triclinic edges of faces of an orthogonal box to transform it into a restricted
parallelepiped. triclinic parallelepiped.
The :doc:`Howto_triclinic <Howto_triclinic>` doc page discusses the The :doc:`Howto_triclinic <Howto_triclinic>` doc page discusses the
tilt factors in detail and explains that the resulting edge vectors of 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) * **B** = (xy,yhi-ylo,0)
* **C** = (xz,yz,zhi-zlo) * **C** = (xz,yz,zhi-zlo)
This restricted form of edge vectors means that **A** is along the This restricted form of edge vectors requires that **A** be in the
x-axis, **B** is in the xy plane with a y-component in the +y direction of the x-axis, **B** be in the xy plane with its y-component
direction, and **C** has a z-component in the +z direction. The in the +y direction, and **C** have its z-component in the +z
origin (lower left corner) of the restricted triclinic box is at direction. The origin (lower left corner) of the restricted triclinic
(xlo,ylo,zlo). box is at (xlo,ylo,zlo).
For a 2d simulation, the zlo and zhi values must straddle zero. The 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. 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 *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 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 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 co-planar. They must also define a right-handed system requirement
**B**) point in the direction of **C**. The origin of the box (origin such that (**A** x **B**) points in the direction of **C**. A
of the 3 edge vectors) is set by the *abc origin* keyword. 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: The default values for these 4 keywords are as follows:
* avec = (1,0,0) * avec = (1,0,0)
* bvec = (0,1,0) * bvec = (0,1,0)
* cvec = (0,0,1) * 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 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 *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 LAMMPS allows specification of general triclinic simulation boxes
as a convenience for users who may be converting data from 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 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 LAMMPS only uses restricted triclinic simulation boxes. This means
the box and per-atom information (e.g. coordinates, velocities) in the box and per-atom information (e.g. coordinates, velocities) in
the data file are converted from general to restricted triclinic the data file are converted from general to restricted triclinic
form as soon as the file is read. This means other sections of the form when the file is read. Other sections of the data file must
data file must specify their per-atom data appropriately. This also list their per-atom data appropriately if vector quantities
requirement is explained below for the relevant sections. The are specified. This requirement is explained below for the relevant
:doc:`Howto_triclinic <Howto_triclinic>` doc page also discusses sections. The :doc:`Howto_triclinic <Howto_triclinic>` doc page
other LAMMPS commands which can input/output general triclinic also discusses other LAMMPS commands which can input/output general
representations of the simulation box and per-atom data. triclinic representations of the simulation box and per-atom data.
The following explanations apply to all 3 kinds of simulation boxes: The following explanations apply to all 3 kinds of simulation boxes:
orthogonal, restricted triclinic, and general triclinic. orthogonal, restricted triclinic, and general triclinic.
@ -509,24 +528,25 @@ needed, so that the image flag would be zero.
.. note:: .. note::
If the system is non-periodic (in a dimension), then all atoms in the If the system is non-periodic (in a dimension), then all atoms in
data file must have coordinates (in that dimension) that are "greater the data file must have coordinates (in that dimension) that are
than or equal to" the lo value and "less than or equal to" the hi "greater than or equal to" the lo value and "less than or equal to"
value. If the non-periodic dimension is of style "fixed" (see the the hi value. If the non-periodic dimension is of style "fixed"
:doc:`boundary <boundary>` command), then the atom coords must be (see the :doc:`boundary <boundary>` command), then the atom coords
strictly "less than" the hi value, due to the way LAMMPS assign atoms must be strictly "less than" the hi value, due to the way LAMMPS
to processors. Note that you should not make the lo/hi values assign atoms to processors. Note that you should not make the
radically smaller/larger than the extent of the atoms. For example, lo/hi values radically smaller/larger than the extent of the atoms.
if your atoms extend from 0 to 50, you should not specify the box For example, if atoms extend from 0 to 50, you should not specify
bounds as -10000 and 10000 unless you also use the :doc:`processors the box bounds as -10000 and 10000 unless you also use the
command <processors>`. This is because LAMMPS uses the specified box :doc:`processors command <processors>`. This is because LAMMPS
size to layout the 3d grid of processors. A huge (mostly empty) box uses the specified box size to layout the 3d grid of processors. A
will be sub-optimal for performance when using "fixed" boundary huge (mostly empty) box will be sub-optimal for performance when
conditions (see the :doc:`boundary <boundary>` command). When using using "fixed" boundary conditions (see the :doc:`boundary
"shrink-wrap" boundary conditions (see the :doc:`boundary <boundary>` <boundary>` command). When using "shrink-wrap" boundary conditions
command), a huge (mostly empty) box may cause a parallel simulation (see the :doc:`boundary <boundary>` command), a huge (mostly empty)
to lose atoms when LAMMPS shrink-wraps the box around the atoms. The box may cause a parallel simulation to lose atoms when LAMMPS
read_data command will generate an error in this case. 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:: .. note::
All of the "extra" settings are only applied in the first data All of the "extra" settings are only applied in the first data file
file read and when no simulation box has yet been created; as soon as read and when no simulation box has yet been created; as soon as
the simulation box is created (and read_data implies that), these the simulation box is created (and read_data implies that), these
settings are *locked* and cannot be changed anymore. Please see the settings are *locked* and cannot be changed anymore. Please see the
description of the *add* keyword above for reading multiple data files. description of the *add* keyword above for reading multiple data
If they appear in later data files, they are ignored. files. If they appear in later data files, they are ignored.
The "ellipsoids" and "lines" and "triangles" and "bodies" settings are The "ellipsoids" and "lines" and "triangles" and "bodies" settings are
only used with :doc:`atom_style ellipsoid or line or tri or body 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:: .. note::
For :doc:`atom_style template <atom_style>`, the molecular For :doc:`atom_style template <atom_style>`, the molecular topology
topology (bonds,angles,etc) is contained in the molecule templates (bonds,angles,etc) is contained in the molecule templates read-in
read-in by the :doc:`molecule <molecule>` command. This means you by the :doc:`molecule <molecule>` command. This means you cannot
cannot set the *bonds*, *angles*, etc header keywords in the data set the *bonds*, *angles*, etc header keywords in the data file,
file, nor can you define *Bonds*, *Angles*, etc sections as discussed nor can you define *Bonds*, *Angles*, etc sections as discussed
below. You can set the *bond types*, *angle types*, etc header below. You can set the *bond types*, *angle types*, etc header
keywords, though it is not necessary. If specified, they must match keywords, though it is not necessary. If specified, they must
the maximum values defined in any of the template molecules. 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 For orthogonal and restricted and general triclinic simulation
boxes, the atom coordinates (x,y,z) listed in this section should boxes, the atom coordinates (x,y,z) listed in this section should
be inside the corresponding simulation box. For restricted be inside the corresponding simulation box. For restricted
triclinic boxes that means the parallelepiped defined by the by the triclinic boxes that means the parallelepiped defined by the *xlo
*xlo xhi*, *ylo yhi*, *zlo zhi*, and *xy xz yz*, keywords. For xhi*, *ylo yhi*, *zlo zhi*, and *xy xz yz*, keywords. For general
general triclinic boxes that means the parallelepiped defined by triclinic boxes that means the parallelepiped defined by the 3 edge
the 3 edge vectors and origin specified by the *avec*, *bvec*, vectors and origin specified by the *avec*, *bvec*, *cvec*, and
*cvec*, and *abc origin* header keywords. See the discussion in *abc origin* header keywords. See the discussion in the header
the header section above about how atom coordinates outside the section above about how atom coordinates outside the simulation box
simulation box are (or are not) remapped to be inside the box. are (or are not) remapped to be inside the box.
.. list-table:: .. 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 * lineflag = 1 for line segment particles, 0 for point or spherical particles
* mass = mass of particle (mass units) * mass = mass of particle (mass units)
* molecule-ID = integer ID of molecule the atom belongs to * 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 * 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) * q = charge on atom (charge units)
* rho = density (need units) for SPH particles * rho = density (need units) for SPH particles
* sp = magnitude of magnetic spin of atom (Bohr magnetons) * 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-atom = which atom within a template molecule the atom is
* template-index = which molecule within the molecule template the atom is part of * template-index = which molecule within the molecule template the atom is part of
* theta = internal temperature of a DPD particle * 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) * volume = volume of Peridynamic particle (distance\^3 units)
* x,y,z = coordinates of atom (distance units) * x,y,z = coordinates of atom (distance units)
* x0,y0,z0 = original (strain-free) coordinates of atom (distance * 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 The units for these quantities depend on the unit style; see the
:doc:`units <units>` command for details. :doc:`units <units>` command for details.
For 2d simulations, z must be specified as 0.0. If the data file is For 2d simulations, the atom coordinate z must be specified as 0.0.
created by another program, then z values for a 2d simulation can be If the data file is created by another program, then z values for a 2d
within epsilon of 0.0, and LAMMPS will force them to zero. 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 .. note::
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.
If the data file defines a general triclinic box, then each of the 3 If the data file defines a general triclinic box, then the
vectors (translational velocity, angular momentum, angule velocity) following per-atom values in the list above are per-atom vectors
sholld be specified for the rotated coordinate axes of the general which imply an orientation: (mux,muy,muz), (normx,normy,normz),
triclinic box. See the :doc:`Howto triclinic <Howto_triclininc>` doc (spx,spy,spz). This menas they should be specified consistent with
page for more details. 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 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 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 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 0.0 when the *Atoms* section is read. Velocities can be set later by
a *Velocities* section in the data file or by a a *Velocities* section in the data file or by a :doc:`velocity
:doc:`velocity <velocity>` or :doc:`set <set>` command in the input <velocity>` or :doc:`set <set>` command in the input script.
script.
---------- ----------
@ -1329,11 +1350,10 @@ LAMMPS normalizes each atom's quaternion in case (a,b,c) is not
specified as a unit vector. specified as a unit vector.
If the data file defines a general triclinic box, then the quaternion If the data file defines a general triclinic box, then the quaternion
for each ellipsoid should be specified for its orientation in the for each ellipsoid should be specified for its orientation relative to
general triclinic system with respect to the standard xyz axes (not the standard x,y,z coordinate axes. When the system is converted to a
the rotated coordinate axes of the general triclinic system). When restricted triclinic box, the ellipsoid quaternions will be altered
the general triclinic box is transformed to a restricted triclinic appropriately.
box, the ellipsoid quaternions will be altered appropriately.
The *Ellipsoids* section must appear after the *Atoms* section. 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 I.e. normal = (c2-c1) x (0,0,1). This orientation may be important
for defining some interactions. 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 If the data file defines a general triclinic box, the (x1,y1) and
(x2,y2) values should be within (or near) its parallelogram area, (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 i.e. near the x,y coordinates of the line segment as defined in the