diff --git a/doc/src/Howto_triclinic.rst b/doc/src/Howto_triclinic.rst index 0a66af4b36..6cbc0644cd 100644 --- a/doc/src/Howto_triclinic.rst +++ b/doc/src/Howto_triclinic.rst @@ -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 ` 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 ` or :doc:`dump custom ` 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 ` 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 ` 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. diff --git a/doc/src/fix_rigid.rst b/doc/src/fix_rigid.rst index a50e215681..2192f9ed1f 100644 --- a/doc/src/fix_rigid.rst +++ b/doc/src/fix_rigid.rst @@ -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 ` 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 ` 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 ` 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 +` 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 ` cutoff plus neighbor skin does not span - this distance, then you should use the :doc:`comm_modify cutoff ` 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 + ` cutoff plus neighbor skin does not span this + distance, then you should use the :doc:`comm_modify cutoff + ` 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 `, :doc:`fix nvt `, :doc:`fix npt `, :doc:`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 ` or :doc:`fix nvt ` should be used for the non-rigid particles. + time-integration fixes (e.g. :doc:`fix nve `, :doc:`fix + nvt `, :doc:`fix npt `, :doc:`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 + ` or :doc:`fix nvt ` 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 ` command), - setting the force on them to 0.0 (via the :doc:`fix setforce ` command), and integrating them as usual - (e.g. via the :doc:`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 + ` command), setting the force on them to 0.0 (via the + :doc:`fix setforce ` command), and integrating them + as usual (e.g. via the :doc:`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 ` or - :doc:`displace_atoms ` or :doc:`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 ` or :doc:`displace_atoms ` or + :doc:`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 ` 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 ` 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 ` and :doc:`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 + ` and :doc:`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 ` commands for more +ellipsoids or line segments or triangles. See the :doc:`atom_style +sphere and ellipsoid and line and tri ` 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 ` and :doc:`delete_bonds ` +between particles within each rigid body. The :doc:`neigh_modify +exclude ` and :doc:`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 `, which are thought -to provide better energy conservation than an iterative approach. +methods described in the paper by :ref:`Miller `, 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) ` and :ref:`(Martyna) `, 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 `. +originally in :ref:`(Hoover) ` and :ref:`(Martyna) +`, 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 `. 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` or :doc:`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 +` or :doc:`fix pour `, add rigid bodies +on-the-fly during a simulation. You specify a *template-ID* previously defined using the :doc:`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 ` 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 `, :doc:`fix nvt -`, :doc:`fix npt `, and :doc:`fix nph `. +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 `, +:doc:`fix nvt `, :doc:`fix npt `, and :doc:`fix nph +`. 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 `, :doc:`fix langevin `, :doc:`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 ` on the group that contains all the -particles in the rigid bodies. The net force added by :doc:`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 `, :doc:`fix langevin `, +:doc:`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 ` on the group that contains +all the particles in the rigid bodies. The net force added by +:doc:`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 ` 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 ` an empty group, though it's an odd thing to do. The -barostatting fixes (:doc:`fix npt ` and :doc:`fix press/berensen -`) 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 ` an empty group, though it's an odd thing to +do. The barostatting fixes (:doc:`fix npt ` and :doc:`fix +press/berensen `) 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 `. 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. diff --git a/doc/src/read_data.rst b/doc/src/read_data.rst index 1d81acb51e..7dda35d7bb 100644 --- a/doc/src/read_data.rst +++ b/doc/src/read_data.rst @@ -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 ` and -:doc:`create_atoms ` commands for alternative methods. -Also see the explanation of the :doc:`-restart command-line switch -` 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 ` and :doc:`read_restart ` +and commands for alternative methods. It is also one of 3 ways to +specify initial atom coordinates: see the :doc:`create_atoms +` and :doc:`read_restart ` and commands +for alternative methods. Also see the explanation of the +:doc:`-restart command-line switch ` 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 ` 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 ` doc page, internally + :doc:`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 ` 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 ` 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 ` 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 `. 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 ` command). When using - "shrink-wrap" boundary conditions (see the :doc:`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 ` 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 `. 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 + ` command). When using "shrink-wrap" boundary conditions + (see the :doc:`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 ` 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 `, the molecular - topology (bonds,angles,etc) is contained in the molecule templates - read-in by the :doc:`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 `, the molecular topology + (bonds,angles,etc) is contained in the molecule templates read-in + by the :doc:`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 ` 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 ` 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 ` 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 ` 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 ` or :doc:`set ` command in the input -script. +a *Velocities* section in the data file or by a :doc:`velocity +` or :doc:`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