diff --git a/doc/src/create_atoms.rst b/doc/src/create_atoms.rst index 3834fbb71f..489d4fa5d1 100644 --- a/doc/src/create_atoms.rst +++ b/doc/src/create_atoms.rst @@ -95,16 +95,16 @@ typically created via the :doc:`create_box ` command. Before using this command, a lattice must also be defined using the :doc:`lattice ` command, unless you specify the *single* style with units = box or the *random* style. For the remainder of this doc -page, a created atom or molecule is referred to as a "particle". +page, a created atom or molecule is referred to as a "particle." If created particles are individual atoms, they are assigned the specified atom *type*, though this can be altered via the *basis* keyword as discussed below. If molecules are being created, the type of each atom in the created molecule is specified in the file read by the :doc:`molecule ` command, and those values are added to -the specified atom *type*\ . E.g. if *type* = 2, and the file specifies -atom types 1,2,3, then each created molecule will have atom types -3,4,5. +the specified atom *type* (e.g., if *type* = 2 and the file specifies +atom types 1, 2, and 3, then each created molecule will have atom types +3, 4, and 5). For the *box* style, the create_atoms command fills the entire simulation box with particles on the lattice. If your simulation box @@ -204,7 +204,7 @@ all requested *N* particles, a warning will be output. If the *region-ID* argument is specified as NULL, then the randomly created particles will be anywhere in the simulation box. If a -*region-ID* is specified, a geometric volume is filled which is both +*region-ID* is specified, a geometric volume is filled that is both inside the simulation box and is also consistent with the region volume. See the :doc:`region ` command for details. Note that a region can be specified so that its "volume" is either inside @@ -219,7 +219,7 @@ interleaving the create_atoms command with :doc:`lattice ` commands specifying different orientations. When this command is used, care should be taken to insure the -resulting system does not contain particles which are highly +resulting system does not contain particles that are highly overlapped. Such overlaps will cause many interatomic potentials to compute huge energies and forces, leading to bad dynamics. There are several strategies to avoid this problem: @@ -291,7 +291,7 @@ and inserts all molecules at a specified orientation. optional keywords allowed by the :doc:`create_box ` command for extra bonds (angles,etc) or extra special neighbors. This is because by default, the :doc:`create_box ` command sets up a - non-molecular system which does not allow molecules to be added. + non-molecular system that does not allow molecules to be added. ---------- @@ -308,11 +308,11 @@ The *ratio* and *subset* keywords can be used in conjunction with the *box* or *region* styles to limit the total number of particles inserted. The lattice defines a set of *Nlatt* eligible sites for inserting particles, which may be limited by the *region* style or the -*var* and *set* keywords. For the *ratio* keyword only the specified -fraction of them (0 <= *frac* <= 1) will be assigned particles. For -the *subset* keyword only the specified *Nsubset* of them will be +*var* and *set* keywords. For the *ratio* keyword, only the specified +fraction of them (:math:`0 \le f \le 1`) will be assigned particles. +For the *subset* keyword only the specified *Nsubset* of them will be assigned particles. In both cases the assigned lattice sites are -chosen randomly. An iterative algorithm is used which insures the +chosen randomly. An iterative algorithm is used that insures the correct number of particles are inserted, in a perfectly random fashion. Which lattice sites are selected will change with the number of processors used. @@ -327,23 +327,23 @@ The *var* and *set* keywords can be used together to provide a criterion for accepting or rejecting the addition of an individual atom, based on its coordinates. They apply to all styles except *single*. The *name* specified for the *var* keyword is the name of -an :doc:`equal-style variable ` which should evaluate to a -zero or non-zero value based on one or two or three variables which -will store the x, y, or z coordinates of an atom (one variable per +an :doc:`equal-style variable ` that should evaluate to a +zero or non-zero value based on one or two or three variables that +will store the *x*, *y*, or *z* coordinates of an atom (one variable per coordinate). If used, these other variables must be :doc:`internal-style variables ` defined in the input script; their initial numeric value can be anything. They must be internal-style variables, because this command resets their values directly. The *set* keyword is used to identify the names of these -other variables, one variable for the x-coordinate of a created atom, -one for y, and one for z. +other variables, one variable for the *x*-coordinate of a created atom, +one for *y*, and one for *z*. .. figure:: img/sinusoid.jpg :figwidth: 50% :align: right :target: _images/sinusoid.jpg -When an atom is created, its x,y,z coordinates become the values for +When an atom is created, its :math:`(x,y,z)` coordinates become the values for any *set* variable that is defined. The *var* variable is then evaluated. If the returned value is 0.0, the atom is not created. If it is non-zero, the atom is created. @@ -352,8 +352,8 @@ As an example, these commands can be used in a 2d simulation, to create a sinusoidal surface. Note that the surface is "rough" due to individual lattice points being "above" or "below" the mathematical expression for the sinusoidal curve. If a finer lattice were used, -the sinusoid would appear to be "smoother". Also note the use of the -"xlat" and "ylat" :doc:`thermo_style ` keywords which +the sinusoid would appear to be "smoother." Also note the use of the +"xlat" and "ylat" :doc:`thermo_style ` keywords, which converts lattice spacings to distance. .. only:: html @@ -379,7 +379,7 @@ converts lattice spacings to distance. The *rotate* keyword allows specification of the orientation at which molecules are inserted. The axis of rotation is -determined by the rotation vector (Rx,Ry,Rz) that goes through the +determined by the rotation vector :math:`(R_x,R_y,R_z)` that goes through the insertion point. The specified *theta* determines the angle of rotation around that axis. Note that the direction of rotation for the atoms around the rotation axis is consistent with the right-hand @@ -388,7 +388,7 @@ wrap around the axis in the direction of rotation. The *radscale* keyword only applies to the *mesh* style and adjusts the radius of created particles (see above), provided this is supported by -the atom style. Its value is a prefactor (must be > 0.0, default is +the atom style. Its value is a prefactor (must be :math:`>` 0.0, default is 1.0) that is applied to the atom radius inferred from the size of the individual triangles in the triangle mesh that the particle corresponds to. @@ -406,12 +406,12 @@ non-overlapping criterion. .. note:: - Checking for overlaps is a costly O(N(N+M)) operation for inserting - *N* new particles into a system with *M* existing particles. This - is because distances to all *M* existing particles are computed for + Checking for overlaps is a costly :math:`\mathcal{O}(N(N+M))` operation for + inserting *N* new particles into a system with *M* existing particles. + This is because distances to all *M* existing particles are computed for each new particle that is added. Thus the intended use of this keyword is to add relatively small numbers of particles to systems - which remain at a relatively low density even after the new + that remain at a relatively low density even after the new particles are created. Careful use of the *maxtry* keyword in combination with *overlap* is recommended. See the discussion above about systems with overlapped particles for alternate @@ -422,7 +422,7 @@ the number of attempts to generate valid coordinates for a single new particle that satisfy all requirements imposed by the *region*, *var*, and *overlap* keywords. The default is 10 attempts per particle before the loop over the requested *N* particles advances to the next -particle. Note that if insertion success is unlikely (e.g. inserting +particle. Note that if insertion success is unlikely (e.g., inserting new particles into a dense system using the *overlap* keyword), setting the *maxtry* keyword to a large value may result in this command running for a long time. @@ -447,7 +447,7 @@ Here is an example for the *random* style using these commands to produce a system as shown in the image with 1520 particles (out of 2000 requested) that are moderately dense and which have no overlaps sufficient to prevent the LJ pair_style from running properly (because -the overlap criterion = 1.0). The create_atoms command ran for 0.3 s +the overlap criterion is 1.0). The create_atoms command ran for 0.3 s on a single CPU core. .. only:: html @@ -460,9 +460,9 @@ The *units* keyword determines the meaning of the distance units used to specify the coordinates of the one particle created by the *single* style, or the overlap distance *Doverlap* by the *overlap* keyword. A *box* value selects standard distance units as defined by the -:doc:`units ` command, e.g. Angstroms for units = real or -metal. A *lattice* value means the distance units are in lattice -spacings. +:doc:`units ` command (e.g., :math:`\mathrm{\mathring{A}}` for +units = *real* or *metal*\ . A *lattice* value means the distance units are in +lattice spacings. ---------- @@ -471,15 +471,15 @@ collection of created atoms are assigned consecutive IDs that start immediately following the largest atom ID existing before the create_atoms command was invoked. This is done by the processor's communicating the number of atoms they each own, the first processor -numbering its atoms from 1 to N1, the second processor from N1+1 to -N2, etc. Where N1 = number of atoms owned by the first processor, N2 -= number owned by the second processor, etc. Thus when the same -simulation is performed on different numbers of processors, there is -no guarantee a particular created atom will be assigned the same ID in -both simulations. If molecules are being created, molecule IDs are -assigned to created molecules in a similar fashion. +numbering its atoms from :math:`1` to :math:`N_1`, the second processor from +:math:`N_1+1` to :math:`N_2`, and so on, where :math:`N_1` is the number of +atoms owned by the first processor, :math:`N_2` is the number owned by the +second processor, and so forth. Thus, when the same simulation is performed on +different numbers of processors, there is no guarantee a particular created +atom will be assigned the same ID in both simulations. If molecules are being +created, molecule IDs are assigned to created molecules in a similar fashion. -Aside from their ID, atom type, and xyz position, other properties of +Aside from their ID, atom type, and :math:`xyz` position, other properties of created atoms are set to default values, depending on which quantities are defined by the chosen :doc:`atom style `. See the :doc:`atom style ` command for more details. See the @@ -500,17 +500,17 @@ how to change these values. If molecules are being created, these defaults can be overridden by values specified in the file read by the :doc:`molecule ` -command. E.g. the file typically defines bonds (angles,etc) between +command. That is, the file typically defines bonds (angles, etc.) between atoms in the molecule, and can optionally define charges on each atom. Note that the *sphere* atom style sets the default particle diameter to 1.0 as well as the density. This means the mass for the particle is not -1.0, but is PI/6 \* diameter\^3 = 0.5236. When using the *mesh* style, -the particle diameter is adjusted from the size of the individual -triangles in the triangle mesh. +1.0, but is :math:`\frac{\pi}{6} d^3 = 0.5236`, where :math:`d` is the +diameter. When using the *mesh* style, the particle diameter is adjusted from +the size of the individual triangles in the triangle mesh. Note that the *ellipsoid* atom style sets the default particle shape -to (0.0 0.0 0.0) and the density to 1.0 which means it is a point +to (0.0 0.0 0.0) and the density to 1.0, which means it is a point particle, not an ellipsoid, and has a mass of 1.0. Note that the *peri* style sets the default volume and density to 1.0 @@ -533,8 +533,9 @@ the z-direction for a 2d model. Related commands """""""""""""""" -:doc:`lattice `, :doc:`region `, :doc:`create_box `, -:doc:`read_data `, :doc:`read_restart ` +:doc:`lattice `, :doc:`region `, +:doc:`create_box `, :doc:`read_data `, +:doc:`read_restart ` Default """"""" diff --git a/doc/src/create_bonds.rst b/doc/src/create_bonds.rst index 1f468dd42a..b42d55b246 100644 --- a/doc/src/create_bonds.rst +++ b/doc/src/create_bonds.rst @@ -67,20 +67,20 @@ the :doc:`bond_style `, :doc:`bond_coeff `, :doc:`dihedral_coeff `, :doc:`improper_style `, :doc:`improper_coeff ` commands. -The *many* style is useful for adding bonds to a system, e.g. between -nearest neighbors in a lattice of atoms, without having to enumerate +The *many* style is useful for adding bonds to a system (e.g., between +nearest neighbors in a lattice of atoms) without having to enumerate all the bonds in the data file read by the :doc:`read_data ` command. -The *single* styles are useful for adding bonds, angles, dihedrals, impropers -to a system incrementally, then continuing a simulation. +The *single* styles are useful for adding bonds, angles, dihedrals, and +impropers to a system incrementally, then continuing a simulation. -Note that this command does not auto-create any angle, dihedral or improper -interactions when a bond is added. Nor does it auto-create any bonds -when an angle, dihedral or improper is added. Or auto-create any angles when a -dihedral or improper is added. Thus the flexibility of this command is limited. -It can be used several times to create different types of bond at -different distances. But it cannot typically auto-create all the +Note that this command does not auto-create any angle, dihedral, or improper +interactions when a bond is added, nor does it auto-create any bonds +when an angle, dihedral, or improper is added. It also will not auto-create +any angles when a dihedral or improper is added. Thus, the flexibility of this +command is limited. It can be used several times to create different types of +bond at different distances, but it cannot typically auto-create all the bonds or angles or dihedrals or impropers that would normally be defined in a data file for a complex system of molecules. @@ -88,36 +88,37 @@ data file for a complex system of molecules. If the system has no bonds (angles, dihedrals, impropers) to begin with, or if more bonds per atom are being added than currently exist, then you - must insure that the number of bond types and the maximum number of - bonds per atom are set to large enough values. And similarly for - angles, dihedrals and impropers. Otherwise an error may occur when too many + must ensure that the number of bond types and the maximum number of + bonds per atom are set to large enough values, and similarly for + angles, dihedrals, and impropers, otherwise an error may occur when too many bonds (angles, dihedrals, impropers) are added to an atom. If the :doc:`read_data ` command is used to define the system, these parameters can be set via the "bond types" and "extra bond per atom" fields in the header section of the data file. If the :doc:`create_box ` command is used to define the system, - these 2 parameters can be set via its optional "bond/types" and - "extra/bond/per/atom" arguments. And similarly for angles, dihedrals and - impropers. See the doc pages for these 2 commands for details. + these two parameters can be set via its optional *bond/types* and + *extra/bond/per/atom* arguments, and similarly for angles, dihedrals, and + impropers. See the doc pages for these two commands for details. ---------- -The *many* style will create bonds between pairs of atoms I,J where I -is in one of the two specified groups, and J is in the other. The two -groups can be the same, e.g. group "all". The created bonds will be -of bond type *btype*, where *btype* must be a value between 1 and the +The *many* style will create bonds between pairs of atoms :math:`I,J`, +where :math:`I` is in one of the two specified groups and :math:`J` is in the +other. The two groups can be the same (e.g., group "all"). The created bonds +will be of bond type *btype*, where *btype* must be a value between 1 and the number of bond types defined. -For a bond to be created, an I,J pair of atoms must be a distance D -apart such that *rmin* <= D <= *rmax*\ . +For a bond to be created, an :math:`I,J` pair of atoms must be a distance +:math:`D` apart such that :math:`r_\text{min} \le D \le r_\text{max}`. The following settings must have been made in an input script before this style is used: -* special_bonds weight for 1-2 interactions must be 0.0 +* special_bonds weight for 1--2 interactions must be 0.0 * a :doc:`pair_style ` must be defined * no :doc:`kspace_style ` defined -* minimum :doc:`pair_style ` cutoff + :doc:`neighbor ` skin >= *rmax* +* minimum :doc:`pair_style ` cutoff + :doc:`neighbor ` + skin :math:`\ge r_\text{max}` These settings are required so that a neighbor list can be created to search for nearby atoms. Pairs of atoms that are already bonded @@ -127,12 +128,12 @@ a distance that encompasses the *rmax* for new bonds to create. .. note:: - If you want to create bonds between pairs of 1-3 or 1-4 atoms in + If you want to create bonds between pairs of 1--3 or 1--4 atoms in the current bond topology, then you need to use :doc:`special_bonds lj 0 1 1 ` to insure those pairs appear in the neighbor list. They will not appear with the default special_bonds - settings which are zero for 1-2, 1-3, and 1-4 atoms. 1-3 or 1-4 - atoms are those which are 2 hops or 3 hops apart in the bond + settings, which are zero for 1--2, 1--3, and 1--4 atoms. 1--3 or 1--4 + atoms are those which are two hops or three hops apart in the bond topology. An additional requirement for this style is that your system must be @@ -145,7 +146,7 @@ neighbor list requires initialization and setup of a simulation, similar to what a :doc:`run ` command would require. Note that you can change any of these settings after this command -executes, e.g. if you wish to use long-range Coulombic interactions +executes (e.g., if you wish to use long-range Coulombic interactions) via the :doc:`kspace_style ` command for your subsequent simulation. @@ -158,8 +159,8 @@ between 1 and the number of bond types defined. The *single/angle* style creates a single angle of type *atype* between three atoms with IDs *aatom1*, *aatom2*, and *aatom3*\ . The ordering of the atoms is the same as in the *Angles* section of a data -file read by the :doc:`read_data ` command. I.e. the 3 atoms are -ordered linearly within the angle; the central atom is *aatom2*\ . +file read by the :doc:`read_data ` command (i.e., the three atoms +are ordered linearly within the angle; the central atom is *aatom2*). *Atype* must be a value between 1 and the number of angle types defined. @@ -180,14 +181,14 @@ the number of improper types defined. ---------- The keyword *special* controls whether an internal list of special -bonds is created after one or more bonds, or a single angle, dihedral or +bonds is created after one or more bonds, or a single angle, dihedral, or improper is added to the system. The default value is *yes*\ . A value of *no* cannot be used with the *many* style. This is an expensive operation since the bond topology for the system -must be walked to find all 1-2, 1-3, 1-4 interactions to store in an +must be walked to find all 1--2, 1--3, and 1--4 interactions to store in an internal list, which is used when pairwise interactions are weighted; see the :doc:`special_bonds ` command for details. @@ -204,10 +205,10 @@ bond (or angle, or dihedral, or improper) is added: create_bonds single/bond 5 17 386 special no create_bonds single/bond 4 112 183 special yes -Note that you MUST insure the internal list is re-built after the last -bond (angle, dihedral, improper) is added, before performing a simulation. -Otherwise pairwise interactions will not be properly excluded or -weighted. LAMMPS does NOT check that you have done this correctly. +Note that you **must** ensure the internal list is rebuilt after the last +bond (angle, dihedral, improper) is added, *before* performing a simulation. +Otherwise, pairwise interactions will not be properly excluded or +weighted. LAMMPS does **not** check that you have done this correctly. ---------- diff --git a/doc/src/create_box.rst b/doc/src/create_box.rst index aa01be43cd..889a57605d 100644 --- a/doc/src/create_box.rst +++ b/doc/src/create_box.rst @@ -50,28 +50,33 @@ The argument N is the number of atom types that will be used in the simulation. If the region is not of style *prism*, then LAMMPS encloses the region -(block, sphere, etc) with an axis-aligned orthogonal bounding box +(block, sphere, etc.) with an axis-aligned orthogonal bounding box which becomes the simulation domain. If the region is of style *prism*, LAMMPS creates a non-orthogonal simulation domain shaped as a parallelepiped with triclinic symmetry. As defined by the :doc:`region prism ` command, the -parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by 3 -edge vectors starting from the origin given by A = (xhi-xlo,0,0); B = -(xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). *Xy,xz,yz* can be 0.0 or +parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by three +edge vectors starting from the origin given by +:math:`\vec a = (x_\text{hi}-x_\text{lo},0,0)`; +:math:`\vec b = (xy,y_\text{hi}-y_\text{lo},0)`; and +:math:`\vec c = (xz,yz,z_\text{hi}-z_\text{lo})`. +The parameters *xy*\ , *xz*\ , and *yz* can be 0.0 or positive or negative values and are called "tilt factors" because they are the amount of displacement applied to faces of an originally orthogonal box to transform it into the parallelepiped. By default, a *prism* region used with the create_box command must -have tilt factors (xy,xz,yz) that do not skew the box more than half -the distance of the parallel box length. For example, if xlo = 2 and -xhi = 12, then the x box length is 10 and the xy tilt factor must be -between -5 and 5. Similarly, both xz and yz must be between --(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, -since if the maximum tilt factor is 5 (as in this example), then -configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all -geometrically equivalent. If you wish to define a box with tilt +have tilt factors :math:`(xy,xz,yz)` that do not skew the box more than half +the distance of the parallel box length. For example, if +:math:`x_\text{lo} = 2` and :math:`x_\text{hi} = 12`, then the :math:`x` +box length is 10 and the :math:`xy` tilt factor must be between :math:`-5` and +:math:`5`. Similarly, both :math:`xz` and :math:`yz` must be between +:math:`-(x_\text{hi}-x_\text{lo})/2` and :math:`+(y_\text{hi}-y_\text{lo})/2`. +Note that this is not a limitation, since if the maximum tilt factor is 5 (as +in this example), then configurations with tilt :math:`= \dots, -15`, +:math:`-5`, :math:`5`, :math:`15`, :math:`25, \dots` +are all geometrically equivalent. If you wish to define a box with tilt factors that exceed these limits, you can use the :doc:`box tilt ` command, with a setting of *large*\ ; a setting of *small* is the default. @@ -81,18 +86,19 @@ geometric description of triclinic boxes, as defined by LAMMPS, and how to transform these parameters to and from other commonly used triclinic representations. -When a prism region is used, the simulation domain should normally be -periodic in the dimension that the tilt is applied to, which is given -by the second dimension of the tilt factor (e.g. y for xy tilt). This -is so that pairs of atoms interacting across that boundary will have -one of them shifted by the tilt factor. Periodicity is set by the -:doc:`boundary ` command. For example, if the xy tilt factor -is non-zero, then the y dimension should be periodic. Similarly, the -z dimension should be periodic if xz or yz is non-zero. LAMMPS does -not require this periodicity, but you may lose atoms if this is not +When a prism region is used, the simulation domain should normally be periodic +in the dimension that the tilt is applied to, which is given by the second +dimension of the tilt factor (e.g., :math:`y` for :math:`xy` tilt). This is so +that pairs of atoms interacting across that boundary will have one of them +shifted by the tilt factor. Periodicity is set by the +:doc:`boundary ` command. For example, if the :math:`xy` tilt factor +is non-zero, then the :math:`y` dimension should be periodic. Similarly, the +:math:`z` dimension should be periodic if :math:`xz` or :math:`yz` is non-zero. +LAMMPS does not require this periodicity, but you may lose atoms if this is not the case. -Also note that if your simulation will tilt the box, e.g. via the :doc:`fix deform ` command, the simulation box must be setup to +Note that if your simulation will tilt the box (e.g., via the +:doc:`fix deform ` command), the simulation box must be set up to be triclinic, even if the tilt factors are initially 0.0. You can also change an orthogonal box to a triclinic box or vice versa by using the :doc:`change box ` command with its *ortho* and @@ -103,11 +109,11 @@ using the :doc:`change box ` command with its *ortho* and If the system is non-periodic (in a dimension), then you should not make the lo/hi box dimensions (as defined in your :doc:`region ` command) radically smaller/larger than the extent - of the atoms you eventually plan to create, e.g. via the - :doc:`create_atoms ` command. For example, if your atoms - extend from 0 to 50, you should not specify the box bounds as -10000 - and 10000. This is because as described above, LAMMPS uses the - specified box size to layout the 3d grid of processors. A huge + of the atoms you eventually plan to create (e.g., via the + :doc:`create_atoms ` command). For example, if your atoms + extend from 0 to 50, you should not specify the box bounds as :math:`-10000` + and :math:`10000`. This is because as described above, LAMMPS uses the + specified box size to lay out 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 @@ -119,23 +125,25 @@ using the :doc:`change box ` command with its *ortho* and The optional keywords can be used to create a system that allows for bond (angle, dihedral, improper) interactions, or for molecules with -special 1-2,1-3,1-4 neighbors to be added later. These optional +special 1--2, 1--3, or 1--4 neighbors to be added later. These optional keywords serve the same purpose as the analogous keywords that can be used in a data file which are recognized by the :doc:`read_data ` command when it sets up a system. Note that if these keywords are not used, then the create_box command creates an atomic (non-molecular) simulation that does not allow bonds -between pairs of atoms to be defined, or a :doc:`bond potential ` to be specified, or for molecules with +between pairs of atoms to be defined, or a +:doc:`bond potential ` to be specified, or for molecules with special neighbors to be added to the system by commands such as :doc:`create_atoms mol `, :doc:`fix deposit ` or :doc:`fix pour `. As an example, see the examples/deposit/in.deposit.molecule script, which deposits molecules onto a substrate. Initially there are no -molecules in the system, but they are added later by the :doc:`fix deposit ` command. The create_box command in the +molecules in the system, but they are added later by the +:doc:`fix deposit ` command. The create_box command in the script uses the bond/types and extra/bond/per/atom keywords to allow -this. If the added molecule contained more than 1 special bond +this. If the added molecule contained more than one special bond (allowed by default), an extra/special/per/atom keyword would also need to be specified. diff --git a/doc/src/delete_atoms.rst b/doc/src/delete_atoms.rst index f70570c040..3f0295f524 100644 --- a/doc/src/delete_atoms.rst +++ b/doc/src/delete_atoms.rst @@ -62,7 +62,7 @@ Description Delete the specified atoms. This command can be used, for example, to carve out voids from a block of material or to delete created atoms -that are too close to each other (e.g. at a grain boundary). +that are too close to each other (e.g., at a grain boundary). For style *group*, all atoms belonging to the group are deleted. @@ -78,7 +78,7 @@ first group specified and the other atom is in the second group are considered. The atom that is in the first group is the one that is deleted. -Note that it is OK for the two group IDs to be the same (e.g. group +Note that it is OK for the two group IDs to be the same (e.g., group *all*\ ), or for some atoms to be members of both groups. In these cases, either atom in the pair may be deleted. Also note that if there are atoms which are members of both groups, the only guarantee @@ -147,7 +147,7 @@ interactions, is one where the topology of the interactions is typically defined in the data file read by the :doc:`read_data ` command, and where the interactions themselves are defined with the :doc:`bond_style `, :doc:`angle_style -`, etc commands. If you delete atoms from such a system, +`, etc. commands. If you delete atoms from such a system, you must be careful not to end up with bonded interactions that are stored by remaining atoms but which include deleted atoms. This will cause LAMMPS to generate a "missing atoms" error when the bonded @@ -158,7 +158,7 @@ It the *bond* keyword is set to *yes* then any bond or angle or dihedral or improper interaction that includes a deleted atom is also removed from the lists of such interactions stored by non-deleted atoms. Note that simply deleting interactions due to dangling bonds -(e.g. at a surface) may result in a inaccurate or invalid model for +(e.g., at a surface) may result in a inaccurate or invalid model for the remaining atoms. It the *mol* keyword is set to *yes*, then for every atom that is @@ -182,17 +182,17 @@ Restrictions The *overlap* styles requires inter-processor communication to acquire ghost atoms and build a neighbor list. This means that your system must be ready to perform a simulation before using this command (force -fields setup, atom masses set, etc). Since a neighbor list is used to +fields setup, atom masses set, etc.). Since a neighbor list is used to find overlapping atom pairs, it also means that you must define a :doc:`pair style ` with the minimum force cutoff distance between any pair of atoms types (plus the :doc:`neighbor ` -skin) >= the specified overlap cutoff. +skin) :math:`\ge` the specified overlap cutoff. If the :doc:`special_bonds ` command is used with a -setting of 0, then a pair of bonded atoms (1-2, 1-3, or 1-4) will not +setting of 0, then a pair of bonded atoms (1--2, 1--3, or 1--4) will not appear in the neighbor list, and thus will not be considered for -deletion by the *overlap* styles. You probably don't want to be -deleting one atom in a bonded pair anyway. +deletion by the *overlap* styles. You probably do not want to +delete one atom in a bonded pair anyway. The *bond yes* option cannot be used with molecular systems defined using molecule template files via the :doc:`molecule ` and diff --git a/doc/src/delete_bonds.rst b/doc/src/delete_bonds.rst index 5603214b2f..ac2ffb3452 100644 --- a/doc/src/delete_bonds.rst +++ b/doc/src/delete_bonds.rst @@ -39,8 +39,8 @@ Examples Description """"""""""" -Turn off (or on) molecular topology interactions, i.e. bonds, angles, -dihedrals, impropers. This command is useful for deleting +Turn off (or on) molecular topology interactions (i.e., bonds, angles, +dihedrals, and/or impropers). This command is useful for deleting interactions that have been previously turned off by bond-breaking potentials. It is also useful for turning off topology interactions between frozen or rigid atoms. Pairwise interactions can be turned @@ -54,15 +54,15 @@ keyword to change the behavior. Several of the styles (\ *atom*, *bond*, *angle*, *dihedral*, *improper*\ ) take a *type* as an argument. The specified *type* should -be an integer from 0 to N, where N is the number of relevant types -(atom types, bond types, etc). A value of 0 is only relevant for +be an integer from 0 to :math:`N`, where :math:`N` is the number of relevant +types (atom types, bond types, etc.). A value of 0 is only relevant for style *bond*\ ; see details below. In all cases, a wildcard asterisk can be used in place of or in conjunction with the *type* argument to -specify a range of types. This takes the form "\*" or "\*n" or "n\*" or -"m\*n". If N = the number of types, then an asterisk with no numeric -values means all types from 0 to N. A leading asterisk means all +specify a range of types. This takes the form "\*" or "\*n" or "m\*" or +"m\*n". If :math:`N` is the number of types, then an asterisk with no numeric +values means all types from 0 to :math:`N`. A leading asterisk means all types from 0 to n (inclusive). A trailing asterisk means all types -from n to N (inclusive). A middle asterisk means all types from m to +from m to N (inclusive). A middle asterisk means all types from m to n (inclusive). Note that it is fine to include a type of 0 for non-bond styles; it will simply be ignored. @@ -79,7 +79,8 @@ must also be of the specified type. Styles *angle*, *dihedral*, and For style *bond*, you can set the type to 0 to delete bonds that have been previously broken by a bond-breaking potential (which sets the -bond type to 0 when a bond is broken); e.g. see the :doc:`bond_style quartic ` command. +bond type to 0 when a bond is broken); for example, see the +:doc:`bond_style quartic ` command. For style *stats* no interactions are turned off (or on); the status of all interactions in the specified group is simply reported. This @@ -88,19 +89,19 @@ bond-breaking potential during a previous run. The default behavior of the delete_bonds command is to turn off interactions by toggling their type to a negative value, but not to -permanently remove the interaction. E.g. a bond_type of 2 is set to --2. The neighbor list creation routines will not include such an +permanently remove the interaction. For example, a bond_type of 2 is set to +:math:`-2.` The neighbor list creation routines will not include such an interaction in their interaction lists. The default is also to not -alter the list of 1-2, 1-3, 1-4 neighbors computed by the +alter the list of 1--2, 1--3, or 1--4 neighbors computed by the :doc:`special_bonds ` command and used to weight pairwise force and energy calculations. This means that pairwise computations -will proceed as if the bond (or angle, etc) were still turned on. +will proceed as if the bond (or angle, etc.) were still turned on. Several keywords can be appended to the argument list to alter the default behaviors. The *any* keyword changes the requirement that all atoms in the bond -(angle, etc) must be in the specified group in order to turn-off the +(angle, etc) must be in the specified group in order to turn off the interaction. Instead, if any of the atoms in the interaction are in the specified group, it will be turned off (or on if the *undo* keyword is used). @@ -109,42 +110,43 @@ The *undo* keyword inverts the delete_bonds command so that the specified bonds, angles, etc are turned on if they are currently turned off. This means a negative value is toggled to positive. For example, for style *angle*, if *type* is specified as 2, then all -angles with current type = -2, are reset to type = 2. Note that the -:doc:`fix shake ` command also sets bond and angle types -negative, so this option should not be used on those interactions. +angles with current type = :math:`-2` are reset to type = :math:`2`. +Note that the :doc:`fix shake ` command also sets bond and angle +types negative, so this option should not be used on those interactions. The *remove* keyword is invoked at the end of the delete_bonds -operation. It causes turned-off bonds (angles, etc) to be removed +operation. It causes turned-off bonds (angles, etc.) to be removed from each atom's data structure and then adjusts the global bond -(angle, etc) counts accordingly. Removal is a permanent change; +(angle, etc.) counts accordingly. Removal is a permanent change; removed bonds cannot be turned back on via the *undo* keyword. -Removal does not alter the pairwise 1-2, 1-3, 1-4 weighting list. +Removal does not alter the pairwise 1--2, 1--3, or 1--4 weighting list. The *special* keyword is invoked at the end of the delete_bonds -operation, after (optional) removal. It re-computes the pairwise 1-2, -1-3, 1-4 weighting list. The weighting list computation treats +operation, after (optional) removal. It re-computes the pairwise 1--2, +1--3, 1--4 weighting list. The weighting list computation treats turned-off bonds the same as turned-on. Thus, turned-off bonds must be removed if you wish to change the weighting list. Note that the choice of *remove* and *special* options affects how -1-2, 1-3, 1-4 pairwise interactions will be computed across bonds that +1--2, 1--3, 1--4 pairwise interactions will be computed across bonds that have been modified by the delete_bonds command. Restrictions """""""""""" This command requires inter-processor communication to acquire ghost -atoms, to coordinate the deleting of bonds, angles, etc between atoms +atoms, to coordinate the deleting of bonds, angles, etc. between atoms shared by multiple processors. This means that your system must be ready to perform a simulation before using this command (force fields -setup, atom masses set, etc). Just as would be needed to run +setup, atom masses set, etc.). Just as would be needed to run dynamics, the force field you define should define a cutoff -(e.g. through a :doc:`pair_style ` command) which is long +(e.g., through a :doc:`pair_style ` command) which is long enough for a processor to acquire the ghost atoms its needs to compute -bond, angle, etc interactions. +bond, angle, etc. interactions. -If deleted bonds (angles, etc) are removed but the 1-2, 1-3, 1-4 -weighting list is not re-computed, this can cause a later :doc:`fix shake ` command to fail due to an atom's bonds being +If deleted bonds (or angles, etc.) are removed but the 1--2, 1--3, and 1--4 +weighting list is not recomputed, this can cause a later +:doc:`fix shake ` command to fail due to an atom's bonds being inconsistent with the weighting list. This should only happen if the group used in the fix command includes both atoms in the bond, in which case you probably should be recomputing the weighting list. diff --git a/doc/src/dielectric.rst b/doc/src/dielectric.rst index bd4f4dff56..09bd9ef1cf 100644 --- a/doc/src/dielectric.rst +++ b/doc/src/dielectric.rst @@ -6,7 +6,7 @@ dielectric command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS dielectric value @@ -25,9 +25,9 @@ Description Set the dielectric constant for Coulombic interactions (pairwise and long-range) to this value. The constant is unitless, since it is used to reduce the strength of the interactions. The value is used in the -denominator of the formulas for Coulombic interactions - e.g. a value +denominator of the formulas for Coulombic interactions (e.g., a value of 4.0 reduces the Coulombic interactions to 25% of their default -strength. See the :doc:`pair_style ` command for more +strength). See the :doc:`pair_style ` command for more details. Restrictions diff --git a/doc/src/dihedral_coeff.rst b/doc/src/dihedral_coeff.rst index b60c3c3d6c..782f9c5571 100644 --- a/doc/src/dihedral_coeff.rst +++ b/doc/src/dihedral_coeff.rst @@ -33,10 +33,10 @@ Dihedral coefficients can also be set in the data file read by the N can be specified in one of two ways. An explicit numeric value can be used, as in the first example above. Or a wild-card asterisk can be used to set the coefficients for multiple dihedral types. This takes the -form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of dihedral types, -then an asterisk with no numeric values means all types from 1 to N. A -leading asterisk means all types from 1 to n (inclusive). A trailing -asterisk means all types from n to N (inclusive). A middle asterisk +form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N` is the number of dihedral +types, then an asterisk with no numeric values means all types from 1 to +:math:`N`. A leading asterisk means all types from 1 to n (inclusive). A +trailing asterisk means all types from m to N (inclusive). A middle asterisk means all types from m to n (inclusive). Note that using a dihedral_coeff command can override a previous setting @@ -51,7 +51,7 @@ for all dihedral types, then overwrite the coeffs for just dihedral type 2: A line in a data file that specifies dihedral coefficients uses the exact same format as the arguments of the dihedral_coeff command in an input script, except that wild-card asterisks should not be used since -coefficients for all N types must be listed in the file. For example, +coefficients for all :math:`N` types must be listed in the file. For example, under the "Dihedral Coeffs" section of a data file, the line that corresponds to the first example above would be listed as @@ -69,11 +69,11 @@ page for details. When comparing the formulas and coefficients for various LAMMPS dihedral styles with dihedral equations defined by other force fields, note that some force field implementations divide/multiply the energy - prefactor *K* by the multiple number of torsions that contain the J-K - bond in an I-J-K-L torsion. LAMMPS does not do this, i.e. the listed - dihedral equation applies to each individual dihedral. Thus you need - to define *K* appropriately to account for this difference if - necessary. + prefactor *K* by the multiple number of torsions that contain the + *J*\ --\ *K* bond in an *I*\ -\ *J*\ -\ *K*\ -\ *L* torsion. LAMMPS does + not do this (i.e., the listed dihedral equation applies to each individual + dihedral). Thus, you need to define *K* appropriately to account for this + difference, if necessary. ---------- diff --git a/doc/src/dihedral_style.rst b/doc/src/dihedral_style.rst index 3fe88c0afe..4e56d1f787 100644 --- a/doc/src/dihedral_style.rst +++ b/doc/src/dihedral_style.rst @@ -51,7 +51,7 @@ to be re-specified. When both a dihedral and pair style is defined, the :doc:`special_bonds ` command often needs to be used to turn off (or weight) the pairwise interaction that would otherwise - exist between 4 bonded atoms. + exist between four bonded atoms. In the formulas listed for each dihedral style, *phi* is the torsional angle defined by the quadruplet of atoms. This angle has a sign @@ -60,11 +60,11 @@ convention as shown in this diagram: .. image:: JPG/dihedral_sign.jpg :align: center -where the I,J,K,L ordering of the 4 atoms that define the dihedral +where the :math:`I,J,K,L` ordering of the four atoms that define the dihedral is from left to right. This sign convention effects several of the dihedral styles listed -below (e.g. charmm, helix) in the sense that the energy formula +below (e.g., charmm, helix) in the sense that the energy formula depends on the sign of phi, which may be reflected in the value of the coefficients you specify. @@ -73,10 +73,10 @@ coefficients you specify. When comparing the formulas and coefficients for various LAMMPS dihedral styles with dihedral equations defined by other force fields, note that some force field implementations divide/multiply the energy - prefactor *K* by the multiple number of torsions that contain the J-K - bond in an I-J-K-L torsion. LAMMPS does not do this, i.e. the listed - dihedral equation applies to each individual dihedral. Thus you need - to define *K* appropriately via the + prefactor *K* by the multiple number of torsions that contain the + *J*\ --\ *K* bond in an *I*\ --\ *J*\ --\ *K*\ --\ *L* torsion. LAMMPS does + not do this (i.e., the listed dihedral equation applies to each individual + dihedral). Thus, you need to define *K* appropriately via the :doc:`dihedral_coeff ` command to account for this difference if necessary. @@ -93,8 +93,9 @@ command. There are also additional accelerated pair styles included in the LAMMPS distribution for faster performance on CPUs, GPUs, and KNLs. -The individual style names on the :ref:`Commands dihedral ` page are followed by one or -more of (g,i,k,o,t) to indicate which accelerated styles exist. +The individual style names on the :ref:`Commands dihedral ` page are +followed by one or more of (g,i,k,o,t) to indicate which accelerated styles +exist. * :doc:`none ` - turn off dihedral interactions * :doc:`zero ` - topology but no interactions diff --git a/doc/src/dimension.rst b/doc/src/dimension.rst index d22d3f19fa..bade4dd061 100644 --- a/doc/src/dimension.rst +++ b/doc/src/dimension.rst @@ -6,7 +6,7 @@ dimension command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS dimension N diff --git a/doc/src/displace_atoms.rst b/doc/src/displace_atoms.rst index fb9239d9de..d9bf367ec4 100644 --- a/doc/src/displace_atoms.rst +++ b/doc/src/displace_atoms.rst @@ -56,7 +56,7 @@ can be imposed on the system. Or two groups of atoms can be brought into closer proximity. The *move* style displaces the group of atoms by the specified 3d -displacement vector. Any of the 3 quantities defining the vector +displacement vector. Any of the three quantities defining the vector components can be specified as an equal-style or atom-style :doc:`variable `. If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, @@ -78,20 +78,20 @@ doc page for more details. The *ramp* style displaces atoms a variable amount in one dimension depending on the atom's coordinate in a (possibly) different dimension. For example, the second example command displaces atoms in -the x-direction an amount between 0.0 and 5.0 distance units. Each -atom's displacement depends on the fractional distance its y -coordinate is between 2.0 and 20.5. Atoms with y-coordinates outside +the *x*\ -direction an amount between 0.0 and 5.0 distance units. Each +atom's displacement depends on the fractional distance its *y* +coordinate is between 2.0 and 20.5. Atoms with *y*\ -coordinates outside those bounds will be moved the minimum (0.0) or maximum (5.0) amount. The *random* style independently moves each atom in the group by a -random displacement, uniformly sampled from a value between -dx and -+dx in the x dimension, and similarly for y and z. Random numbers are -used in such a way that the displacement of a particular atom is the -same, regardless of how many processors are being used. +random displacement, uniformly sampled from a value between :math:`-dx` and +:math:`+dx` in the *x* dimension, and similarly for *y* and *z*. +Random numbers are used in such a way that the displacement of a particular +atom is the same, regardless of how many processors are being used. The *rotate* style rotates each atom in the group by the angle *theta* -around a rotation axis *R* = (Rx,Ry,Rz) that goes through a point *P* = -(Px,Py,Pz). The direction of rotation for the atoms around the +around a rotation axis :math:`R = (R_x,R_y,R_z)` that goes through a point +:math:`P = (P_x,P_y,P_z)`. The direction of rotation for the atoms around the rotation axis is consistent with the right-hand rule: if your right-hand thumb points along *R*, then your fingers wrap around the axis in the direction of positive theta. @@ -104,10 +104,10 @@ atom's rotation. Distance units for displacements and the origin point of the *rotate* style are determined by the setting of *box* or *lattice* for the *units* keyword. *Box* means distance units as defined by the -:doc:`units ` command - e.g. Angstroms for *real* units. -*Lattice* means distance units are in lattice spacings. The -:doc:`lattice ` command must have been previously used to -define the lattice spacing. +:doc:`units ` command (e.g., :math:`\mathrm{\mathring A}` for +*real* or *metal* units). *Lattice* means distance units are in lattice +spacings. The :doc:`lattice ` command must have been previously used +to define the lattice spacing. ---------- @@ -139,7 +139,7 @@ Restrictions """""""""""" For a 2d simulation, only rotations around the a vector parallel to -the z-axis are allowed. +the :math:`z`-axis are allowed. Related commands """""""""""""""" diff --git a/doc/src/dump.rst b/doc/src/dump.rst index b0b7b7abae..0bef244e0c 100644 --- a/doc/src/dump.rst +++ b/doc/src/dump.rst @@ -176,10 +176,10 @@ Examples Description """"""""""" -Dump a snapshot of atom quantities to one or more files every N +Dump a snapshot of atom quantities to one or more files every :math:`N` timesteps in one of several styles. The *image* and *movie* styles are the exception: the *image* style renders a JPG, PNG, or PPM image file -of the atom configuration every N timesteps while the *movie* style +of the atom configuration every :math:`N` timesteps while the *movie* style combines and compresses them into a movie file; both are discussed in detail on the :doc:`dump image ` page. The timesteps on which dump output is written can also be controlled by a variable. @@ -188,8 +188,7 @@ See the :doc:`dump_modify every ` command. Only information for atoms in the specified group is dumped. The :doc:`dump_modify thresh and region and refresh ` commands can also alter what atoms are included. Not all styles support -these options; see details on the :doc:`dump_modify ` doc -page. +these options; see details on the :doc:`dump_modify ` doc page. As described below, the filename determines the kind of output (text or binary or gzipped, one big file or one per timestep, one big file @@ -231,7 +230,7 @@ by the regular dump styles, which may be required on clusters where the interface to the high-speed network disallows using the fork() library call (which is needed for a pipe). For the remainder of this page, you should thus consider the *atom* and *atom/gz* styles -(etc) to be inter-changeable, with the exception of the required +(etc.) to be inter-changeable, with the exception of the required filename suffix. Similarly, the *atom/zstd*, *cfg/zstd*, *custom/zstd*, *local/zstd*, @@ -243,9 +242,9 @@ the compression level in both variants. As explained below, the *atom/mpiio*, *cfg/mpiio*, *custom/mpiio*, and *xyz/mpiio* styles are identical in command syntax and in the format of the dump files they create, to the corresponding styles without -"mpiio", except the single dump file they produce is written in +"mpiio," except the single dump file they produce is written in parallel via the MPI-IO library. For the remainder of this page, -you should thus consider the *atom* and *atom/mpiio* styles (etc) to +you should thus consider the *atom* and *atom/mpiio* styles (etc.) to be inter-changeable. The one exception is how the filename is specified for the MPI-IO styles, as explained below. @@ -285,16 +284,16 @@ For an orthogonal simulation box this information is formatted as: zlo zhi where xlo,xhi are the maximum extents of the simulation box in the -x-dimension, and similarly for y and z. The "xx yy zz" represent 6 -characters that encode the style of boundary for each of the 6 -simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi). Each of -the 6 characters is either p = periodic, f = fixed, s = shrink wrap, -or m = shrink wrapped with a minimum value. See the +:math:`x`-dimension, and similarly for :math:`y` and :math:`z`. The +"xx yy zz" terms are six characters that encode the style of boundary for each +of the sisx simulation box boundaries (xlo,xhi; ylo,yhi; and zlo,zhi). Each of +the six characters is either p (periodic), f (fixed), s (shrink wrap), +or m (shrink wrapped with a minimum value). See the :doc:`boundary ` command for details. For triclinic simulation boxes (non-orthogonal), an orthogonal bounding box which encloses the triclinic simulation box is output, -along with the 3 tilt factors (xy, xz, yz) of the triclinic box, +along with the 3 tilt factors (*xy*, *xz*, *yz*) of the triclinic box, formatted as follows: .. parsed-literal:: @@ -305,15 +304,15 @@ formatted as follows: zlo_bound zhi_bound yz The presence of the text "xy xz yz" in the ITEM line indicates that -the 3 tilt factors will be included on each of the 3 following lines. +the three tilt factors will be included on each of the three following lines. This bounding box is convenient for many visualization programs. The -meaning of the 6 character flags for "xx yy zz" is the same as above. +meaning of the six character flags for "xx yy zz" is the same as above. Note that the first two numbers on each line are now xlo_bound instead -of xlo, etc, since they represent a bounding box. See the :doc:`Howto +of xlo, etc. because they represent a bounding box. See the :doc:`Howto triclinic ` page for a geometric description of -triclinic boxes, as defined by LAMMPS, simple formulas for how the 6 -bounding box extents (xlo_bound,xhi_bound,etc) are calculated from the +triclinic boxes, as defined by LAMMPS, simple formulas for how the six +bounding box extents (xlo_bound, xhi_bound, etc.) are calculated from the triclinic parameters, and how to transform those parameters to and from other commonly used triclinic representations. @@ -324,8 +323,8 @@ attributes you specify in the dump command for the *custom* style. For style *atom*, atom coordinates are written to the file, along with the atom ID and atom type. By default, atom coords are written in a -scaled format (from 0 to 1). I.e. an x value of 0.25 means the atom -is at a location 1/4 of the distance from xlo to xhi of the box +scaled format (from 0 to 1). That is, an :math:`x` value of 0.25 means the +atom is at a location 1/4 of the distance from *xlo* to *xhi* of the box boundaries. The format can be changed to unscaled coords via the :doc:`dump_modify ` settings. Image flags can also be added for each atom via dump_modify. @@ -344,11 +343,11 @@ For style *local*, local output generated by :doc:`computes ` and :doc:`fixes ` is used to generate lines of output that is written to the dump file. This local data is typically calculated by each processor based on the atoms it owns, but there may be zero or -more entities per atom, e.g. a list of bond distances. An explanation +more entities per atom (e.g., a list of bond distances). An explanation of the possible dump local attributes is given below. Note that by using input from the :doc:`compute property/local ` command with dump local, it is possible to -generate information on bonds, angles, etc that can be cut and pasted +generate information on bonds, angles, etc. that can be cut and pasted directly into a data file read by the :doc:`read_data ` command. @@ -408,18 +407,17 @@ The *xyz* style writes XYZ files, which is a simple text-based coordinate format that many codes can read. Specifically it has a line with the number of atoms, then a comment line that is usually ignored followed by one line per atom with the atom type -and the x-, y-, and z-coordinate of that atom. You can use the -:doc:`dump_modify element ` option to change the output -from using the (numerical) atom type to an element name (or some -other label). This will help many visualization programs to guess -bonds and colors. +and the :math:`x`-, :math:`y`-, and :math:`z`-coordinate of that atom. +You can use the :doc:`dump_modify element ` option to change the +output from using the (numerical) atom type to an element name (or some other +label). This will help many visualization programs to guess bonds and colors. .. versionadded:: 4May2022 Dump style *yaml* has the same command syntax as style *custom* and writes YAML format files that can be easily parsed by a variety of data processing tools and programming languages. Each timestep will be -written as a YAML "document" (i.e. starts with "---" and ends with +written as a YAML "document" (i.e., starts with "---" and ends with "..."). The style supports writing one file per timestep through the "\*" wildcard but not multi-processor outputs with the "%" token in the filename. In addition to per-atom data, :doc:`thermo ` data can @@ -435,14 +433,14 @@ Below is an example for a YAML format dump created by the following commands. dump out all yaml 100 dump.yaml id type x y z vx vy vz ix iy iz dump_modify out time yes units yes thermo yes format 1 %5d format "% 10.6e" -The tags "time", "units", and "thermo" are optional and enabled by the -dump_modify command. The list under the "box" tag has 3 lines for -orthogonal boxes and 4 lines with triclinic boxes, where the first 3 are -the box boundaries and the 4th the three tilt factors (xy, xz, yz). The -"thermo" data follows the format of the *yaml* thermo style. The -"keywords" tag lists the per-atom properties contained in the "data" -columns, which contain a list with one line per atom. The keywords may -be renamed using the dump_modify command same as for the *custom* dump +The tags "time," "units," and "thermo" are optional and enabled by the +dump_modify command. The list under the "box" tag has three lines for +orthogonal boxes and four lines for triclinic boxes, where the first three are +the box boundaries and the fourth the three tilt factors (:math:`xy`, +:math:`xz`, :math:`yz`). The "thermo" data follows the format of the *yaml* +thermo style. The "keywords" tag lists the per-atom properties contained in +the "data" columns, which contain a list with one line per atom. The keywords +may be renamed using the dump_modify command same as for the *custom* dump style. .. code-block:: yaml @@ -487,14 +485,14 @@ popular molecular viewing program. ---------- -Dumps are performed on timesteps that are a multiple of N (including +Dumps are performed on timesteps that are a multiple of :math:`N` (including timestep 0) and on the last timestep of a minimization if the minimization converges. Note that this means a dump will not be performed on the initial timestep after the dump command is invoked, -if the current timestep is not a multiple of N. This behavior can be +if the current timestep is not a multiple of :math:`N`. This behavior can be changed via the :doc:`dump_modify first ` command, which can also be useful if the dump command is invoked after a minimization -ended on an arbitrary timestep. N can be changed between runs by +ended on an arbitrary timestep. :math:`N` can be changed between runs by using the :doc:`dump_modify every ` command (not allowed for *dcd* style). The :doc:`dump_modify every ` command also allows a variable to be used to determine the sequence of @@ -515,19 +513,19 @@ For example, tmp.dump.\* becomes tmp.dump.0, tmp.dump.10000, tmp.dump.20000, etc. This option is not available for the *dcd* and *xtc* styles. Note that the :doc:`dump_modify pad ` command can be used to insure all timestep numbers are the same length -(e.g. 00010), which can make it easier to read a series of dump files +(e.g., 00010), which can make it easier to read a series of dump files in order with some post-processing tools. If a "%" character appears in the filename, then each of P processors writes a portion of the dump file, and the "%" character is replaced -with the processor ID from 0 to P-1. For example, tmp.dump.% becomes -tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc. This creates smaller -files and can be a fast mode of output on parallel machines that support -parallel I/O for output. This option is **not** available for the *dcd*, -*xtc*, *xyz*, and *yaml* styles. +with the processor ID from :math:`0` to :math:`P-1`. For example, tmp.dump.% +becomes tmp.dump.0, tmp.dump.1, ... tmp.dump.:math:`P-1`, etc. This creates +smaller files and can be a fast mode of output on parallel machines that +support parallel I/O for output. This option is **not** available for the +*dcd*, *xtc*, *xyz*, and *yaml* styles. -By default, P = the number of processors meaning one file per -processor, but P can be set to a smaller value via the *nfile* or +By default, :math:`P` is the the number of processors, meaning one file per +processor, but :math:`P` can be set to a smaller value via the *nfile* or *fileper* keywords of the :doc:`dump_modify ` command. These options can be the most efficient way of writing out dump files when running on large numbers of processors. @@ -539,15 +537,15 @@ For the *atom/mpiio*, *cfg/mpiio*, *custom/mpiio*, and *xyz/mpiio* styles, a single dump file is written in parallel via the MPI-IO library, which is part of the MPI standard for versions 2.0 and above. Using MPI-IO requires two steps. First, build LAMMPS with its MPIIO -package installed, e.g. +package installed, viz., .. code-block:: bash make yes-mpiio # installs the MPIIO package make mpi # build LAMMPS for your platform -Second, use a dump filename which contains ".mpiio". Note that it -does not have to end in ".mpiio", just contain those characters. +Second, use a dump filename which contains ".mpiio." Note that it +does not have to end in ".mpiio," just contain those characters. Unlike MPI-IO restart files, which must be both written and read using MPI-IO, the dump files produced by these MPI-IO styles are identical in format to the files produced by their non-MPI-IO style @@ -564,42 +562,41 @@ MPI-IO. Note that MPI-IO dump files are one large file which all processors write to. You thus cannot use the "%" wildcard character described above in the filename since that specifies generation of multiple -files. You can use the ".bin" or ".lammpsbin" suffix described below in an MPI-IO -dump file; again this file will be written in parallel and have the +files. You can use the ".bin" or ".lammpsbin" suffix described below in an +MPI-IO dump file; again this file will be written in parallel and have the same binary format as if it were written without MPI-IO. -If the filename ends with ".bin" or ".lammpsbin", the dump file (or files, if "\*" or -"%" is also used) is written in binary format. A binary dump file +If the filename ends with ".bin" or ".lammpsbin", the dump file (or files, if +"\*" or "%" is also used) is written in binary format. A binary dump file will be about the same size as a text version, but will typically write out much faster. Of course, when post-processing, you will need -to convert it back to text format (see the :ref:`binary2txt tool `) or write your own code to read the binary -file. The format of the binary file can be understood by looking at -the tools/binary2txt.cpp file. This option is only available for the -*atom* and *custom* styles. +to convert it back to text format (see the :ref:`binary2txt tool `) or +write your own code to read the binary file. The format of the binary file can +be understood by looking at the :file:`tools/binary2txt.cpp` file. This option +is only available for the *atom* and *custom* styles. If the filename ends with ".gz", the dump file (or files, if "\*" or "%" -is also used) is written in gzipped format. A gzipped dump file will -be about 3x smaller than the text version, but will also take longer -to write. This option is not available for the *dcd* and *xtc* -styles. +is also used) is written in gzipped format. A gzipped dump file will be about +:math:`3\times` smaller than the text version, but will also take longer +to write. This option is not available for the *dcd* and *xtc* styles. ---------- Note that in the discussion which follows, for styles which can reference values from a compute or fix or custom atom property, like -the *custom*\ , *cfg*\ , or *local* styles, the bracketed index I can +the *custom*\ , *cfg*\ , or *local* styles, the bracketed index :math:`i` can be specified using a wildcard asterisk with the index to effectively -specify multiple values. This takes the form "\*" or "\*n" or "n\*" -or "m\*n". If N = the number of columns in the array, then an -asterisk with no numeric values means all column indices from 1 to N. +specify multiple values. This takes the form "\*" or "\*n" or "m\*" +or "m\*n." If :math:`N` is the number of columns in the array, then an +asterisk with no numeric values means all column indices from 1 to :math:`N`. A leading asterisk means all indices from 1 to n (inclusive). A -trailing asterisk means all indices from n to N (inclusive). A middle +trailing asterisk means all indices from m to :math:`N` (inclusive). A middle asterisk means all indices from m to n (inclusive). Using a wildcard is the same as if the individual columns of the array -had been listed one by one. E.g. these 2 dump commands are +had been listed one by one. For example, these two dump commands are equivalent, since the :doc:`compute stress/atom ` -command creates a per-atom array with 6 columns: +command creates a per-atom array with six columns: .. code-block:: LAMMPS @@ -614,13 +611,12 @@ This section explains the local attributes that can be specified as part of the *local* style. The *index* attribute can be used to generate an index number from 1 -to N for each line written into the dump file, where N is the total -number of local datums from all processors, or lines of output that +to :math:`N` for each line written into the dump file, where :math:`N` is the +total number of local datums from all processors, or lines of output that will appear in the snapshot. Note that because data from different processors depend on what atoms they currently own, and atoms migrate between processor, there is no guarantee that the same index will be -used for the same info (e.g. a particular bond) in successive -snapshots. +used for the same info (e.g., a particular bond) in successive snapshots. The *c_ID* and *c_ID[I]* attributes allow local vectors or arrays calculated by a :doc:`compute ` to be output. The ID in the @@ -637,10 +633,10 @@ custom ` command, and per-atom quantities can be output by the dump custom command. If *c_ID* is used as a attribute, then the local vector calculated by -the compute is printed. If *c_ID[I]* is used, then I must be in the -range from 1-M, which will print the Ith column of the local array -with M columns calculated by the compute. See the discussion above -for how I can be specified with a wildcard asterisk to effectively +the compute is printed. If *c_ID[i]* is used, then :math:`i` must be in the +range from :math:`1-M`, which will print the Ith column of the local array +with :math:`M` columns calculated by the compute. See the discussion above +for how :math:`i` can be specified with a wildcard asterisk to effectively specify multiple values. The *f_ID* and *f_ID[I]* attributes allow local vectors or arrays @@ -649,11 +645,11 @@ should be replaced by the actual ID of the fix that has been defined previously in the input script. If *f_ID* is used as a attribute, then the local vector calculated by -the fix is printed. If *f_ID[I]* is used, then I must be in the -range from 1-M, which will print the Ith column of the local with M -columns calculated by the fix. See the discussion above for how I can -be specified with a wildcard asterisk to effectively specify multiple -values. +the fix is printed. If *f_ID[i]* is used, then :math:`i` must be in the +range :math:`1`--:math:`M`, which will print the :math:`i`\ th column of the +local with :math:`M` columns calculated by the fix. See the discussion above +for how :math:`i` can be specified with a wildcard asterisk to effectively +specify multiple values. Here is an example of how to dump bond info for a system, including the distance and energy of each bond: @@ -674,46 +670,47 @@ The *id*, *mol*, *proc*, *procp1*, *type*, *element*, *mass*, *vx*, *Id* is the atom ID. *Mol* is the molecule ID, included in the data file for molecular systems. *Proc* is the ID of the processor (0 to -Nprocs-1) that currently owns the atom. *Procp1* is the proc ID+1, -which can be convenient in place of a *type* attribute (1 to Ntypes) -for coloring atoms in a visualization program. *Type* is the atom -type (1 to Ntypes). *Element* is typically the chemical name of an -element, which you must assign to each type via the :doc:`dump_modify -element ` command. More generally, it can be any string -you wish to associated with an atom type. *Mass* is the atom mass. -*Vx*, *vy*, *vz*, *fx*, *fy*, *fz*, and *q* are components of atom -velocity and force and atomic charge. +:math:`N_\text{procs}-1`) that currently owns the atom. +*Procp1* is the proc ID+1, which can be convenient in place of a *type* +attribute (1 to :math:`N_\text{types}`) for coloring atoms in a visualization +program. *Type* is the atom type (1 to :math:`N_\text{types}`). *Element* is +typically the chemical name of an element, which you must assign to each type +via the :doc:`dump_modify element ` command. More generally, it +can be any string you wish to associated with an atom type. *Mass* is the atom +mass. The quantities *vx*, *vy*, *vz*, *fx*, *fy*, *fz*, and *q* are components +of atom velocity and force and atomic charge. There are several options for outputting atom coordinates. The *x*, -*y*, *z* attributes write atom coordinates "unscaled", in the -appropriate distance :doc:`units ` (Angstroms, sigma, etc). Use -*xs*, *ys*, *zs* if you want the coordinates "scaled" to the box size, -so that each value is 0.0 to 1.0. If the simulation box is triclinic -(tilted), then all atom coords will still be between 0.0 and 1.0. -I.e. actual unscaled (x,y,z) = xs\*A + ys\*B + zs\*C, where (A,B,C) are -the non-orthogonal vectors of the simulation box edges, as discussed -on the :doc:`Howto triclinic ` page. +*y*, and *z* attributes write atom coordinates "unscaled," in the +appropriate distance :doc:`units ` (:math:`\mathrm{\mathring A}`, +:math:`\sigma`, etc.). Use *xs*, *ys*, *zs* if you want the coordinates +"scaled" to the box size, so that each value is 0.0 to 1.0. If the simulation +box is triclinic (tilted), then all atom coords will still be between 0.0 and +1.0. The actual unscaled :math:`(x,y,z)` coordinate is +:math:`x_s a + y_s b + z_s c`, where :math:`(a,b,c)` are the non-orthogonal +vectors of the simulation box edges, as discussed on the +:doc:`Howto triclinic ` page. -Use *xu*, *yu*, *zu* if you want the coordinates "unwrapped" by the +Use *xu*, *yu*, and *zu* if you want the coordinates "unwrapped" by the image flags for each atom. Unwrapped means that if the atom has passed through a periodic boundary one or more times, the value is printed for what the coordinate would be if it had not been wrapped -back into the periodic box. Note that using *xu*, *yu*, *zu* means +back into the periodic box. Note that using *xu*, *yu*, and *zu* means that the coordinate values may be far outside the box bounds printed -with the snapshot. Using *xsu*, *ysu*, *zsu* is similar to using -*xu*, *yu*, *zu*, except that the unwrapped coordinates are scaled by +with the snapshot. Using *xsu*, *ysu*, and *zsu* is similar to using +*xu*, *yu*, and *zu*, except that the unwrapped coordinates are scaled by the box size. Atoms that have passed through a periodic boundary will have the corresponding coordinate increased or decreased by 1.0. -The image flags can be printed directly using the *ix*, *iy*, *iz* +The image flags can be printed directly using the *ix*, *iy*, and *iz* attributes. For periodic dimensions, they specify which image of the simulation box the atom is considered to be in. An image of 0 means it is inside the box as defined. A value of 2 means add 2 box lengths -to get the true value. A value of -1 means subtract 1 box length to +to get the true value. A value of :math:`-1` means subtract 1 box length to get the true value. LAMMPS updates these flags as atoms cross periodic boundaries during the simulation. -The *mux*, *muy*, *muz* attributes are specific to dipolar systems +The *mux*, *muy*, and *muz* attributes are specific to dipolar systems defined with an atom style of *dipole*\ . They give the orientation of the atom's point dipole moment. The *mu* attribute gives the magnitude of the atom's dipole moment. @@ -724,7 +721,7 @@ style of *sphere*\ . The *omegax*, *omegay*, and *omegaz* attributes are specific to finite-size spherical particles that have an angular velocity. Only -certain atom styles, such as *sphere* define this quantity. +certain atom styles, such as *sphere*, define this quantity. The *angmomx*, *angmomy*, and *angmomz* attributes are specific to finite-size aspherical particles that have an angular momentum. Only @@ -749,10 +746,10 @@ command. Instead, global quantities can be output by the can be output by the dump local command. If *c_ID* is used as a attribute, then the per-atom vector calculated -by the compute is printed. If *c_ID[I]* is used, then I must be in -the range from 1-M, which will print the Ith column of the per-atom -array with M columns calculated by the compute. See the discussion -above for how I can be specified with a wildcard asterisk to +by the compute is printed. If *c_ID[i]* is used, then :math:`i` must be in +the range from 1 to :math:`M`, which will print the :math:`i`\ th column of the +per-atom array with :math:`M` columns calculated by the compute. See the +discussion above for how :math:`i` can be specified with a wildcard asterisk to effectively specify multiple values. The *f_ID* and *f_ID[I]* attributes allow vector or array per-atom @@ -766,11 +763,11 @@ Since it can time-average per-atom quantities produced by any be written to a dump file. If *f_ID* is used as a attribute, then the per-atom vector calculated -by the fix is printed. If *f_ID[I]* is used, then I must be in the -range from 1-M, which will print the Ith column of the per-atom array -with M columns calculated by the fix. See the discussion above for -how I can be specified with a wildcard asterisk to effectively specify -multiple values. +by the fix is printed. If *f_ID[i]* is used, then :math:`i` must be in the +range from 1 to :math:`M`, which will print the :math:`i`\ th column of the +per-atom array with :math:`M` columns calculated by the fix. See the +discussion above for how :math:`i` can be specified with a wildcard asterisk to +effectively specify multiple values. The *v_name* attribute allows per-atom vectors calculated by a :doc:`variable ` to be output. The name in the attribute @@ -780,8 +777,7 @@ can be referenced, since it is the only style that generates per-atom values. Variables of style *atom* can reference individual atom attributes, per-atom attributes, thermodynamic keywords, or invoke other computes, fixes, or variables when they are evaluated, so this -is a very general means of creating quantities to output to a dump -file. +is a very general means of creating quantities to output to a dump file. The *i_name*, *d_name*, *i2_name*, *d2_name* attributes refer to per-atom integer and floating-point vectors or arrays that have been @@ -789,10 +785,10 @@ added via the :doc:`fix property/atom ` command. When that command is used specific names are given to each attribute which are the "name" portion of these keywords. For arrays *i2_name* and *d2_name*, the column of the array must also be included following -the name in brackets: e.g. d2_xyz[I], i2_mySpin[I], where I is in the -range from 1-M, where M is the number of columns in the custom array. -See the discussion above for how I can be specified with a wildcard -asterisk to effectively specify multiple values. +the name in brackets (e.g., d2_xyz[i], i2_mySpin[i], where :math:`i` is in the +range from 1 to :math:`M`, where :math:`M` is the number of columns in the +custom array). See the discussion above for how :math:`i` can be specified with +a wildcard asterisk to effectively specify multiple values. See the :doc:`Modify ` page for information on how to add new compute and fix styles to LAMMPS to calculate per-atom quantities @@ -807,9 +803,9 @@ To write gzipped dump files, you must either compile LAMMPS with the -DLAMMPS_GZIP option or use the styles from the COMPRESS package. See the :doc:`Build settings ` page for details. -While a dump command is active (i.e. has not been stopped by using -the undump command), no commands may be used that will change the -timestep (e.g. :doc:`reset_timestep `). LAMMPS +While a dump command is active (i.e., has not been stopped by using +the :doc:`undump command `), no commands may be used that will change +the timestep (e.g., :doc:`reset_timestep `). LAMMPS will terminate with an error otherwise. The *atom/gz*, *cfg/gz*, *custom/gz*, and *xyz/gz* styles are part of @@ -822,7 +818,7 @@ are part of the MPIIO package. They are only enabled if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. -The *xtc*, *dcd* and *yaml* styles are part of the EXTRA-DUMP package. +The *xtc*, *dcd*, and *yaml* styles are part of the EXTRA-DUMP package. They are only enabled if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. @@ -832,7 +828,8 @@ Related commands :doc:`dump atom/adios `, :doc:`dump custom/adios `, :doc:`dump cfg/uef `, :doc:`dump h5md `, :doc:`dump image `, :doc:`dump molfile `, -:doc:`dump_modify `, :doc:`undump `, :doc:`write_dump ` +:doc:`dump_modify `, :doc:`undump `, +:doc:`write_dump ` Default """"""" diff --git a/doc/src/dump_modify.rst b/doc/src/dump_modify.rst index 1fac32e426..371944d8da 100644 --- a/doc/src/dump_modify.rst +++ b/doc/src/dump_modify.rst @@ -33,7 +33,7 @@ Syntax *delay* arg = Dstep Dstep = delay output until this timestep *element* args = E1 E2 ... EN, where N = # of atom types - E1,...,EN = element name, e.g. C or Fe or Ga + E1,...,EN = element name (e.g., C or Fe or Ga) *every* arg = N N = dump every this many timesteps N can be a variable (see below) @@ -53,7 +53,7 @@ Syntax *no* to not write the header *image* arg = *yes* or *no* *label* arg = string - string = character string (e.g. BONDS) to use in header of dump local file + string = character string (e.g., BONDS) to use in header of dump local file *maxfiles* arg = Fmax Fmax = keep only the most recent *Fmax* snapshots (one snapshot per file) *nfile* arg = Nf @@ -153,8 +153,8 @@ be used if the *append yes* keyword is also used. The *N* argument is the index of which frame to append to. A negative value can be specified for *N*, which means a frame counted from the end of the file. The *at* keyword can only be used if the dump_modify command is -before the first command that causes dump snapshots to be output, -e.g. a :doc:`run ` or :doc:`minimize ` command. Once the +before the first command that causes dump snapshots to be output +(e.g., a :doc:`run ` or :doc:`minimize ` command). Once the dump file has been opened, this keyword has no further effect. ---------- @@ -185,7 +185,7 @@ during an equilibration phase. ---------- The *element* keyword applies only to the dump *cfg*, *xyz*, and -*image* styles. It associates element names (e.g. H, C, Fe) with +*image* styles. It associates element names (e.g., H, C, Fe) with LAMMPS atom types. See the list of element names at the bottom of this page. @@ -262,7 +262,7 @@ in file tmp.times: When using a file-style variable with the *every* keyword, the file of timesteps must list a first timestep that is beyond the - current timestep (e.g. it cannot be 0). And it must list one or more + current timestep (e.g., it cannot be 0). And it must list one or more timesteps beyond the length of the run you perform. This is because the dump command will generate an error if the next timestep it reads from the file is not a value greater than the current timestep. Thus @@ -275,10 +275,10 @@ in file tmp.times: The *every/time* keyword can be used with any dump style except the *dcd* and *xtc* styles. It does two things. It specifies that the -interval between dump snapshots will be set in simulation time, -i.e. in time units of the :doc:`units ` command. This can be -useful when the timestep size varies during a simulation run, e.g. by -use of the :doc:`fix dt/reset ` command. The default is +interval between dump snapshots will be set in simulation time +(i.e. in time units of the :doc:`units ` command). This can be +useful when the timestep size varies during a simulation run (e.g., by +use of the :doc:`fix dt/reset ` command). The default is to specify the interval in timesteps; see the *every* keyword. The *every/time* command also sets the interval value. @@ -340,7 +340,7 @@ file tmp.times: When using a file-style variable with the *every/time* keyword, the file of timesteps must list a first time that is beyond the time - associated with the current timestep (e.g. it cannot be 0.0). And + associated with the current timestep (e.g., it cannot be 0.0). And it must list one or more times beyond the length of the run you perform. This is because the dump command will generate an error if the next time it reads from the file is not a value greater than @@ -409,16 +409,16 @@ by the text-based dump styles: *atom*, *local*, *custom*, *cfg*, and *xyz* styles, and their MPIIO variants. Only the *line* or *none* options can be used with the *atom* and *xyz* styles. -All the specified format strings are C-style formats, e.g. as used by +All the specified format strings are C-style formats, such as used by the C/C++ printf() command. The *line* keyword takes a single argument which is the format string for an entire line of output for -each atom (do not include a trailing "\n"), with N fields, which you -must enclose in quotes if it is more than one field. The *int* and +each atom (do not include a trailing "\n"), with :math:`N` fields, which you +must enclose in quotes if there is more than one field. The *int* and *float* keywords take a single format argument and are applied to all -integer or floating-point quantities output. The setting for *M -string* also takes a single format argument which is used for the Mth -value output in each line, e.g. the fifth column is output in high -precision for "format 5 %20.15g". +integer or floating-point quantities output. The setting for *M string* +also takes a single format argument which is used for the :math:`M`\ th +value output in each line (e.g., the fifth column is output in high +precision by "format 5 %20.15g"). .. note:: @@ -442,7 +442,7 @@ settings, reverting all values to their default format. corresponding 8-byte form if it is needed when outputting those values. However, when specifying the *line* option or *format M string* option for those values, you should specify a format string - appropriate for an 8-byte signed integer, e.g. one with "%ld", if + appropriate for an 8-byte signed integer (e.g., one with "%ld") if LAMMPS was compiled with the -DLAMMPS_BIGBIG option for 8-byte IDs. .. note:: @@ -462,7 +462,7 @@ settings, reverting all values to their default format. will output the two atom IDs for atoms in each bond as integers. If the dump_modify command were omitted, they would appear as -floating-point values, assuming they were large integers (more than 6 +floating-point values, assuming they were large integers (more than six digits). The "index" keyword should use the "%d" format since it is not generated by a compute or fix, and is stored internally as an integer. @@ -482,43 +482,43 @@ information typically written to the header. ---------- The *image* keyword applies only to the dump *atom* style. If the -image value is *yes*, 3 flags are appended to each atom's coords which +image value is *yes*, three flags are appended to each atom's coords which are the absolute box image of the atom in each dimension. For -example, an x image flag of -2 with a normalized coord of 0.5 means -the atom is in the center of the box, but has passed through the box -boundary 2 times and is really 2 box lengths to the left of its +example, an :math:`x` image flag of :math:`-2` with a normalized coord of 0.5 +means the atom is in the center of the box, but has passed through the box +boundary twice and is really two box lengths to the left of its current coordinate. Note that for dump style *custom* these various values can be printed in the dump file by using the appropriate atom attributes in the dump command itself. ---------- -The *label* keyword applies only to the dump *local* style. When -it writes local information, such as bond or angle topology -to a dump file, it will use the specified *label* to format -the header. By default this includes 2 lines: +The *label* keyword applies only to the dump *local* style. +When it writes local information, such as bond or angle topology +to a dump file, it will use the specified *label* to format the header. +By default this includes two lines: .. parsed-literal:: ITEM: NUMBER OF ENTRIES ITEM: ENTRIES ... -The word "ENTRIES" will be replaced with the string specified, -e.g. BONDS or ANGLES. +The word "ENTRIES" will be replaced with the string specified +(e.g., BONDS or ANGLES). ---------- The *maxfiles* keyword can only be used when a '\*' wildcard is -included in the dump file name, i.e. when writing a new file(s) for -each snapshot. The specified *Fmax* is how many snapshots will be +included in the dump file name (i.e., when writing a new file(s) for +each snapshot). The specified *Fmax* is how many snapshots will be kept. Once this number is reached, the file(s) containing the oldest snapshot is deleted before a new dump file is written. If the -specified *Fmax* <= 0, then all files are retained. +specified :math:`\text{Fmax} \le 0`, then all files are retained. -This can be useful for debugging, especially if you don't know on what -timestep something bad will happen, e.g. when LAMMPS will exit with an -error. You can dump every timestep, and limit the number of dump -files produced, even if you run for 1000s of steps. +This can be useful for debugging, especially if you do not know on what +timestep something bad will happen (e.g., when LAMMPS will exit with an +error). You can dump every time step and limit the number of dump +files produced, even if you run for thousands of steps. ---------- @@ -527,28 +527,29 @@ The *nfile* or *fileper* keywords can be used in conjunction with the styles except the *dcd*, *image*, *movie*, *xtc*, and *xyz* styles (for which "%" is not allowed). As explained on the :doc:`dump ` command doc page, the "%" character causes the dump file to be written -in pieces, one piece for each of P processors. By default P = the -number of processors the simulation is running on. The *nfile* or -*fileper* keyword can be used to set P to a smaller value, which can +in pieces, one piece for each of :math:`P` processors. By default, :math:`P` +is the number of processors the simulation is running on. The *nfile* or +*fileper* keyword can be used to set :math:`P` to a smaller value, which can be more efficient when running on a large number of processors. -The *nfile* keyword sets P to the specified Nf value. For example, if -Nf = 4, and the simulation is running on 100 processors, 4 files will -be written, by processors 0,25,50,75. Each will collect information -from itself and the next 24 processors and write it to a dump file. +The *nfile* keyword sets :math:`P` to the specified :math:`N_f` value. +For example, if :math:`N_f = 4`, and the simulation is running on 100 +processors, four files will be written by processors 0, 25, 50, and 75. +Each will collect information from itself and the next 24 processors and write +it to a dump file. -For the *fileper* keyword, the specified value of Np means write one -file for every Np processors. For example, if Np = 4, every fourth -processor (0,4,8,12,etc) will collect information from itself and the -next 3 processors and write it to a dump file. +For the *fileper* keyword, the specified value of :math:`N_p` means write one +file for every :math:`N_p` processors. For example, if :math:`N_p = 4`, +every fourth processor (0, 4, 8, 12, etc.) will collect information from itself +and the next three processors and write it to a dump file. ---------- The *pad* keyword only applies when the dump filename is specified with a wildcard "\*" character which becomes the timestep. If *pad* is 0, which is the default, the timestep is converted into a string of -unpadded length, e.g. 100 or 12000 or 2000000. When *pad* is -specified with *Nchar* > 0, the string is padded with leading zeroes +unpadded length (e.g., 100 or 12000 or 2000000). When *pad* is +specified with *Nchar* :math:`>` 0, the string is padded with leading zeroes so they are all the same length = *Nchar*\ . For example, pad 7 would yield 0000100, 0012000, 2000000. This can be useful so that post-processing programs can easily read the files in ascending @@ -570,9 +571,9 @@ because it requires no extra computation. ---------- The *precision* keyword only applies to the dump *xtc* style. A -specified value of N means that coordinates are stored to 1/N -nanometer accuracy, e.g. for N = 1000, the coordinates are written to -1/1000 nanometer accuracy. +specified value of :math:`N` means that coordinates are stored to :math:`1/N` +nanometer accuracy (e.g., for :math:`N = 1000`, the coordinates are written to +:math:`1/1000` nanometer accuracy). ---------- @@ -582,7 +583,7 @@ be written, by refreshing a compute that is used as a threshold for determining which atoms are included in a dump snapshot. The specified *c_ID* gives the ID of the compute. It is prefixed by "c\_" to indicate a compute, which is the only current option. At some -point, other options may be added, e.g. fixes or variables. +point, other options may be added (e.g., fixes or variables). .. note:: @@ -615,19 +616,19 @@ commands: The :doc:`compute displace/atom ` command calculates the displacement of each atom from its reference position. -The "4" index is the scalar displacement; 1,2,3 are the xyz components -of the displacement. The :doc:`dump_modify thresh ` -command will cause only atoms that have displaced more than 0.6 -Angstroms to be output on a given snapshot (assuming metal units). -However, note that when an atom is output, we also need to update the -reference position for that atom to its new coordinates. So that it -will not be output in every snapshot thereafter. That reference -position is stored by :doc:`compute displace/atom `. So the dump_modify -*refresh* option triggers a call to compute displace/atom at the end -of every dump to perform that update. The *refresh check* option -shown as part of the :doc:`compute displace/atom ` command enables the compute -to respond to the call from the dump command, and update the -appropriate reference positions. This is done be defining an +The "4" index is the scalar displacement; 1, 2, and 3 are the :math:`xyz` +components of the displacement. The :doc:`dump_modify thresh ` +command will cause only atoms that have displaced more than +:math:`0.6~\mathrm{\mathring A}` to be output on a given snapshot (assuming +metal units). However, note that when an atom is output, we also need to +update the reference position for that atom to its new coordinates. So that it +will not be output in every snapshot thereafter. That reference position is +stored by :doc:`compute displace/atom `. So the +dump_modify *refresh* option triggers a call to compute displace/atom at the +end of every dump to perform that update. The *refresh check* option +shown as part of the :doc:`compute displace/atom ` +command enables the compute to respond to the call from the dump command, and +update the appropriate reference positions. This is done be defining an :doc:`atom-style variable `, *check* in this example, which calculates a Boolean value (0 or 1) for each atom, based on the same criterion used by dump_modify thresh. @@ -661,18 +662,18 @@ value of *yes* means atom coords are written in normalized units from 0.0 to 1.0 in each box dimension. If the simulation box is triclinic (tilted), then all atom coords will still be between 0.0 and 1.0. A value of *no* means they are written in absolute distance units -(e.g. Angstroms or sigma). +(e.g., :math:`\mathrm{\mathring A}` or :math:`\sigma`). ---------- The *sfactor* and *tfactor* keywords only apply to the dump *xtc* style. They allow customization of the unit conversion factors used -when writing to XTC files. By default they are initialized for +when writing to XTC files. By default, they are initialized for whatever :doc:`units ` style is being used, to write out -coordinates in nanometers and time in picoseconds. I.e. for *real* +coordinates in nanometers and time in picoseconds. For example, for *real* units, LAMMPS defines *sfactor* = 0.1 and *tfactor* = 0.001, since the -Angstroms and fs used by *real* units are 0.1 nm and 0.001 ps -respectively. If you are using a units system with distance and time +:math:`\mathrm{\mathring A}}` and fs used by *real* units are 0.1 nm and +0.001 ps, respectively. If you are using a units system with distance and time units far from nm and ps, you may wish to write XTC files with different units, since the compression algorithm used in XTC files is most effective when the typical magnitude of position data is between @@ -683,18 +684,19 @@ most effective when the typical magnitude of position data is between The *sort* keyword determines whether lines of per-atom output in a snapshot are sorted or not. A sort value of *off* means they will typically be written in indeterminate order, either in serial or -parallel. This is the case even in serial if the :doc:`atom_modify sort ` option is turned on, which it is by default, to -improve performance. A sort value of *id* means sort the output by -atom ID. A sort value of N or -N means sort the output by the value -in the Nth column of per-atom info in either ascending or descending -order. +parallel. This is the case even in serial if the +:doc:`atom_modify sort ` option is turned on, which it is by +default, to improve performance. A sort value of *id* means sort the output by +atom ID. A sort value of :math:`N` or :math:`-N` means sort the output by the +value in the :math:`N`\ th column of per-atom info in either ascending or +descending order. The dump *local* style cannot be sorted by atom ID, since there are typically multiple lines of output per atom. Some dump styles, such as *dcd* and *xtc*, require sorting by atom ID to format the output file correctly. If multiple processors are writing the dump file, via the "%" wildcard in the dump filename and the *nfile* or *fileper* -keywords are set to non-default values (i.e. the number of dump file +keywords are set to non-default values (i.e., the number of dump file pieces is not equal to the number of procs), then sorting cannot be performed. @@ -729,11 +731,12 @@ are written to the dump file or included in the image. The possible attributes that can be tested for are the same as those that can be specified in the :doc:`dump custom ` command, with the exception of the *element* attribute, since it is not a numeric value. Note -that a different attributes can be used than those output by the :doc:`dump custom ` command. E.g. you can output the coordinates and -stress of atoms whose energy is above some threshold. +that a different attributes can be used than those output by the +:doc:`dump custom ` command. For example, you can output the coordinates +and stress of atoms whose energy is above some threshold. If an atom-style variable is used as the attribute, then it can -produce continuous numeric values or effective Boolean 0/1 values +produce continuous numeric values or effective Boolean 0/1 values, which may be useful for the comparison operator. Boolean values can be generated by variable formulas that use comparison or Boolean math operators or special functions like gmask() and rmask() and grmask(). @@ -749,7 +752,7 @@ Three examples follow. dump_modify ... thresh ix != LAST -This will dump atoms which have crossed the periodic x boundary of the +This will dump atoms which have crossed the periodic :math:`x` boundary of the simulation box since the last dump. (Note that atoms that crossed once and then crossed back between the two dump timesteps would not be included.) @@ -769,9 +772,8 @@ region since the last dump. dump_modify ... thresh v_charge |^ LAST This will dump atoms whose charge has changed from an absolute value -less than 1/2 to greater than 1/2 (or vice versa) since the last dump. -E.g. due to reactions and subsequent charge equilibration in a -reactive force field. +less than :math:`\frac12` to greater than :math:`\frac12` (or vice versa) since the last dump (e.g., due to reactions and subsequent charge equilibration in a +reactive force field). The choice of operators listed above are the usual comparison operators. The XOR operation (exclusive or) is also included as "\|\^". @@ -783,7 +785,7 @@ threshold criterion is met. Otherwise it is not met. The *time* keyword only applies to the dump *atom*, *custom*, *local*, and *xyz* styles (and their COMPRESS package versions *atom/gz*, -*custom/gz* and *local/gz*\ ). For the first 3 styles, if set to +*custom/gz* and *local/gz*\ ). For the first three styles, if set to *yes*, each frame will will contain two extra lines before the "ITEM: TIMESTEP" entry: @@ -798,7 +800,7 @@ as the timestep value. This will output the current elapsed simulation time in current time units equivalent to the :doc:`thermo keyword ` *time*\ . This is to simplify post-processing of trajectories using a variable time -step, e.g. when using :doc:`fix dt/reset `. +step (e.g., when using :doc:`fix dt/reset `). The default setting is *no*\ . ---------- @@ -836,9 +838,8 @@ compression level can be controlled by the :code:`compression_level` keyword. File names with these styles have to end in either :code:`.gz` or :code:`.zst`. -GZ supports compression levels from -1 (default), 0 (no compression), -and 1 to -9. 9 being the best compression. The COMPRESS :code:`/gz` styles use 9 +GZ supports compression levels from :math:`-1` (default), 0 (no compression), +and 1 to 9, 9 being the best compression. The COMPRESS :code:`/gz` styles use 9 as default compression level. Zstd offers a wider range of compression levels, including negative