From fe8a7a3799b64180bb87e2142279d5f1ba7df46c Mon Sep 17 00:00:00 2001 From: Karl Hammond Date: Tue, 16 Aug 2022 20:29:12 -0500 Subject: [PATCH] Math replacements; code-block LAMMPS; clarity and parsing-friendly edits --- doc/src/compute_bond_local.rst | 6 +- doc/src/compute_chunk_atom.rst | 2 +- doc/src/compute_coord_atom.rst | 4 +- doc/src/compute_entropy_atom.rst | 4 +- doc/src/compute_global_atom.rst | 44 ++++++----- doc/src/compute_group_group.rst | 38 +++++----- doc/src/compute_gyration.rst | 37 ++++----- doc/src/compute_gyration_chunk.rst | 38 +++++----- doc/src/compute_gyration_shape.rst | 60 ++++++++------- doc/src/compute_gyration_shape_chunk.rst | 59 ++++++++------- doc/src/compute_heat_flux.rst | 58 ++++++++------- doc/src/compute_hexorder_atom.rst | 4 +- doc/src/compute_hma.rst | 69 +++++++++-------- doc/src/compute_improper.rst | 14 ++-- doc/src/compute_improper_local.rst | 7 +- doc/src/compute_inertia_chunk.rst | 33 ++++---- doc/src/compute_ke.rst | 15 ++-- doc/src/compute_ke_atom.rst | 6 +- doc/src/compute_ke_atom_eff.rst | 2 +- doc/src/compute_ke_eff.rst | 8 +- doc/src/compute_ke_rigid.rst | 17 +++-- doc/src/compute_mesont.rst | 17 ++--- doc/src/compute_mliap.rst | 39 +++++----- doc/src/compute_momentum.rst | 7 +- doc/src/compute_msd.rst | 19 ++--- doc/src/compute_msd_chunk.rst | 44 ++++++----- doc/src/compute_msd_nongauss.rst | 30 ++++---- doc/src/compute_nbond_atom.rst | 2 +- doc/src/compute_omega_chunk.rst | 36 +++++---- doc/src/compute_orientorder_atom.rst | 95 ++++++++++++++---------- doc/src/compute_pair.rst | 4 +- doc/src/compute_pair_local.rst | 27 ++++--- doc/src/compute_pe.rst | 14 ++-- doc/src/compute_pe_atom.rst | 19 ++--- doc/src/compute_plasticity_atom.rst | 17 +++-- doc/src/compute_pressure.rst | 72 ++++++++++-------- doc/src/compute_pressure_uef.rst | 8 +- doc/src/compute_property_atom.rst | 36 ++++----- doc/src/compute_property_chunk.rst | 29 +++++--- doc/src/compute_property_local.rst | 87 ++++++++++++++-------- doc/src/compute_ptm_atom.rst | 44 ++++++----- doc/src/compute_rdf.rst | 94 +++++++++++------------ doc/src/set.rst | 4 +- 43 files changed, 702 insertions(+), 567 deletions(-) diff --git a/doc/src/compute_bond_local.rst b/doc/src/compute_bond_local.rst index 468fcc710d..ed779d986e 100644 --- a/doc/src/compute_bond_local.rst +++ b/doc/src/compute_bond_local.rst @@ -123,7 +123,7 @@ directly. The *set* keyword is used to identify the name of this other variable associated with theta. As an example, these commands can be added to the bench/in.rhodo -script to compute the length\^2 of every bond in the system and +script to compute the length\ :math:`^2` of every bond in the system and output the statistics in various ways: .. code-block:: LAMMPS @@ -141,11 +141,11 @@ output the statistics in various ways: fix 10 all ave/histo 10 10 100 0 6 20 c_2[3] mode vector file tmp.histo The :doc:`dump local ` command will output the energy, length, -and length\^2 for every bond in the system. The +and length\ :math:`^2` for every bond in the system. The :doc:`thermo_style ` command will print the average of those quantities via the :doc:`compute reduce ` command with thermo output, and the :doc:`fix ave/histo ` -command will histogram the length\^2 values and write them to a file. +command will histogram the length\ :math:`^2` values and write them to a file. ---------- diff --git a/doc/src/compute_chunk_atom.rst b/doc/src/compute_chunk_atom.rst index 5a806aa6d5..cdb8b097c0 100644 --- a/doc/src/compute_chunk_atom.rst +++ b/doc/src/compute_chunk_atom.rst @@ -602,7 +602,7 @@ be used. For non-orthogonal (triclinic) simulation boxes, only the *reduced* option may be used. A *box* value selects standard distance units as defined by the -:doc:`units ` command (e.g., Ångströms for units = *real* or *metal*). +:doc:`units ` command (e.g., Angstroms for units = *real* or *metal*). A *lattice* value means the distance units are in lattice spacings. The :doc:`lattice ` command must have been previously used to define the lattice spacing. A *reduced* value means normalized diff --git a/doc/src/compute_coord_atom.rst b/doc/src/compute_coord_atom.rst index 54bdfbb2f6..cf50122d64 100644 --- a/doc/src/compute_coord_atom.rst +++ b/doc/src/compute_coord_atom.rst @@ -11,11 +11,11 @@ Syntax .. code-block:: LAMMPS - compute ID group-ID coord/atom cstyle args ... + compute ID group-ID coord/atom style args ... * ID, group-ID are documented in :doc:`compute ` command * coord/atom = style name of this compute command -* cstyle = *cutoff* or *orientorder* +* style = *cutoff* or *orientorder* .. parsed-literal:: diff --git a/doc/src/compute_entropy_atom.rst b/doc/src/compute_entropy_atom.rst index f733c00f97..b529bbf192 100644 --- a/doc/src/compute_entropy_atom.rst +++ b/doc/src/compute_entropy_atom.rst @@ -98,13 +98,13 @@ by the corresponding volume. This option can be useful when dealing with inhomogeneous systems such as those that have surfaces. Here are typical input parameters for fcc aluminum (lattice -constant 4.05 Ångströms), +constant 4.05 Angstroms), .. parsed-literal:: compute 1 all entropy/atom 0.25 5.7 avg yes 3.7 -and for bcc sodium (lattice constant 4.23 Ångströms), +and for bcc sodium (lattice constant 4.23 Angstroms), .. parsed-literal:: diff --git a/doc/src/compute_global_atom.rst b/doc/src/compute_global_atom.rst index 1ee4abdde0..b013a6f270 100644 --- a/doc/src/compute_global_atom.rst +++ b/doc/src/compute_global_atom.rst @@ -6,7 +6,7 @@ compute global/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID style index input1 input2 ... @@ -55,18 +55,20 @@ reference a global vector or array from a :doc:`compute ` or :doc:`fix ` or the evaluation of an vector-style :doc:`variable `. Details are given below. -The *index* value for an atom is used as a index I (from 1 to N) into -the vector associated with each of the input values. The Ith value +The *index* value for an atom is used as an index :math:`I` (from 1 to +:math:`N`, where :math:`N` is the number of atoms) into the vector +associated with each of the input values. The :math:`I`\ th value from the input vector becomes one output value for that atom. If the -atom is not in the specified group, or the index I < 1 or I > M, where -M is the actual length of the input vector, then an output value of -0.0 is assigned to the atom. +atom is not in the specified group, or the index :math:`I < 1` or +:math:`I > M`, where :math:`M` is the actual length of the input vector, +then an output value of 0.0 is assigned to the atom. An example of how this command is useful, is in the context of "chunks" which are static or dynamic subsets of atoms. The :doc:`compute chunk/atom ` command assigns unique chunk IDs -to each atom. It's output can be used as the *index* parameter for +to each atom. Its output can be used as the *index* parameter for this command. Various other computes with "chunk" in their style -name, such as :doc:`compute com/chunk ` or :doc:`compute msd/chunk `, calculate properties for each +name, such as :doc:`compute com/chunk ` or +:doc:`compute msd/chunk `, calculate properties for each chunk. The output of these commands are global vectors or arrays, with one or more values per chunk, and can be used as input values for this command. This command will then assign the global chunk value to @@ -102,17 +104,18 @@ they work. Note that for input values from a compute or fix, the bracketed index 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 size of the vector (for *mode* = scalar) +or "m\*" or "m\*n". If :math:`N` is the size of the vector +(for *mode* = scalar) or the number of columns in the array (for *mode* = vector), then an -asterisk with no numeric values means all indices from 1 to 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 -asterisk means all indices from m to n (inclusive). +asterisk with no numeric values means all indices from 1 to :math:`N`. +A leading asterisk means all indices from 1 to n (inclusive). A +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 compute global/atom commands -are equivalent, since the :doc:`compute com/chunk ` -command creates a global array with 3 columns: +had been listed one by one. For example, the following two compute global/atom +commands are equivalent, since the :doc:`compute com/chunk ` +command creates a global array with three columns: .. code-block:: LAMMPS @@ -124,14 +127,14 @@ command creates a global array with 3 columns: ---------- This section explains the *index* parameter. Note that it must -reference per-atom values, as contrasted with the *input* values which +reference per-atom values, as contrasted with the *input* values, which must reference global values. Note that all of these options generate floating point values. When they are used as an index into the specified input vectors, they simple rounded down to convert the value to integer indices. The -final values should range from 1 to N (inclusive), since they are used -to access values from N-length vectors. +final values should range from 1 to :math:`N` (inclusive), since they are used +to access values from :math:`N`-length vectors. If *index* begins with "c\_", a compute ID must follow which has been previously defined in the input script. The compute must generate @@ -177,7 +180,8 @@ global vector or array. See the individual :doc:`compute ` doc page for details. If no bracketed integer is appended, the vector calculated by the compute is used. If a bracketed integer is appended, the Ith column of the array calculated by the compute is -used. Users can also write code for their own compute styles and :doc:`add them to LAMMPS `. See the discussion above for how +used. Users can also write code for their own compute styles and +:doc:`add them to LAMMPS `. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values. diff --git a/doc/src/compute_group_group.rst b/doc/src/compute_group_group.rst index d361bc806d..87e855ae1e 100644 --- a/doc/src/compute_group_group.rst +++ b/doc/src/compute_group_group.rst @@ -6,7 +6,7 @@ compute group/group command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID group/group group2-ID keyword value ... @@ -102,19 +102,20 @@ frequently. If you have a bonded system, then the settings of :doc:`special_bonds ` command can remove pairwise - interactions between atoms in the same bond, angle, or dihedral. This - is the default setting for the :doc:`special_bonds ` - command, and means those pairwise interactions do not appear in the - neighbor list. Because this compute uses a neighbor list, it also - means those pairs will not be included in the group/group interaction. - This does not apply when using long-range coulomb interactions - (\ *coul/long*, *coul/msm*, *coul/wolf* or similar. One way to get - around this would be to set special_bond scaling factors to very tiny - numbers that are not exactly zero (e.g. 1.0e-50). Another workaround - is to write a dump file, and use the :doc:`rerun ` command to - compute the group/group interactions for snapshots in the dump file. - The rerun script can use a :doc:`special_bonds ` command - that includes all pairs in the neighbor list. + interactions between atoms in the same bond, angle, or dihedral. This is + the default setting for the :doc:`special_bonds ` command, + and means those pairwise interactions do not appear in the neighbor list. + Because this compute uses a neighbor list, it also means those pairs will + not be included in the group/group interaction. This does not apply when + using long-range Coulomb interactions + (\ *coul/long*, *coul/msm*, *coul/wolf* or similar). One way to get + around this would be to set *special_bond* scaling factors to very tiny + numbers that are not exactly zero (e.g., :math:`1.0 \times 10^{-50}`). + Another workaround would be to write a dump file and use the + :doc:`rerun ` command to compute the group/group interactions for + snapshots in the dump file. The rerun script can use a + :doc:`special_bonds ` command that includes all pairs in the + neighbor list. If you desire a breakdown of the interactions into a pairwise and Kspace component, simply invoke the compute twice with the appropriate @@ -132,20 +133,21 @@ Output info """"""""""" This compute calculates a global scalar (the energy) and a global -vector of length 3 (force), which can be accessed by indices 1-3. +vector of length 3 (force), which can be accessed by indices 1--3. These values can be used by any command that uses global scalar or -vector values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output +vector values from a compute as input. See the +:doc:`Howto output ` page for an overview of LAMMPS output options. Both the scalar and vector values calculated by this compute are -"extensive". The scalar value will be in energy :doc:`units `. +"extensive." The scalar value will be in energy :doc:`units `. The vector values will be in force :doc:`units `. Restrictions """""""""""" Not all pair styles can be evaluated in a pairwise mode as required by -this compute. For example, 3-body and other many-body potentials, +this compute. For example, three-body and other many-body potentials, such as :doc:`Tersoff ` and :doc:`Stillinger-Weber ` cannot be used. :doc:`EAM ` potentials will re-use previously computed embedding term contributions, diff --git a/doc/src/compute_gyration.rst b/doc/src/compute_gyration.rst index 18c46f4772..5610dd1d98 100644 --- a/doc/src/compute_gyration.rst +++ b/doc/src/compute_gyration.rst @@ -6,7 +6,7 @@ compute gyration command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID gyration @@ -23,51 +23,54 @@ Examples Description """"""""""" -Define a computation that calculates the radius of gyration Rg of the +Define a computation that calculates the radius of gyration :math:`R_g` of the group of atoms, including all effects due to atoms passing through periodic boundaries. -Rg is a measure of the size of the group of atoms, and is computed as -the square root of the Rg\^2 value in this formula +:math:`R_g` is a measure of the size of the group of atoms, and is computed as +the square root of the :math:`R_g^2` value in this formula .. math:: - {R_g}^2 = \frac{1}{M} \sum_i m_i (r_i - r_{cm})^2 + R_g^2 = \frac{1}{M} \sum_i m_i (r_i - r_{\text{cm}})^2 -where :math:`M` is the total mass of the group, :math:`r_{cm}` is the +where :math:`M` is the total mass of the group, :math:`r_{\text{cm}}` is the center-of-mass position of the group, and the sum is over all atoms in the group. -A :math:`{R_g}^2` tensor, stored as a 6-element vector, is also calculated +A :math:`R_g^2` tensor, stored as a 6-element vector, is also calculated by this compute. The formula for the components of the tensor is the -same as the above formula, except that :math:`(r_i - r_{cm})^2` is replaced -by :math:`(r_{i,x} - r_{cm,x}) \cdot (r_{i,y} - r_{cm,y})` for the xy component, -and so on. The 6 components of the vector are ordered xx, yy, zz, xy, xz, yz. -Note that unlike the scalar :math:`R_g`, each of the 6 values of the tensor +same as the above formula, except that :math:`(r_i - r_{\text{cm}})^2` is +replaced by +:math:`(r_{i,x} - r_{\text{cm},x}) \cdot (r_{i,y} - r_{\text{cm},y})` for the +:math:`xy` component, and so on. The six components of the vector are ordered +:math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`, :math:`yz`. +Note that unlike the scalar :math:`R_g`, each of the six values of the tensor is effectively a "squared" value, since the cross-terms may be negative -and taking a sqrt() would be invalid. +and taking a square root would be invalid. .. note:: The coordinates of an atom contribute to :math:`R_g` in "unwrapped" form, - by using the image flags associated with each atom. See the :doc:`dump custom ` command for a discussion of "unwrapped" coordinates. + by using the image flags associated with each atom. See the + :doc:`dump custom ` command for a discussion of "unwrapped" coordinates. See the Atoms section of the :doc:`read_data ` command for a discussion of image flags and how they are set for each atom. You can - reset the image flags (e.g. to 0) before invoking this compute by + reset the image flags (e.g., to 0) before invoking this compute by using the :doc:`set image ` command. Output info """"""""""" This compute calculates a global scalar (:math:`R_g`) and a global vector of -length 6 (:math:`{R_g}^2` tensor), which can be accessed by indices 1-6. These +length 6 (:math:`R_g^2` tensor), which can be accessed by indices 1--6. These values can be used by any command that uses a global scalar value or vector values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. The scalar and vector values calculated by this compute are -"intensive". The scalar and vector values will be in distance and -distance\^2 :doc:`units ` respectively. +"intensive." The scalar and vector values will be in distance and +distance\ :math:`^2` :doc:`units `, respectively. Restrictions """""""""""" diff --git a/doc/src/compute_gyration_chunk.rst b/doc/src/compute_gyration_chunk.rst index 0255d4f95a..e7517cdbcd 100644 --- a/doc/src/compute_gyration_chunk.rst +++ b/doc/src/compute_gyration_chunk.rst @@ -6,7 +6,7 @@ compute gyration/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID gyration/chunk chunkID keyword value ... @@ -31,28 +31,31 @@ Examples Description """"""""""" -Define a computation that calculates the radius of gyration Rg for +Define a computation that calculates the radius of gyration :math:`R_g` for multiple chunks of atoms. -In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom ` command, which assigns each atom +In LAMMPS, chunks are collections of atoms defined by a +:doc:`compute chunk/atom ` command, which assigns each atom to a single chunk (or no chunk). The ID for this command is specified as chunkID. For example, a single chunk could be the atoms in a -molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom ` and :doc:`Howto chunk ` +molecule or atoms in a spatial bin. +See the :doc:`compute chunk/atom ` and +:doc:`Howto chunk ` doc pages for details of how chunks can be defined and examples of how they can be used to measure properties of a system. -This compute calculates the radius of gyration Rg for each chunk, +This compute calculates the radius of gyration :math:`R_g` for each chunk, which includes all effects due to atoms passing through periodic boundaries. -Rg is a measure of the size of a chunk, and is computed by this +:math:`R_g` is a measure of the size of a chunk, and is computed by the formula .. math:: - {R_g}^2 = \frac{1}{M} \sum_i m_i (r_i - r_{cm})^2 + R_g^2 = \frac{1}{M} \sum_i m_i (r_i - r_{\text{cm}})^2 -where :math:`M` is the total mass of the chunk, :math:`r_{cm}` is +where :math:`M` is the total mass of the chunk, :math:`r_{\text{cm}}` is the center-of-mass position of the chunk, and the sum is over all atoms in the chunk. @@ -64,13 +67,13 @@ thus also not contribute to this calculation. You can specify the "all" group for this command if you simply want to include atoms with non-zero chunk IDs. -If the *tensor* keyword is specified, then the scalar Rg value is not -calculated, but an Rg tensor is instead calculated for each chunk. +If the *tensor* keyword is specified, then the scalar :math:`R_g` value is not +calculated, but an :math:`R_g` tensor is instead calculated for each chunk. The formula for the components of the tensor is the same as the above -formula, except that :math:`(r_i - r_{cm})^2` is replaced by -:math:`(r_{i,x} - r_{cm,x}) \cdot (r_{i,y} - r_{cm,y})` for the xy -component, and so on. The 6 components of the tensor are -ordered xx, yy, zz, xy, xz, yz. +formula, except that :math:`(r_i - r_{\text{cm}})^2` is replaced by +:math:`(r_{i,x} - r_{\text{cm},x}) \cdot (r_{i,y} - r_{\text{cm},y})` for the +:math:`xy` component, and so on. The six components of the tensor are +ordered :math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`, :math:`yz`. .. note:: @@ -79,7 +82,7 @@ ordered xx, yy, zz, xy, xz, yz. command for a discussion of "unwrapped" coordinates. See the Atoms section of the :doc:`read_data ` command for a discussion of image flags and how they are set for each atom. You can - reset the image flags (e.g. to 0) before invoking this compute by + reset the image flags (e.g., to 0) before invoking this compute by using the :doc:`set image ` command. The simplest way to output the results of the compute gyration/chunk @@ -98,8 +101,9 @@ Output info This compute calculates a global vector if the *tensor* keyword is not specified and a global array if it is. The length of the vector or number of rows in the array = the number of chunks *Nchunk* as -calculated by the specified :doc:`compute chunk/atom ` command. If the *tensor* keyword -is specified, the global array has 6 columns. The vector or array can +calculated by the specified :doc:`compute chunk/atom ` +command. If the *tensor* keyword is specified, the global array has six +columns. The vector or array can be accessed by any command that uses global values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. diff --git a/doc/src/compute_gyration_shape.rst b/doc/src/compute_gyration_shape.rst index 8eee14e787..892677b0ba 100644 --- a/doc/src/compute_gyration_shape.rst +++ b/doc/src/compute_gyration_shape.rst @@ -6,7 +6,7 @@ compute gyration/shape command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID gyration/shape compute-ID @@ -28,30 +28,33 @@ Define a computation that calculates the eigenvalues of the gyration tensor of a group of atoms and three shape parameters. The computation includes all effects due to atoms passing through periodic boundaries. -The three computed shape parameters are the asphericity, b, the acylindricity, c, -and the relative shape anisotropy, k: +The three computed shape parameters are the asphericity, :math:`b`, +the acylindricity, :math:`c`, and the relative shape anisotropy, :math:`k`, +viz., .. math:: - c = & l_z - 0.5(l_y+l_x) \\ - b = & l_y - l_x \\ - k = & \frac{3}{2} \frac{l_x^2+l_y^2+l_z^2}{(l_x+l_y+l_z)^2} - \frac{1}{2} + b &= l_z - \frac12(l_y+l_x) \\ + c &= l_y - l_x \\ + k &= \frac{3}{2} \frac{l_x^2+l_y^2+l_z^2}{(l_x+l_y+l_z)^2} - \frac{1}{2} -where :math:`l_x` <= :math:`l_y` <= :math:`l_z` are the three eigenvalues of the gyration tensor. A general description -of these parameters is provided in :ref:`(Mattice) ` while an application to polymer systems +where :math:`l_x \le l_y \le l_z` are the three eigenvalues of the gyration +tensor. A general description of these parameters is provided in +:ref:`(Mattice) ` while an application to polymer systems can be found in :ref:`(Theodorou) `. -The asphericity is always non-negative and zero only when the three principal -moments are equal. This zero condition is met when the distribution of particles -is spherically symmetric (hence the name asphericity) but also whenever the particle -distribution is symmetric with respect to the three coordinate axes, e.g., -when the particles are distributed uniformly on a cube, tetrahedron or other Platonic -solid. The acylindricity is always non-negative and zero only when the two principal -moments are equal. This zero condition is met when the distribution of particles is -cylindrically symmetric (hence the name, acylindricity), but also whenever the particle -distribution is symmetric with respect to the two coordinate axes, e.g., when the -particles are distributed uniformly on a regular prism. the relative shape anisotropy -is bounded between zero (if all points are spherically symmetric) and one -(if all points lie on a line). +The asphericity is always non-negative and zero only when the three principal +moments are equal. This zero condition is met when the distribution of +particles is spherically symmetric (hence the name asphericity) but also +whenever the particle distribution is symmetric with respect to the three +coordinate axes (e.g., when the particles are distributed uniformly on a cube, +tetrahedron or other Platonic solid). The acylindricity is always non-negative +and zero only when the two principal moments are equal. This zero condition is +met when the distribution of particles is cylindrically symmetric (hence the +name, acylindricity), but also whenever the particle distribution is symmetric +with respect to the two coordinate axes (e.g., when the +particles are distributed uniformly on a regular prism). +The relative shape anisotropy is bounded between zero (if all points are +spherically symmetric) and one (if all points lie on a line). .. note:: @@ -60,22 +63,23 @@ is bounded between zero (if all points are spherically symmetric) and one See the :doc:`dump custom ` command for a discussion of "unwrapped" coordinates. See the Atoms section of the :doc:`read_data ` command for a discussion of image flags and how they are set for each - atom. You can reset the image flags (e.g. to 0) before invoking this + atom. You can reset the image flags (e.g., to 0) before invoking this compute by using the :doc:`set image ` command. Output info """"""""""" -This compute calculates a global vector of -length 6, which can be accessed by indices 1-6. The first three values are the -eigenvalues of the gyration tensor followed by the asphericity, the acylindricity -and the relative shape anisotropy. The computed values can be used by any command -that uses global vector values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output +This compute calculates a global vector of length 6, which can be accessed by +indices 1--6. The first three values are the eigenvalues of the gyration tensor +followed by the asphericity, the acylindricity and the relative shape +anisotropy. The computed values can be used by any command that uses global +vector values from a compute as input. See the +:doc:`Howto output ` page for an overview of LAMMPS output options. The vector values calculated by this compute are -"intensive". The first five vector values will be in -distance\^2 :doc:`units ` while the sixth one is dimensionless. +"intensive." The first five vector values will be in +distance\ :math:`2` :doc:`units ` while the sixth one is dimensionless. Restrictions """""""""""" diff --git a/doc/src/compute_gyration_shape_chunk.rst b/doc/src/compute_gyration_shape_chunk.rst index f9d9df8db0..2bf8c970e9 100644 --- a/doc/src/compute_gyration_shape_chunk.rst +++ b/doc/src/compute_gyration_shape_chunk.rst @@ -6,7 +6,7 @@ compute gyration/shape/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID gyration/shape/chunk compute-ID @@ -28,28 +28,32 @@ Define a computation that calculates the eigenvalues of the gyration tensor and three shape parameters of multiple chunks of atoms. The computation includes all effects due to atoms passing through periodic boundaries. -The three computed shape parameters are the asphericity, b, the acylindricity, c, -and the relative shape anisotropy, k: +The three computed shape parameters are the asphericity, :math:`b`, +the acylindricity, :math:`c`, and the relative shape anisotropy, :math:`k`, +viz., .. math:: - c = & l_z - 0.5(l_y+l_x) \\ - b = & l_y - l_x \\ - k = & \frac{3}{2} \frac{l_x^2+l_y^2+l_z^2}{(l_x+l_y+l_z)^2} - \frac{1}{2} + b &= l_z - \frac12(l_y+l_x) \\ + c &= l_y - l_x \\ + k &= \frac{3}{2} \frac{l_x^2+l_y^2+l_z^2}{(l_x+l_y+l_z)^2} - \frac{1}{2} -where :math:`l_x` <= :math:`l_y` <= :math:`l_z` are the three eigenvalues of the gyration tensor. A general description -of these parameters is provided in :ref:`(Mattice) ` while an application to polymer systems -can be found in :ref:`(Theodorou) `. The asphericity is always non-negative and zero -only when the three principal moments are equal. This zero condition is met when the distribution -of particles is spherically symmetric (hence the name asphericity) but also whenever the particle -distribution is symmetric with respect to the three coordinate axes, e.g., -when the particles are distributed uniformly on a cube, tetrahedron or other Platonic -solid. The acylindricity is always non-negative and zero only when the two principal -moments are equal. This zero condition is met when the distribution of particles is -cylindrically symmetric (hence the name, acylindricity), but also whenever the particle -distribution is symmetric with respect to the two coordinate axes, e.g., when the -particles are distributed uniformly on a regular prism. the relative shape anisotropy -is bounded between zero (if all points are spherically symmetric) and one +where :math:`l_x \le l_y \le l_z` are the three eigenvalues of the gyration +tensor. A general description of these parameters is provided in +:ref:`(Mattice) ` while an application to polymer systems +can be found in :ref:`(Theodorou) `. The asphericity is always +non-negative and zero only when the three principal moments are equal. +This zero condition is met when the distribution of particles is spherically +symmetric (hence the name asphericity) but also whenever the particle +distribution is symmetric with respect to the three coordinate axes (e.g., +when the particles are distributed uniformly on a cube, tetrahedron, or other +Platonic solid). The acylindricity is always non-negative and zero only when +the two principal moments are equal. This zero condition is met when the +distribution of particles is cylindrically symmetric (hence the name, +acylindricity), but also whenever the particle distribution is symmetric with +respect to the two coordinate axes (e.g., when the particles are distributed +uniformly on a regular prism). The relative shape anisotropy +is bounded between 0 (if all points are spherically symmetric) and 1 (if all points lie on a line). The tensor keyword must be specified in the compute gyration/chunk command. @@ -61,22 +65,23 @@ The tensor keyword must be specified in the compute gyration/chunk command. See the :doc:`dump custom ` command for a discussion of "unwrapped" coordinates. See the Atoms section of the :doc:`read_data ` command for a discussion of image flags and how they are set for each - atom. You can reset the image flags (e.g. to 0) before invoking this + atom. You can reset the image flags (e.g., to 0) before invoking this compute by using the :doc:`set image ` command. Output info """"""""""" This compute calculates a global array with six columns, -which can be accessed by indices 1-6. The first three columns are the -eigenvalues of the gyration tensor followed by the asphericity, the acylindricity -and the relative shape anisotropy. The computed values can be used by any command -that uses global array values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output -options. +which can be accessed by indices 1--6. The first three columns are the +eigenvalues of the gyration tensor followed by the asphericity, the +acylindricity and the relative shape anisotropy. The computed values can be +used by any command that uses global array values from a compute as input. +See the :doc:`Howto output ` page for an overview of LAMMPS +output options. The array calculated by this compute is -"intensive". The first five columns will be in -distance\^2 :doc:`units ` while the sixth one is dimensionless. +"intensive." The first five columns will be in +distance\ :math:`^2` :doc:`units ` while the sixth one is dimensionless. Restrictions """""""""""" diff --git a/doc/src/compute_heat_flux.rst b/doc/src/compute_heat_flux.rst index 56975adc70..4302ecddb8 100644 --- a/doc/src/compute_heat_flux.rst +++ b/doc/src/compute_heat_flux.rst @@ -6,7 +6,7 @@ compute heat/flux command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID heat/flux ke-ID pe-ID stress-ID @@ -28,13 +28,13 @@ Description Define a computation that calculates the heat flux vector based on contributions from atoms in the specified group. This can be used by -itself to measure the heat flux through a set of atoms (e.g. a region +itself to measure the heat flux through a set of atoms (e.g., a region between two thermostatted reservoirs held at different temperatures), or to calculate a thermal conductivity using the equilibrium Green-Kubo formalism. For other non-equilibrium ways to compute a thermal conductivity, see -the :doc:`Howto kappa ` doc page.. These include use of +the :doc:`Howto kappa ` doc page. These include use of the :doc:`fix thermal/conductivity ` command for the Muller-Plathe method. Or the :doc:`fix heat ` command which can add or subtract heat from groups of atoms. @@ -52,12 +52,12 @@ third calculates per-atom stress (\ *stress-ID*\ ). (or any group whose atoms are superset of the atoms in this compute's group). LAMMPS does not check for this. -In case of two-body interactions, the heat flux is defined as: +In case of two-body interactions, the heat flux :math:`\mathbf{J}` is defined as .. math:: \mathbf{J} &= \frac{1}{V} \left[ \sum_i e_i \mathbf{v}_i - \sum_{i} \mathbf{S}_{i} \mathbf{v}_i \right] \\ &= \frac{1}{V} \left[ \sum_i e_i \mathbf{v}_i + \sum_{i` and :doc:`compute centroid/stress/atom ` for possible definitions of atomic stress :math:`\mathbf{S}_i` in the case of bonded and many-body interactions. -The tensor multiplies :math:`\mathbf{v}_i` as a 3x3 matrix-vector multiply +The tensor multiplies :math:`\mathbf{v}_i` by a :math:`3\times3` matrix to yield a vector. -Note that as discussed below, the 1/:math:`{V}` scaling factor in the -equation for :math:`\mathbf{J}` is NOT included in the calculation performed by -these computes; you need to add it for a volume appropriate to the atoms -included in the calculation. +Note that as discussed below, the :math:`1/V` scaling factor in the +equation for :math:`\mathbf{J}` is **not** included in the calculation +performed by these computes; you need to add it for a volume appropriate to the +atoms included in the calculation. .. note:: @@ -103,7 +103,7 @@ included in the calculation. contribution when computed via :doc:`compute stress/atom ` are highly unphysical and should not be used. -The Green-Kubo formulas relate the ensemble average of the +The Green--Kubo formulas relate the ensemble average of the auto-correlation of the heat flux :math:`\mathbf{J}` to the thermal conductivity :math:`\kappa`: @@ -112,17 +112,18 @@ to the thermal conductivity :math:`\kappa`: ---------- -The heat flux can be output every so many timesteps (e.g. via the +The heat flux can be output every so many timesteps (e.g., via the :doc:`thermo_style custom ` command). Then as a post-processing operation, an auto-correlation can be performed, its -integral estimated, and the Green-Kubo formula above evaluated. +integral estimated, and the Green--Kubo formula above evaluated. The :doc:`fix ave/correlate ` command can calculate the auto-correlation. The trap() function in the :doc:`variable ` command can calculate the integral. -An example LAMMPS input script for solid Ar is appended below. The -result should be: average conductivity ~0.29 in W/mK. +An example LAMMPS input script for solid argon is appended below. The +result should be an average conductivity +:math:`\approx 0.29~\mathrm{W/m \cdot K}`. ---------- @@ -130,22 +131,22 @@ Output info """"""""""" This compute calculates a global vector of length 6. -The first 3 components are the :math:`x`, :math:`y`, :math:`z` -components of the full heat flux vector, -i.e. (:math:`J_x`, :math:`J_y`, :math:`J_z`). -The next 3 components are the :math:`x`, :math:`y`, :math:`z` components -of just the convective portion of the flux, i.e. the -first term in the equation for :math:`\mathbf{J}`. -Each component can be -accessed by indices 1-6. These values can be used by any command that -uses global vector values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output -options. +The first three components are the :math:`x`, :math:`y`, and :math:`z` +components of the full heat flux vector +(i.e., :math:`J_x`, :math:`J_y`, and :math:`J_z`). +The next three components are the :math:`x`, :math:`y`, and :math:`z` +components of just the convective portion of the flux (i.e., the +first term in the equation for :math:`\mathbf{J}`). +Each component can be accessed by indices 1--6. These values can be used by any +command that uses global vector values from a compute as input. +See the :doc:`Howto output ` documentation for an overview of +LAMMPS output options. -The vector values calculated by this compute are "extensive", meaning +The vector values calculated by this compute are "extensive," meaning they scale with the number of atoms in the simulation. They can be divided by the appropriate volume to get a flux, which would then be an "intensive" value, meaning independent of the number of atoms in -the simulation. Note that if the compute is "all", then the +the simulation. Note that if the compute is "all," then the appropriate volume to divide by is the simulation box volume. However, if a sub-group is used, it should be the volume containing those atoms. @@ -172,6 +173,9 @@ none ---------- +Example Input File +------------------ + .. code-block:: LAMMPS # Sample LAMMPS input script for thermal conductivity of solid Ar diff --git a/doc/src/compute_hexorder_atom.rst b/doc/src/compute_hexorder_atom.rst index 8b8bc3f4d0..1fb8113a89 100644 --- a/doc/src/compute_hexorder_atom.rst +++ b/doc/src/compute_hexorder_atom.rst @@ -6,7 +6,7 @@ compute hexorder/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID hexorder/atom keyword values ... @@ -102,7 +102,7 @@ Output info This compute calculates a per-atom array with 2 columns, giving the real and imaginary parts :math:`q_n`, a complex number restricted to the -unit disk of the complex plane i.e. :math:`Re(q_n)^2 + Im(q_n)^2 <= 1`. +unit disk of the complex plane (i.e., :math:`\Re(q_n)^2 + \Im(q_n)^2 \le 1`). These values can be accessed by any command that uses per-atom values from a compute as input. See the :doc:`Howto output ` doc diff --git a/doc/src/compute_hma.rst b/doc/src/compute_hma.rst index e9c3133ebb..8c0c958ae5 100644 --- a/doc/src/compute_hma.rst +++ b/doc/src/compute_hma.rst @@ -6,20 +6,23 @@ compute hma command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID hma temp-ID keyword ... * ID, group-ID are documented in :doc:`compute ` command * hma = style name of this compute command * temp-ID = ID of fix that specifies the set temperature during canonical simulation -* keyword = *anharmonic* *u* *p Pharm* *cv* +* one or more keywords or keyword/argument pairs must be appended +* keyword = *anharmonic* or *u* or *p* or *cv* .. parsed-literal:: *anharmonic* = compute will return anharmonic property values *u* = compute will return potential energy - *p* = compute will return pressure. the following keyword must be the difference between the harmonic pressure and lattice pressure as described below + *p* value = Pharm = compute will return pressure + Pharm = difference between the harmonic pressure and lattice pressure + as described below *cv* = compute will return the heat capacity Examples @@ -74,44 +77,48 @@ A detailed description of this method can be found in (:ref:`Moustafa _{HMA} = \frac{d}{2} (N-1) k_B T + \left< U + \frac{1}{2} F\bullet\Delta r \right> + \left< U\right>_\text{HMA} = \frac{d}{2} (N-1) k_B T + \left< U + \frac{1}{2} \vec F\cdot\Delta \vec r \right> where :math:`N` is the number of atoms in the system, :math:`k_B` is Boltzmann's -constant, :math:`T` is the temperature, :math:`d` is the -dimensionality of the system (2 or 3 for 2d/3d), :math:`F\bullet\Delta r` is the sum of dot products of the -atomic force vectors and displacement (from lattice sites) vectors, and :math:`U` is the sum of -pair, bond, angle, dihedral, improper, kspace (long-range), and fix energies. +constant, :math:`T` is the temperature, :math:`d` is the dimensionality of the +system (2 or 3 for 2d/3d), :math:`\vec F\cdot\Delta\vec r` is the sum of dot +products of the atomic force vectors and displacement (from lattice sites) +vectors, and :math:`U` is the sum of pair, bond, angle, dihedral, improper, +kspace (long-range), and fix energies. The pressure is computed by the formula: .. math:: - \left< P\right>_{HMA} = \Delta \hat P + \left< P_{vir} + \frac{\beta \Delta \hat P - \rho}{d(N-1)} F\bullet\Delta r \right> + \left< P\right>_{HMA} = \Delta \hat P + \left< P_\text{vir} + + \frac{\beta \Delta \hat P - \rho}{d(N-1)} \vec F\cdot\Delta \vec r \right> -where :math:`\rho` is the number density of the system, :math:`\Delta \hat P` is the -difference between the harmonic and lattice pressure, :math:`P_{vir}` is -the virial pressure computed as the sum of pair, bond, angle, dihedral, -improper, kspace (long-range), and fix contributions to the force on each -atom, and :math:`k_B=1/k_B T`. Although the method will work for any value of :math:`\Delta \hat P` +where :math:`\rho` is the number density of the system, :math:`\Delta \hat P` +is the difference between the harmonic and lattice pressure, +:math:`P_\text{vir}` is the virial pressure computed as the sum of pair, bond, +angle, dihedral, improper, kspace (long-range), and fix contributions to the +force on each atom, and :math:`k_B=1/k_B T`. Although the method will work for +any value of :math:`\Delta \hat P` specified (use pressure :doc:`units `), the precision of the resultant pressure is sensitive to :math:`\Delta \hat P`; the precision tends to be -best when :math:`\Delta \hat P` is the actual the difference between the lattice -pressure and harmonic pressure. +best when :math:`\Delta \hat P` is the actual the difference between the +lattice pressure and harmonic pressure. .. math:: - \left_{HMA} = \frac{d}{2} (N-1) k_B + \frac{1}{k_B T^2} \left( \left< - U_{HMA}^2 \right> - \left^2 \right) + \frac{1}{4 T} - \left< F\bullet\Delta r + \Delta r \bullet \Phi \bullet \Delta r \right> + \left_\text{HMA} = \frac{d}{2} (N-1) k_B + + \frac{1}{k_B T^2} \left( \left + - \left^2 \right) + \frac{1}{4 T} + \left<\vec F\cdot\Delta\vec r + \Delta r \cdot\Phi\cdot \Delta\vec r\right> where :math:`\Phi` is the Hessian matrix. The compute hma command computes the full expression for :math:`C_V` except for the -:math:`\left^2` in the variance term, which can be obtained by -passing the *u* keyword; you must add this extra contribution to the :math:`C_V` -value reported by this compute. The variance term can cause significant -round-off error when computing :math:`C_V`. To address this, the *anharmonic* -keyword can be passed and/or the output format can be specified with more -digits. +:math:`\left^2` in the variance term, which can be obtained +by passing the *u* keyword; you must add this extra contribution to the +:math:`C_V` value reported by this compute. The variance term can cause +significant round-off error when computing :math:`C_V`. To address this, the +*anharmonic* keyword can be passed and/or the output format can be specified +with more digits. .. code-block:: LAMMPS @@ -124,8 +131,10 @@ When using this keyword, the compute must be first active (it must be included via a :doc:`thermo_style custom ` command) while the atoms are still at their lattice sites (before equilibration). -The temp-ID specified with compute hma command should be same as the fix-ID of Nose-Hoover (:doc:`fix nvt `) or -Berendsen (:doc:`fix temp/berendsen `) thermostat used for the simulation. While using this command, Langevin thermostat +The temp-ID specified with compute hma command should be same as the fix-ID of +the Nose--Hoover (:doc:`fix nvt `) or +Berendsen (:doc:`fix temp/berendsen `) thermostat used for +the simulation. While using this command, the Langevin thermostat (:doc:`fix langevin `) should be avoided as its extra forces interfere with the HMA implementation. @@ -160,10 +169,10 @@ Output info This compute calculates a global vector that includes the n properties requested as arguments to the command (the potential energy, pressure and/or heat -capacity). The elements of the vector can be accessed by indices 1-n by any +capacity). The elements of the vector can be accessed by indices 1--n by any command that uses global vector values as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. -The vector values calculated by this compute are "extensive". The +The vector values calculated by this compute are "extensive." The scalar value will be in energy :doc:`units `. Restrictions @@ -180,7 +189,7 @@ Related commands :doc:`compute pe `, :doc:`compute pressure ` :doc:`dynamical matrix ` provides a finite difference -formulation of the hessian provided by Pair's single_hessian, which is used by +formulation of the Hessian provided by Pair's single_hessian, which is used by this compute. Default diff --git a/doc/src/compute_improper.rst b/doc/src/compute_improper.rst index 2d6684b240..75e944d8d2 100644 --- a/doc/src/compute_improper.rst +++ b/doc/src/compute_improper.rst @@ -6,7 +6,7 @@ compute improper command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID improper @@ -34,11 +34,13 @@ total energy contributed by one or more of the hybrid sub-styles. Output info """"""""""" -This compute calculates a global vector of length N where N is the -number of sub_styles defined by the :doc:`improper_style hybrid ` command. which can be accessed by indices -1-N. These values can be used by any command that uses global scalar -or vector values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output -options. +This compute calculates a global vector of length :math:`N`, where :math:`N` is +the number of sub_styles defined by the +:doc:`improper_style hybrid ` command. +These styles can be accessed by the indices 1 through :math:`N`. +These values can be used by any command that uses global scalar or vector +values from a compute as input. See the :doc:`Howto output ` +page for an overview of LAMMPS output options. The vector values are "extensive" and will be in energy :doc:`units `. diff --git a/doc/src/compute_improper_local.rst b/doc/src/compute_improper_local.rst index 3a849bf20c..5377b60baa 100644 --- a/doc/src/compute_improper_local.rst +++ b/doc/src/compute_improper_local.rst @@ -6,7 +6,7 @@ compute improper/local command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID improper/local value1 value2 ... @@ -40,7 +40,7 @@ the individual improper styles listed on The local data stored by this command is generated by looping over all the atoms owned on a processor and their impropers. An improper will -only be included if all 4 atoms in the improper are in the specified +only be included if all four atoms in the improper are in the specified compute group. Note that as atoms migrate from processor to processor, there will be @@ -69,7 +69,8 @@ array is the number of impropers. If a single keyword is specified, a local vector is produced. If two or more keywords are specified, a local array is produced where the number of columns = the number of keywords. The vector or array can be accessed by any command that -uses local values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output +uses local values from a compute as input. See the +:doc:`Howto output ` page for an overview of LAMMPS output options. The output for *chi* will be in degrees. diff --git a/doc/src/compute_inertia_chunk.rst b/doc/src/compute_inertia_chunk.rst index 42f5725d92..74f59dd7a7 100644 --- a/doc/src/compute_inertia_chunk.rst +++ b/doc/src/compute_inertia_chunk.rst @@ -6,7 +6,7 @@ compute inertia/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID inertia/chunk chunkID @@ -27,16 +27,20 @@ Description Define a computation that calculates the inertia tensor for multiple chunks of atoms. -In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom ` command, which assigns each atom +In LAMMPS, chunks are collections of atoms defined by a +:doc:`compute chunk/atom ` command, which assigns each atom to a single chunk (or no chunk). The ID for this command is specified as chunkID. For example, a single chunk could be the atoms in a -molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom ` and :doc:`Howto chunk ` +molecule or atoms in a spatial bin. See the +:doc:`compute chunk/atom ` and +:doc:`Howto chunk ` doc pages for details of how chunks can be defined and examples of how they can be used to measure properties of a system. -This compute calculates the 6 components of the symmetric inertia -tensor for each chunk, ordered Ixx,Iyy,Izz,Ixy,Iyz,Ixz. The -calculation includes all effects due to atoms passing through periodic +This compute calculates the six components of the symmetric inertia +tensor for each chunk, ordered +:math:`I_{xx},I_{yy},I_{zz},I_{xy},I_{yz},I_{xz}`. +The calculation includes all effects due to atoms passing through periodic boundaries. Note that only atoms in the specified group contribute to the @@ -55,7 +59,8 @@ non-zero chunk IDs. of "unwrapped" coordinates. See the Atoms section of the :doc:`read_data ` command for a discussion of image flags and how they are set for each atom. You can reset the image flags - (e.g. to 0) before invoking this compute by using the :doc:`set image ` command. + (e.g., to 0) before invoking this compute by using the + :doc:`set image ` command. The simplest way to output the results of the compute inertia/chunk calculation to a file is to use the :doc:`fix ave/time ` @@ -71,14 +76,16 @@ Output info """"""""""" This compute calculates a global array where the number of rows = the -number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom ` command. The number of columns = -6 for the 6 components of the inertia tensor for each chunk, ordered -as listed above. These values can be accessed by any command that -uses global array values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output +number of chunks *Nchunk* as calculated by the specified +:doc:`compute chunk/atom ` command. +The number of columns is 6, one for each of the 6 components of the inertia +tensor for each chunk, ordered as listed above. These values can be accessed +by any command that uses global array values from a compute as input. See the +:doc:`Howto output ` page for an overview of LAMMPS output options. -The array values are "intensive". The array values will be in -mass\*distance\^2 :doc:`units `. +The array values are "intensive." The array values will be in +mass\*distance\ :math:`^2` :doc:`units `. Restrictions """""""""""" diff --git a/doc/src/compute_ke.rst b/doc/src/compute_ke.rst index 786f17b1d8..4eb07b920c 100644 --- a/doc/src/compute_ke.rst +++ b/doc/src/compute_ke.rst @@ -6,7 +6,7 @@ compute ke command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID ke @@ -27,7 +27,8 @@ Define a computation that calculates the translational kinetic energy of a group of particles. The kinetic energy of each particle is computed as :math:`\frac{1}{2} m -v^2`, where *m* and *v* are the mass and velocity of the particle. +v^2`, where *m* and *v* are the mass and velocity of the particle, +respectively. There is a subtle difference between the quantity calculated by this compute and the kinetic energy calculated by the *ke* or *etotal* @@ -38,10 +39,10 @@ formula above. For thermodynamic output, the *ke* keyword infers kinetic energy from the temperature of the system with :math:`\frac{1}{2} k_B T` of energy for each degree of freedom. For the default temperature computation via the :doc:`compute temp -` command, these are the same. But different computes -that calculate temperature can subtract out different non-thermal -components of velocity and/or include different degrees of freedom -(translational, rotational, etc). +` command, these are the same. +However, different computes that calculate temperature can subtract out +different non-thermal components of velocity and/or include different degrees +of freedom (translational, rotational, etc.). Output info """"""""""" @@ -51,7 +52,7 @@ can be used by any command that uses a global scalar value from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output options. -The scalar value calculated by this compute is "extensive". The +The scalar value calculated by this compute is "extensive." The scalar value will be in energy :doc:`units `. Restrictions diff --git a/doc/src/compute_ke_atom.rst b/doc/src/compute_ke_atom.rst index 277b6ea6d6..34a5ab4073 100644 --- a/doc/src/compute_ke_atom.rst +++ b/doc/src/compute_ke_atom.rst @@ -6,7 +6,7 @@ compute ke/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID ke/atom @@ -26,8 +26,8 @@ Description Define a computation that calculates the per-atom translational kinetic energy for each atom in a group. -The kinetic energy is simply 1/2 m v\^2, where m is the mass and v is -the velocity of each atom. +The kinetic energy is simply :math:`\frac12 m v^2`, where :math:`m` is the mass +and :math:`v` is the velocity of each atom. The value of the kinetic energy will be 0.0 for atoms not in the specified compute group. diff --git a/doc/src/compute_ke_atom_eff.rst b/doc/src/compute_ke_atom_eff.rst index 4587632818..fa186225bd 100644 --- a/doc/src/compute_ke_atom_eff.rst +++ b/doc/src/compute_ke_atom_eff.rst @@ -6,7 +6,7 @@ compute ke/atom/eff command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID ke/atom/eff diff --git a/doc/src/compute_ke_eff.rst b/doc/src/compute_ke_eff.rst index 233352ba7a..8e49d25cbe 100644 --- a/doc/src/compute_ke_eff.rst +++ b/doc/src/compute_ke_eff.rst @@ -6,7 +6,7 @@ compute ke/eff command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID ke/eff @@ -29,9 +29,9 @@ group of eFF particles (nuclei and electrons), as modeled with the The kinetic energy for each nucleus is computed as :math:`\frac{1}{2} m v^2` and the kinetic energy for each electron is computed as -:math:`\frac{1}{2}(m_e v^2 + \frac{3}{4} m_e s^2)`, where *m* -corresponds to the nuclear mass, :math:`m_e` to the electron mass, *v* -to the translational velocity of each particle, and *s* to the radial +:math:`\frac{1}{2}(m_e v^2 + \frac{3}{4} m_e s^2)`, where :math:`m` +corresponds to the nuclear mass, :math:`m_e` to the electron mass, :math:`v` +to the translational velocity of each particle, and :math:`s` to the radial velocity of the electron, respectively. There is a subtle difference between the quantity calculated by this diff --git a/doc/src/compute_ke_rigid.rst b/doc/src/compute_ke_rigid.rst index 680b1a60fc..b3e446daf6 100644 --- a/doc/src/compute_ke_rigid.rst +++ b/doc/src/compute_ke_rigid.rst @@ -6,7 +6,7 @@ compute ke/rigid command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID ke/rigid fix-ID @@ -25,11 +25,13 @@ Description """"""""""" Define a computation that calculates the translational kinetic energy -of a collection of rigid bodies, as defined by one of the :doc:`fix rigid ` command variants. +of a collection of rigid bodies, as defined by one of the +:doc:`fix rigid ` command variants. -The kinetic energy of each rigid body is computed as 1/2 M Vcm\^2, -where M is the total mass of the rigid body, and Vcm is its -center-of-mass velocity. +The kinetic energy of each rigid body is computed as +:math:`\frac12 M V_\text{cm}^2`, +where :math:`M` is the total mass of the rigid body, and :math:`V_\text{cm}` +is its center-of-mass velocity. The *fix-ID* should be the ID of one of the :doc:`fix rigid ` commands which defines the rigid bodies. The group specified in the @@ -42,10 +44,11 @@ Output info This compute calculates a global scalar (the summed KE of all the rigid bodies). This value can be used by any command that uses a -global scalar value from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output +global scalar value from a compute as input. See the +:doc:`Howto output ` page for an overview of LAMMPS output options. -The scalar value calculated by this compute is "extensive". The +The scalar value calculated by this compute is "extensive." The scalar value will be in energy :doc:`units `. Restrictions diff --git a/doc/src/compute_mesont.rst b/doc/src/compute_mesont.rst index c396a33dbc..0569155134 100644 --- a/doc/src/compute_mesont.rst +++ b/doc/src/compute_mesont.rst @@ -6,30 +6,29 @@ compute mesont command Syntax """""" +.. code-block:: LAMMPS -.. parsed-literal:: - - compute ID group-ID mesont mode + compute ID group-ID mesont style * ID, group-ID are documented in :doc:`compute ` command * mesont = style name of the compute command -* mode = one of estretch, ebend, etube (see details below) +* style = *estretch* or *ebend* or *etube* Examples """""""" -.. parsed-literal:: +.. code-block:: LAMMPS compute 1 all mesont estretch Description """"""""""" -These computes define computations for the stretching (estretch), bending -(ebend), and intertube (etube) per-node (atom) and total energies. The -evaluated value is selected by a parameter passed to the compute: estretch, -ebend, etube. +These computes define computations for the stretching (*estretch*), bending +(*ebend*), and intertube (*etube*) per-node (atom) and total energies. The +evaluated value is selected by the style parameter passed to the compute +(*estretch*, *ebend*,or *etube*). Output info """"""""""" diff --git a/doc/src/compute_mliap.rst b/doc/src/compute_mliap.rst index 350f4c800c..6abd3e5a6b 100644 --- a/doc/src/compute_mliap.rst +++ b/doc/src/compute_mliap.rst @@ -36,10 +36,10 @@ Description """"""""""" Compute style *mliap* provides a general interface to the gradient -of machine-learning interatomic potentials w.r.t. model parameters. +of machine-learning interatomic potentials with respect to model parameters. It is used primarily for calculating the gradient of energy, force, and -stress components w.r.t. model parameters, which is useful when training -:doc:`mliap pair_style ` models to match target data. +stress components with respect to model parameters, which is useful when +training :doc:`mliap pair_style ` models to match target data. It provides separate definitions of the interatomic potential functional form (*model*) and the geometric quantities that characterize the atomic positions @@ -58,8 +58,8 @@ The compute *mliap* command must be followed by two keywords The *model* keyword is followed by the model style (*linear*, *quadratic* or *mliappy*). The *mliappy* model is only available if -LAMMPS is built with the *mliappy* python module. There are -:ref:`specific installation instructions ` for that. +LAMMPS is built with the *mliappy* Python module. There are +:ref:`specific installation instructions ` for that module. The *descriptor* keyword is followed by a descriptor style, and additional arguments. The compute currently supports two descriptor @@ -79,13 +79,13 @@ described in detail there. must match the value of *nelems* in the descriptor file. Compute *mliap* calculates a global array containing gradient information. -The number of columns in the array is :math:`nelems \times nparams + 1`. -The first row of the array contain the derivative of potential energy w.r.t. to -each parameter and each element. The last six rows +The number of columns in the array is *nelems* :math:`\times` *nparams* + 1. +The first row of the array contain the derivative of potential energy with +respect to. to each parameter and each element. The last six rows of the array contain the corresponding derivatives of the virial stress tensor, listed in Voigt notation: *pxx*, *pyy*, *pzz*, -*pyz*, *pxz*, *pxy*. In between the energy and stress rows are -the 3\*\ *N* rows containing the derivatives of the force components. +*pyz*, *pxz*, and *pxy*. In between the energy and stress rows are +the :math:`3N` rows containing the derivatives of the force components. See section below on output for a detailed description of how rows and columns are ordered. @@ -107,19 +107,19 @@ layout in the global array. The optional keyword *gradgradflag* controls how the force gradient is calculated. A value of 1 requires that the model provide -the matrix of double gradients of energy w.r.t. both parameters +the matrix of double gradients of energy with respect to both parameters and descriptors. For the linear and quadratic models this matrix is sparse and so is easily calculated and stored. For other models, this matrix may be prohibitively expensive to calculate and store. A value of 0 requires that the descriptor provide the derivative -of the descriptors w.r.t. the position of every neighbor atom. +of the descriptors with respect to the position of every neighbor atom. This is not optimal for linear and quadratic models, but may be a better choice for more complex models. Atoms not in the group do not contribute to this compute. Neighbor atoms not in the group do not contribute to this compute. The neighbor list needed to compute this quantity is constructed each -time the calculation is performed (i.e. each time a snapshot of atoms +time the calculation is performed (i.e., each time a snapshot of atoms is dumped). Thus it can be inefficient to compute/dump this quantity too frequently. @@ -144,17 +144,20 @@ too frequently. Output info """"""""""" -Compute *mliap* evaluates a global array. -The columns are arranged into +Compute *mliap* evaluates a global array. The columns are arranged into *nelems* blocks, listed in order of element *I*\ . Each block contains one column for each of the *nparams* model parameters. A final column contains the corresponding energy, force component on an atom, or virial stress component. The rows of the array appear in the following order: -* 1 row: Derivatives of potential energy w.r.t. each parameter of each element. -* 3\*\ *N* rows: Derivatives of force components. x, y, and z components of force on atom *i* appearing in consecutive rows. The atoms are sorted based on atom ID. -* 6 rows: Derivatives of virial stress tensor w.r.t. each parameter of each element. The ordering of the rows follows Voigt notation: *pxx*, *pyy*, *pzz*, *pyz*, *pxz*, *pxy*. +* 1 row: Derivatives of potential energy with respect to each parameter of each element. +* :math:`3N` rows: Derivatives of force components; the *x*, *y*, and *z* + components of the force on atom *i* appear in consecutive rows. The atoms are + sorted based on atom ID. +* 6 rows: Derivatives of the virial stress tensor with respect to each + parameter of each element. The ordering of the rows follows Voigt notation: + *pxx*, *pyy*, *pzz*, *pyz*, *pxz*, *pxy*. These values can be accessed by any command that uses a global array from a compute as input. See the :doc:`Howto output ` doc diff --git a/doc/src/compute_momentum.rst b/doc/src/compute_momentum.rst index 40d2f527f5..59215c889b 100644 --- a/doc/src/compute_momentum.rst +++ b/doc/src/compute_momentum.rst @@ -6,7 +6,7 @@ compute momentum command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID momentum @@ -24,7 +24,8 @@ Description """"""""""" Define a computation that calculates the translational momentum *p* -of a group of particles. It is computed as the sum :math:`\vec{p} = \sum_i m_i \cdot \vec{v}_i` +of a group of particles. It is computed as the sum +:math:`\vec{p} = \sum_i m_i \cdot \vec{v}_i` over all particles in the compute group, where *m* and *v* are the mass and velocity vector of the particle, respectively. @@ -36,7 +37,7 @@ length 3. This value can be used by any command that uses a global vector value from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. -The vector value calculated by this compute is "extensive". The vector +The vector value calculated by this compute is "extensive." The vector value will be in mass\*velocity :doc:`units `. Restrictions diff --git a/doc/src/compute_msd.rst b/doc/src/compute_msd.rst index 6e89cc59c1..77694ca8fc 100644 --- a/doc/src/compute_msd.rst +++ b/doc/src/compute_msd.rst @@ -6,7 +6,7 @@ compute msd command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID msd keyword values ... @@ -34,12 +34,13 @@ Description Define a computation that calculates the mean-squared displacement (MSD) of the group of atoms, including all effects due to atoms passing through periodic boundaries. For computation of the non-Gaussian -parameter of mean-squared displacement, see the :doc:`compute msd/nongauss ` command. +parameter of mean-squared displacement, see the +:doc:`compute msd/nongauss ` command. -A vector of four quantities is calculated by this compute. The first 3 -elements of the vector are the squared dx,dy,dz displacements, summed -and averaged over atoms in the group. The fourth element is the total -squared displacement, i.e. (dx\*dx + dy\*dy + dz\*dz), summed and +A vector of four quantities is calculated by this compute. The first three +elements of the vector are the squared *dx*, *dy*, and *dz* displacements, +summed and averaged over atoms in the group. The fourth element is the total +squared displacement (i.e., :math:`dx^2 + dy^2 + dz^2`), summed and averaged over atoms in the group. The slope of the mean-squared displacement (MSD) versus time is @@ -100,12 +101,12 @@ Output info """"""""""" This compute calculates a global vector of length 4, which can be -accessed by indices 1-4 by any command that uses global vector values +accessed by indices 1--4 by any command that uses global vector values from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output options. -The vector values are "intensive". The vector values will be in -distance\^2 :doc:`units `. +The vector values are "intensive." The vector values will be in +distance\ :math:`^2` :doc:`units `. Restrictions """""""""""" diff --git a/doc/src/compute_msd_chunk.rst b/doc/src/compute_msd_chunk.rst index ed13a32b7c..6be5196782 100644 --- a/doc/src/compute_msd_chunk.rst +++ b/doc/src/compute_msd_chunk.rst @@ -6,7 +6,7 @@ compute msd/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID msd/chunk chunkID @@ -27,19 +27,21 @@ Description Define a computation that calculates the mean-squared displacement (MSD) for multiple chunks of atoms. -In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom ` command, which assigns each atom +In LAMMPS, chunks are collections of atoms defined by a +:doc:`compute chunk/atom ` command, which assigns each atom to a single chunk (or no chunk). The ID for this command is specified as chunkID. For example, a single chunk could be the atoms in a -molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom ` and :doc:`Howto chunk ` +molecule or atoms in a spatial bin. See the +:doc:`compute chunk/atom ` and +:doc:`Howto chunk ` doc pages for details of how chunks can be defined and examples of how they can be used to measure properties of a system. Four quantities are calculated by this compute for each chunk. The -first 3 quantities are the squared dx,dy,dz displacements of the -center-of-mass. The fourth component is the total squared displacement, -i.e. (dx\*dx + dy\*dy + dz\*dz) of the center-of-mass. These -calculations include all effects due to atoms passing through periodic -boundaries. +first 3 quantities are the squared *dx*, *dy*, and *dz* displacements of the +center-of-mass. The fourth component is the total squared displacement +(i.e., :math:`dx^2 + dy^2 + dz^2`) of the center-of-mass. These calculations +include all effects due to atoms passing through periodic boundaries. Note that only atoms in the specified group contribute to the calculation. The :doc:`compute chunk/atom ` command @@ -58,12 +60,14 @@ compute command was first invoked. .. note:: - The number of chunks *Nchunk* calculated by the :doc:`compute chunk/atom ` command must remain constant each - time this compute is invoked, so that the displacement for each chunk + The number of chunks *Nchunk* calculated by the + :doc:`compute chunk/atom ` command must remain constant + each time this compute is invoked, so that the displacement for each chunk from its original position can be computed consistently. If *Nchunk* does not remain constant, an error will be generated. If needed, you - can enforce a constant *Nchunk* by using the *nchunk once* or *ids - once* options when specifying the :doc:`compute chunk/atom ` command. + can enforce a constant *Nchunk* by using the *nchunk once* or *ids once* + options when specifying the :doc:`compute chunk/atom ` + command. .. note:: @@ -84,7 +88,8 @@ compute command was first invoked. "unwrapped" coordinates. See the Atoms section of the :doc:`read_data ` command for a discussion of image flags and how they are set for each atom. You can reset the image flags - (e.g. to 0) before invoking this compute by using the :doc:`set image ` command. + (e.g., to 0) before invoking this compute by using the + :doc:`set image ` command. .. note:: @@ -109,14 +114,15 @@ Output info """"""""""" This compute calculates a global array where the number of rows = the -number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom ` command. The number of columns = -4 for dx,dy,dz and the total displacement. These values can be -accessed by any command that uses global array values from a compute -as input. See the :doc:`Howto output ` page for an +number of chunks *Nchunk* as calculated by the specified +:doc:`compute chunk/atom ` command. +The number of columns = 4 for *dx*, *dy*, *dz*, and the total displacement. +These values can be accessed by any command that uses global array values from +a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. -The array values are "intensive". The array values will be in -distance\^2 :doc:`units `. +The array values are "intensive." The array values will be in +distance\ :math:`^2` :doc:`units `. Restrictions """""""""""" diff --git a/doc/src/compute_msd_nongauss.rst b/doc/src/compute_msd_nongauss.rst index 1658d26f93..16c4e0b06c 100644 --- a/doc/src/compute_msd_nongauss.rst +++ b/doc/src/compute_msd_nongauss.rst @@ -6,7 +6,7 @@ compute msd/nongauss command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID msd/nongauss keyword values ... @@ -35,21 +35,21 @@ Define a computation that calculates the mean-squared displacement including all effects due to atoms passing through periodic boundaries. A vector of three quantities is calculated by this compute. The first -element of the vector is the total squared dx,dy,dz displacements -drsquared = (dx\*dx + dy\*dy + dz\*dz) of atoms, and the second is the -fourth power of these displacements drfourth = (dx\*dx + dy\*dy + -dz\*dz)\*(dx\*dx + dy\*dy + dz\*dz), summed and averaged over atoms in the -group. The third component is the nonGaussian diffusion parameter NGP = -3\*drfourth/(5\*drsquared\*drsquared), i.e. +element of the vector is the total squared displacement, +:math:`dr^2 = dx^2 + dy^2 + dz^2`, of the atoms, and the second is the +fourth power of these displacements, :math:`dr^4 = (dx^2 + dy^2 + dz^2)^2`, +summed and averaged over atoms in the group. The third component is the +non-Gaussian diffusion parameter NGP, .. math:: - NGP(t) = 3<(r(t)-r(0))^4>/(5<(r(t)-r(0))^2>^2) - 1 + \text{NGP}(t) = \frac{3\left\langle(r(t)-r(0))^4\right\rangle} + {5\left\langle(r(t)-r(0))^2\right\rangle^2} - 1. The NGP is a commonly used quantity in studies of dynamical -heterogeneity. Its minimum theoretical value (-0.4) occurs when all -atoms have the same displacement magnitude. NGP=0 for Brownian -diffusion, while NGP > 0 when some mobile atoms move faster than +heterogeneity. Its minimum theoretical value :math:`(-0.4)` occurs when all +atoms have the same displacement magnitude. :math:`\text{NGP}=0` for Brownian +diffusion, while :math:`\text{NGP} > 0` when some mobile atoms move faster than others. If the *com* option is set to *yes* then the effect of any drift in @@ -63,13 +63,13 @@ Output info """"""""""" This compute calculates a global vector of length 3, which can be -accessed by indices 1-3 by any command that uses global vector values +accessed by indices 1--3 by any command that uses global vector values from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output options. -The vector values are "intensive". The first vector value will be in -distance\^2 :doc:`units `, the second is in distance\^4 units, and -the third is dimensionless. +The vector values are "intensive." The first vector value will be in +distance\ :math:`^2` :doc:`units `, the second is in +distance\ :math:`^4` units, and the third is dimensionless. Restrictions """""""""""" diff --git a/doc/src/compute_nbond_atom.rst b/doc/src/compute_nbond_atom.rst index e86986287f..0e53de3e49 100644 --- a/doc/src/compute_nbond_atom.rst +++ b/doc/src/compute_nbond_atom.rst @@ -6,7 +6,7 @@ compute nbond/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID nbond/atom diff --git a/doc/src/compute_omega_chunk.rst b/doc/src/compute_omega_chunk.rst index 90baf9e2b3..8c32d6491e 100644 --- a/doc/src/compute_omega_chunk.rst +++ b/doc/src/compute_omega_chunk.rst @@ -6,7 +6,7 @@ compute omega/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID omega/chunk chunkID @@ -27,18 +27,23 @@ Description Define a computation that calculates the angular velocity (omega) of multiple chunks of atoms. -In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom ` command, which assigns each atom +In LAMMPS, chunks are collections of atoms defined by a +:doc:`compute chunk/atom ` command, which assigns each atom to a single chunk (or no chunk). The ID for this command is specified as chunkID. For example, a single chunk could be the atoms in a -molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom ` and :doc:`Howto chunk ` +molecule or atoms in a spatial bin. See the +:doc:`compute chunk/atom ` and +:doc:`Howto chunk ` doc pages for details of how chunks can be defined and examples of how they can be used to measure properties of a system. -This compute calculates the 3 components of the angular velocity -vector for each chunk, via the formula L = Iw where L is the angular -momentum vector of the chunk, I is its moment of inertia tensor, and w -is omega = angular velocity of the chunk. The calculation includes -all effects due to atoms passing through periodic boundaries. +This compute calculates the three components of the angular velocity +vector for each chunk via the formula +:math:`\vec L = \mathrm{I}\cdot \vec\omega`, where :math:`\vec L` is the +angular momentum vector of the chunk, :math:`\mathrm{I}` is its moment of +inertia tensor, and :math:`\omega` is the angular velocity of the chunk. +The calculation includes all effects due to atoms passing through periodic +boundaries. Note that only atoms in the specified group contribute to the calculation. The :doc:`compute chunk/atom ` command @@ -56,7 +61,8 @@ non-zero chunk IDs. of "unwrapped" coordinates. See the Atoms section of the :doc:`read_data ` command for a discussion of image flags and how they are set for each atom. You can reset the image flags - (e.g. to 0) before invoking this compute by using the :doc:`set image ` command. + (e.g., to 0) before invoking this compute by using the + :doc:`set image ` command. The simplest way to output the results of the compute omega/chunk calculation to a file is to use the :doc:`fix ave/time ` @@ -71,14 +77,14 @@ command, for example: Output info """"""""""" -This compute calculates a global array where the number of rows = the -number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom ` command. The number of columns = -3 for the 3 xyz components of the angular velocity for each chunk. +This compute calculates a global array where the number of rows is the +number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom ` command. The number of columns is 3 for the three +(*x*, *y*, *z*) components of the angular velocity for each chunk. These values can be accessed by any command that uses global array -values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output -options. +values from a compute as input. See the :doc:`Howto output ` +page for an overview of LAMMPS output options. -The array values are "intensive". The array values will be in +The array values are "intensive." The array values will be in velocity/distance :doc:`units `. Restrictions diff --git a/doc/src/compute_orientorder_atom.rst b/doc/src/compute_orientorder_atom.rst index 82c7c57495..d564a3abd0 100644 --- a/doc/src/compute_orientorder_atom.rst +++ b/doc/src/compute_orientorder_atom.rst @@ -9,7 +9,7 @@ Accelerator Variants: *orientorder/atom/kk* Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID orientorder/atom keyword values ... @@ -42,30 +42,30 @@ Description """"""""""" Define a computation that calculates a set of bond-orientational -order parameters :math:`Q_l` for each atom in a group. These order parameters +order parameters :math:`Q_\ell` for each atom in a group. These order parameters were introduced by :ref:`Steinhardt et al. ` as a way to characterize the local orientational order in atomic structures. -For each atom, :math:`Q_l` is a real number defined as follows: +For each atom, :math:`Q_\ell` is a real number defined as follows: .. math:: - \bar{Y}_{lm} = & \frac{1}{nnn}\sum_{j = 1}^{nnn} Y_{lm}( \theta( {\bf r}_{ij} ), \phi( {\bf r}_{ij} ) ) \\ - Q_l = & \sqrt{\frac{4 \pi}{2 l + 1} \sum_{m = -l}^{m = l} \bar{Y}_{lm} \bar{Y}^*_{lm}} + \bar{Y}_{\ell m} = & \frac{1}{nnn}\sum_{j = 1}^{nnn} Y_{\ell m}\bigl( \theta( {\bf r}_{ij} ), \phi( {\bf r}_{ij} ) \bigr) \\ + Q_\ell = & \sqrt{\frac{4 \pi}{2 \ell + 1} \sum_{m = -\ell }^{m = \ell } \bar{Y}_{\ell m} \bar{Y}^*_{\ell m}} The first equation defines the local order parameters as averages -of the spherical harmonics :math:`Y_{lm}` for each neighbor. +of the spherical harmonics :math:`Y_{\ell m}` for each neighbor. These are complex number components of the 3D analog of the 2D order parameter :math:`q_n`, which is implemented as LAMMPS compute :doc:`hexorder/atom `. The summation is over the *nnn* nearest -neighbors of the central atom. -The angles :math:`theta` and :math:`phi` are the standard spherical polar angles +neighbors of the central atom. The angles :math:`\theta` and :math:`\phi` are +the standard spherical polar angles defining the direction of the bond vector :math:`r_{ij}`. -The phase and sign of :math:`Y_{lm}` follow the standard conventions, -so that :math:`{\rm sign}(Y_{ll}(0,0)) = (-1)^l`. -The second equation defines :math:`Q_l`, which is a +The phase and sign of :math:`Y_{\ell m}` follow the standard conventions, +so that :math:`\mathrm{sign}(Y_{\ell\ell}(0,0)) = (-1)^\ell`. +The second equation defines :math:`Q_\ell`, which is a rotationally invariant non-negative amplitude obtained by summing -over all the components of degree *l*\ . +over all the components of degree :math:`\ell`. The optional keyword *cutoff* defines the distance cutoff used when searching for neighbors. The default value, also @@ -73,7 +73,7 @@ the maximum allowable value, is the cutoff specified by the pair style. The optional keyword *nnn* defines the number of nearest -neighbors used to calculate :math:`Q_l`. The default value is 12. +neighbors used to calculate :math:`Q_\ell`. The default value is 12. If the value is NULL, then all neighbors up to the specified distance cutoff are used. @@ -84,32 +84,45 @@ degree of each order parameter. Because :math:`Q_2` and all odd-degree order parameters are zero for atoms in cubic crystals (see :ref:`Steinhardt `), the default order parameters are :math:`Q_4`, :math:`Q_6`, :math:`Q_8`, :math:`Q_{10}`, and :math:`Q_{12}`. For the FCC -crystal with *nnn* =12, :math:`Q_4 = \sqrt{\frac{7}{192}} = 0.19094...`. +crystal with *nnn* =12, + +.. math:: + Q_4 = \sqrt{\frac{7}{192}} \approx 0.19094 + The numerical values of all order -parameters up to :math:`Q_12` for a range of commonly encountered +parameters up to :math:`Q_{12}` for a range of commonly encountered high-symmetry structures are given in Table I of :ref:`Mickel et al. `, and these can be reproduced with this compute. -The optional keyword *wl* will output the third-order invariants :math:`W_l` +The optional keyword *wl* will output the third-order invariants :math:`W_\ell` (see Eq. 1.4 in :ref:`Steinhardt `) for the same degrees as -for the :math:`Q_l` parameters. For the FCC crystal with *nnn* =12, -:math:`W_4` = -sqrt(14/143).(49/4096)/Pi\^1.5 = -0.0006722136... +for the :math:`Q_\ell` parameters. For the FCC crystal with *nnn* = 12, + +.. math:: + + W_4 = -\sqrt{\frac{14}{143}} \left(\frac{49}{4096}\right) \pi^{-3/2} \approx -0.0006722136 The optional keyword *wl/hat* will output the normalized third-order -invariants :math:`\hat{W}_l` (see Eq. 2.2 in :ref:`Steinhardt `) -for the same degrees as for the :math:`Q_l` parameters. For the FCC crystal -with *nnn* =12, :math:`\hat{W}_4 = -\frac{7}{3} \sqrt{\frac{2}{429}} = -0.159317...` -The numerical -values of :math:`\hat{W}_l` for a range of commonly encountered high-symmetry -structures are given in Table I of :ref:`Steinhardt `, and these -can be reproduced with this keyword. +invariants :math:`\hat{W}_\ell` (see Eq. 2.2 in :ref:`Steinhardt `) +for the same degrees as for the :math:`Q_\ell` parameters. For the FCC crystal +with *nnn* =12, + +.. math:: + + \hat{W}_4 = -\frac{7}{3} \sqrt{\frac{2}{429}} \approx -0.159317 + +The numerical values of :math:`\hat{W}_\ell` for a range of commonly +encountered high-symmetry structures are given in Table I of +:ref:`Steinhardt `, and these can be reproduced with this keyword. The optional keyword *components* will output the components of the -*normalized* complex vector :math:`\hat{Y}_{lm} = \bar{Y}_{lm}/|\bar{Y}_{lm}|` of degree *ldegree*\, -which must be included in the list of order parameters to be computed. This option can be used -in conjunction with :doc:`compute coord_atom ` to -calculate the ten Wolde's criterion to identify crystal-like -particles, as discussed in :ref:`ten Wolde `. +*normalized* complex vector +:math:`\hat{Y}_{\ell m} = \bar{Y}_{\ell m}/|\bar{Y}_{\ell m}|` +of degree *ldegree*\, which must be included in the list of order parameters to +be computed. This option can be used in conjunction with +:doc:`compute coord_atom ` to calculate the ten Wolde's +criterion to identify crystal-like particles, as discussed in +:ref:`ten Wolde `. The optional keyword *chunksize* is only applicable when using the the KOKKOS package and is ignored otherwise. This keyword controls @@ -119,12 +132,12 @@ if there are 32768 atoms in the simulation and the *chunksize* is set to 16384, the parameter calculation will be broken up into two passes. -The value of :math:`Q_l` is set to zero for atoms not in the +The value of :math:`Q_\ell` is set to zero for atoms not in the specified compute group, as well as for atoms that have less than *nnn* neighbors within the distance cutoff, unless *nnn* is NULL. The neighbor list needed to compute this quantity is constructed each -time the calculation is performed (i.e. each time a snapshot of atoms +time the calculation is performed (i.e., each time a snapshot of atoms is dumped). Thus it can be inefficient to compute/dump this quantity too frequently. @@ -155,19 +168,21 @@ Output info """"""""""" This compute calculates a per-atom array with *nlvalues* columns, -giving the :math:`Q_l` values for each atom, which are real numbers on the -range :math:`0 <= Q_l <= 1`. +giving the :math:`Q_\ell` values for each atom, which are real numbers in the +range :math:`0 \le Q_\ell \le 1`. -If the keyword *wl* is set to yes, then the :math:`W_l` values for each +If the keyword *wl* is set to yes, then the :math:`W_\ell` values for each atom will be added to the output array, which are real numbers. -If the keyword *wl/hat* is set to yes, then the :math:`\hat{W}_l` +If the keyword *wl/hat* is set to yes, then the :math:`\hat{W}_\ell` values for each atom will be added to the output array, which are real numbers. If the keyword *components* is set, then the real and imaginary parts -of each component of *normalized* :math:`\hat{Y}_{lm}` will be added to the -output array in the following order: :math:`{\rm Re}(\hat{Y}_{-m}), {\rm Im}(\hat{Y}_{-m}), -{\rm Re}(\hat{Y}_{-m+1}), {\rm Im}(\hat{Y}_{-m+1}), \dots , {\rm Re}(\hat{Y}_m), {\rm Im}(\hat{Y}_m)`. +of each component of *normalized* :math:`\hat{Y}_{\ell m}` will be added to the +output array in the following order: +:math:`\Re(\hat{Y}_{-m}),` :math:`\Im(\hat{Y}_{-m}),` +:math:`\Re(\hat{Y}_{-m+1}),` :math:`\Im(\hat{Y}_{-m+1}), \dotsc,` +:math:`\Re(\hat{Y}_m),` :math:`\Im(\hat{Y}_m).` In summary, the per-atom array will contain *nlvalues* columns, followed by an additional *nlvalues* columns if *wl* is set to yes, followed by @@ -193,7 +208,7 @@ Default """"""" The option defaults are *cutoff* = pair style cutoff, *nnn* = 12, -*degrees* = 5 4 6 8 10 12 i.e. :math:`Q_4`, :math:`Q_6`, :math:`Q_8`, :math:`Q_{10}`, and :math:`Q_{12}`, +*degrees* = 5 4 6 8 10 12 (i.e., :math:`Q_4`, :math:`Q_6`, :math:`Q_8`, :math:`Q_{10}`, and :math:`Q_{12}`), *wl* = no, *wl/hat* = no, *components* off, and *chunksize* = 16384 ---------- diff --git a/doc/src/compute_pair.rst b/doc/src/compute_pair.rst index b43c4bd6d7..2ec7fc0421 100644 --- a/doc/src/compute_pair.rst +++ b/doc/src/compute_pair.rst @@ -6,7 +6,7 @@ compute pair command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID pair pstyle [nstyle] [evalue] @@ -74,7 +74,7 @@ Output info This compute calculates a global scalar which is *epair* or *evdwl* or *ecoul*\ . If the pair style supports it, it also calculates a global -vector of length >= 1, as determined by the pair style. These values +vector of length :math:`\ge` 1, as determined by the pair style. These values can be used by any command that uses global scalar or vector values from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output options. diff --git a/doc/src/compute_pair_local.rst b/doc/src/compute_pair_local.rst index 38953d203c..56dc009d55 100644 --- a/doc/src/compute_pair_local.rst +++ b/doc/src/compute_pair_local.rst @@ -6,7 +6,7 @@ compute pair/local command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID pair/local value1 value2 ... keyword args ... @@ -57,7 +57,7 @@ force cutoff distance for that interaction, as defined by the commands. The value *dist* is the distance between the pair of atoms. -The values *dx*, *dy*, and *dz* are the xyz components of the +The values *dx*, *dy*, and *dz* are the :math:`(x,y,z)` components of the *distance* between the pair of atoms. This value is always the distance from the atom of lower to the one with the higher id. @@ -65,21 +65,21 @@ The value *eng* is the interaction energy for the pair of atoms. The value *force* is the force acting between the pair of atoms, which is positive for a repulsive force and negative for an attractive -force. The values *fx*, *fy*, and *fz* are the xyz components of +force. The values *fx*, *fy*, and *fz* are the :math:`(x,y,z)` components of *force* on atom I. A pair style may define additional pairwise quantities which can be -accessed as *p1* to *pN*, where N is defined by the pair style. Most -pair styles do not define any additional quantities, so N = 0. An +accessed as *p1* to *pN*, where :math:`N` is defined by the pair style. Most +pair styles do not define any additional quantities, so :math:`N = 0`. An example of ones that do are the :doc:`granular pair styles ` which calculate the tangential force between two particles and return -its components and magnitude acting on atom I for N = 1,2,3,4. See -individual pair styles for details. +its components and magnitude acting on atom :math:`I` for +:math:`N \in \{1,2,3,4\}`. See individual pair styles for details. When using *pN* with pair style *hybrid*, the output will be the Nth quantity from the sub-style that computes the pairwise interaction (based on atom types). If that sub-style does not define a *pN*, -the output will be 0.0. The maximum allowed N is the maximum number +the output will be 0.0. The maximum allowed :math:`N` is the maximum number of quantities provided by any sub-style. When using *pN* with pair style *hybrid/overlay* the quantities @@ -104,7 +104,9 @@ the pairwise cutoff defined by the :doc:`pair_style ` command for the types of the two atoms is used. For the *radius* setting, the sum of the radii of the two particles is used as a cutoff. For example, this is appropriate for granular particles which -only interact when they are overlapping, as computed by :doc:`granular pair styles `. Note that if a granular model defines atom +only interact when they are overlapping, as computed by +:doc:`granular pair styles `. +Note that if a granular model defines atom types such that all particles of a specific type are monodisperse (same diameter), then the two settings are effectively identical. @@ -113,7 +115,8 @@ no consistent ordering of the entries within the local vector or array from one timestep to the next. The only consistency that is guaranteed is that the ordering on a particular timestep will be the same for local vectors or arrays generated by other compute commands. -For example, pair output from the :doc:`compute property/local ` command can be combined +For example, pair output from the +:doc:`compute property/local ` command can be combined with data from this command and output by the :doc:`dump local ` command in a consistent way. @@ -127,13 +130,13 @@ Here is an example of how to do this: .. note:: - For pairs, if two atoms I,J are involved in 1-2, 1-3, 1-4 + For pairs, if two atoms I,J are involved in 1--2, 1--3, and 1--4 interactions within the molecular topology, their pairwise interaction may be turned off, and thus they may not appear in the neighbor list, and will not be part of the local data created by this command. More specifically, this will be true of I,J pairs with a weighting factor of 0.0; pairs with a non-zero weighting factor are included. The - weighting factors for 1-2, 1-3, and 1-4 pairwise interactions are set + weighting factors for 1--2, 1--3, and 1--4 pairwise interactions are set by the :doc:`special_bonds ` command. An exception is if long-range Coulombics are being computed via the :doc:`kspace_style ` command, then atom pairs with diff --git a/doc/src/compute_pe.rst b/doc/src/compute_pe.rst index 4597ea7533..825fe4cba4 100644 --- a/doc/src/compute_pe.rst +++ b/doc/src/compute_pe.rst @@ -6,7 +6,7 @@ compute pe command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID pe keyword ... @@ -27,19 +27,19 @@ Description """"""""""" Define a computation that calculates the potential energy of the -entire system of atoms. The specified group must be "all". See the +entire system of atoms. The specified group must be "all." See the :doc:`compute pe/atom ` command if you want per-atom energies. These per-atom values could be summed for a group of atoms via the :doc:`compute reduce ` command. -The energy is calculated by the various pair, bond, etc potentials +The energy is calculated by the various pair, bond, etc. potentials defined for the simulation. If no extra keywords are listed, then the potential energy is the sum of pair, bond, angle, dihedral, improper, -kspace (long-range), and fix energy. I.e. it is as if all the -keywords were listed. If any extra keywords are listed, then only +:math:`k`-space (long-range), and fix energy (i.e., it is as though all the +keywords were listed). If any extra keywords are listed, then only those components are summed to compute the potential energy. -The Kspace contribution requires 1 extra FFT each timestep the energy +The :math:`k`-space contribution requires 1 extra FFT each timestep the energy is calculated, if using the PPPM solver via the :doc:`kspace_style pppm ` command. Thus it can increase the cost of the PPPM calculation if it is needed on a large fraction of the simulation timesteps. @@ -73,7 +73,7 @@ value can be used by any command that uses a global scalar value from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output options. -The scalar value calculated by this compute is "extensive". The +The scalar value calculated by this compute is "extensive." The scalar value will be in energy :doc:`units `. Restrictions diff --git a/doc/src/compute_pe_atom.rst b/doc/src/compute_pe_atom.rst index ab6db9c786..99f63ca877 100644 --- a/doc/src/compute_pe_atom.rst +++ b/doc/src/compute_pe_atom.rst @@ -6,7 +6,7 @@ compute pe/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID pe/atom keyword ... @@ -34,20 +34,20 @@ you want the potential energy of the entire system. The per-atom energy is calculated by the various pair, bond, etc potentials defined for the simulation. If no extra keywords are listed, then the potential energy is the sum of pair, bond, angle, -dihedral,improper, kspace (long-range), and fix energy. I.e. it is as -if all the keywords were listed. If any extra keywords are listed, +dihedral, improper, :math:`k`-space (long-range), and fix energy (i.e., it is as +though all the keywords were listed). If any extra keywords are listed, then only those components are summed to compute the potential energy. Note that the energy of each atom is due to its interaction with all other atoms in the simulation, not just with other atoms in the group. -For an energy contribution produced by a small set of atoms (e.g. 4 +For an energy contribution produced by a small set of atoms (e.g., 4 atoms in a dihedral or 3 atoms in a Tersoff 3-body interaction), that -energy is assigned in equal portions to each atom in the set. -E.g. 1/4 of the dihedral energy to each of the 4 atoms. +energy is assigned in equal portions to each atom in the set (e.g., 1/4 of the +dihedral energy to each of the four atoms). The :doc:`dihedral_style charmm ` style calculates -pairwise interactions between 1-4 atoms. The energy contribution of +pairwise interactions between 1--4 atoms. The energy contribution of these terms is included in the pair energy, not the dihedral energy. The KSpace contribution is calculated using the method in @@ -81,8 +81,9 @@ in the last 2 columns of thermo output: .. note:: The per-atom energy does not include any Lennard-Jones tail - corrections to the energy added by the :doc:`pair_modify tail yes ` command, since those are contributions to the - global system energy. + corrections to the energy added by the + :doc:`pair_modify tail yes ` command, since those are + contributions to the global system energy. Output info """"""""""" diff --git a/doc/src/compute_plasticity_atom.rst b/doc/src/compute_plasticity_atom.rst index 6861dd7cfc..ad0c22dbf5 100644 --- a/doc/src/compute_plasticity_atom.rst +++ b/doc/src/compute_plasticity_atom.rst @@ -6,7 +6,7 @@ compute plasticity/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID plasticity/atom @@ -24,16 +24,19 @@ Description """"""""""" Define a computation that calculates the per-atom plasticity for each -atom in a group. This is a quantity relevant for :doc:`Peridynamics models `. See `this document `_ +atom in a group. This is a quantity relevant for +:doc:`Peridynamics models `. +See `this document `_ for an overview of LAMMPS commands for Peridynamics modeling. The plasticity for a Peridynamic particle is the so-called consistency -parameter (lambda). For elastic deformation lambda = 0, otherwise -lambda > 0 for plastic deformation. For details, see +parameter (:math:`\lambda`). For elastic deformation, :math:`\lambda = 0`, +otherwise :math:`\lambda > 0` for plastic deformation. For details, see :ref:`(Mitchell) ` and the PDF doc included in the LAMMPS distribution in `doc/PDF/PDLammps_EPS.pdf `_. -This command can be invoked for one of the Peridynamic :doc:`pair styles `: peri/eps. +This command can be invoked for one of the Peridynamic +:doc:`pair styles `: peri/eps. The plasticity value will be 0.0 for atoms not in the specified compute group. @@ -46,7 +49,7 @@ any command that uses per-atom values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. -The per-atom vector values are unitless numbers (lambda) >= 0.0. +The per-atom vector values are unitless numbers :math:`\lambda \ge 0.0`. Restrictions """""""""""" @@ -70,5 +73,5 @@ none .. _Mitchell: **(Mitchell)** Mitchell, "A non-local, ordinary-state-based -viscoelasticity model for peridynamics", Sandia National Lab Report, +viscoelasticity model for peridynamics," Sandia National Lab Report, 8064:1-28 (2011). diff --git a/doc/src/compute_pressure.rst b/doc/src/compute_pressure.rst index ab57786c05..9b086abbee 100644 --- a/doc/src/compute_pressure.rst +++ b/doc/src/compute_pressure.rst @@ -6,7 +6,7 @@ compute pressure command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID pressure temp-ID keyword ... @@ -29,7 +29,8 @@ Description """"""""""" Define a computation that calculates the pressure of the entire system -of atoms. The specified group must be "all". See the :doc:`compute stress/atom ` command if you want per-atom +of atoms. The specified group must be "all." See the +:doc:`compute stress/atom ` command if you want per-atom pressure (stress). These per-atom values could be summed for a group of atoms via the :doc:`compute reduce ` command. @@ -37,35 +38,36 @@ The pressure is computed by the formula .. math:: - P = \frac{N k_B T}{V} + \frac{\sum_{i}^{N'} r_i \bullet f_i}{dV} + P = \frac{N k_B T}{V} + \frac{1}{V d}\sum_{i=1}^{N'} \vec r_i \cdot \vec f_i where *N* is the number of atoms in the system (see discussion of DOF -below), :math:`k_B` is the Boltzmann constant, *T* is the temperature, d -is the dimensionality of the system (2 or 3 for 2d/3d), and *V* is the +below), :math:`k_B` is the Boltzmann constant, *T* is the temperature, *d* +is the dimensionality of the system (2 for 2d, 3 for 3d), and *V* is the system volume (or area in 2d). The second term is the virial, equal to --dU/dV, computed for all pairwise as well as 2-body, 3-body, 4-body, -many-body, and long-range interactions, where :math:`r_i` and -:math:`f_i` are the position and force vector of atom *i*, and the black -dot indicates a dot product. This is computed in parallel for each -sub-domain and then summed over all parallel processes. Thus N' -necessarily includes atoms from neighboring sub-domains (so-called ghost -atoms) and the position and force vectors of ghost atoms are thus +:math:`-dU/dV`, computed for all pairwise as well as 2-body, 3-body, 4-body, +many-body, and long-range interactions, where :math:`\vec r_i` and +:math:`\vec f_i` are the position and force vector of atom *i*, and the +dot indicates the dot product (scalar product). This is computed in parallel +for each sub-domain and then summed over all parallel processes. Thus +:math:`N'` necessarily includes atoms from neighboring sub-domains (so-called +ghost atoms) and the position and force vectors of ghost atoms are thus included in the summation. Only when running in serial and without -periodic boundary conditions is N' = N = the number of atoms in the -system. :doc:`Fixes ` that impose constraints (e.g. the :doc:`fix +periodic boundary conditions is :math:`N' = N` the number of atoms in the +system. :doc:`Fixes ` that impose constraints (e.g., the :doc:`fix shake ` command) may also contribute to the virial term. A symmetric pressure tensor, stored as a 6-element vector, is also -calculated by this compute. The 6 components of the vector are -ordered xx, yy, zz, xy, xz, yz. The equation for the I,J components -(where I and J = x,y,z) is similar to the above formula, except that -the first term uses components of the kinetic energy tensor and the +calculated by this compute. The six components of the vector are +ordered :math:`xx,` :math:`yy,` :math:`zz,` :math:`xy,` :math:`xz,` :math:`yz.` +The equation for the :math:`(I,J)` components (where :math:`I` and :math:`J` +are :math:`x`, :math:`y`, or :math:`z`) is similar to the above formula, +except that the first term uses components of the kinetic energy tensor and the second term uses components of the virial tensor: .. math:: - P_{IJ} = \frac{\sum_{k}^{N} m_k v_{k_I} v_{k_J}}{V} + - \frac{\sum_{k}^{N'} r_{k_I} f_{k_J}}{V} + P_{IJ} = \frac{1}{V}\sum_{k=1}^{N} m_k v_{k_I} v_{k_J} + + \frac{1}{V}\sum_{k=1}^{N'} r_{k_I} f_{k_J}. If no extra keywords are listed, the entire equations above are calculated. This includes a kinetic energy (temperature) term and the @@ -89,27 +91,30 @@ command. If the kinetic energy is not included in the pressure, than the temperature compute is not used and can be specified as NULL. Normally the temperature compute used by compute pressure should calculate the temperature of all atoms for consistency with the virial -term, but any compute style that calculates temperature can be used, -e.g. one that excludes frozen atoms or other degrees of freedom. +term, but any compute style that calculates temperature can be used +(e.g., one that excludes frozen atoms or other degrees of freedom). Note that if desired the specified temperature compute can be one that subtracts off a bias to calculate a temperature using only the thermal -velocity of the atoms, e.g. by subtracting a background streaming -velocity. See the doc pages for individual :doc:`compute commands ` to determine which ones include a bias. +velocity of the atoms (e.g., by subtracting a background streaming +velocity). +See the doc pages for individual :doc:`compute commands ` to determine +which ones include a bias. -Also note that the N in the first formula above is really -degrees-of-freedom divided by d = dimensionality, where the DOF value -is calculated by the temperature compute. See the various :doc:`compute temperature ` styles for details. +Also note that the :math:`N` in the first formula above is really +degrees-of-freedom divided by :math:`d` = dimensionality, where the DOF value +is calculated by the temperature compute. +See the various :doc:`compute temperature ` styles for details. -A compute of this style with the ID of "thermo_press" is created when +A compute of this style with the ID of thermo_press is created when LAMMPS starts up, as if this command were in the input script: .. code-block:: LAMMPS compute thermo_press all pressure thermo_temp -where "thermo_temp" is the ID of a similarly defined compute of style -"temp". See the "thermo_style" command for more details. +where thermo_temp is the ID of a similarly defined compute of style +"temp." See the :doc:`thermo_style ` command for more details. ---------- @@ -122,15 +127,16 @@ Output info This compute calculates a global scalar (the pressure) and a global vector of length 6 (pressure tensor), which can be accessed by indices -1-6. These values can be used by any command that uses global scalar +1--6. These values can be used by any command that uses global scalar or vector values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. The ordering of values in the symmetric pressure tensor is as follows: -pxx, pyy, pzz, pxy, pxz, pyz. +:math:`p_{xx},` :math:`p_{yy},` :math:`p_{zz},` :math:`p_{xy},` +:math:`p_{xz},` :math:`p_{yz}.` The scalar and vector values calculated by this compute are -"intensive". The scalar and vector values will be in pressure +"intensive." The scalar and vector values will be in pressure :doc:`units `. Restrictions diff --git a/doc/src/compute_pressure_uef.rst b/doc/src/compute_pressure_uef.rst index 2e53961d00..2168272b57 100644 --- a/doc/src/compute_pressure_uef.rst +++ b/doc/src/compute_pressure_uef.rst @@ -6,7 +6,7 @@ compute pressure/uef command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID pressure/uef temp-ID keyword ... @@ -42,14 +42,14 @@ Restrictions """""""""""" This fix is part of the UEF package. It is only enabled if LAMMPS -was built with that package. See the :doc:`Build package ` page for more info. +was built with that package. See the :doc:`Build package ` page +for more info. This command can only be used when :doc:`fix nvt/uef ` or :doc:`fix npt/uef ` is active. The kinetic contribution to the pressure tensor -will be accurate only when -the compute specified by *temp-ID* is a +will be accurate only when the compute specified by *temp-ID* is a :doc:`compute temp/uef `. Related commands diff --git a/doc/src/compute_property_atom.rst b/doc/src/compute_property_atom.rst index fee859d96e..34ff62944a 100644 --- a/doc/src/compute_property_atom.rst +++ b/doc/src/compute_property_atom.rst @@ -6,7 +6,7 @@ compute property/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID property/atom input1 input2 ... @@ -127,7 +127,7 @@ LAMMPS. The values are stored in a per-atom vector or array as discussed below. Zeroes are stored for atoms not in the specified group or for quantities that are not defined for a particular particle in the group -(e.g. *shapex* if the particle is not an ellipsoid). +(e.g., *shapex* if the particle is not an ellipsoid). Attributes *i_name*, *d_name*, *i2_name*, *d2_name* refer to custom per-atom integer and floating-point vectors or arrays that have been @@ -135,7 +135,7 @@ 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 attributes. 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[2], i2_mySpin[3]. +the name in brackets (e.g., d2_xyz[2] or i2_mySpin[3]). The additional quantities only accessible via this command, and not directly via the :doc:`dump custom ` command, are as follows. @@ -144,21 +144,21 @@ directly via the :doc:`dump custom ` command, are as follows. number of explicit bonds assigned to an atom. Note that if the :doc:`newton bond ` command is set to *on*\ , which is the default, then every bond in the system is assigned to only one of the -two atoms in the bond. Thus a bond between atoms I,J may be tallied -for either atom I or atom J. If :doc:`newton bond off ` is -set, it will be tallied with both atom I and atom J. +two atoms in the bond. Thus a bond between atoms :math:`I` and :math:`J` may +be tallied for either atom :math:`I` or atom :math:`J`. +If :doc:`newton bond off ` is set, it will be tallied with both atom +:math:`I` and atom :math:`J`. -*Shapex*, *shapey*, and *shapez* are defined for ellipsoidal particles -and define the 3d shape of each particle. +The quantities *shapex*, *shapey*, and *shapez* are defined for ellipsoidal +particles and define the 3d shape of each particle. -*Quatw*, *quati*, *quatj*, and *quatk* are defined for ellipsoidal -particles and body particles and store the 4-vector quaternion +The quantities *quatw*, *quati*, *quatj*, and *quatk* are defined for +ellipsoidal particles and body particles and store the 4-vector quaternion representing the orientation of each particle. See the :doc:`set ` command for an explanation of the quaternion vector. -*End1x*, *end1y*, *end1z*, *end2x*, *end2y*, *end2z*, are -defined for line segment particles and define the end points of each -line segment. +*End1x*, *end1y*, *end1z*, *end2x*, *end2y*, *end2z*, are defined for line +segment particles and define the end points of each line segment. *Corner1x*, *corner1y*, *corner1z*, *corner2x*, *corner2y*, *corner2z*, *corner3x*, *corner3y*, *corner3z*, are defined for @@ -179,12 +179,12 @@ per-atom values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. The vector or array values will be in whatever :doc:`units ` the -corresponding attribute is in, e.g. velocity units for vx, charge -units for q, etc. +corresponding attribute is in (e.g., velocity units for *vx*, charge +units for *q*). -For the spin quantities, sp is in the units of the Bohr magneton, spx, -spy, and spz are unitless quantities, and fmx, fmy and fmz are given -in rad/THz. +For the spin quantities, *sp* is in the units of the Bohr magneton; +*spx*, *spy*, and *spz* are unitless quantities; and *fmx*, *fmy*, and *fmz* +are given in rad/THz. Restrictions """""""""""" diff --git a/doc/src/compute_property_chunk.rst b/doc/src/compute_property_chunk.rst index 48b3641e84..60d20042bb 100644 --- a/doc/src/compute_property_chunk.rst +++ b/doc/src/compute_property_chunk.rst @@ -6,7 +6,7 @@ compute property/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID property/chunk chunkID input1 input2 ... @@ -35,19 +35,24 @@ Description Define a computation that stores the specified attributes of chunks of atoms. -In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom ` command, which assigns each atom +In LAMMPS, chunks are collections of atoms defined by a +:doc:`compute chunk/atom ` command, which assigns each atom to a single chunk (or no chunk). The ID for this command is specified -as chunkID. For example, a single chunk could be the atoms in a -molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom ` and :doc:`Howto chunk ` -doc pages for details of how chunks can be defined and examples of how -they can be used to measure properties of a system. +as chunkID. For example, a single chunk could be the atoms in a molecule or +atoms in a spatial bin. See the :doc:`compute chunk/atom ` +and :doc:`Howto chunk ` doc pages for details of how chunks can be +defined and examples of how they can be used to measure properties of a system. This compute calculates and stores the specified attributes of chunks -as global data so they can be accessed by other :doc:`output commands ` and used in conjunction with other -commands that generate per-chunk data, such as :doc:`compute com/chunk ` or :doc:`compute msd/chunk `. +as global data so they can be accessed by other +:doc:`output commands ` and used in conjunction with other +commands that generate per-chunk data, such as +:doc:`compute com/chunk ` or +:doc:`compute msd/chunk `. Note that only atoms in the specified group contribute to the -calculation of the *count* attribute. The :doc:`compute chunk/atom ` command defines its own group; +calculation of the *count* attribute. The +:doc:`compute chunk/atom ` command defines its own group; atoms will have a chunk ID = 0 if they are not in that group, signifying they are not assigned to a chunk, and will thus also not contribute to this calculation. You can specify the "all" group for @@ -59,7 +64,7 @@ The *count* attribute is the number of atoms in the chunk. The *id* attribute stores the original chunk ID for each chunk. It can only be used if the *compress* keyword was set to *yes* for the :doc:`compute chunk/atom ` command referenced by -chunkID. This means that the original chunk IDs (e.g. molecule IDs) +chunkID. This means that the original chunk IDs (e.g., molecule IDs) will have been compressed to remove chunk IDs with no atoms assigned to them. Thus a compressed chunk ID of 3 may correspond to an original chunk ID (molecule ID in this case) of 415. The *id* attribute will @@ -75,7 +80,7 @@ is the center point of the bin in the corresponding dimension. Style Note that if the value of the *units* keyword used in the :doc:`compute chunk/atom command ` is *box* or *lattice*, the *coordN* attributes will be in distance :doc:`units `. If the value of the *units* keyword is *reduced*, the *coordN* attributes -will be in unitless reduced units (0-1). +will be in unitless reduced units (0--1). The simplest way to output the results of the compute property/chunk calculation to a file is to use the :doc:`fix ave/time ` @@ -105,7 +110,7 @@ accessed by any command that uses global values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. -The vector or array values are "intensive". The values will be +The vector or array values are "intensive." The values will be unitless or in the units discussed above. Restrictions diff --git a/doc/src/compute_property_local.rst b/doc/src/compute_property_local.rst index 357f46b70d..2f74f45bf4 100644 --- a/doc/src/compute_property_local.rst +++ b/doc/src/compute_property_local.rst @@ -6,37 +6,65 @@ compute property/local command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID property/local attribute1 attribute2 ... keyword args ... * ID, group-ID are documented in :doc:`compute ` command * property/local = style name of this compute command -* one or more attributes may be appended +* one or more attributes of the same type (neighbor, pair, bond, angle, + dihedral, or improper) may be appended .. parsed-literal:: - possible attributes = natom1 natom2 ntype1 ntype2 - patom1 patom2 ptype1 ptype2 - batom1 batom2 btype - aatom1 aatom2 aatom3 atype - datom1 datom2 datom3 datom4 dtype - iatom1 iatom2 iatom3 iatom4 itype + possible attributes = natom1, natom2, ntype1, ntype2, + patom1, patom2, ptype1, ptype2, + batom1, batom2, btype, + aatom1, aatom2, aatom3, atype, + datom1, datom2, datom3, datom4, dtype, + iatom1, iatom2, iatom3, iatom4, itype + + * Neighbor attributes .. parsed-literal:: - natom1, natom2 = IDs of 2 atoms in each pair (within neighbor cutoff) - ntype1, ntype2 = type of 2 atoms in each pair (within neighbor cutoff) - patom1, patom2 = IDs of 2 atoms in each pair (within force cutoff) - ptype1, ptype2 = type of 2 atoms in each pair (within force cutoff) - batom1, batom2 = IDs of 2 atoms in each bond - btype = bond type of each bond - aatom1, aatom2, aatom3 = IDs of 3 atoms in each angle - atype = angle type of each angle - datom1, datom2, datom3, datom4 = IDs of 4 atoms in each dihedral - dtype = dihedral type of each dihedral - iatom1, iatom2, iatom3, iatom4 = IDs of 4 atoms in each improper - itype = improper type of each improper + natom1, natom2 = store IDs of 2 atoms in each pair (within neighbor cutoff) + ntype1, ntype2 = store types of 2 atoms in each pair (within neighbor cutoff) + + * Pair attributes + + .. parsed-literal:: + + patom1, patom2 = store IDs of 2 atoms in each pair (within force cutoff) + ptype1, ptype2 = store types of 2 atoms in each pair (within force cutoff) + + * Bond attributes + + .. parsed-literal:: + + batom1, batom2 = store IDs of 2 atoms in each bond + btype = store bond type of each bond + + * Angle attributes + + .. parsed-literal:: + + aatom1, aatom2, aatom3 = store IDs of 3 atoms in each angle + atype = store angle type of each angle + + * Dihedral attributes + + .. parsed-literal:: + + datom1, datom2, datom3, datom4 = store IDs of 4 atoms in each dihedral + dtype = store dihedral type of each dihedral + + * Improper attributes + + .. parsed-literal:: + + iatom1, iatom2, iatom3, iatom4 = store IDs of 4 atoms in each improper + itype = store improper type of each improper * zero or more keyword/arg pairs may be appended * keyword = *cutoff* @@ -66,7 +94,7 @@ If multiple attributes are specified then they must all generate the same amount of information, so that the resulting local array has the same number of rows for each column. This means that only bond attributes can be specified together, or angle attributes, etc. Bond -and angle attributes can not be mixed in the same compute +and angle attributes cannot be mixed in the same compute property/local command. If the inputs are pair attributes, the local data is generated by @@ -113,21 +141,21 @@ same for local vectors or arrays generated by other compute commands. For example, output from the :doc:`compute bond/local ` command can be combined with bond atom indices from this command and output by the :doc:`dump local ` command in a consistent way. -The *natom1* and *natom2*, or *patom1* and *patom2* attributes refer +The *natom1* and *natom2* or *patom1* and *patom2* attributes refer to the atom IDs of the 2 atoms in each pairwise interaction computed by the :doc:`pair_style ` command. The *ntype1* and -*ntype2*, or *ptype1* and *ptype2* attributes refer to the atom types +*ntype2* or *ptype1* and *ptype2* attributes refer to the atom types of the 2 atoms in each pairwise interaction. .. note:: - For pairs, if two atoms I,J are involved in 1-2, 1-3, 1-4 + For pairs, if two atoms :math:`I,J` are involved in 1--2, 1--3, 1--4 interactions within the molecular topology, their pairwise interaction may be turned off, and thus they may not appear in the neighbor list, and will not be part of the local data created by this command. More - specifically, this may be true of I,J pairs with a weighting factor of - 0.0; pairs with a non-zero weighting factor are included. The - weighting factors for 1-2, 1-3, and 1-4 pairwise interactions are set + specifically, this may be true of :math:`I,J` pairs with a weighting factor + of 0.0; pairs with a non-zero weighting factor are included. The + weighting factors for 1--2, 1--3, and 1--4 pairwise interactions are set by the :doc:`special_bonds ` command. The *batom1* and *batom2* attributes refer to the atom IDs of the 2 @@ -136,7 +164,7 @@ the type of the bond, from 1 to Nbtypes = # of bond types. The number of bond types is defined in the data file read by the :doc:`read_data ` command. -The attributes that start with "a", "d", "i", refer to similar values +The attributes that start with "a," "d," and "i" refer to similar values for :doc:`angles `, :doc:`dihedrals `, and :doc:`impropers `. @@ -149,7 +177,8 @@ the array is the number of bonds, angles, etc. If a single input is specified, a local vector is produced. If two or more inputs are specified, a local array is produced where the number of columns = the number of inputs. The vector or array can be accessed by any command -that uses local values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output +that uses local values from a compute as input. See the +:doc:`Howto output ` page for an overview of LAMMPS output options. The vector or array values will be integers that correspond to the diff --git a/doc/src/compute_ptm_atom.rst b/doc/src/compute_ptm_atom.rst index 3e209d1dc5..3d024802ab 100644 --- a/doc/src/compute_ptm_atom.rst +++ b/doc/src/compute_ptm_atom.rst @@ -6,13 +6,13 @@ compute ptm/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID ptm/atom structures threshold group2-ID * ID, group-ID are documented in :doc:`compute ` command * ptm/atom = style name of this compute command -* structures = structure types to search for +* structures = *default* or *all* or any hyphen-separated combination of *fcc*, *hcp*, *bcc*, *ico*, *sc*, *dcub*, *dhex*, or *graphene* = structure types to search for * threshold = lattice distortion threshold (RMSD) * group2-ID determines which group is used for neighbor selection (optional, default "all") @@ -43,9 +43,10 @@ Currently, there are seven lattice structures PTM recognizes: * dhex (diamond hexagonal) = 7 * graphene = 8 -The value of the PTM structure will be 0 for unknown types and -1 for atoms not in the specified -compute group. The choice of structures to search for can be specified using the "structures" -argument, which is a hyphen-separated list of structure keywords. +The value of the PTM structure will be 0 for unknown types and :math:`-1` for +atoms not in the specified compute group. The choice of structures to search +for can be specified using the "structures" argument, which is a +hyphen-separated list of structure keywords. Two convenient pre-set options are provided: * default: fcc-hcp-bcc-ico @@ -63,21 +64,25 @@ The deviation is calculated as: .. math:: - \text{RMSD}(\mathbf{u}, \mathbf{v}) = \min_{s, \mathbf{Q}} \sqrt{\frac{1}{N} \sum\limits_{i=1}^{N} - {\left|\left| s[\vec{u_i} - \overline{\mathbf{u}}] - \mathbf{Q} \vec{v_i} \right|\right|}^2} + \text{RMSD}(\mathbf{u}, \mathbf{v}) + = \min_{s, \mathbf{Q}} \sqrt{\frac{1}{N} \sum\limits_{i=1}^{N} + {\left\lVert s[\vec{u_i} - \mathbf{\bar{u}}] + - \mathbf{Q} \cdot \vec{v_i} \right\rVert}^2} -Here, u and v contain the coordinates of the local and ideal structures respectively, -s is a scale factor, and Q is a rotation. The best match is identified by the -lowest RMSD value, using the optimal scaling, rotation, and correspondence between the +Here, :math:`\vec u` and :math:`\vec v` contain the coordinates of the local +and ideal structures respectively, :math:`s` is a scale factor, and +:math:`\mathbf Q` is a rotation. The best match is identified by the lowest +RMSD value, using the optimal scaling, rotation, and correspondence between the points. -The 'threshold' keyword sets an upper limit on the maximum permitted deviation before -a local structure is identified as disordered. Typical values are in the range 0.1-0.15, -but larger values may be desirable at higher temperatures. -A value of 0 is equivalent to infinity and can be used if no threshold is desired. +The *threshold* keyword sets an upper limit on the maximum permitted deviation +before a local structure is identified as disordered. Typical values are in +the range 0.1--0.15, but larger values may be desirable at higher temperatures. +A value of 0 is equivalent to infinity and can be used if no threshold is +desired. The neighbor list needed to compute this quantity is constructed each -time the calculation is performed (e.g. each time a snapshot of atoms +time the calculation is performed (e.g., each time a snapshot of atoms is dumped). Thus it can be inefficient to compute/dump this quantity too frequently or to have multiple compute/dump commands, each with a *ptm/atom* style. By default the compute processes **all** neighbors @@ -102,11 +107,12 @@ Results are stored in the per-atom array in the following order: * qy * qz -The type is a number from -1 to 8. The rmsd is a positive real number. +The type is a number from :math:`-1` to 8. The rmsd is a positive real number. The interatomic distance is computed from the scale factor in the RMSD equation. -The (qw,qx,qy,qz) parameters represent the orientation of the local structure -in quaternion form. The reference coordinates for each template (from which the -orientation is determined) can be found in the *ptm_constants.h* file in the PTM source directory. +The :math:`(qw,qx,qy,qz)` parameters represent the orientation of the local +structure in quaternion form. The reference coordinates for each template +(from which the orientation is determined) can be found in the +*ptm_constants.h* file in the PTM source directory. For atoms that are not within the compute group-ID, all values are set to zero. Restrictions diff --git a/doc/src/compute_rdf.rst b/doc/src/compute_rdf.rst index 85366eab2a..8c561ca615 100644 --- a/doc/src/compute_rdf.rst +++ b/doc/src/compute_rdf.rst @@ -6,7 +6,7 @@ compute rdf command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID rdf Nbin itype1 jtype1 itype2 jtype2 ... keyword/value ... @@ -38,7 +38,7 @@ Description """"""""""" Define a computation that calculates the radial distribution function -(RDF), also called g(r), and the coordination number for a group of +(RDF), also called :math:`g(r)`, and the coordination number for a group of particles. Both are calculated in histogram form by binning pairwise distances into *Nbin* bins from 0.0 to the maximum force cutoff defined by the :doc:`pair_style ` command or the cutoff @@ -58,27 +58,27 @@ shell of distances in 3d and a thin ring of distances in 2d. using long-range coulomb interactions (\ *coul/long*, *coul/msm*, *coul/wolf* or similar. One way to get around this would be to set special_bond scaling factors to very tiny numbers that are not exactly - zero (e.g. 1.0e-50). Another workaround is to write a dump file, and - use the :doc:`rerun ` command to compute the RDF for snapshots in - the dump file. The rerun script can use a + zero (e.g., :math:`1.0 \times 10^{-50}`). Another workaround is to write a + dump file, and use the :doc:`rerun ` command to compute the RDF for + snapshots in the dump file. The rerun script can use a :doc:`special_bonds ` command that includes all pairs in the neighbor list. By default the RDF is computed out to the maximum force cutoff defined by the :doc:`pair_style ` command. If the *cutoff* keyword -is used, then the RDF is computed accurately out to the *Rcut* > 0.0 +is used, then the RDF is computed accurately out to the *Rcut* :math:`> 0.0` distance specified. .. note:: Normally, you should only use the *cutoff* keyword if no pair - style is defined, e.g. the :doc:`rerun ` command is being used to - post-process a dump file of snapshots. Or if you really want the RDF + style is defined (e.g., the :doc:`rerun ` command is being used to + post-process a dump file of snapshots) or if you really want the RDF for distances beyond the pair_style force cutoff and cannot easily post-process a dump file to calculate it. This is because using the *cutoff* keyword incurs extra computation and possibly communication, - which may slow down your simulation. If you specify a *Rcut* <= force - cutoff, you will force an additional neighbor list to be built at + which may slow down your simulation. If you specify *Rcut* :math:`\le` + force cutoff, you will force an additional neighbor list to be built at every timestep this command is invoked (or every reneighboring timestep, whichever is less frequent), which is inefficient. LAMMPS will warn you if this is the case. If you specify a *Rcut* > force @@ -92,56 +92,56 @@ distance specified. The *itypeN* and *jtypeN* arguments are optional. These arguments must come in pairs. If no pairs are listed, then a single histogram -is computed for g(r) between all atom types. If one or more pairs are +is computed for :math:`g(r)` between all atom types. If one or more pairs are listed, then a separate histogram is generated for each *itype*,\ *jtype* pair. The *itypeN* and *jtypeN* settings can be specified in one of two ways. An explicit numeric value can be used, as in the fourth example above. Or a wild-card asterisk can be used to specify a range of atom -types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = the -number of atom 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 means all types from m to n -(inclusive). +types. This takes the form "\*" or "\*n" or "m\*" or "m\*n". If +:math:`N` is the number of atom 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 :math:`N` +(inclusive). A middle asterisk means all types from m to n (inclusive). If both *itypeN* and *jtypeN* are single values, as in the fourth example -above, this means that a g(r) is computed where atoms of type *itypeN* +above, this means that a :math:`g(r)` is computed where atoms of type *itypeN* are the central atom, and atoms of type *jtypeN* are the distribution atom. If either *itypeN* and *jtypeN* represent a range of values via the wild-card asterisk, as in the fifth example above, this means that a -g(r) is computed where atoms of any of the range of types represented +:math:`g(r)` is computed where atoms of any of the range of types represented by *itypeN* are the central atom, and atoms of any of the range of types represented by *jtypeN* are the distribution atom. Pairwise distances are generated by looping over a pairwise neighbor list, just as they would be in a :doc:`pair_style ` -computation. The distance between two atoms I and J is included in a -specific histogram if the following criteria are met: +computation. The distance between two atoms :math:`I` and :math:`J` is +included in a specific histogram if the following criteria are met: -* atoms I,J are both in the specified compute group -* the distance between atoms I,J is less than the maximum force cutoff -* the type of the I atom matches itypeN (one or a range of types) -* the type of the J atom matches jtypeN (one or a range of types) +* atoms :math:`I` and :math:`J` are both in the specified compute group +* the distance between atoms :math:`I` and :math:`J` is less than the maximum + force cutoff +* the type of the :math:`I` atom matches *itypeN* (one or a range of types) +* the type of the :math:`J` atom matches *jtypeN* (one or a range of types) It is OK if a particular pairwise distance is included in more than one individual histogram, due to the way the *itypeN* and *jtypeN* arguments are specified. -The g(r) value for a bin is calculated from the histogram count by +The :math:`g(r)` value for a bin is calculated from the histogram count by scaling it by the idealized number of how many counts there would be if atoms of type *jtypeN* were uniformly distributed. Thus it involves the count of *itypeN* atoms, the count of *jtypeN* atoms, the volume of the entire simulation box, and the volume of the bin's thin shell in 3d (or the area of the bin's thin ring in 2d). -A coordination number coord(r) is also calculated, which is the number -of atoms of type *jtypeN* within the current bin or closer, averaged +A coordination number :math:`\mathrm{coord}(r)` is also calculated, which is +the number of atoms of type *jtypeN* within the current bin or closer, averaged over atoms of type *itypeN*\ . This is calculated as the area- or -volume-weighted sum of g(r) values over all bins up to and including +volume-weighted sum of :math:`g(r)` values over all bins up to and including the current bin, multiplied by the global average volume density of -atoms of type jtypeN. +atoms of type *jtypeN*. The simplest way to output the results of the compute rdf calculation to a file is to use the :doc:`fix ave/time ` command, for @@ -155,41 +155,43 @@ example: Output info """"""""""" -This compute calculates a global array with the number of rows = -*Nbins*, and the number of columns = 1 + 2\*Npairs, where Npairs is the -number of I,J pairings specified. The first column has the bin -coordinate (center of the bin), Each successive set of 2 columns has -the g(r) and coord(r) values for a specific set of *itypeN* versus -*jtypeN* interactions, as described above. These values can be used +This compute calculates a global array in which the number of rows is +*Nbins* and the number of columns is :math:`1 + 2N_\text{pairs}`, where +:math:`N_\text{pairs}` is the number of :math:`I,J` pairings specified. +The first column has the bin coordinate (center of the bin), and each +successive set of two columns has the :math:`g(r)` and :math:`\text{coord}(r)` +values for a specific set of *itypeN* versus *jtypeN* interactions, +as described above. These values can be used by any command that uses a global values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. -The array values calculated by this compute are all "intensive". +The array values calculated by this compute are all "intensive." The first column of array values will be in distance -:doc:`units `. The g(r) columns of array values are normalized -numbers >= 0.0. The coordination number columns of array values are -also numbers >= 0.0. +:doc:`units `. The :math:`g(r)` columns of array values are normalized +numbers :math:`\ge 0.0`. The coordination number columns of array values are +also numbers :math:`\ge 0.0`. Restrictions """""""""""" The RDF is not computed for distances longer than the force cutoff, -since processors (in parallel) don't know about atom coordinates for +since processors (in parallel) do not know about atom coordinates for atoms further away than that distance. If you want an RDF for larger distances, you can use the :doc:`rerun ` command to post-process a dump file and set the cutoff for the potential to be longer in the rerun script. Note that in the rerun context, the force cutoff is arbitrary, since you are not running dynamics and thus are not changing -your model. The definition of g(r) used by LAMMPS is only appropriate +your model. The definition of :math:`g(r)` used by LAMMPS is only appropriate for characterizing atoms that are uniformly distributed throughout the simulation cell. In such cases, the coordination number is still correct and meaningful. As an example, if a large simulation cell -contains only one atom of type *itypeN* and one of *jtypeN*, then g(r) +contains only one atom of type *itypeN* and one of *jtypeN*, then :math:`g(r)` will register an arbitrarily large spike at whatever distance they -happen to be at, and zero everywhere else. Coord(r) will show a step -change from zero to one at the location of the spike in g(r). +happen to be at, and zero everywhere else. +The function :math:`\text{coord}(r)` will show a step +change from zero to one at the location of the spike in :math:`g(r)`. .. note:: @@ -198,7 +200,7 @@ change from zero to one at the location of the spike in g(r). parameters need to be re-computed in every step and include collective communication operations. This will reduce performance and limit parallel efficiency and scaling. For systems, where only the type - of atoms changes (e.g. when using :doc:`fix atom/swap `), + of atoms changes (e.g., when using :doc:`fix atom/swap `), you need to explicitly request the dynamic normalization updates via :doc:`compute_modify dynamic yes ` diff --git a/doc/src/set.rst b/doc/src/set.rst index cc1d2766e3..5bc2cfb957 100644 --- a/doc/src/set.rst +++ b/doc/src/set.rst @@ -14,8 +14,8 @@ Syntax * ID = atom ID range or type range or mol ID range or group ID or region ID * one or more keyword/value pairs may be appended * keyword = *type* or *type/fraction* or *type/ratio* or *type/subset* - or *mol* or *x* or *y* or *z* or *charge* or *dipole* or - *dipole/random* or *quat* or *spin* or *spin/random* or + or *mol* or *x* or *y* or *z* or *vx* or *vy* or *vz* or *charge* or + *dipole* or *dipole/random* or *quat* or *spin* or *spin/random* or *quat* or *quat/random* or *diameter* or *shape* or *length* or *tri* or *theta* or *theta/random* or *angmom* or *omega* or *mass* or *density* or *density/disc* or