diff --git a/doc/src/angle_style.rst b/doc/src/angle_style.rst index e745524add..5be7bc1a9a 100644 --- a/doc/src/angle_style.rst +++ b/doc/src/angle_style.rst @@ -10,7 +10,7 @@ Syntax angle_style style -* style = *none* or *hybrid* or *charmm* or *class2* or *cosine* or *cosine/squared* or *harmonic* +* style = *none* or *zero* or *hybrid* or *amoeba* or *charmm* or *class2* or *class2/p6* or *cosine* or *cosine/buck6d* or *cosine/delta* or *cosine/periodic* or *cosine/shift* or *cosine/shift/exp* or *cosine/squared* or *cross* or *dipole* or *fourier* or *fourier/simple* or *gaussian* or *harmonic* or *mm3* or *quartic* or *spica* or *table* Examples """""""" diff --git a/doc/src/angle_zero.rst b/doc/src/angle_zero.rst index a0d5a02e1e..c87f686bcb 100644 --- a/doc/src/angle_zero.rst +++ b/doc/src/angle_zero.rst @@ -8,7 +8,10 @@ Syntax .. code-block:: LAMMPS - angle_style zero *nocoeff* + angle_style zero keyword + +* zero or more keywords may be appended +* keyword = *nocoeff* Examples """""""" diff --git a/doc/src/balance.rst b/doc/src/balance.rst index 1d24e467d8..4873fc35c9 100644 --- a/doc/src/balance.rst +++ b/doc/src/balance.rst @@ -6,7 +6,7 @@ balance command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS balance thresh style args ... keyword args ... diff --git a/doc/src/bond_style.rst b/doc/src/bond_style.rst index 95ba1572c1..1573a6847b 100644 --- a/doc/src/bond_style.rst +++ b/doc/src/bond_style.rst @@ -10,7 +10,7 @@ Syntax bond_style style args -* style = *none* or *hybrid* or *class2* or *fene* or *fene/expand* or *harmonic* or *morse* or *nonlinear* or *quartic* +* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/shift* or *harmonic/shift/cut* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table* * args = none for any style except *hybrid* diff --git a/doc/src/bond_zero.rst b/doc/src/bond_zero.rst index bcbbe8a014..cd18e857ef 100644 --- a/doc/src/bond_zero.rst +++ b/doc/src/bond_zero.rst @@ -8,7 +8,10 @@ Syntax .. code-block:: LAMMPS - bond_style zero [nocoeff] + bond_style zero keyword + +* zero or more keywords may be appended +* keyword = *nocoeff* Examples """""""" diff --git a/doc/src/boundary.rst b/doc/src/boundary.rst index d6458e7c39..3af0e2fa43 100644 --- a/doc/src/boundary.rst +++ b/doc/src/boundary.rst @@ -6,7 +6,7 @@ boundary command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS boundary x y z diff --git a/doc/src/box.rst b/doc/src/box.rst index b9c586b6f7..096a171249 100644 --- a/doc/src/box.rst +++ b/doc/src/box.rst @@ -6,7 +6,7 @@ box command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS box keyword value ... diff --git a/doc/src/clear.rst b/doc/src/clear.rst index e9664a6112..a8d224a5c9 100644 --- a/doc/src/clear.rst +++ b/doc/src/clear.rst @@ -6,18 +6,18 @@ clear command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS clear Examples """""""" -.. parsed-literal:: +.. code-block:: LAMMPS - (commands for 1st simulation) + # (commands for 1st simulation) clear - (commands for 2nd simulation) + # (commands for 2nd simulation) Description """"""""""" diff --git a/doc/src/comm_modify.rst b/doc/src/comm_modify.rst index 914509b14d..d0526b792b 100644 --- a/doc/src/comm_modify.rst +++ b/doc/src/comm_modify.rst @@ -10,8 +10,8 @@ Syntax comm_modify keyword value ... -* zero or more keyword/value pairs may be appended -* keyword = *mode* or *cutoff* or *cutoff/multi* or *multi/reduce* or *group* or *vel* +* one or more keyword/value pairs may be appended +* keyword = *mode* or *cutoff* or *cutoff/multi* or *group* or *reduce/multi* or *vel* .. parsed-literal:: diff --git a/doc/src/compute.rst b/doc/src/compute.rst index 508c440e78..7d1e423e93 100644 --- a/doc/src/compute.rst +++ b/doc/src/compute.rst @@ -6,7 +6,7 @@ compute command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID style args @@ -33,8 +33,8 @@ they are calculated from information about atoms on the current timestep or iteration, though a compute may internally store some information about a previous state of the system. Defining a compute does not perform a computation. Instead computes are invoked by other -LAMMPS commands as needed, e.g. to calculate a temperature needed for -a thermostat fix or to generate thermodynamic or dump file output. +LAMMPS commands as needed (e.g., to calculate a temperature needed for +a thermostat fix or to generate thermodynamic or dump file output). See the :doc:`Howto output ` page for a summary of various LAMMPS output options, many of which involve computes. @@ -45,15 +45,15 @@ underscores. Computes calculate one of three styles of quantities: global, per-atom, or local. A global quantity is one or more system-wide -values, e.g. the temperature of the system. A per-atom quantity is -one or more values per atom, e.g. the kinetic energy of each atom. +values (e.g., the temperature of the system). A per-atom quantity is +one or more values per atom (e.g., the kinetic energy of each atom). Per-atom values are set to 0.0 for atoms not in the specified compute group. Local quantities are calculated by each processor based on the -atoms it owns, but there may be zero or more per atom, e.g. a list of -bond distances. Computes that produce per-atom quantities have the -word "atom" in their style, e.g. *ke/atom*\ . Computes that produce -local quantities have the word "local" in their style, -e.g. *bond/local*\ . Styles with neither "atom" or "local" in their +atoms it owns, but there may be zero or more per atom (e.g., a list of +bond distances). Computes that produce per-atom quantities have the +word "atom" in their style (e.g., *ke/atom*\ ). Computes that produce +local quantities have the word "local" in their style +(e.g., *bond/local*\ ). Styles with neither "atom" or "local" in their style produce global quantities. Note that a single compute can produce either global or per-atom or @@ -64,8 +64,8 @@ compute page will explain. Global, per-atom, and local quantities each come in three kinds: a single scalar value, a vector of values, or a 2d array of values. The doc page for each compute describes the style and kind of values it -produces, e.g. a per-atom vector. Some computes produce more than one -kind of a single style, e.g. a global scalar and a global vector. +produces (e.g., a per-atom vector). Some computes produce more than one +kind of a single style (e.g., a global scalar and a global vector). When a compute quantity is accessed, as in many of the output commands discussed below, it can be referenced via the following bracket @@ -80,14 +80,14 @@ notation, where ID is the ID of the compute: +-------------+--------------------------------------------+ In other words, using one bracket reduces the dimension of the -quantity once (vector -> scalar, array -> vector). Using two brackets -reduces the dimension twice (array -> scalar). Thus a command that -uses scalar compute values as input can also process elements of a +quantity once (vector :math:`\to` scalar, array :math:`\to` vector). Using two +brackets reduces the dimension twice (array :math:`\to` scalar). Thus a +command that uses scalar compute values as input can also process elements of a vector or array. Note that commands and :doc:`variables ` which use compute -quantities typically do not allow for all kinds, e.g. a command may -require a vector of values, not a scalar. This means there is no +quantities typically do not allow for all kinds (e.g., a command may +require a vector of values, not a scalar). This means there is no ambiguity about referring to a compute quantity as c_ID even if it produces, for example, both a scalar and vector. The doc pages for various commands explain the details. @@ -111,14 +111,14 @@ ways: The results of computes that calculate global quantities can be either "intensive" or "extensive" values. Intensive means the value is -independent of the number of atoms in the simulation, -e.g. temperature. Extensive means the value scales with the number of -atoms in the simulation, e.g. total rotational kinetic energy. +independent of the number of atoms in the simulation +(e.g., temperature). Extensive means the value scales with the number of +atoms in the simulation (e.g., total rotational kinetic energy). :doc:`Thermodynamic output ` will normalize extensive values by the number of atoms in the system, depending on the "thermo_modify norm" setting. It will not normalize intensive values. -If a compute value is accessed in another way, e.g. by a -:doc:`variable `, you may want to know whether it is an +If a compute value is accessed in another way (e.g., by a +:doc:`variable `), you may want to know whether it is an intensive or extensive value. See the page for individual computes for further info. @@ -187,8 +187,8 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`cluster/atom ` - cluster ID for each atom * :doc:`cna/atom ` - common neighbor analysis (CNA) for each atom * :doc:`cnp/atom ` - common neighborhood parameter (CNP) for each atom -* :doc:`com ` - center-of-mass of group of atoms -* :doc:`com/chunk ` - center-of-mass for each chunk +* :doc:`com ` - center of mass of group of atoms +* :doc:`com/chunk ` - center of mass for each chunk * :doc:`contact/atom ` - contact count for each spherical particle * :doc:`coord/atom ` - coordination number for each atom * :doc:`damage/atom ` - Peridynamic damage for each atom @@ -198,10 +198,10 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`dipole ` - dipole vector and total dipole * :doc:`dipole/chunk ` - dipole vector and total dipole for each chunk * :doc:`displace/atom ` - displacement of each atom -* :doc:`dpd ` - -* :doc:`dpd/atom ` - +* :doc:`dpd ` - total values of internal conductive energy, internal mechanical energy, chemical energy, and harmonic average of internal temperature +* :doc:`dpd/atom ` - per-particle values of internal conductive energy, internal mechanical energy, chemical energy, and internal temperature * :doc:`edpd/temp/atom ` - per-atom temperature for each eDPD particle in a group -* :doc:`efield/atom ` - +* :doc:`efield/atom ` - electric field at each atom * :doc:`entropy/atom ` - pair entropy fingerprint of each atom * :doc:`erotate/asphere ` - rotational energy of aspherical particles * :doc:`erotate/rigid ` - rotational energy of rigid bodies @@ -213,7 +213,7 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`fep/ta ` - compute free energies for a test area perturbation * :doc:`force/tally ` - force between two groups of atoms via the tally callback mechanism * :doc:`fragment/atom ` - fragment ID for each atom -* :doc:`global/atom ` - +* :doc:`global/atom ` - assign global values to each atom from arrays of global values * :doc:`group/group ` - energy/force between two groups of atoms * :doc:`gyration ` - radius of gyration of group of atoms * :doc:`gyration/chunk ` - radius of gyration for each chunk @@ -232,7 +232,7 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`ke/atom/eff ` - per-atom translational and radial kinetic energy in the electron force field model * :doc:`ke/eff ` - kinetic energy of a group of nuclei and electrons in the electron force field model * :doc:`ke/rigid ` - translational kinetic energy of rigid bodies -* :doc:`mliap ` - gradients of energy and forces w.r.t. model parameters and related quantities for training machine learning interatomic potentials +* :doc:`mliap ` - gradients of energy and forces with respect to model parameters and related quantities for training machine learning interatomic potentials * :doc:`momentum ` - translational momentum * :doc:`msd ` - mean-squared displacement of group of atoms * :doc:`msd/chunk ` - mean-squared displacement for each chunk @@ -254,35 +254,35 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`property/chunk ` - extract various per-chunk attributes * :doc:`property/local ` - convert local attributes to localvectors/arrays * :doc:`ptm/atom ` - determines the local lattice structure based on the Polyhedral Template Matching method -* :doc:`rdf ` - radial distribution function g(r) histogram of group of atoms +* :doc:`rdf ` - radial distribution function :math:`g(r)` histogram of group of atoms * :doc:`reduce ` - combine per-atom quantities into a single global value * :doc:`reduce/chunk ` - reduce per-atom quantities within each chunk * :doc:`reduce/region ` - same as compute reduce, within a region * :doc:`rigid/local ` - extract rigid body attributes * :doc:`saed ` - electron diffraction intensity on a mesh of reciprocal lattice nodes * :doc:`slice ` - extract values from global vector or array -* :doc:`smd/contact/radius ` - +* :doc:`smd/contact/radius ` - contact radius for Smooth Mach Dynamics * :doc:`smd/damage ` - damage status of SPH particles in Smooth Mach Dynamics -* :doc:`smd/hourglass/error ` - +* :doc:`smd/hourglass/error ` - error associated with approximated relative separation in Smooth Mach Dynamics * :doc:`smd/internal/energy ` - per-particle enthalpy in Smooth Mach Dynamics * :doc:`smd/plastic/strain ` - equivalent plastic strain per particle in Smooth Mach Dynamics * :doc:`smd/plastic/strain/rate ` - time rate of the equivalent plastic strain in Smooth Mach Dynamics * :doc:`smd/rho ` - per-particle mass density in Smooth Mach Dynamics * :doc:`smd/tlsph/defgrad ` - deformation gradient in Smooth Mach Dynamics * :doc:`smd/tlsph/dt ` - CFL-stable time increment per particle in Smooth Mach Dynamics -* :doc:`smd/tlsph/num/neighs ` - -* :doc:`smd/tlsph/shape ` - -* :doc:`smd/tlsph/strain ` - -* :doc:`smd/tlsph/strain/rate ` - +* :doc:`smd/tlsph/num/neighs ` - number of particles inside the smoothing kernel radius for Smooth Mach Dynamics +* :doc:`smd/tlsph/shape ` - current shape of the volume of a particle for Smooth Mach Dynamics +* :doc:`smd/tlsph/strain ` - Green--Lagrange strain tensor for Smooth Mach Dynamics +* :doc:`smd/tlsph/strain/rate ` - rate of strain for Smooth Mach Dynamics * :doc:`smd/tlsph/stress ` - per-particle Cauchy stress tensor for SPH particles -* :doc:`smd/triangle/vertices ` - +* :doc:`smd/triangle/vertices ` - coordinates of vertices corresponding to the triangle elements of a mesh for Smooth Mach Dynamics * :doc:`smd/ulsph/effm ` - per-particle effective shear modulus -* :doc:`smd/ulsph/num/neighs ` - -* :doc:`smd/ulsph/strain ` - -* :doc:`smd/ulsph/strain/rate ` - +* :doc:`smd/ulsph/num/neighs ` - number of neighbor particles inside the smoothing kernel radius for Smooth Mach Dynamics +* :doc:`smd/ulsph/strain ` - logarithmic strain tensor for Smooth Mach Dynamics +* :doc:`smd/ulsph/strain/rate ` - logarithmic strain rate for Smooth Mach Dynamics * :doc:`smd/ulsph/stress ` - per-particle Cauchy stress tensor and von Mises equivalent stress in Smooth Mach Dynamics * :doc:`smd/vol ` - per-particle volumes and their sum in Smooth Mach Dynamics -* :doc:`snap ` - gradients of SNAP energy and forces w.r.t. linear coefficients and related quantities for fitting SNAP potentials +* :doc:`snap ` - gradients of SNAP energy and forces with respect to linear coefficients and related quantities for fitting SNAP potentials * :doc:`sna/atom ` - bispectrum components for each atom * :doc:`sna/grid ` - global array of bispectrum components on a regular grid * :doc:`sna/grid/local ` - local array of bispectrum components on a regular grid @@ -308,7 +308,7 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`temp/cs ` - temperature based on the center-of-mass velocity of atom pairs that are bonded to each other * :doc:`temp/deform ` - temperature excluding box deformation velocity * :doc:`temp/deform/eff ` - temperature excluding box deformation velocity in the electron force field model -* :doc:`temp/drude ` - temperature of Core-Drude pairs +* :doc:`temp/drude ` - temperature of Core--Drude pairs * :doc:`temp/eff ` - temperature of a group of nuclei and electrons in the electron force field model * :doc:`temp/partial ` - temperature excluding one or more dimensions of velocity * :doc:`temp/profile ` - temperature excluding a binned velocity profile @@ -324,7 +324,7 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`vcm/chunk ` - velocity of center-of-mass for each chunk * :doc:`viscosity/cos ` - velocity profile under cosine-shaped acceleration * :doc:`voronoi/atom ` - Voronoi volume and neighbors for each atom -* :doc:`xrd ` - x-ray diffraction intensity on a mesh of reciprocal lattice nodes +* :doc:`xrd ` - X-ray diffraction intensity on a mesh of reciprocal lattice nodes Restrictions """""""""""" @@ -333,7 +333,9 @@ Restrictions Related commands """""""""""""""" -:doc:`uncompute `, :doc:`compute_modify `, :doc:`fix ave/atom `, :doc:`fix ave/time `, :doc:`fix ave/histo ` +:doc:`uncompute `, :doc:`compute_modify `, +:doc:`fix ave/atom `, :doc:`fix ave/time `, +:doc:`fix ave/histo ` Default """"""" diff --git a/doc/src/compute_ackland_atom.rst b/doc/src/compute_ackland_atom.rst index 0dc6630980..33644b6d7e 100644 --- a/doc/src/compute_ackland_atom.rst +++ b/doc/src/compute_ackland_atom.rst @@ -6,7 +6,7 @@ compute ackland/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID ackland/atom keyword/value @@ -17,7 +17,7 @@ Syntax .. parsed-literal:: - *legacy* yes/no = use (\ *yes*\ ) or do not use (\ *no*\ ) legacy ackland algorithm implementation + *legacy* args = *yes* or *no* = use (\ *yes*\ ) or do not use (\ *no*\ ) legacy Ackland algorithm implementation Examples """""""" diff --git a/doc/src/compute_adf.rst b/doc/src/compute_adf.rst index 31351a547c..6adc6cabf0 100644 --- a/doc/src/compute_adf.rst +++ b/doc/src/compute_adf.rst @@ -6,7 +6,7 @@ compute adf command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID adf Nbin itype1 jtype1 ktype1 Rjinner1 Rjouter1 Rkinner1 Rkouter1 ... @@ -16,10 +16,10 @@ Syntax * itypeN = central atom type for Nth ADF histogram (see asterisk form below) * jtypeN = J atom type for Nth ADF histogram (see asterisk form below) * ktypeN = K atom type for Nth ADF histogram (see asterisk form below) -* RjinnerN = inner radius of J atom shell for Nth ADF histogram (distance units) -* RjouterN = outer radius of J atom shell for Nth ADF histogram (distance units) +* RjinnerN = inner radius of J atom shell for Nth ADF histogram (distance units) +* RjouterN = outer radius of J atom shell for Nth ADF histogram (distance units) * RkinnerN = inner radius of K atom shell for Nth ADF histogram (distance units) -* RkouterN = outer radius of K atom shell for Nth ADF histogram (distance units) +* RkouterN = outer radius of K atom shell for Nth ADF histogram (distance units) * zero or one keyword/value pairs may be appended * keyword = *ordinate* @@ -177,8 +177,8 @@ Output info """"""""""" This compute calculates a global array with the number of rows = -*Nbins*, and the number of columns = 1 + 2\*Ntriples, where Ntriples is the -number of I,J,K triples specified. The first column has the bin +*Nbins* and the number of columns = :math:`1 + 2 \times` *Ntriples*, where *Ntriples* +is the number of I,J,K triples specified. The first column has the bin coordinate (angle-related ordinate at midpoint of bin). Each subsequent column has the two ADF values for a specific set of (\ *itypeN*,\ *jtypeN*,\ *ktypeN*\ ) interactions, as described above. These values can be used @@ -192,10 +192,10 @@ The first column of array values is the angle-related ordinate, either the angle in degrees or radians, or the cosine of the angle. Each subsequent pair of columns gives the first and second kinds of ADF for a specific set of (\ *itypeN*,\ *jtypeN*,\ *ktypeN*\ ). The values -in the first ADF column are normalized numbers >= 0.0, +in the first ADF column are normalized numbers :math:`\ge 0.0`, whose integral w.r.t. the ordinate is 1, i.e. the first ADF is a normalized probability distribution. -The values in the second ADF column are also numbers >= 0.0. +The values in the second ADF column are also numbers :math:`\ge 0.0`. They are the cumulative density distribution of angles per atom. By definition, this ADF is monotonically increasing from zero to a maximum value equal to the average total number of diff --git a/doc/src/compute_angle.rst b/doc/src/compute_angle.rst index b4a7d9a060..ee08af24d8 100644 --- a/doc/src/compute_angle.rst +++ b/doc/src/compute_angle.rst @@ -6,7 +6,7 @@ compute angle command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID angle @@ -35,12 +35,12 @@ 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:`angle_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 *N*, where *N* is the number +of sub_styles defined by the :doc:`angle_style hybrid ` command, +which can be accessed by indices 1 through *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_angle_local.rst b/doc/src/compute_angle_local.rst index 688bfbeecb..126dd309af 100644 --- a/doc/src/compute_angle_local.rst +++ b/doc/src/compute_angle_local.rst @@ -6,7 +6,7 @@ compute angle/local command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID angle/local value1 value2 ... keyword args ... @@ -47,7 +47,7 @@ interactions. The number of datums generated, aggregated across all processors, equals the number of angles in the system, modified by the group parameter as explained below. -The value *theta* is the angle for the 3 atoms in the interaction. +The value *theta* is the angle for the three atoms in the interaction. The value *eng* is the interaction energy for the angle. @@ -65,8 +65,8 @@ Note that the value of theta for each angle which stored in the internal variable is in radians, not degrees. As an example, these commands can be added to the bench/in.rhodo -script to compute the cosine and cosine\^2 of every angle in the system -and output the statistics in various ways: +script to compute the cosine and cosine-squared of every angle in the +system and output the statistics in various ways: .. code-block:: LAMMPS @@ -83,19 +83,20 @@ and output the statistics in various ways: fix 10 all ave/histo 10 10 100 -1 1 20 c_2[3] mode vector file tmp.histo -The :doc:`dump local ` command will output the energy, angle, -cosine(angle), cosine\^2(angle) for every angle 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 cosine(angle) values and write them to a +The :doc:`dump local ` command will output the potential energy +(:math:`\phi`), the angle (:math:`\theta`), :math:`\cos(\theta`), and +:math:`\cos^2(\theta)` for every angle :math:`\theta` 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 :math:`\cos(\theta)` values and write them to a file. ---------- The local data stored by this command is generated by looping over all the atoms owned on a processor and their angles. An angle will only -be included if all 3 atoms in the angle are in the specified compute +be included if all three atoms in the angle are in the specified compute group. Any angles that have been broken (see the :doc:`angle_style ` command) by setting their angle type to 0 are not included. Angles that have been turned off (see the :doc:`fix shake ` or :doc:`delete_bonds ` commands) by diff --git a/doc/src/compute_angmom_chunk.rst b/doc/src/compute_angmom_chunk.rst index 10678c4e47..2e98742772 100644 --- a/doc/src/compute_angmom_chunk.rst +++ b/doc/src/compute_angmom_chunk.rst @@ -6,7 +6,7 @@ compute angmom/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID angmom/chunk chunkID @@ -72,13 +72,13 @@ 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 momentum for each chunk. +number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom ` command. The number of columns = 3 for the three +(*x*, *y*, *z*) components of the angular momentum 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. -The array values are "intensive". The array values will be in +The array values are "intensive." The array values will be in mass-velocity-distance :doc:`units `. Restrictions diff --git a/doc/src/compute_ave_sphere_atom.rst b/doc/src/compute_ave_sphere_atom.rst index 48dbf377cb..e5ed7e1437 100644 --- a/doc/src/compute_ave_sphere_atom.rst +++ b/doc/src/compute_ave_sphere_atom.rst @@ -9,7 +9,7 @@ Accelerator Variants: *ave/sphere/atom/kk* Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID ave/sphere/atom keyword values ... @@ -37,13 +37,13 @@ Description Define a computation that calculates the local mass density and temperature for each atom based on its neighbors inside a spherical -cutoff. If an atom has M neighbors, then its local mass density is -calculated as the sum of its mass and its M neighbor masses, divided +cutoff. If an atom has :math:`M` neighbors, then its local mass density is +calculated as the sum of its mass and its :math:`M` neighbor masses, divided by the volume of the cutoff sphere (or circle in 2d). The local temperature of the atom is calculated as the temperature of the -collection of M+1 atoms, after subtracting the center-of-mass velocity -of the M+1 atoms from each of the M+1 atom's velocities. This is -effectively the thermal velocity of the neighborhood of the central +collection of :math:`M+1` atoms, after subtracting the center-of-mass velocity +of the :math:`M+1` atoms from each of the :math:`M+1` atom's velocities. This +is effectively the thermal velocity of the neighborhood of the central atom, similar to :doc:`compute temp/com `. The optional keyword *cutoff* defines the distance cutoff used when diff --git a/doc/src/compute_basal_atom.rst b/doc/src/compute_basal_atom.rst index 3a74379acb..b6391eb5b5 100644 --- a/doc/src/compute_basal_atom.rst +++ b/doc/src/compute_basal_atom.rst @@ -6,7 +6,7 @@ compute basal/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID basal/atom @@ -47,12 +47,12 @@ in examples/PACKAGES/basal. Output info """"""""""" -This compute calculates a per-atom array with 3 columns, which can be -accessed by indices 1-3 by any command that uses per-atom values from +This compute calculates a per-atom array with three columns, which can be +accessed by indices 1--3 by any command that uses per-atom values from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output options. -The per-atom vector values are unitless since the 3 columns represent +The per-atom vector values are unitless since the three columns represent components of a unit vector. Restrictions diff --git a/doc/src/compute_body_local.rst b/doc/src/compute_body_local.rst index 662838b08f..95c8b14330 100644 --- a/doc/src/compute_body_local.rst +++ b/doc/src/compute_body_local.rst @@ -6,7 +6,7 @@ compute body/local command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID body/local input1 input2 ... @@ -33,7 +33,7 @@ Description """"""""""" Define a computation that calculates properties of individual body -sub-particles. The number of datums generated, aggregated across all +sub-particles. The number of data generated, aggregated across all processors, equals the number of body sub-particles plus the number of non-body particles in the system, modified by the group parameter as explained below. See the :doc:`Howto body ` page for @@ -41,8 +41,8 @@ more details on using body particles. The local data stored by this command is generated by looping over all the atoms. An atom will only be included if it is in the group. If -the atom is a body particle, then its N sub-particles will be looped -over, and it will contribute N datums to the count of datums. If it +the atom is a body particle, then its :math:`N` sub-particles will be looped +over, and it will contribute :math:`N` data to the count of data. If it is not a body particle, it will contribute 1 datum. For both body particles and non-body particles, the *id* keyword @@ -64,8 +64,8 @@ by the :doc:`atom_style body `, determines how many fields exist and what they are. See the :doc:`Howto_body ` doc page for details of the different styles. -Here is an example of how to output body information using the :doc:`dump local ` command with this compute. If fields 1,2,3 for the -body sub-particles are x,y,z coordinates, then the dump file will be +Here is an example of how to output body information using the :doc:`dump local ` command with this compute. If fields 1, 2, and 3 for the +body sub-particles are (*x*, *y*, *z*) coordinates, then the dump file will be formatted similar to the output of a :doc:`dump atom or custom ` command. @@ -79,7 +79,7 @@ Output info This compute calculates a local vector or local array depending on the number of keywords. The length of the vector or number of rows in the -array is the number of datums as described above. If a single keyword +array is the number of data as described above. 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 diff --git a/doc/src/compute_bond.rst b/doc/src/compute_bond.rst index ddca97420d..82caef8e93 100644 --- a/doc/src/compute_bond.rst +++ b/doc/src/compute_bond.rst @@ -6,7 +6,7 @@ compute bond command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID bond @@ -35,10 +35,13 @@ 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:`bond_style hybrid ` command, which can be accessed by indices 1-N. +This compute calculates a global vector of length :math:`N`, where :math:`N` +is the number of sub_styles defined by the +:doc:`bond_style hybrid ` command, +which can be accessed by 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 +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 diff --git a/doc/src/compute_bond_local.rst b/doc/src/compute_bond_local.rst index 24b0943484..ed779d986e 100644 --- a/doc/src/compute_bond_local.rst +++ b/doc/src/compute_bond_local.rst @@ -6,7 +6,7 @@ compute bond/local command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID bond/local value1 value2 ... keyword args ... @@ -35,8 +35,8 @@ Syntax .. parsed-literal:: - *set* args = dist name - dist = only currently allowed arg + *set* args = *dist* name + *dist* = only currently allowed arg name = name of variable to set with distance (dist) Examples @@ -49,7 +49,7 @@ Examples compute 1 all bond/local dist fx fy fz - compute 1 all angle/local dist v_distsq set dist d + compute 1 all bond/local dist v_distsq set dist d Description """"""""""" @@ -82,32 +82,34 @@ relative to the center of mass (COM) velocity of the 2 atoms in the bond. The value *engvib* is the vibrational kinetic energy of the two atoms -in the bond, which is simply 1/2 m1 v1\^2 + 1/2 m2 v2\^2, where v1 and -v2 are the magnitude of the velocity of the 2 atoms along the bond -direction, after the COM velocity has been subtracted from each. - -The value *engrot* is the rotational kinetic energy of the two atoms -in the bond, which is simply 1/2 m1 v1\^2 + 1/2 m2 v2\^2, where v1 and -v2 are the magnitude of the velocity of the 2 atoms perpendicular to -the bond direction, after the COM velocity has been subtracted from +in the bond, which is simply :math:`\frac12 m_1 v_1^2 + \frac12 m_2 v_2^2,` +where :math:`v_1` and :math:`v_2` are the magnitude of the velocity of the two +atoms along the bond direction, after the COM velocity has been subtracted from each. -The value *engtrans* is the translational kinetic energy associated -with the motion of the COM of the system itself, namely 1/2 (m1+m2) -Vcm\^2 where Vcm = magnitude of the velocity of the COM. +The value *engrot* is the rotational kinetic energy of the two atoms +in the bond, which is simply :math:`\frac12 m_1 v_1^2 + \frac12 m_2 v_2^2,` +where :math:`v_1` and :math:`v_2` are the magnitude of the velocity of the two +atoms perpendicular to the bond direction, after the COM velocity has been +subtracted from each. -Note that these 3 kinetic energy terms are simply a partitioning of -the summed kinetic energy of the 2 atoms themselves. I.e. total KE = -1/2 m1 v1\^2 + 1/2 m2 v2\^2 = engvib + engrot + engtrans, where v1,v2 -are the magnitude of the velocities of the 2 atoms, without any -adjustment for the COM velocity. +The value *engtrans* is the translational kinetic energy associated +with the motion of the COM of the system itself, namely :math:`\frac12(m_1+m_2) +V_{\mathrm{cm}}^2`, where `Vcm` = magnitude of the velocity of the COM. + +Note that these three kinetic energy terms are simply a partitioning of +the summed kinetic energy of the two atoms themselves. That is, the total +kinetic energy is +:math:`\frac12 m_1 v_1^2 + \frac12 m_2 v_2^2` = engvib + engrot + engtrans, +where :math:`v_1` and :math:`v_2` are the magnitude of the velocities of the +two atoms, without any adjustment for the COM velocity. The value *omega* is the magnitude of the angular velocity of the two atoms around their COM position. The value *velvib* is the magnitude of the relative velocity of the two atoms in the bond towards each other. A negative value means the -2 atoms are moving toward each other; a positive value means they are +two atoms are moving toward each other; a positive value means they are moving apart. The value *v_name* can be used together with the *set* keyword to @@ -121,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 distance\^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 @@ -138,12 +140,12 @@ 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, distance, -distance\^2 for every bond in the system. The +The :doc:`dump local ` command will output the energy, length, +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 distance\^2 values and write them to a file. +with thermo output, and the :doc:`fix ave/histo ` +command will histogram the length\ :math:`^2` values and write them to a file. ---------- diff --git a/doc/src/compute_born_matrix.rst b/doc/src/compute_born_matrix.rst index 423df9961d..920ae46532 100644 --- a/doc/src/compute_born_matrix.rst +++ b/doc/src/compute_born_matrix.rst @@ -6,20 +6,26 @@ compute born/matrix command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID born/matrix keyword value ... * ID, group-ID are documented in :doc:`compute ` command * born/matrix = style name of this compute command -* zero or more keyword/value pairs may be appended +* zero or more keywords or keyword/value pairs may be appended .. parsed-literal:: - keyword = *numdiff* + keyword = *numdiff* or *pair* or *bond* or *angle* or *dihedral* or *improper* *numdiff* values = delta virial-ID delta = magnitude of strain (dimensionless) virial-ID = ID of pressure compute for virial (string) + (*numdiff* cannot be used with any other keyword) + *pair* = compute pair-wise contributions + *bond* = compute bonding contributions + *angle* = compute angle contributions + *dihedral* = compute dihedral contributions + *improper* = compute improper contributions Examples """""""" @@ -36,8 +42,8 @@ Description .. versionadded:: 4May2022 Define a compute that calculates -:math:`\frac{\partial{}^2U}{\partial\varepsilon_{i}\partial\varepsilon_{j}}` the -second derivatives of the potential energy :math:`U` w.r.t. strain +:math:`\frac{\partial{}^2U}{\partial\varepsilon_{i}\partial\varepsilon_{j}},` the +second derivatives of the potential energy :math:`U` with respect to the strain tensor :math:`\varepsilon` elements. These values are related to: .. math:: @@ -69,14 +75,14 @@ whose 21 independent elements are output in this order: .. math:: - \begin{matrix} + \begin{bmatrix} C_{1} & C_{7} & C_{8} & C_{9} & C_{10} & C_{11} \\ C_{7} & C_{2} & C_{12} & C_{13} & C_{14} & C_{15} \\ \vdots & C_{12} & C_{3} & C_{16} & C_{17} & C_{18} \\ \vdots & C_{13} & C_{16} & C_{4} & C_{19} & C_{20} \\ \vdots & \vdots & \vdots & C_{19} & C_{5} & C_{21} \\ \vdots & \vdots & \vdots & \vdots & C_{21} & C_{6} - \end{matrix} + \end{bmatrix} in this matrix the indices of :math:`C_{k}` value are the corresponding element :math:`k` in the global vector output by this compute. Each term comes from the sum @@ -169,14 +175,14 @@ requiring that it use the virial keyword e.g. **Output info:** This compute calculates a global vector with 21 values that are -the second derivatives of the potential energy w.r.t. strain. +the second derivatives of the potential energy with respect to strain. The values are in energy units. The values are ordered as explained above. These values can be used by any command that uses global values from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output options. -The array values calculated by this compute are all "extensive". +The array values calculated by this compute are all "extensive." Restrictions """""""""""" @@ -188,7 +194,7 @@ the :doc:`Build package ` page for more info. The Born term can be decomposed as a product of two terms. The first one is a general term which depends on the configuration. The second one is specific to -every interaction composing your force field (non-bonded, bonds, angle...). +every interaction composing your force field (non-bonded, bonds, angle, ...). Currently not all LAMMPS interaction styles implement the *born_matrix* method giving first and second order derivatives and LAMMPS will exit with an error if this compute is used with such interactions unless the *numdiff* option is diff --git a/doc/src/compute_centro_atom.rst b/doc/src/compute_centro_atom.rst index 3d32b75459..eab8793466 100644 --- a/doc/src/compute_centro_atom.rst +++ b/doc/src/compute_centro_atom.rst @@ -6,17 +6,17 @@ compute centro/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID centro/atom lattice keyword value ... * ID, group-ID are documented in :doc:`compute ` command - centro/atom = style name of this compute command - lattice = *fcc* or *bcc* or N = # of neighbors per atom to include +* centro/atom = style name of this compute command +* lattice = *fcc* or *bcc* or N = # of neighbors per atom to include * zero or more keyword/value pairs may be appended * keyword = *axes* -.. parsed-literal:: + .. parsed-literal:: *axes* value = *no* or *yes* *no* = do not calculate 3 symmetry axes @@ -83,12 +83,13 @@ atoms with smallest contributions to the centrosymmetry parameter, i.e. the two most symmetric pairs of atoms. The third vector is normal to the first two by the right-hand rule. All three vectors are normalized to unit length. For FCC crystals, the first two vectors -will lie along a <110> direction, while the third vector will lie -along either a <100> or <111> direction. For HCP crystals, the first -two vectors will lie along <1000> directions, while the third vector -will lie along <0001>. This provides a simple way to measure local -orientation in HCP structures. In general, the *axes* keyword can be -used to estimate the orientation of symmetry axes in the neighborhood +will lie along a :math:`\langle110\rangle` direction, while the third vector +will lie along either a :math:`\langle100\rangle` or :math:`\langle111\rangle` +direction. For HCP crystals, the first two vectors will lie along +:math:`\langle1000\rangle` directions, while the third vector +will lie along :math:`\langle0001\rangle`. This provides a simple way to +measure local orientation in HCP structures. In general, the *axes* keyword +can be used to estimate the orientation of symmetry axes in the neighborhood of any atom. Only atoms within the cutoff of the pairwise neighbor list are @@ -96,7 +97,7 @@ considered as possible neighbors. Atoms not in the compute group are included in the :math:`N` neighbors used in this calculation. 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 *centro/atom* style. @@ -111,11 +112,11 @@ options. If the *axes* keyword setting is *yes*, then a per-atom array is calculated. The first column is the centrosymmetry parameter. The -next three columns are the x, y, and z components of the first +next three columns are the *x*, *y*, and *z* components of the first symmetry axis, followed by the second, and third symmetry axes in -columns 5-7 and 8-10. +columns 5--7 and 8--10. -The centrosymmetry values are unitless values >= 0.0. Their magnitude +The centrosymmetry values are unitless values :math:`\ge 0.0`. Their magnitude depends on the lattice style due to the number of contributing neighbor pairs in the summation in the formula above. And it depends on the local defects surrounding the central atom, as described above. For diff --git a/doc/src/compute_chunk_atom.rst b/doc/src/compute_chunk_atom.rst index 9d36827c25..d151692771 100644 --- a/doc/src/compute_chunk_atom.rst +++ b/doc/src/compute_chunk_atom.rst @@ -6,7 +6,7 @@ compute chunk/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID chunk/atom style args keyword values ... @@ -150,14 +150,14 @@ The *binning* styles perform a spatial binning of atoms, and assign an atom the chunk ID corresponding to the bin number it is in. *Nchunk* is set to the number of bins, which can change if the simulation box size changes. This also depends on the setting of the *units* -keyword; e.g. for *reduced* units the number of chunks may not change -even if the box size does. +keyword (e.g., for *reduced* units the number of chunks may not change +even if the box size does). The *bin/1d*, *bin/2d*, and *bin/3d* styles define bins as 1d layers (slabs), 2d pencils, or 3d boxes. The *dim*, *origin*, and *delta* settings are specified 1, 2, or 3 times. For 2d or 3d bins, there is -no restriction on specifying dim = x before dim = y or z, or dim = y -before dim = z. Bins in a particular *dim* have a bin size in that +no restriction on specifying dim = *x* before dim = *y* or *z*, or dim = *y* +before dim = *z*. Bins in a particular *dim* have a bin size in that dimension given by *delta*\ . In each dimension, bins are defined relative to a specified *origin*, which may be the lower/upper edge of the simulation box (in that dimension), or its center point, or a @@ -170,10 +170,11 @@ boxes aligned with the xyz coordinate axes. For triclinic (non-orthogonal) simulation boxes, the bin faces are parallel to the tilted faces of the simulation box. See the :doc:`Howto triclinic ` page for a discussion of the geometry of triclinic boxes in LAMMPS. As described there, a tilted -simulation box has edge vectors a,b,c. In that nomenclature, bins in -the x dimension have faces with normals in the "b" cross "c" -direction. Bins in y have faces normal to the "a" cross "c" -direction. And bins in z have faces normal to the "a" cross "b" +simulation box has edge vectors :math:`\vec a`, :math:`\vec b`, and +:math:`\vec c`. In that nomenclature, bins in +the *x* dimension have faces with normals in the :math:`\vec b \times \vec c` +direction, bins in *y* have faces normal to the :math:`\vec a \times \vec c` +direction, and bins in *z* have faces normal to the :math:`\vec a \times \vec b` direction. Note that in order to define the size and position of these bins in an unambiguous fashion, the *units* option must be set to *reduced* when using a triclinic simulation box, as noted below. @@ -181,46 +182,46 @@ to *reduced* when using a triclinic simulation box, as noted below. The meaning of *origin* and *delta* for triclinic boxes is as follows. Consider a triclinic box with bins that are 1d layers or slabs in the x dimension. No matter how the box is tilted, an *origin* of 0.0 -means start layers at the lower "b" cross "c" plane of the simulation -box and an *origin* of 1.0 means to start layers at the upper "b" -cross "c" face of the box. A *delta* value of 0.1 in *reduced* units -means there will be 10 layers from 0.0 to 1.0, regardless of the -current size or shape of the simulation box. +means start layers at the lower :math:`\vec b \times \vec c` plane of the +simulation box and an *origin* of 1.0 means to start layers at the upper +:math:`\vec b \times \vec c` face of the box. A *delta* value of 0.1 in +*reduced* units means there will be 10 layers from 0.0 to 1.0, regardless of +the current size or shape of the simulation box. The *bin/sphere* style defines a set of spherical shell bins around the origin (\ *xorig*,\ *yorig*,\ *zorig*\ ), using *nsbin* bins with radii equally spaced between *srmin* and *srmax*\ . This is effectively a 1d vector of bins. For example, if *srmin* = 1.0 and *srmax* = 10.0 and -*nsbin* = 9, then the first bin spans 1.0 < r < 2.0, and the last bin -spans 9.0 < r 10.0. The geometry of the bins is the same whether the -simulation box is orthogonal or triclinic; i.e. the spherical shells +*nsbin* = 9, then the first bin spans :math:`1.0 < r < 2.0`, and the last bin +spans :math:`9.0 < r < 10.0`. The geometry of the bins is the same whether the +simulation box is orthogonal or triclinic (i.e., the spherical shells are not tilted or scaled differently in different dimensions to -transform them into ellipsoidal shells. +transform them into ellipsoidal shells). The *bin/cylinder* style defines bins for a cylinder oriented along the axis *dim* with the axis coordinates in the other two radial -dimensions at (\ *c1*,\ *c2*\ ). For dim = x, c1/c2 = y/z; for dim = y, -c1/c2 = x/z; for dim = z, c1/c2 = x/y. This is effectively a 2d array -of bins. The first dimension is along the cylinder axis, the second -dimension is radially outward from the cylinder axis. The bin size -and positions along the cylinder axis are specified by the *origin* -and *delta* values, the same as for the *bin/1d*, *bin/2d*, and -*bin/3d* styles. There are *ncbin* concentric circle bins in the +dimensions at (\ *c1*,\ *c2*\ ). For dim = *x*, :math:`c_1/c_2 = y/z`; +for dim = *y*, :math:`c_1/c_2 = x/z`; for dim = *z*, +:math:`c_1/c_2 = x/y`. This is effectively a 2d array of bins. The first +dimension is along the cylinder axis, the second dimension is radially outward +from the cylinder axis. The bin size and positions along the cylinder axis are +specified by the *origin* and *delta* values, the same as for the *bin/1d*, +*bin/2d*, and *bin/3d* styles. There are *ncbin* concentric circle bins in the radial direction from the cylinder axis with radii equally spaced between *crmin* and *crmax*\ . For example, if *crmin* = 1.0 and -*crmax* = 10.0 and *ncbin* = 9, then the first bin spans 1.0 < r < -2.0, and the last bin spans 9.0 < r 10.0. The geometry of the bins in +*crmax* = 10.0 and *ncbin* = 9, then the first bin spans :math:`1.0 < r < 2.0` +and the last bin spans :math:`9.0 < r < 10.0`. The geometry of the bins in the radial dimensions is the same whether the simulation box is -orthogonal or triclinic; i.e. the concentric circles are not tilted or +orthogonal or triclinic (i.e., the concentric circles are not tilted or scaled differently in the two different dimensions to transform them -into ellipses. +into ellipses). The created bins (and hence the chunk IDs) are numbered consecutively from 1 to the number of bins = *Nchunk*\ . For *bin2d* and *bin3d*, the numbering varies most rapidly in the first dimension (which could be -x, y, or z), next rapidly in the second dimension, and most slowly in the +*x*, *y*, or *z*), next rapidly in the second dimension, and most slowly in the third dimension. For *bin/sphere*, the bin with smallest radii is chunk -1 and the bni with largest radii is chunk Nchunk = *ncbin*\ . For +1 and the bin with largest radii is chunk Nchunk = *ncbin*\ . For *bin/cylinder*, the numbering varies most rapidly in the dimension along the cylinder axis and most slowly in the radial direction. @@ -236,8 +237,8 @@ assigned to the atom. ---------- The *type* style uses the atom type as the chunk ID. *Nchunk* is set -to the number of atom types defined for the simulation, e.g. via the -:doc:`create_box ` or :doc:`read_data ` commands. +to the number of atom types defined for the simulation (e.g., via the +:doc:`create_box ` or :doc:`read_data ` commands). ---------- @@ -264,8 +265,8 @@ on a quantity calculated and stored by a compute, fix, or variable. In each case, it must be a per-atom quantity. In each case the referenced floating point values are converted to an integer chunk ID as follows. The floating point value is truncated (rounded down) to -an integer value. If the integer value is <= 0, then a chunk ID of 0 -is assigned to the atom. If the integer value is > 0, it becomes the +an integer value. If the integer value is :math:`\le 0`, then a chunk ID of 0 +is assigned to the atom. If the integer value is :math:`> 0`, it becomes the chunk ID to the atom. *Nchunk* is set to the largest chunk ID. Note that this excludes atoms which are not in the specified group or optional region. @@ -362,7 +363,7 @@ If *limit* is set to *Nc* = 0, then no limit is imposed on *Nchunk*, though the *compress* keyword can still be used to reduce *Nchunk*, as described below. -If *Nc* > 0, then the effect of the *limit* keyword depends on whether +If *Nc* :math:`>` 0, then the effect of the *limit* keyword depends on whether the *compress* keyword is also used with a setting of *yes*, and whether the *compress* keyword is specified before the *limit* keyword or after. @@ -374,7 +375,7 @@ First, here is what occurs if *compress yes* is not set. If *limit* is set to *Nc max*, then *Nchunk* is reset to the smaller of *Nchunk* and *Nc*\ . If *limit* is set to *Nc exact*, then *Nchunk* is reset to *Nc*, whether the original *Nchunk* was larger or smaller than *Nc*\ . -If *Nchunk* shrank due to the *limit* setting, then atom chunk IDs > +If *Nchunk* shrank due to the *limit* setting, then atom chunk IDs :math:`>` *Nchunk* will be reset to 0 or *Nchunk*, depending on the setting of the *discard* keyword. If *Nchunk* grew, there will simply be some chunks with no atoms assigned to them. @@ -384,22 +385,22 @@ If *compress yes* is set, and the *compress* keyword comes before the described below, which resets *Nchunk*\ . The *limit* keyword is then applied to the new *Nchunk* value, exactly as described in the preceding paragraph. Note that in this case, all atoms will end up -with chunk IDs <= *Nc*, but their original values (e.g. molecule ID or -compute/fix/variable) may have been > *Nc*, because of the compression -operation. +with chunk IDs :math:`\le` *Nc*, but their original values (e.g., molecule ID +or compute/fix/variable) may have been :math:`>` *Nc*, because of the +compression operation. If *compress yes* is set, and the *compress* keyword comes after the *limit* keyword, then the *limit* value of *Nc* is applied first to -the uncompressed value of *Nchunk*, but only if *Nc* < *Nchunk* +the uncompressed value of *Nchunk*, but only if *Nc* :math:`<` *Nchunk* (whether *Nc max* or *Nc exact* is used). This effectively means all -atoms with chunk IDs > *Nc* have their chunk IDs reset to 0 or *Nc*, +atoms with chunk IDs :math:`>` *Nc* have their chunk IDs reset to 0 or *Nc*, depending on the setting of the *discard* keyword. The compression operation is then performed, which may shrink *Nchunk* further. If -the new *Nchunk* < *Nc* and *limit* = *Nc exact* is specified, then +the new *Nchunk* :math:`<` *Nc* and *limit* = *Nc exact* is specified, then *Nchunk* is reset to *Nc*, which results in extra chunks with no atoms assigned to them. Note that in this case, all atoms will end up with -chunk IDs <= *Nc*, and their original values (e.g. molecule ID or -compute/fix/variable value) will also have been <= *Nc*\ . +chunk IDs :math:`\le` *Nc*, and their original values (e.g., molecule ID or +compute/fix/variable value) will also have been :math:`\le` *Nc*\ . ---------- @@ -601,7 +602,8 @@ 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. Angstroms for units = real or metal. +:doc:`units ` command (e.g., :math:`\mathrm{\mathring A}` +for units = *real* or *metal*). A *lattice* value means the distance units are in lattice spacings. The :doc:`lattice ` command must have been previously used to define the lattice spacing. A *reduced* value means normalized @@ -615,8 +617,8 @@ scaled by the lattice spacing or reduced value of the *x* dimension. Note that for the *bin/cylinder* style, the radii *crmin* and *crmax* are scaled by the lattice spacing or reduced value of the first -dimension perpendicular to the cylinder axis. E.g. y for an x-axis -cylinder, x for a y-axis cylinder, and x for a z-axis cylinder. +dimension perpendicular to the cylinder axis (e.g., *y* for an *x*-axis +cylinder, *x* for a *y*-axis cylinder, and *x* for a *z*-axis cylinder). ---------- diff --git a/doc/src/compute_chunk_spread_atom.rst b/doc/src/compute_chunk_spread_atom.rst index 1fd260ab2c..dc80ad9ea9 100644 --- a/doc/src/compute_chunk_spread_atom.rst +++ b/doc/src/compute_chunk_spread_atom.rst @@ -6,7 +6,7 @@ compute chunk/spread/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID chunk/spread/atom chunkID input1 input2 ... @@ -18,10 +18,10 @@ Syntax .. parsed-literal:: - c_ID = global vector calculated by a compute with ID - c_ID[I] = Ith column of global array calculated by a compute with ID, I can include wildcard (see below) - f_ID = global vector calculated by a fix with ID - f_ID[I] = Ith column of global array calculated by a fix with ID, I can include wildcard (see below) + c_ID = global vector calculated by a compute with ID + c_ID[I] = Ith column of global array calculated by a compute with ID, I can include wildcard (see below) + f_ID = global vector calculated by a fix with ID + f_ID[I] = Ith column of global array calculated by a fix with ID, I can include wildcard (see below) Examples """""""" diff --git a/doc/src/compute_cluster_atom.rst b/doc/src/compute_cluster_atom.rst index 32954480cc..876186b6b6 100644 --- a/doc/src/compute_cluster_atom.rst +++ b/doc/src/compute_cluster_atom.rst @@ -14,7 +14,7 @@ compute aggregate/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID cluster/atom cutoff compute ID group-ID fragment/atom keyword value ... @@ -69,9 +69,9 @@ fragments or not, based on the *yes* or *no* setting. If the setting is *no* (the default), their fragment IDs are set to 0. An aggregate is defined by combining the rules for clusters and -fragments, i.e. a set of atoms, where each of it is within the cutoff +fragments (i.e., a set of atoms, where each of them is within the cutoff distance from one or more atoms within a fragment that is part of -the same cluster. This measure can be used to track molecular assemblies +the same cluster). This measure can be used to track molecular assemblies like micelles. For computes *cluster/atom* and *aggregate/atom* a neighbor list @@ -92,9 +92,9 @@ style computes. does not apply when using long-range coulomb (\ *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 clusters 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 clusters + for snapshots in the dump file. The rerun script can use a :doc:`special_bonds ` command that includes all pairs in the neighbor list. @@ -114,7 +114,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 will be an ID > 0, as explained above. +The per-atom vector values will be an ID :math:`> 0`, as explained above. Restrictions """""""""""" @@ -129,5 +129,5 @@ Related commands Default """"""" -The default for fragment/atom is single no. +The default for fragment/atom is single=no. diff --git a/doc/src/compute_cna_atom.rst b/doc/src/compute_cna_atom.rst index 756a9d932c..144a09d467 100644 --- a/doc/src/compute_cna_atom.rst +++ b/doc/src/compute_cna_atom.rst @@ -6,7 +6,7 @@ compute cna/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID cna/atom cutoff @@ -44,20 +44,22 @@ performed on mono-component systems. The CNA calculation can be sensitive to the specified cutoff value. You should insure the appropriate nearest neighbors of an atom are -found within the cutoff distance for the presumed crystal structure. -E.g. 12 nearest neighbor for perfect FCC and HCP crystals, 14 nearest -neighbors for perfect BCC crystals. These formulas can be used to +found within the cutoff distance for the presumed crystal structure +(e.g., 12 nearest neighbor for perfect FCC and HCP crystals, 14 nearest +neighbors for perfect BCC crystals). These formulas can be used to obtain a good cutoff distance: .. math:: - r_{c}^{fcc} = & \frac{1}{2} \left(\frac{\sqrt{2}}{2} + 1\right) \mathrm{a} \simeq 0.8536 \:\mathrm{a} \\ - r_{c}^{bcc} = & \frac{1}{2}(\sqrt{2} + 1) \mathrm{a} \simeq 1.207 \:\mathrm{a} \\ - r_{c}^{hcp} = & \frac{1}{2}\left(1+\sqrt{\frac{4+2x^{2}}{3}}\right) \mathrm{a} + r_{c}^{\mathrm{fcc}} = & \frac{1}{2} \left(\frac{\sqrt{2}}{2} + 1\right) a + \approx 0.8536 a \\ + r_{c}^{\mathrm{bcc}} = & \frac{1}{2}(\sqrt{2} + 1) a + \approx 1.207 a \\ + r_{c}^{\mathrm{hcp}} = & \frac{1}{2}\left(1+\sqrt{\frac{4+2x^{2}}{3}}\right) a -where a is the lattice constant for the crystal structure concerned -and in the HCP case, x = (c/a) / 1.633, where 1.633 is the ideal c/a -for HCP crystals. +where :math:`a` is the lattice constant for the crystal structure concerned +and in the HCP case, :math:`x = (c/a) / 1.633`, where 1.633 is the ideal +:math:`c/a` for HCP crystals. Also note that since the CNA calculation in LAMMPS uses the neighbors of an owned atom to find the nearest neighbors of a ghost atom, the diff --git a/doc/src/compute_cnp_atom.rst b/doc/src/compute_cnp_atom.rst index 59c45107b3..41fdb8324e 100644 --- a/doc/src/compute_cnp_atom.rst +++ b/doc/src/compute_cnp_atom.rst @@ -6,7 +6,7 @@ compute cnp/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID cnp/atom cutoff @@ -28,7 +28,7 @@ Define a computation that calculates the Common Neighborhood Parameter (CNP) for each atom in the group. In solid-state systems the CNP is a useful measure of the local crystal structure around an atom and can be used to characterize whether the -atom is part of a perfect lattice, a local defect (e.g. a dislocation +atom is part of a perfect lattice, a local defect (e.g., a dislocation or stacking fault), or at a surface. The value of the CNP parameter will be 0.0 for atoms not in the @@ -40,7 +40,7 @@ This parameter is computed using the following formula from .. math:: - Q_{i} = \frac{1}{n_i}\sum_{j = 1}^{n_i} \left | \sum_{k = 1}^{n_{ij}} \vec{R}_{ik} + \vec{R}_{jk} \right | ^{2} + Q_{i} = \frac{1}{n_i}\sum_{j = 1}^{n_i} \left\lVert \sum_{k = 1}^{n_{ij}} \vec{R}_{ik} + \vec{R}_{jk} \right\rVert^{2} where the index *j* goes over the :math:`n_i` nearest neighbors of atom *i*, and the index *k* goes over the :math:`n_{ij}` common nearest neighbors @@ -58,13 +58,15 @@ obtain a good cutoff distance: .. math:: - r_{c}^{fcc} = & \frac{1}{2} \left(\frac{\sqrt{2}}{2} + 1\right) \mathrm{a} \simeq 0.8536 \:\mathrm{a} \\ - r_{c}^{bcc} = & \frac{1}{2}(\sqrt{2} + 1) \mathrm{a} \simeq 1.207 \:\mathrm{a} \\ - r_{c}^{hcp} = & \frac{1}{2}\left(1+\sqrt{\frac{4+2x^{2}}{3}}\right) \mathrm{a} + r_{c}^{\mathrm{fcc}} = & \frac{1}{2} \left(\frac{\sqrt{2}}{2} + 1\right) a + \approx 0.8536 a \\ + r_{c}^{\mathrm{bcc}} = & \frac{1}{2}(\sqrt{2} + 1) a + \approx 1.207 a \\ + r_{c}^{\mathrm{hcp}} = & \frac{1}{2}\left(1+\sqrt{\frac{4+2x^{2}}{3}}\right) a -where a is the lattice constant for the crystal structure concerned -and in the HCP case, x = (c/a) / 1.633, where 1.633 is the ideal c/a -for HCP crystals. +where :math:`a` is the lattice constant for the crystal structure concerned +and in the HCP case, :math:`x = (c/a) / 1.633`, where 1.633 is the ideal +:math:`c/a` for HCP crystals. Also note that since the CNP calculation in LAMMPS uses the neighbors of an owned atom to find the nearest neighbors of a ghost atom, the @@ -81,7 +83,7 @@ cutoff is the argument used with the compute cnp/atom command. LAMMPS will issue a warning if this is not the case. 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 *cnp/atom* style. @@ -103,9 +105,9 @@ values: BCC lattice = 0.0 HCP lattice = 4.4 - FCC (111) surface ~ 13.0 - FCC (100) surface ~ 26.5 - FCC dislocation core ~ 11 + FCC (111) surface = 13.0 + FCC (100) surface = 26.5 + FCC dislocation core = 11 Restrictions """""""""""" diff --git a/doc/src/compute_com.rst b/doc/src/compute_com.rst index 203eaaf687..df5373293e 100644 --- a/doc/src/compute_com.rst +++ b/doc/src/compute_com.rst @@ -6,7 +6,7 @@ compute com command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID com @@ -28,7 +28,7 @@ of atoms, including all effects due to atoms passing through periodic boundaries. A vector of three quantities is calculated by this compute, which -are the x,y,z coordinates of the center of mass. +are the :math:`(x,y,z)` coordinates of the center of mass. .. note:: @@ -38,17 +38,18 @@ are the x,y,z coordinates of the center of mass. "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. 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 vector values will be in +The vector values are "intensive." The vector values will be in distance :doc:`units `. Restrictions diff --git a/doc/src/compute_com_chunk.rst b/doc/src/compute_com_chunk.rst index 3165acfbcc..a2df80d5d8 100644 --- a/doc/src/compute_com_chunk.rst +++ b/doc/src/compute_com_chunk.rst @@ -6,7 +6,7 @@ compute com/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID com/chunk chunkID @@ -34,7 +34,7 @@ molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom ` 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 com/chunk calculation to a file is to use the :doc:`fix ave/time ` @@ -70,13 +71,13 @@ 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 x,y,z center-of-mass coordinates of each chunk. These +number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom ` command. The number of columns is +3 for the :math:`(x,y,z)` center-of-mass coordinates of 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 ` doc 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 distance :doc:`units `. Restrictions diff --git a/doc/src/compute_contact_atom.rst b/doc/src/compute_contact_atom.rst index 23b5f4639d..31aa24aa60 100644 --- a/doc/src/compute_contact_atom.rst +++ b/doc/src/compute_contact_atom.rst @@ -6,7 +6,7 @@ compute contact/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID contact/atom group2-ID @@ -44,11 +44,11 @@ accessed by 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 will be a number >= 0.0, as explained +The per-atom vector values will be a number :math:`\ge 0.0`, as explained above. The optional *group2-ID* argument allows to specify from which group atoms -contribute to the coordination number. Default setting is group 'all'. +contribute to the coordination number. Default setting is group 'all.' Restrictions """""""""""" diff --git a/doc/src/compute_coord_atom.rst b/doc/src/compute_coord_atom.rst index bff2a8a8af..b8bd29135b 100644 --- a/doc/src/compute_coord_atom.rst +++ b/doc/src/compute_coord_atom.rst @@ -9,23 +9,23 @@ Accelerator Variants: *coord/atom/kk* Syntax """""" -.. parsed-literal:: +.. 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:: - *cutoff* args = cutoff [group group2-ID] typeN - cutoff = distance within which to count coordination neighbors (distance units) - group *group2-ID* = select group-ID to restrict which atoms to consider for coordination number (optional) - typeN = atom type for Nth coordination count (see asterisk form below) - *orientorder* args = orientorderID threshold - orientorderID = ID of an orientorder/atom compute - threshold = minimum value of the product of two "connected" atoms + *cutoff* args = cutoff [*group* group2-ID] typeN + cutoff = distance within which to count coordination neighbors (distance units) + *group* group2-ID = select group-ID to restrict which atoms to consider for coordination number (optional) + typeN = atom type for Nth coordination count (see asterisk form below) + *orientorder* args = orientorderID threshold + orientorderID = ID of an orientorder/atom compute + threshold = minimum value of the product of two "connected" atoms Examples """""""" @@ -54,7 +54,7 @@ neighboring atoms, unless selected by type, type range, or group option, are included in the coordination number tally. The optional *group* keyword allows to specify from which group atoms -contribute to the coordination number. Default setting is group 'all'. +contribute to the coordination number. Default setting is group 'all.' The *typeN* keywords allow specification of which atom types contribute to each coordination number. One coordination number is @@ -65,15 +65,15 @@ includes atoms of all types (same as the "\*" format, see below). The *typeN* keywords can be specified in one of two ways. An explicit numeric value can be used, as in the second 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 +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 N. A leading asterisk means all types from 1 to n -(inclusive). A trailing asterisk means all types from n to N +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). The *orientorder* cstyle calculates the number of "connected" neighbor -atoms J around each central atom I. For this *cstyle*, connected is +atoms *j* around each central atom *i*\ . For this *cstyle*, connected is defined by the orientational order parameter calculated by the :doc:`compute orientorder/atom ` command. This *cstyle* thus allows one to apply the ten Wolde's criterion to @@ -84,16 +84,16 @@ The ID of the previously specified :doc:`compute orientorder/atom ` doc page for an overview of LAMMPS output options. -The per-atom vector or array values will be a number >= 0.0, as +The per-atom vector or array values will be a number :math:`\ge 0.0`, as explained above. Restrictions diff --git a/doc/src/compute_damage_atom.rst b/doc/src/compute_damage_atom.rst index 3847a4de66..b75a3ebc57 100644 --- a/doc/src/compute_damage_atom.rst +++ b/doc/src/compute_damage_atom.rst @@ -6,7 +6,7 @@ compute damage/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID damage/atom @@ -48,7 +48,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 (damage) >= 0.0. +The per-atom vector values are unitless numbers (damage) :math:`\ge 0.0`. Restrictions """""""""""" diff --git a/doc/src/compute_dihedral.rst b/doc/src/compute_dihedral.rst index d4198dde3c..1d987ec12f 100644 --- a/doc/src/compute_dihedral.rst +++ b/doc/src/compute_dihedral.rst @@ -6,7 +6,7 @@ compute dihedral command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID dihedral @@ -34,10 +34,12 @@ 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:`dihedral_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 +This compute calculates a global vector of length :math:`N`, where :math:`N` +is the number of sub_styles defined by the +:doc:`dihedral_style hybrid ` command, which 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 diff --git a/doc/src/compute_dihedral_local.rst b/doc/src/compute_dihedral_local.rst index 82d3c3ab72..291b870373 100644 --- a/doc/src/compute_dihedral_local.rst +++ b/doc/src/compute_dihedral_local.rst @@ -6,7 +6,7 @@ compute dihedral/local command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID dihedral/local value1 value2 ... keyword args ... @@ -35,7 +35,6 @@ Examples .. code-block:: LAMMPS compute 1 all dihedral/local phi - compute 1 all dihedral/local phi v_cos set phi p Description @@ -46,25 +45,26 @@ interactions. The number of datums generated, aggregated across all processors, equals the number of dihedral angles in the system, modified by the group parameter as explained below. -The value *phi* is the dihedral angle, as defined in the diagram on -the :doc:`dihedral_style ` doc page. +The value *phi* (:math:`\phi`) is the dihedral angle, as defined in the diagram +on the :doc:`dihedral_style ` doc page. -The value *v_name* can be used together with the *set* keyword to -compute a user-specified function of the dihedral angle phi. The -*name* specified for the *v_name* value is the name of an :doc:`equal-style variable ` which should evaluate a formula based on a -variable which will store the angle phi. This other variable must +The value *v_name* can be used together with the *set* keyword to compute a +user-specified function of the dihedral angle :math:`\phi`. The *name* +specified for the *v_name* value is the name of an +:doc:`equal-style variable ` which should evaluate a formula based on +a variable which will store the angle :math:`\phi`. This other variable must be an :doc:`internal-style variable ` defined in the input script; its initial numeric value can be anything. It must be an internal-style variable, because this command resets its value directly. The *set* keyword is used to identify the name of this -other variable associated with phi. +other variable associated with :math:`\phi`. -Note that the value of phi for each angle which stored in the internal +Note that the value of :math:`\phi` for each angle which stored in the internal variable is in radians, not degrees. As an example, these commands can be added to the bench/in.rhodo -script to compute the cosine and cosine\^2 of every dihedral angle in -the system and output the statistics in various ways: +script to compute the :math:`\cos\phi` and :math:`\cos^2\phi` of every dihedral +angle in the system and output the statistics in various ways: .. code-block:: LAMMPS @@ -81,19 +81,18 @@ the system and output the statistics in various ways: fix 10 all ave/histo 10 10 100 -1 1 20 c_2[2] mode vector file tmp.histo -The :doc:`dump local ` command will output the angle, -cosine(angle), cosine\^2(angle) for every dihedral in the system. The -:doc:`thermo_style ` command will print the average of +The :doc:`dump local ` command will output the angle (:math:`\phi`), +:math:`\cos(\phi)`, and :math:`\cos^2(\phi)` for every dihedral 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 cosine(angle) values and write them to a -file. +command will histogram the cosine(angle) values and write them to a file. ---------- The local data stored by this command is generated by looping over all the atoms owned on a processor and their dihedrals. A dihedral will -only be included if all 4 atoms in the dihedral are in the specified +only be included if all four atoms in the dihedral are in the specified compute group. Note that as atoms migrate from processor to processor, there will be @@ -101,7 +100,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, dihedral output from the :doc:`compute property/local ` command can be combined +For example, dihedral 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. @@ -120,9 +120,10 @@ This compute calculates a local vector or local array depending on the number of values. The length of the vector or number of rows in the array is the number of dihedrals. If a single value is specified, a local vector is produced. If two or more values are specified, a -local array is produced where the number of columns = the number of +local array is produced where the number of columns is equal to the number of values. 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 +local values from a compute as input. See the +:doc:`Howto output ` page for an overview of LAMMPS output options. The output for *phi* will be in degrees. diff --git a/doc/src/compute_dilatation_atom.rst b/doc/src/compute_dilatation_atom.rst index 0e3159ffe7..8e3c86a4af 100644 --- a/doc/src/compute_dilatation_atom.rst +++ b/doc/src/compute_dilatation_atom.rst @@ -6,12 +6,12 @@ compute dilatation/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID dilatation/atom * ID, group-ID are documented in compute command -* dilation/atom = style name of this compute command +* dilatation/atom = style name of this compute command Examples """""""" @@ -30,13 +30,13 @@ for an overview of LAMMPS commands for Peridynamics modeling. For small deformation, dilatation of is the measure of the volumetric strain. -The dilatation "theta" for each peridynamic particle I is calculated -as a sum over its neighbors with unbroken bonds, where the -contribution of the IJ pair is a function of the change in bond length +The dilatation :math:`\theta` for each peridynamic particle :math:`i` is +calculated as a sum over its neighbors with unbroken bonds, where the +contribution of the :math:`ij` pair is a function of the change in bond length (versus the initial length in the reference state), the volume fraction of the particles and an influence function. See the -`PDLAMMPS user guide `_ for a formal -definition of dilatation. +`PDLAMMPS user guide `_ for +a formal definition of dilatation. This command can only be used with a subset of the Peridynamic :doc:`pair styles `: peri/lps, peri/ves and peri/eps. @@ -51,13 +51,14 @@ 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 (theta) >= 0.0. +The per-atom vector values are unitless numbers :math:`(\theta \ge 0.0)`. Restrictions """""""""""" This compute is part of the PERI package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +LAMMPS was built with that package. See the +:doc:`Build package ` page for more info. Related commands """""""""""""""" diff --git a/doc/src/compute_dipole.rst b/doc/src/compute_dipole.rst index 243efc0576..7fb4b54fab 100644 --- a/doc/src/compute_dipole.rst +++ b/doc/src/compute_dipole.rst @@ -6,13 +6,13 @@ compute dipole command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS - compute ID group-ID dipole charge-correction + compute ID group-ID dipole arg * ID, group-ID are documented in :doc:`compute ` command * dipole = style name of this compute command -* charge-correction = *mass* or *geometry*, use COM or geometric center for charged chunk correction (optional) +* arg = *mass* or *geometry* = use COM or geometric center for charged chunk correction (optional) Examples """""""" @@ -43,7 +43,7 @@ and per-atom dipole moments, if present, contribute to the computed dipole. :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 + 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. Output info @@ -54,8 +54,9 @@ the computed dipole moment and a global vector of length 3 with the dipole vector. See the :doc:`Howto output ` page for an overview of LAMMPS output options. -The computed values are "intensive". The array values will be in -dipole units, i.e. charge units times distance :doc:`units `. +The computed values are "intensive." The array values will be in +dipole units (i.e., charge :doc:`units ` times distance +:doc:`units `). Restrictions """""""""""" diff --git a/doc/src/compute_dipole_chunk.rst b/doc/src/compute_dipole_chunk.rst index fc1e8d7709..24e6442a63 100644 --- a/doc/src/compute_dipole_chunk.rst +++ b/doc/src/compute_dipole_chunk.rst @@ -6,14 +6,14 @@ compute dipole/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS - compute ID group-ID dipole/chunk chunkID charge-correction + compute ID group-ID dipole/chunk chunkID arg * ID, group-ID are documented in :doc:`compute ` command * dipole/chunk = style name of this compute command * chunkID = ID of :doc:`compute chunk/atom ` command -* charge-correction = *mass* or *geometry*, use COM or geometric center for charged chunk correction (optional) +* arg = *mass* or *geometry* = use COM or geometric center for charged chunk correction (optional) Examples """""""" @@ -38,8 +38,8 @@ or atoms in a spatial bin. See the :doc:`compute chunk/atom 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 x,y,z coordinates of the dipole vector and -the total dipole moment for each chunk, which includes all effects due +This compute calculates the :math:`(x,y,z)` coordinates of the dipole vector +and the total dipole moment for each chunk, which includes all effects due to atoms passing through periodic boundaries. For chunks with a net charge the resulting dipole is made position independent by subtracting the position vector of the center of mass or geometric center times the @@ -62,7 +62,7 @@ chunk IDs. "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 + (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 com/chunk @@ -80,14 +80,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 -the x,y,z dipole vector components and the total dipole of each +chunk/atom ` command. The number of columns is 4 for +the :math:`(x,y,z)` dipole vector components and the total dipole of 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. -The array values are "intensive". The array values will be in -dipole units, i.e. charge units times distance :doc:`units `. +The array values are "intensive." The array values will be in +dipole units (i.e., charge :doc:`units ` times distance +:doc:`units `). Restrictions """""""""""" diff --git a/doc/src/compute_displace_atom.rst b/doc/src/compute_displace_atom.rst index 688e73d914..fc063cea50 100644 --- a/doc/src/compute_displace_atom.rst +++ b/doc/src/compute_displace_atom.rst @@ -6,7 +6,7 @@ compute displace/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID displace/atom @@ -35,9 +35,9 @@ atom in the group from its original (reference) coordinates, including all effects due to atoms passing through periodic boundaries. A vector of four quantities per atom is calculated by this compute. -The first 3 elements of the vector are the dx,dy,dz displacements. -The fourth component is the total displacement, i.e. sqrt(dx\*dx + dy\*dy + -dz\*dz). +The first three elements of the vector are the :math:`(dx,dy,dz)` +displacements. The fourth component is the total displacement +(i.e., :math:`\sqrt{dx^2 + dy^2 + dz^2}`). The displacement of an atom is from its original position at the time the compute command was issued. The value of the displacement will be @@ -50,7 +50,7 @@ the compute command was issued. The value of the displacement will be ` 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 + can reset the image flags (e.g., to 0) before invoking this compute by using the :doc:`set image ` command. .. note:: @@ -60,7 +60,7 @@ the compute command was issued. The value of the displacement will be you should use the same ID for this compute, as in the original run. This is so that the fix this compute creates to store per-atom quantities will also have the same ID, and thus be initialized - correctly with time=0 atom coordinates from the restart file. + correctly with time = 0 atom coordinates from the restart file. ---------- @@ -95,14 +95,15 @@ something like the following commands: refresh c_dsp delay 100 The :doc:`dump_modify thresh ` command will only output -atoms that have displaced more than 0.6 Angstroms on each snapshot -(assuming metal units). The dump_modify *refresh* option triggers a +atoms that have displaced more than :math:`0.6~\mathrm{\mathring A}` on each +snapshot (assuming metal units). The dump_modify *refresh* option triggers a call to this compute at the end of every dump. -The *refresh* argument for this compute is the ID of an :doc:`atom-style variable ` which calculates a Boolean value (0 or 1) +The *refresh* argument for this compute is the ID of an +:doc:`atom-style variable ` which calculates a Boolean value (0 or 1) based on the same criterion used by dump_modify thresh. This compute -evaluates the atom-style variable. For each atom that returns 1 -(true), the original (reference) coordinates of the atom (stored by +evaluates the atom-style variable. For each atom that returns 1 (true), +the original (reference) coordinates of the atom (stored by this compute) are updated. The effect of these commands is that a particular atom will only be @@ -125,8 +126,8 @@ would be empty. Output info """"""""""" -This compute calculates a per-atom array with 4 columns, which can be -accessed by indices 1-4 by any command that uses per-atom values from +This compute calculates a per-atom array with four columns, which can be +accessed by indices 1--4 by any command that uses per-atom 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_dpd.rst b/doc/src/compute_dpd.rst index bc6e1d2321..16fa9279ff 100644 --- a/doc/src/compute_dpd.rst +++ b/doc/src/compute_dpd.rst @@ -6,7 +6,7 @@ compute dpd command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID dpd @@ -24,9 +24,9 @@ Description """"""""""" Define a computation that accumulates the total internal conductive -energy (:math:`U^{cond}`), the total internal mechanical energy -(:math:`U^{mech}`), the total chemical energy (:math:`U^{chem}`) -and the *harmonic* average of the internal temperature (:math:`\theta_{avg}`) +energy (:math:`U^{\text{cond}}`), the total internal mechanical energy +(:math:`U^{\text{mech}}`), the total chemical energy (:math:`U^\text{chem}`) +and the *harmonic* average of the internal temperature (:math:`\theta_\text{avg}`) for the entire system of particles. See the :doc:`compute dpd/atom ` command if you want per-particle internal energies and internal temperatures. @@ -36,22 +36,24 @@ relations: .. math:: - U^{cond} = & \displaystyle\sum_{i=1}^{N} u_{i}^{cond} \\ - U^{mech} = & \displaystyle\sum_{i=1}^{N} u_{i}^{mech} \\ - U^{chem} = & \displaystyle\sum_{i=1}^{N} u_{i}^{chem} \\ - U = & \displaystyle\sum_{i=1}^{N} (u_{i}^{cond} + u_{i}^{mech} + u_{i}^{chem}) \\ - \theta_{avg} = & (\frac{1}{N}\displaystyle\sum_{i=1}^{N} \frac{1}{\theta_{i}})^{-1} \\ + U^\text{cond} = & \sum_{i=1}^{N} u_{i}^\text{cond} \\ + U^\text{mech} = & \sum_{i=1}^{N} u_{i}^\text{mech} \\ + U^\text{chem} = & \sum_{i=1}^{N} u_{i}^\text{chem} \\ + U = & \sum_{i=1}^{N} (u_{i}^\text{cond} + + u_{i}^\text{mech} + u_{i}^\text{chem}) \\ + \theta_{avg} = & \biggl(\frac{1}{N}\sum_{i=1}^{N} + \frac{1}{\theta_{i}}\biggr)^{-1} \\ -where :math:`N` is the number of particles in the system +where :math:`N` is the number of particles in the system. ---------- Output info """"""""""" -This compute calculates a global vector of length 5 (:math:`U^{cond}`, -:math:`U^{mech}`, :math:`U^{chem}`, :math:`\theta_{avg}`, :math:`N`), -which can be accessed by indices 1-5. +This compute calculates a global vector of length 5 (:math:`U^\text{cond}`, +:math:`U^\text{mech}`, :math:`U^\text{chem}`, :math:`\theta_\text{avg}`, +:math:`N`), which can be accessed by indices 1 through 5. See the :doc:`Howto output ` page for an overview of LAMMPS output options. @@ -61,7 +63,8 @@ Restrictions """""""""""" This command is part of the DPD-REACT package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +LAMMPS was built with that package. +See the :doc:`Build package ` page for more info. This command also requires use of the :doc:`atom_style dpd ` command. diff --git a/doc/src/compute_dpd_atom.rst b/doc/src/compute_dpd_atom.rst index 6104c4a273..7b38b8ff4f 100644 --- a/doc/src/compute_dpd_atom.rst +++ b/doc/src/compute_dpd_atom.rst @@ -6,7 +6,7 @@ compute dpd/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID dpd/atom @@ -23,29 +23,28 @@ Examples Description """"""""""" -Define a computation that accesses the per-particle internal -conductive energy (:math:`u^{cond}`), internal mechanical -energy (:math:`u^{mech}`), internal chemical energy (:math:`u^{chem}`) -and internal temperatures (:math:`\theta`) for each particle in a group. +Define a computation that accesses the per-particle internal conductive energy +(:math:`u^\text{cond}`), internal mechanical energy (:math:`u^\text{mech}`), +internal chemical energy (:math:`u^\text{chem}`) and internal temperatures +(:math:`\theta`) for each particle in a group. See the :doc:`compute dpd ` command if you want the total internal conductive energy, the total internal mechanical energy, the -total chemical energy and -average internal temperature of the entire system or group of dpd -particles. +total chemical energy and average internal temperature of the entire system or +group of dpd particles. Output info """"""""""" -This compute calculates a per-particle array with 4 columns (:math:`u^{cond}`, -:math:`u^{mech}`, :math:`u^{chem}`, :math:`\theta`), which can be accessed -by indices 1-4 by any +This compute calculates a per-particle array with four columns +(:math:`u^\text{cond}`, :math:`u^\text{mech}`, :math:`u^\text{chem}`, +:math:`\theta`), which can be accessed by indices 1--4 by any command that uses per-particle values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. -The per-particle array values will be in energy (:math:`u^{cond}`, -:math:`u^{mech}`, :math:`u^{chem}`) -and temperature (:math:`theta`) :doc:`units `. +The per-particle array values will be in energy (:math:`u^\text{cond}`, +:math:`u^\text{mech}`, :math:`u^\text{chem}`) +and temperature (:math:`\theta`) :doc:`units `. Restrictions """""""""""" diff --git a/doc/src/compute_edpd_temp_atom.rst b/doc/src/compute_edpd_temp_atom.rst index 3568a6364f..d376511ec0 100644 --- a/doc/src/compute_edpd_temp_atom.rst +++ b/doc/src/compute_edpd_temp_atom.rst @@ -6,7 +6,7 @@ compute edpd/temp/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID edpd/temp/atom diff --git a/doc/src/compute_efield_atom.rst b/doc/src/compute_efield_atom.rst index a3d2cb888d..1e63264b2a 100644 --- a/doc/src/compute_efield_atom.rst +++ b/doc/src/compute_efield_atom.rst @@ -6,12 +6,19 @@ compute efield/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS - compute ID group-ID efield/atom + compute ID group-ID efield/atom keyword val * ID, group-ID are documented in :doc:`compute ` command * efield/atom = style name of this compute command +* zero or more keyword/value pairs may be appended +* keyword = *pair* or *kspace* + + .. parsed-literal:: + + *pair* args = *yes* or *no* + *kspace* args = *yes* or *no* Examples """""""" @@ -23,10 +30,10 @@ Examples Used in input scripts: - .. parsed-literal:: +.. parsed-literal:: - examples/PACKAGES/dielectric/in.confined - examples/PACKAGES/dielectric/in.nopbc + examples/PACKAGES/dielectric/in.confined + examples/PACKAGES/dielectric/in.nopbc Description """"""""""" diff --git a/doc/src/compute_entropy_atom.rst b/doc/src/compute_entropy_atom.rst index e3d585dfde..78f784ff75 100644 --- a/doc/src/compute_entropy_atom.rst +++ b/doc/src/compute_entropy_atom.rst @@ -6,24 +6,23 @@ compute entropy/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID entropy/atom sigma cutoff keyword value ... * ID, group-ID are documented in :doc:`compute ` command * entropy/atom = style name of this compute command -* sigma = width of gaussians used in the g(r) smoothing -* cutoff = cutoff for the g(r) calculation +* sigma = width of Gaussians used in the :math:`g(r)` smoothing +* cutoff = cutoff for the :math:`g(r)` calculation * one or more keyword/value pairs may be appended .. parsed-literal:: keyword = *avg* or *local* - *avg* values = *yes* or *no* cutoff2 - *yes* = average the pair entropy over neighbors - *no* = do not average the pair entropy over neighbors + *avg* args = neigh cutoff2 + neigh value = *yes* or *no* = whether to average the pair entropy over neighbors cutoff2 = cutoff for the averaging over neighbors - *local* values = *yes* or *no* = use the local density around each atom to normalize the g(r) + *local* arg = *yes* or *no* = use the local density around each atom to normalize the g(r) Examples """""""" @@ -53,31 +52,32 @@ This parameter for atom i is computed using the following formula from s_S^i=-2\pi\rho k_B \int\limits_0^{r_m} \left [ g(r) \ln g(r) - g(r) + 1 \right ] r^2 dr -where r is a distance, g(r) is the radial distribution function of atom -i and rho is the density of the system. The g(r) computed for each -atom i can be noisy and therefore it is smoothed using: +where :math:`r` is a distance, :math:`g(r)` is the radial distribution function +of atom :math:`i`, and :math:`\rho` is the density of the system. +The :math:`g(r)` computed for each atom :math:`i` can be noisy and therefore it +is smoothed using .. math:: g_m^i(r) = \frac{1}{4 \pi \rho r^2} \sum\limits_{j} \frac{1}{\sqrt{2 \pi \sigma^2}} e^{-(r-r_{ij})^2/(2\sigma^2)} -where the sum in j goes through the neighbors of atom i, and :math:`\sigma` -is a parameter to control the smoothing. +where the sum over :math:`j` goes through the neighbors of atom :math:`i` and +:math:`\sigma` is a parameter to control the smoothing. The input parameters are *sigma* the smoothing parameter :math:`\sigma`, -and the *cutoff* for the calculation of g(r). +and the *cutoff* for the calculation of :math:`g(r)`. If the keyword *avg* has the setting *yes*, then this compute also -averages the parameter over the neighbors of atom i according to: +averages the parameter over the neighbors of atom :math:`i` according to .. math:: - \left< s_S^i \right> = \frac{\sum_j s_S^j + s_S^i}{N + 1} + \left< s_S^i \right> = \frac{\sum_j s_S^j + s_S^i}{N + 1}, -where the sum j goes over the neighbors of atom i and N is the number -of neighbors. This procedure provides a sharper distinction between -order and disorder environments. In this case the input parameter -*cutoff2* is the cutoff for the averaging over the neighbors and +where the sum over :math:`j` goes over the neighbors of atom :math:`i` and +:math:`N` is the number of neighbors. This procedure provides a sharper +distinction between order and disorder environments. In this case the input +parameter *cutoff2* is the cutoff for the averaging over the neighbors and must also be specified. If the *avg yes* option is used, the effective cutoff of the neighbor @@ -90,14 +90,14 @@ to increase the skin of the neighbor list with: See :doc:`neighbor ` for details. -If the *local yes* option is used, the g(r) is normalized by the +If the *local yes* option is used, the :math:`g(r)` is normalized by the local density around each atom, that is to say the density around each atom is the number of neighbors within the neighbor list cutoff divided 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 Angstroms), +constant :math:`4.05~\mathrm{\mathring A}`), .. parsed-literal:: @@ -114,7 +114,8 @@ Output info By default, this compute calculates the pair entropy value for each atom as a per-atom vector, which can be accessed by any command that -uses per-atom values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output +uses per-atom values from a compute as input. See the +:doc:`Howto output ` page for an overview of LAMMPS output options. The pair entropy values have units of the Boltzmann constant. They are diff --git a/doc/src/compute_erotate_asphere.rst b/doc/src/compute_erotate_asphere.rst index 2b4edc8017..44415c63cc 100644 --- a/doc/src/compute_erotate_asphere.rst +++ b/doc/src/compute_erotate_asphere.rst @@ -6,7 +6,7 @@ compute erotate/asphere command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID erotate/asphere @@ -30,9 +30,9 @@ ellipsoids, or line segments, or triangles. See the for descriptions of these options. For all 3 types of particles, the rotational kinetic energy is -computed as 1/2 I w\^2, where I is the inertia tensor for the -aspherical particle and w is its angular velocity, which is computed -from its angular momentum if needed. +computed as :math:`\frac12 I \omega^2`, where :math:`I` is the inertia tensor +for the aspherical particle and :math:`\omega` is its angular velocity, which +is computed from its angular momentum if needed. .. note:: @@ -48,7 +48,7 @@ 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 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 @@ -65,7 +65,7 @@ This compute requires that triangular particles atoms store a size and shape and quaternion orientation and angular momentum as defined by the :doc:`atom_style tri ` command. -All particles in the group must be finite-size. They cannot be point +All particles in the group must be of finite size. They cannot be point particles. Related commands diff --git a/doc/src/compute_erotate_rigid.rst b/doc/src/compute_erotate_rigid.rst index acbcf5cb0c..1e03a2316c 100644 --- a/doc/src/compute_erotate_rigid.rst +++ b/doc/src/compute_erotate_rigid.rst @@ -6,7 +6,7 @@ compute erotate/rigid command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID erotate/rigid fix-ID @@ -25,18 +25,20 @@ Description """"""""""" Define a computation that calculates the rotational kinetic energy of -a collection of rigid bodies, as defined by one of the :doc:`fix rigid ` command variants. +a collection of rigid bodies, as defined by one of the +:doc:`fix rigid ` command variants. -The rotational energy of each rigid body is computed as 1/2 I Wbody\^2, -where I is the inertia tensor for the rigid body, and Wbody is its -angular velocity vector. Both I and Wbody are in the frame of -reference of the rigid body, i.e. I is diagonalized. +The rotational energy of each rigid body is computed as +:math:`\frac12 I \omega_\text{body}^2`, +where :math:`I` is the inertia tensor for the rigid body and +:math:`\omega_\text{body}` is its angular velocity vector. +Both :math:`I` and :math:`\omega_\text{body}` are in the frame of +reference of the rigid body (i.e., :math:`I` is diagonal). 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 compute command is ignored. The rotational energy of all the rigid -bodies defined by the fix rigid command in included in the -calculation. +bodies defined by the fix rigid command in included in the calculation. Output info """"""""""" @@ -46,14 +48,15 @@ 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 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 """""""""""" This compute is part of the RIGID package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +LAMMPS was built with that package. See the +:doc:`Build package ` page for more info. Related commands """""""""""""""" diff --git a/doc/src/compute_erotate_sphere.rst b/doc/src/compute_erotate_sphere.rst index 6890f18212..28b0052b89 100644 --- a/doc/src/compute_erotate_sphere.rst +++ b/doc/src/compute_erotate_sphere.rst @@ -6,7 +6,7 @@ compute erotate/sphere command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID erotate/sphere @@ -26,8 +26,9 @@ Description Define a computation that calculates the rotational kinetic energy of a group of spherical particles. -The rotational energy is computed as 1/2 I w\^2, where I is the moment -of inertia for a sphere and w is the particle's angular velocity. +The rotational energy is computed as :math:`\frac12 I \omega^2`, +where :math:`I` is the moment of inertia for a sphere and :math:`\omega` +is the particle's angular velocity. .. note:: @@ -43,7 +44,7 @@ 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 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_erotate_sphere_atom.rst b/doc/src/compute_erotate_sphere_atom.rst index 76025b36f7..611cd83c01 100644 --- a/doc/src/compute_erotate_sphere_atom.rst +++ b/doc/src/compute_erotate_sphere_atom.rst @@ -6,7 +6,7 @@ compute erotate/sphere/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID erotate/sphere/atom @@ -26,8 +26,9 @@ Description Define a computation that calculates the rotational kinetic energy for each particle in a group. -The rotational energy is computed as 1/2 I w\^2, where I is the moment -of inertia for a sphere and w is the particle's angular velocity. +The rotational energy is computed as :math:`\frac12 I \omega^2`, where +:math:`I` is the moment of inertia for a sphere and :math:`\omega` is the +particle's angular velocity. .. note:: @@ -36,8 +37,7 @@ of inertia for a sphere and w is the particle's angular velocity. as in 3d. The value of the rotational kinetic energy will be 0.0 for atoms not -in the specified compute group or for point particles with a radius = -0.0. +in the specified compute group or for point particles with a radius of 0.0. Output info """"""""""" diff --git a/doc/src/compute_event_displace.rst b/doc/src/compute_event_displace.rst index 6cf04e83ba..f8911e1224 100644 --- a/doc/src/compute_event_displace.rst +++ b/doc/src/compute_event_displace.rst @@ -6,7 +6,7 @@ compute event/displace command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID event/displace threshold @@ -27,10 +27,9 @@ Description Define a computation that flags an "event" if any particle in the group has moved a distance greater than the specified threshold distance when compared to a previously stored reference state -(i.e. the previous event). This compute is typically used in +(i.e., the previous event). This compute is typically used in conjunction with the :doc:`prd ` and :doc:`tad ` commands, -to detect if a transition -to a new minimum energy basin has occurred. +to detect if a transition to a new minimum energy basin has occurred. This value calculated by the compute is equal to 0 if no particle has moved far enough, and equal to 1 if one or more particles have moved @@ -51,7 +50,7 @@ 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 options. -The scalar value calculated by this compute is "intensive". The +The scalar value calculated by this compute is "intensive." The scalar value will be a 0 or 1 as explained above. Restrictions diff --git a/doc/src/compute_fabric.rst b/doc/src/compute_fabric.rst index 3ded3d7adc..f1a5d3d7f9 100644 --- a/doc/src/compute_fabric.rst +++ b/doc/src/compute_fabric.rst @@ -6,9 +6,9 @@ compute fabric command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS - compute ID group-ID fabric cutoff attribute1 attribute2 ... keyword values ... + compute ID group-ID fabric cutoff attribute ... keyword values ... * ID, group-ID are documented in :doc:`compute ` command * fabric = style name of this compute command @@ -20,6 +20,7 @@ Syntax *radius* = cutoffs determined based on atom diameters (atom style sphere) * one or more attributes may be appended +* attribute = *contact* or *branch* or *force/normal* or *force/tangential* .. parsed-literal:: @@ -63,7 +64,7 @@ tangential force tensor. The contact tensor is calculated as .. math:: - C_{ab} = \frac{15}{2} (\phi_{ab} - \mathrm{tr}(\phi) \delta_{ab}) + C_{ab} = \frac{15}{2} (\phi_{ab} - \mathrm{Tr}(\phi) \delta_{ab}) where :math:`a` and :math:`b` are the :math:`x`, :math:`y`, :math:`z` directions, :math:`\delta_{ab}` is the Kronecker delta function, and @@ -75,13 +76,14 @@ the tensor :math:`\phi` is defined as where :math:`n` loops over the :math:`N_p` pair interactions in the simulation, :math:`r_{a}` is the :math:`a` component of the radial vector between the -two pairwise interacting particles, and :math:`r` is the magnitude of the radial vector. +two pairwise interacting particles, and :math:`r` is the magnitude of the +radial vector. The branch tensor is calculated as .. math:: - B_{ab} = \frac{15}{6 \mathrm{tr}(D)} (D_{ab} - \mathrm{tr}(D) \delta_{ab}) + B_{ab} = \frac{15}{6 \mathrm{Tr}(D)} (D_{ab} - \mathrm{Tr}(D) \delta_{ab}) where the tensor :math:`D` is defined as @@ -91,14 +93,15 @@ where the tensor :math:`D` is defined as \frac{1}{N_c (r^2 + C_{cd} r_c r_d)} \frac{r_{a} r_{b}}{r} -where :math:`N_c` is the total number of contacts in the system and the subscripts -:math:`c` and :math:`d` indices are summed according to Einstein notation. +where :math:`N_c` is the total number of contacts in the system and the +subscripts :math:`c` and :math:`d` indices are summed according to Einstein +notation. The normal force fabric tensor is calculated as .. math:: - F^n_{ab} = \frac{15}{6 \mathrm{tr}(N)} (N_{ab} - \mathrm{tr}(N) \delta_{ab}) + F^n_{ab} = \frac{15}{6\, \mathrm{Tr}(N)} (N_{ab} - \mathrm{Tr}(N) \delta_{ab}) where the tensor :math:`N` is defined as @@ -116,7 +119,7 @@ as .. math:: - F^t_{ab} = \frac{15}{9 \mathrm{tr}(N)} (T_{ab} - \mathrm{tr}(T) \delta_{ab}) + F^t_{ab} = \frac{15}{9\, \mathrm{Tr}(N)} (T_{ab} - \mathrm{Tr}(T) \delta_{ab}) where the tensor :math:`T` is defined as @@ -133,21 +136,23 @@ Interactions between two atoms are only included in calculations if the atom typ are in the two lists. Each list consists of a series of type ranges separated by commas. The range can be specified as a single numeric value, or a wildcard asterisk can be used to specify a range -of values. This takes the form "\*" or "\*n" or "n\*" or "m\*n". For -example, if M = the number of atom types, then an asterisk with no numeric -values means all types from 1 to M. A leading asterisk means all types -from 1 to n (inclusive). A trailing asterisk means all types from n to M -(inclusive). A middle asterisk means all types from m to n (inclusive). -Multiple *type/include* keywords may be added. +of values. This takes the form "\*" or "\*n" or "m\*" or "m\*n". For +example, if :math:`M` is the number of atom types, then an asterisk with no +numeric values means all types from 1 to :math:`M`. A leading asterisk means +all types from 1 to n (inclusive). A trailing asterisk means all types from +m to :math:`M` (inclusive). A middle asterisk means all types from m to n +(inclusive). Multiple *type/include* keywords may be added. Output info """"""""""" -This compute calculates a local vector of doubles and a scalar. The vector stores the -unique components of the first requested tensor in the order xx, yy, zz, xy, xz, yz -followed by the same components for all subsequent tensors. The length of the vector -is therefore six times the number of requested tensors. The scalar output is the -number of pairwise interactions included in the calculation of the fabric tensor. +This compute calculates a local vector of doubles and a scalar. The vector +stores the unique components of the first requested tensor in the order +:math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`, :math:`yz` +followed by the same components for all subsequent tensors. +The length of the vector is therefore six times the number of requested +tensors. The scalar output is the number of pairwise interactions included in +the calculation of the fabric tensor. Restrictions """""""""""" @@ -164,7 +169,7 @@ following fixes which add rigid-body constraints: :doc:`fix shake `, :doc:`fix rattle `, :doc:`fix rigid `, :doc:`fix rigid/small `. It does not support granular pair styles that extend beyond the contact of atomic radii -(e.g. JKR and DMT). +(e.g., JKR and DMT). Related commands """""""""""""""" diff --git a/doc/src/compute_fep.rst b/doc/src/compute_fep.rst index 5275716c45..e2de8d405b 100644 --- a/doc/src/compute_fep.rst +++ b/doc/src/compute_fep.rst @@ -6,7 +6,7 @@ compute fep command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID fep temp attribute args ... keyword value ... @@ -19,12 +19,12 @@ Syntax .. parsed-literal:: *pair* args = pstyle pparam I J v_delta - pstyle = pair style name, e.g. lj/cut + pstyle = pair style name (e.g., *lj/cut*) pparam = parameter to perturb I,J = type pair(s) to set parameter for v_delta = variable with perturbation to apply (in the units of the parameter) *atom* args = aparam I v_delta - aparam = parameter to perturb + aparam = *charge* = parameter to perturb I = type to set parameter for v_delta = variable with perturbation to apply (in the units of the parameter) @@ -37,8 +37,8 @@ Syntax *no* = ignore tail correction to pair energies (usually small in fep) *yes* = include tail correction to pair energies *volume* value = *no* or *yes* - *no* = ignore volume changes (e.g. in *NVE* or *NVT* trajectories) - *yes* = include volume changes (e.g. in *NpT* trajectories) + *no* = ignore volume changes (e.g., in *NVE* or *NVT* trajectories) + *yes* = include volume changes (e.g., in *NPT* trajectories) Examples """""""" @@ -84,7 +84,7 @@ It is possible but not necessary that the coupling parameter (or a function thereof) appears as a multiplication factor of the potential energy. Therefore, this compute can apply perturbations to interaction parameters that are not directly proportional to the potential energy -(e.g. :math:`\sigma` in Lennard-Jones potentials). +(e.g., :math:`\sigma` in Lennard-Jones potentials). This command can be combined with :doc:`fix adapt ` to perform multistage free-energy perturbation calculations along @@ -92,9 +92,9 @@ stepwise alchemical transformations during a simulation run: .. math:: - \Delta_0^1 A = \sum_{i=0}^{n-1} \Delta_{\lambda_i}^{\lambda_{i+1}} A = - kT + \Delta_0^1 A = \sum_{i=0}^{n-1} \Delta_{\lambda_i}^{\lambda_{i+1}} A = - k_B T \sum_{i=0}^{n-1} \ln \left< \exp \left( - \frac{U(\lambda_{i+1}) - - U(\lambda_i)}{kT} \right) \right>_{\lambda_i} + U(\lambda_i)}{k_B T} \right) \right>_{\lambda_i} This compute is suitable for the finite-difference thermodynamic integration (FDTI) method :ref:`(Mezei) `, which is based on an @@ -107,7 +107,8 @@ perturbation method using a very small :math:`\delta`: A(\lambda)}{\partial\lambda} \right)_\lambda \mathrm{d}\lambda \approx \sum_{i=0}^{n-1} w_i \frac{A(\lambda_{i} + \delta) - A(\lambda_i)}{\delta} -where :math:`w_i` are weights of a numerical quadrature. The :doc:`fix adapt ` command can be used to define the stages of +where :math:`w_i` are weights of a numerical quadrature. The +:doc:`fix adapt ` command can be used to define the stages of :math:`\lambda` at which the derivative is calculated and averaged. The compute fep calculates the exponential Boltzmann term and also the @@ -125,14 +126,14 @@ the derivative of the potential energy with respect to :math:`\lambda`: Another technique to calculate free energy differences is the acceptance ratio method :ref:`(Bennet) `, which can be implemented -by calculating the potential energy differences with :math:`\delta` = 1.0 on +by calculating the potential energy differences with :math:`\delta = 1.0` on both the forward and reverse routes: .. math:: - \left< \frac{1}{1 + \exp\left[\left(U_1 - U_0 - \Delta_0^1A \right) /kT + \left< \frac{1}{1 + \exp\left[\left(U_1 - U_0 - \Delta_0^1A \right) /k_B T \right]} \right>_0 = \left< \frac{1}{1 + \exp\left[\left(U_0 - U_1 + - \Delta_0^1A \right) /kT \right]} \right>_1 + \Delta_0^1A \right) /k_B T \right]} \right>_1 The value of the free energy difference is determined by numerical root finding to establish the equality. @@ -226,17 +227,17 @@ the pair\_\*.cpp file associated with the potential. Similar to the :doc:`pair_coeff ` command, I and J can be specified in one of two ways. Explicit numeric values can be used for -each, as in the first example above. I <= J is required. LAMMPS sets +each, as in the first example above. I :math:`\le` J is required. LAMMPS sets the coefficients for the symmetric J,I interaction to the same values. A wild-card asterisk can be used in place of or in conjunction with the I,J arguments to set the coefficients for multiple pairs 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 +atom 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 N (inclusive). A middle asterisk means all types from m to n -(inclusive). Note that only type pairs with I <= J are considered; if -asterisks imply type pairs where J < I, they are ignored. +(inclusive). Note that only type pairs with I :math:`\le` J are considered; if +asterisks imply type pairs where J :math:`<` I, they are ignored. If :doc:`pair_style hybrid or hybrid/overlay ` is being used, then the *pstyle* will be a sub-style name. You must specify @@ -275,8 +276,8 @@ trajectories during which the volume fluctuates or changes :ref:`(Allen and Tild .. math:: - \Delta_0^1 A = - kT \sum_{i=0}^{n-1} \ln \frac{\left< V \exp \left( - - \frac{U(\lambda_{i+1}) - U(\lambda_i)}{kT} \right) + \Delta_0^1 A = - k_B T \sum_{i=0}^{n-1} \ln \frac{\left< V \exp \left( - + \frac{U(\lambda_{i+1}) - U(\lambda_i)}{k_B T} \right) \right>_{\lambda_i}}{\left< V \right>_{\lambda_i}} ---------- @@ -286,8 +287,8 @@ Output info This compute calculates a global vector of length 3 which contains the energy difference ( :math:`U_1-U_0` ) as c_ID[1], the -Boltzmann factor :math:`\exp(-(U_1-U_0)/kT)`, or -:math:`V \exp(-(U_1-U_0)/kT)`, as c_ID[2] and the +Boltzmann factor :math:`\exp(-(U_1-U_0)/k_B T)`, or +:math:`V \exp(-(U_1-U_0)/k_B T)`, as c_ID[2] and the volume of the simulation box :math:`V` as c_ID[3]. :math:`U_1` is the pair potential energy obtained with the perturbed parameters and :math:`U_0` is the pair potential energy obtained with the @@ -298,7 +299,7 @@ These output results can be used by any command that uses a global scalar or vector from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output options. For example, the computed values can be averaged using :doc:`fix ave/time `. -The values calculated by this compute are "extensive". +The values calculated by this compute are "extensive." Restrictions """""""""""" diff --git a/doc/src/compute_fep_ta.rst b/doc/src/compute_fep_ta.rst index eeb4a10915..1fe89194ca 100644 --- a/doc/src/compute_fep_ta.rst +++ b/doc/src/compute_fep_ta.rst @@ -6,7 +6,7 @@ compute fep/ta command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID fep/ta temp plane scale_factor keyword value ... @@ -20,9 +20,9 @@ Syntax .. parsed-literal:: - *tail* value = *no* or *yes* - *no* = ignore tail correction to pair energies (usually small in fep) - *yes* = include tail correction to pair energies + *tail* value = *no* or *yes* + *no* = ignore tail correction to pair energies (usually small in fep) + *yes* = include tail correction to pair energies Examples """""""" @@ -42,11 +42,12 @@ in a single simulation: .. math:: \gamma = \lim_{\Delta \mathcal{A} \to 0} \left( \frac{\Delta A_{0 \to 1 }}{\Delta \mathcal{A}}\right)_{N,V,T} - = - \frac{kT}{\Delta \mathcal{A}} \ln \left< \exp(-(U_1 - U_0)/kT) \right>_0 + = - \frac{k_B T}{\Delta \mathcal{A}} \ln \left\langle \exp\left(\frac{-(U_1 - U_0)}{k_B T}\right) \right\rangle_0 During the perturbation, both axes of *plane* are scaled by multiplying -:math:`\sqrt{scale\_factor}`, while the other axis divided by -*scale_factor* such that the overall volume of the system is maintained. +:math:`\sqrt{\mathrm{scale\_factor}}`, while the other axis divided by +:math:`\mathrm{scale\_factor}` such that the overall volume of the system is +maintained. The *tail* keyword controls the calculation of the tail correction to "van der Waals" pair energies beyond the cutoff, if this has been @@ -60,8 +61,8 @@ Output info """"""""""" This compute calculates a global vector of length 3 which contains the -energy difference ( :math:`U_1-U_0` ) as c_ID[1], the Boltzmann factor -:math:`\exp(-(U_1-U_0)/kT)`, as c_ID[2] and the change in the *plane* +energy difference :math:`(U_1-U_0)` as c_ID[1], the Boltzmann factor +:math:`\exp\bigl(-(U_1-U_0)/k_B T\bigr)`, as c_ID[2] and the change in the *plane* area :math:`\Delta \mathcal{A}` as c_ID[3]. :math:`U_1` is the potential energy of the perturbed state and :math:`U_0` is the potential energy of the reference state. The energies include kspace terms if these are 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_modify.rst b/doc/src/compute_modify.rst index a68f3c14e1..947a610b88 100644 --- a/doc/src/compute_modify.rst +++ b/doc/src/compute_modify.rst @@ -37,24 +37,27 @@ Description Modify one or more parameters of a previously defined compute. Not all compute styles support all parameters. -The *extra/dof* or *extra* keyword refers to how many -degrees-of-freedom are subtracted (typically from 3N) as a normalizing +The *extra/dof* or *extra* keyword refers to how many degrees of freedom are +subtracted (typically from :math:`3N`) as a normalizing factor in a temperature computation. Only computes that compute a -temperature use this option. The default is 2 or 3 for :doc:`2d or 3d systems ` which is a correction factor for an ensemble -of velocities with zero total linear momentum. For compute +temperature use this option. The default is 2 or 3 for +:doc:`2d or 3d systems `, which is a correction factor for an +ensemble of velocities with zero total linear momentum. For compute temp/partial, if one or more velocity components are excluded, the value used for *extra* is scaled accordingly. You can use a negative number for the *extra* parameter if you need to add degrees-of-freedom. See the :doc:`compute temp/asphere ` command for an example. The *dynamic/dof* or *dynamic* keyword determines whether the number -of atoms N in the compute group and their associated degrees of -freedom are re-computed each time a temperature is computed. Only +of atoms :math:`N` in the compute group and their associated degrees of +freedom (DOF) are re-computed each time a temperature is computed. Only compute styles that calculate a temperature use this option. By -default, N and their DOF are assumed to be constant. If you are -adding atoms or molecules to the system (see the :doc:`fix pour `, :doc:`fix deposit `, and :doc:`fix gcmc ` commands) or expect atoms or molecules to be lost -(e.g. due to exiting the simulation box or via :doc:`fix evaporate `), then this option should be used to -insure the temperature is correctly normalized. +default, :math:`N` and their DOF are assumed to be constant. If you are +adding atoms or molecules to the system (see the :doc:`fix pour `, +:doc:`fix deposit `, and :doc:`fix gcmc ` commands) or +expect atoms or molecules to be lost (e.g., due to exiting the simulation box +or via :doc:`fix evaporate `), then this option should be used +to ensure the temperature is correctly normalized. .. note:: @@ -75,4 +78,4 @@ Default """"""" The option defaults are extra/dof = 2 or 3 for 2d or 3d systems and -dynamic/dof = no. +dynamic/dof = *no*. 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..01535aa880 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..bcfec11f80 100644 --- a/doc/src/compute_pair_local.rst +++ b/doc/src/compute_pair_local.rst @@ -6,14 +6,14 @@ compute pair/local command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID pair/local value1 value2 ... keyword args ... * ID, group-ID are documented in :doc:`compute ` command * pair/local = style name of this compute command * one or more values may be appended -* value = *dist* or *dx* or *dy* or *dz* or *eng* or *force* or *fx* or *fy* or *fz* or *pN* +* value = *dist* or *dx* or *dy* or *dz* or *eng* or *force* or *fx* or *fy* or *fz* or *p1* or *p2* or ... .. parsed-literal:: @@ -22,7 +22,7 @@ Syntax *eng* = pairwise energy *force* = pairwise force *fx*,\ *fy*,\ *fz* = components of pairwise force - *pN* = pair style specific quantities for allowed N values + *p1*, *p2*, ... = pair style specific quantities for allowed N values * zero or more keyword/arg pairs may be appended * keyword = *cutoff* @@ -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 -example of ones that do are the :doc:`granular pair styles ` +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..c1a9e3d2ec 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,37 @@ 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 -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 -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 -shake ` command) may also contribute to the virial term. +below), :math:`k_B` is the Boltzmann constant, :math:`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 :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 +: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 +92,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 +128,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..6475a4b962 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..2ccc03cf8f 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/compute_reduce.rst b/doc/src/compute_reduce.rst index c2d85753db..b85b2b7dbb 100644 --- a/doc/src/compute_reduce.rst +++ b/doc/src/compute_reduce.rst @@ -10,7 +10,7 @@ compute reduce/region command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID style arg mode input1 input2 ... keyword args ... @@ -25,11 +25,11 @@ Syntax * mode = *sum* or *min* or *max* or *ave* or *sumsq* or *avesq* or *sumabs* or *aveabs* * one or more inputs can be listed -* input = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID[N], f_ID, f_ID[N], v_name +* input = *x* or *y* or *z* or *vx* or *vy* or *vz* or *fx* or *fy* or *fz* or c_ID or c_ID[N] or f_ID or f_ID[N] or v_name .. parsed-literal:: - x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force component) + *x*,\ *y*,\ *z*,\ *vx*,\ *vy*,\ *vz*,\ *fx*,\ *fy*,\ *fz* = atom attribute (position, velocity, force component) c_ID = per-atom or local vector calculated by a compute with ID c_ID[I] = Ith column of per-atom or local array calculated by a compute with ID, I can include wildcard (see below) f_ID = per-atom or local vector calculated by a fix with ID @@ -76,10 +76,10 @@ then divides by the number of values in the vector. The *sumsq* option sums the square of the values in the vector into a global total. The *avesq* setting does the same as *sumsq*, then divides the sum of squares by the number of values. The last two options can be -useful for calculating the variance of some quantity, e.g. variance = -sumsq - ave\^2. The *sumabs* option sums the absolute values in the -vector into a global total. The *aveabs* setting does the same as -*sumabs*, then divides the sum of absolute values by the number of +useful for calculating the variance of some quantity (e.g., variance = +sumsq :math:`-` ave\ :math:`^2`). The *sumabs* option sums the absolute +values in the vector into a global total. The *aveabs* setting does the same +as *sumabs*, then divides the sum of absolute values by the number of values. Each listed input is operated on independently. For per-atom inputs, @@ -97,20 +97,21 @@ component) or can be the result of a :doc:`compute ` or :doc:`fix ` or the evaluation of an atom-style :doc:`variable `. -Note that for values from a compute or fix, the bracketed index I can +Note that for values from a compute or fix, the bracketed index :math:`I` can be specified using a wildcard asterisk with the index to effectively -specify multiple values. This takes the form "\*" or "\*n" or "n\*" or -"m\*n". If N = the size of the vector (for *mode* = scalar) or the +specify multiple values. This takes the form "\*" or "\*n" 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 +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 n to N (inclusive). A middle asterisk +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 reduce commands are -equivalent, since the :doc:`compute stress/atom ` -command creates a per-atom array with 6 columns: +had been listed one by one. For example, the following two compute reduce +commands are equivalent, since the +:doc:`compute stress/atom ` command creates a per-atom +array with six columns: .. code-block:: LAMMPS @@ -121,12 +122,13 @@ command creates a per-atom array with 6 columns: ---------- -The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are -self-explanatory. Note that other atom attributes can be used as -inputs to this fix by using the :doc:`compute property/atom ` command and then specifying +The atom attribute values (*x*, *y*, *z*, *vx*, *vy*, *vz*, *fx*, *fy*, and +*fz*) are self-explanatory. Note that other atom attributes can be used as +inputs to this fix by using the +:doc:`compute property/atom ` command and then specifying an input value from that compute. -If a value begins with "c\_", a compute ID must follow which has been +If a value begins with "c\_," a compute ID must follow which has been previously defined in the input script. Computes can generate per-atom or local quantities. See the individual :doc:`compute ` page for details. If no bracketed integer @@ -134,10 +136,10 @@ 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 I can be specified with a wildcard asterisk +discussion above for how :math:`I` can be specified with a wildcard asterisk to effectively specify multiple values. -If a value begins with "f\_", a fix ID must follow which has been +If a value begins with "f\_," a fix ID must follow which has been previously defined in the input script. Fixes can generate per-atom or local quantities. See the individual :doc:`fix ` page for details. Note that some fixes only produce their values on certain @@ -145,27 +147,27 @@ timesteps, which must be compatible with when compute reduce references the values, else an error results. If no bracketed integer is appended, the vector calculated by the fix is used. If a bracketed integer is appended, the Ith column of the array calculated by the fix -is used. Users can also write code for their own fix style 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. +is used. Users can also write code for their own fix style and +:doc:`add them to LAMMPS `. See the discussion above for how +:math:`I` can be specified with a wildcard asterisk to effectively specify +multiple values. -If a value begins with "v\_", a variable name must follow which has +If a value begins with "v\_," a variable name must follow which has been previously defined in the input script. It must be an :doc:`atom-style variable `. Atom-style variables can reference thermodynamic keywords and various per-atom attributes, or invoke other computes, fixes, or variables when they are evaluated, so -this is a very general means of generating per-atom quantities to -reduce. +this is a very general means of generating per-atom quantities to reduce. ---------- If the *replace* keyword is used, two indices *vec1* and *vec2* are -specified, where each index ranges from 1 to the # of input values. +specified, where each index ranges from 1 to the number of input values. The replace keyword can only be used if the *mode* is *min* or *max*\ . It works as follows. A min/max is computed as usual on the *vec2* -input vector. The index N of that value within *vec2* is also stored. +input vector. The index :math:`N` of that value within *vec2* is also stored. Then, instead of performing a min/max on the *vec1* input vector, the -stored index is used to select the Nth element of the *vec1* vector. +stored index is used to select the :math:`N`\ th element of the *vec1* vector. Thus, for example, if you wish to use this compute to find the bond with maximum stretch, you can do it as follows: @@ -178,8 +180,10 @@ with maximum stretch, you can do it as follows: thermo_style custom step temp c_3[1] c_3[2] c_3[3] The first two input values in the compute reduce command are vectors -with the IDs of the 2 atoms in each bond, using the :doc:`compute property/local ` command. The last input -value is bond distance, using the :doc:`compute bond/local ` command. Instead of taking the +with the IDs of the 2 atoms in each bond, using the +:doc:`compute property/local ` command. The last input +value is bond distance, using the +:doc:`compute bond/local ` command. Instead of taking the max of the two atom ID vectors, which does not yield useful information in this context, the *replace* keywords will extract the atom IDs for the two atoms in the bond of maximum stretch. These atom @@ -192,10 +196,13 @@ value. If multiple inputs are specified, this compute produces a global vector of values, the length of which is equal to the number of inputs specified. -As discussed below, for the *sum*, *sumabs* and *sumsq* modes, the value(s) -produced by this compute are all "extensive", meaning their value +As discussed below, for the *sum*, *sumabs*, and *sumsq* modes, the value(s) +produced by this compute are all "extensive," meaning their value scales linearly with the number of atoms involved. If normalized -values are desired, this compute can be accessed by the :doc:`thermo_style custom ` command with :doc:`thermo_modify norm yes ` set as an option. Or it can be accessed by a +values are desired, this compute can be accessed by the +:doc:`thermo_style custom ` command with +:doc:`thermo_modify norm yes ` set as an option. +Or it can be accessed by a :doc:`variable ` that divides by the appropriate atom count. ---------- @@ -203,17 +210,17 @@ values are desired, this compute can be accessed by the :doc:`thermo_style custo Output info """"""""""" -This compute calculates a global scalar if a single input value is -specified or a global vector of length N where N is the number of -inputs, and which can be accessed by indices 1 to N. These values can +This compute calculates a global scalar if a single input value is specified +or a global vector of length :math:`N`, where :math:`N` is the number of +inputs, and which can be accessed by indices 1 to :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 ` doc page for an overview of LAMMPS output options. All the scalar or vector values calculated by this compute are -"intensive", except when the *sum*, *sumabs* or *sumsq* modes are used on +"intensive," except when the *sum*, *sumabs*, or *sumsq* modes are used on per-atom or local vectors, in which case the calculated values are -"extensive". +"extensive." The scalar or vector values will be in whatever :doc:`units ` the quantities being reduced are in. diff --git a/doc/src/compute_reduce_chunk.rst b/doc/src/compute_reduce_chunk.rst index 256ff15920..c988af276f 100644 --- a/doc/src/compute_reduce_chunk.rst +++ b/doc/src/compute_reduce_chunk.rst @@ -61,7 +61,7 @@ per-atom values for each chunk. Note that only atoms in the specified group contribute to the reduction operation. If the *chunkID* compute returns a 0 for the -chunk ID of an atom (i.e. the atom is not in a chunk defined by the +chunk ID of an atom (i.e., the atom is not in a chunk defined by the :doc:`compute chunk/atom ` command), that atom will also not contribute to the reduction operation. An input that is a compute or fix may define its own group which affects the quantities @@ -74,17 +74,18 @@ of an atom-style :doc:`variable `. Note that for 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 the +specify multiple values. This takes the form "\*" or "\*n" 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 +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 n to N (inclusive). A middle asterisk +asterisk means all indices from n 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 reduce/chunk -commands are equivalent, since the :doc:`compute property/chunk ` command creates a per-atom +had been listed one by one. For example, the following two compute reduce/chunk +commands are equivalent, since the +:doc:`compute property/chunk ` command creates a per-atom array with 3 columns: .. code-block:: LAMMPS @@ -101,13 +102,13 @@ The commands below can be added to the examples/in.micelle script. Imagine a collection of polymer chains or small molecules with hydrophobic end groups. All the hydrophobic (HP) atoms are assigned -to a group called "phobic". +to a group called "phobic." These commands will assign a unique cluster ID to all HP atoms within a specified distance of each other. A cluster will contain all HP -atoms in a single molecule, but also the HP atoms in nearby molecules, -e.g. molecules that have clumped to form a micelle due to the -attraction induced by the hydrophobicity. The output of the +atoms in a single molecule, but also the HP atoms in nearby molecules +(e.g., molecules that have clumped to form a micelle due to the +attraction induced by the hydrophobicity). The output of the chunk/reduce command will be a cluster ID per chunk (molecule). Molecules with the same cluster ID are in the same micelle. @@ -136,7 +137,7 @@ atoms of that atom's molecule belong to. The result from compute chunk/spread/atom can be used to define a new set of chunks, where all the atoms in all the molecules in the same -micelle are assigned to the same chunk, i.e. one chunk per micelle. +micelle are assigned to the same chunk (i.e., one chunk per micelle). .. code-block:: LAMMPS @@ -144,9 +145,8 @@ micelle are assigned to the same chunk, i.e. one chunk per micelle. Further analysis on a per-micelle basis can now be performed using any of the per-chunk computes listed on the :doc:`Howto chunk ` -doc page. E.g. count the number of atoms in each micelle, calculate -its center or mass, shape (moments of inertia), radius of gyration, -etc. +doc page (e.g., count the number of atoms in each micelle, calculate +its center or mass, shape/moments of inertia, and radius of gyration). .. code-block:: LAMMPS @@ -155,7 +155,7 @@ etc. Each snapshot in the tmp.micelle file will have one line per micelle with its count of atoms, plus a first line for a chunk with all the -solvent atoms. By the time 50000 steps have elapsed there are a +solvent atoms. By the time 50000 steps have elapsed, there are a handful of large micelles. ---------- diff --git a/doc/src/compute_rigid_local.rst b/doc/src/compute_rigid_local.rst index 6817f0ac1e..456fc57c38 100644 --- a/doc/src/compute_rigid_local.rst +++ b/doc/src/compute_rigid_local.rst @@ -108,7 +108,8 @@ The *mass* attribute is the total mass of the rigid body. There are two options for outputting the coordinates of the center of mass (COM) of the body. The *x*, *y*, *z* attributes write the COM -"unscaled", in the appropriate distance :doc:`units ` (Angstroms, +"unscaled", in the appropriate distance :doc:`units ` +(:math:`\mathrm{\mathring A}`, sigma, etc). Use *xu*, *yu*, *zu* if you want the COM "unwrapped" by the image flags for each body. Unwrapped means that if the body COM has passed through a periodic boundary one or more times, the value diff --git a/doc/src/compute_saed.rst b/doc/src/compute_saed.rst index 6704d8f0d6..1a746ab7b9 100644 --- a/doc/src/compute_saed.rst +++ b/doc/src/compute_saed.rst @@ -86,19 +86,20 @@ will defined using the *c* values for the spacing along each reciprocal lattice axis. Note that manual mapping of the reciprocal space mesh is good for comparing diffraction results from multiple simulations; however it can reduce the likelihood that Bragg reflections will be satisfied -unless small spacing parameters <0.05 Angstrom\^(-1) are implemented. -Meshes with manual spacing do not require a periodic boundary. +unless small spacing parameters (:math:`<0.05~\mathrm{\mathring A}^-1`) +are implemented. Meshes with manual spacing do not require a periodic +boundary. The limits of the reciprocal lattice mesh are determined by the use of the *Kmax*, *Zone*, and *dR_Ewald* parameters. The rectilinear mesh created about the origin of reciprocal space is terminated at the boundary of a sphere of radius *Kmax* centered at the origin. If -*Zone* parameters z1=z2=z3=0 are used, diffraction intensities are +*Zone* parameters *z1* = *z2* = *z3* = 0 are used, diffraction intensities are computed throughout the entire spherical volume - note this can greatly increase the cost of computation. Otherwise, *Zone* -parameters will denote the z1=h, z2=k, and z3=l (in a global since) -zone axis of an intersecting Ewald sphere. Diffraction intensities -will only be computed at the intersection of the reciprocal lattice +parameters will denote the :math:`z1=h`, :math:`z2=k`, and :math:`z3=\ell` +(in a global sense) zone axis of an intersecting Ewald sphere. Diffraction +intensities will only be computed at the intersection of the reciprocal lattice mesh and a *dR_Ewald* thick surface of the Ewald sphere. See the example 3D intensity data and the intersection of a [010] zone axis in the below image. diff --git a/doc/src/compute_stress_atom.rst b/doc/src/compute_stress_atom.rst index 2c8be0c05a..08f7e3032e 100644 --- a/doc/src/compute_stress_atom.rst +++ b/doc/src/compute_stress_atom.rst @@ -10,7 +10,7 @@ compute centroid/stress/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID style temp-ID keyword ... diff --git a/doc/src/compute_stress_mop.rst b/doc/src/compute_stress_mop.rst index d439e18d34..4ad2261bb0 100644 --- a/doc/src/compute_stress_mop.rst +++ b/doc/src/compute_stress_mop.rst @@ -10,7 +10,7 @@ compute stress/mop/profile command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID style dir args keywords ... @@ -28,6 +28,9 @@ Syntax origin = *lower* or *center* or *upper* or coordinate value (distance units) is the position of the first plane delta = value (distance units) is the distance between planes +Examples +"""""""" + .. code-block:: LAMMPS compute 1 all stress/mop x lower total @@ -49,7 +52,7 @@ components are computed in directions *dir*,\ *x*\ ; *dir*,\ *y*\ ; and *dir*,\ *z*\ ; where *dir* is the direction normal to the plane, while in compute *stress/mop/profile* the profile of the stress is computed. -Contrary to methods based on histograms of atomic stress (i.e. using +Contrary to methods based on histograms of atomic stress (i.e., using :doc:`compute stress/atom `), the method of planes is compatible with mechanical balance in heterogeneous systems and at interfaces :ref:`(Todd) `. @@ -57,9 +60,9 @@ interfaces :ref:`(Todd) `. The stress tensor is the sum of a kinetic term and a configurational term, which are given respectively by Eq. (21) and Eq. (16) in :ref:`(Todd) `. For the kinetic part, the algorithm considers that -atoms have crossed the plane if their positions at times t-dt and t are -one on either side of the plane, and uses the velocity at time t-dt/2 -given by the velocity-Verlet algorithm. +atoms have crossed the plane if their positions at times :math:`t-\Delta t` +and :math:`t` are one on either side of the plane, and uses the velocity at +time :math:`t-\Delta t/2` given by the velocity Verlet algorithm. Between one and three keywords can be used to indicate which contributions to the stress must be computed: kinetic stress (kin), @@ -74,11 +77,9 @@ command, since those are contributions to the global system pressure. NOTE 3: The local stress profile generated by compute *stress/mop/profile* is similar to that obtained by compute :doc:`stress/cartesian `. -A key difference -is that compute *stress/mop/profile* considers particles -crossing a set of planes, -while compute *stress/cartesian* computes averages for a set of -small volumes. More information +A key difference is that compute *stress/mop/profile* considers particles +crossing a set of planes, while compute *stress/cartesian* computes averages +for a set of small volumes. More information on the similarities and differences can be found in :ref:`(Ikeshoji)`. diff --git a/doc/src/compute_stress_profile.rst b/doc/src/compute_stress_profile.rst index 9cd89fdb07..9761c68b1e 100644 --- a/doc/src/compute_stress_profile.rst +++ b/doc/src/compute_stress_profile.rst @@ -15,7 +15,7 @@ compute stress/spherical command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID style args @@ -26,8 +26,9 @@ Syntax .. parsed-literal:: *stress/cartesian* args = dim bin_width - dim = x, y, or z. One or two dim/bin_width pairs may be appended + dim = *x* or *y* or *z* bin_width = width of the bin + one or two dim/bin_width pairs may be appended *stress/cylinder* args = zlo zh Rmax bin_width keyword zlo = minimum z-boundary for cylinder zhi = maximum z-boundary for cylinder @@ -63,7 +64,7 @@ gives the total stress tensor :math:`P = P^k+P^v`. These computes can for example be used to calculate the diagonal components of the local stress tensor of interfaces with flat, cylindrical, or spherical symmetry. These computes obeys momentum balance through fluid -interfaces. They use the Irving-Kirkwood contour, which is the straight +interfaces. They use the Irving--Kirkwood contour, which is the straight line between particle pairs. The *stress/cartesian* computes the stress profile along one or two @@ -83,27 +84,28 @@ center of the local volume in the first and second dimensions, number density, :math:`P^k_{xx}`, :math:`P^k_{yy}`, :math:`P^k_{zz}`, :math:`P^v_{xx}`, :math:`P^v_{yy}`, and :math:`P^v_{zz}`. There are 8 columns when one dimension is specified and 9 columns when two -dimensions are specified. The number of bins/rows are -(L1/bin_width1)*(L2/bin_width2), L1 and L2 are the sizes of the -simulation box in the specified dimensions, and bin_width1 and -bin_width2 are the specified bin widths. When only one dimension is -specified the number of bins/rows are L1/bin_width. +dimensions are specified. The number of bins (rows) is +:math:`(L_1/b_1)(L_2/b_2)`, where :math:`L_1` and :math:`L_2` are the lengths +of the simulation box in the specified dimensions and :math:`b_1` and +:math:`b_2` are the specified bin widths. When only one dimension is +specified, the number of bins (rows) is :math:`L_1/b_1`. The default output columns for *stress/cylinder* are the radius to the center of the cylindrical shell, number density, :math:`P^k_{rr}`, :math:`P^k_{\phi\phi}`, :math:`P^k_{zz}`, :math:`P^v_{rr}`, :math:`P^v_{\phi\phi}`, and :math:`P^v_{zz}`. When the keyword *ke* is -set to no, the kinetic contributions are not calculated, and -consequently there are only 5 columns the radius to the center of the -cylindrical shell, number density, :math:`P^v_{rr}`, -:math:`P^v_{\phi\phi}`, :math:`P^v_{zz}`. The number of bins/rows are -Rmax/bin_width. +set to *no*, the kinetic contributions are not calculated, and +consequently there are only 5 columns: the position of the center of the +cylindrical shell, the number density, :math:`P^v_{rr}`, +:math:`P^v_{\phi\phi}`, and :math:`P^v_{zz}`. The number of bins (rows) is +:math:`R_\text{max}/b`, where :math:`b` is the specified bin width. -The output columns for *stress/spherical* are the radius to the center -of the spherical shell, number density, :math:`P^k_{rr}`, +The output columns for *stress/spherical* are the position of the center +of the spherical shell, the number density, :math:`P^k_{rr}`, :math:`P^k_{\theta\theta}`, :math:`P^k_{\phi\phi}`, :math:`P^v_{rr}`, :math:`P^v_{\theta\theta}`, and :math:`P^v_{\phi\phi}`. There are 8 -columns and the number of bins/rows are Rmax/bin_width. +columns and the number of bins (rows) is :math:`R_\text{max}/b`, where +:math:`b` is the specified bin width. This array can be output with :doc:`fix ave/time `, @@ -112,12 +114,13 @@ This array can be output with :doc:`fix ave/time `, compute p all stress/cartesian x 0.1 fix 2 all ave/time 100 1 100 c_p[*] file dump_p.out mode vector -The values calculated by this compute are "intensive". The stress +The values calculated by this compute are "intensive." The stress values will be in pressure :doc:`units `. The number density values are in inverse volume :doc:`units `. NOTE 1: The local stress does not include any Lennard-Jones tail -corrections to the stress added by the :doc:`pair_modify tail yes ` +corrections to the stress added by the +:doc:`pair_modify tail yes ` command, since those are contributions to the global system pressure. NOTE 2: The local stress profiles generated by these computes are @@ -134,11 +137,11 @@ Restrictions """""""""""" These computes calculate the stress tensor contributions for pair -styles only (i.e. no bond, angle, dihedral, etc. contributions, and in +styles only (i.e., no bond, angle, dihedral, etc. contributions, and in the presence of bonded interactions, the result will be incorrect due to exclusions for special bonds) and requires pairwise force calculations -not available for most many-body pair styles. K-space calculations are -also excluded. +not available for most many-body pair styles. +Note that :math:`k`-space calculations are also excluded. These computes are part of the EXTRA-COMPUTE package. They are only enabled if LAMMPS was built with that package. See the :doc:`Build diff --git a/doc/src/compute_tally.rst b/doc/src/compute_tally.rst index 47f8c5da48..fd979d19a0 100644 --- a/doc/src/compute_tally.rst +++ b/doc/src/compute_tally.rst @@ -26,7 +26,7 @@ compute stress/tally command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID style group2-ID @@ -57,8 +57,8 @@ accumulated directly during the non-bonded force computation. The computes *force/tally*, *pe/tally*, *stress/tally*, and *heat/flux/tally* are primarily provided as example how to program additional, more sophisticated computes using the tally callback -mechanism. Compute *pe/mol/tally* is one such style, that can -- through using this mechanism - separately tally intermolecular +mechanism. Compute *pe/mol/tally* is one such style, that can---through using +this mechanism---separately tally intermolecular and intramolecular energies. Something that would otherwise be impossible without integrating this as a core functionality into the base classes of LAMMPS. @@ -92,7 +92,7 @@ Although, the *heat/flux/virial/tally* compute does not include the convective term, it can be used to obtain the total heat flux over control surfaces, when there are no particles crossing over, -such as is often in solid-solid and solid-liquid interfaces. +such as is often in solid--solid and solid--liquid interfaces. This would be identical to the method of planes method. Note that the *heat/flux/virial/tally* compute is distinctly different from the *heat/flux* and *heat/flux/tally* computes, @@ -152,7 +152,7 @@ Output info atom scalar (the contributions of the single atom to the global scalar). -- Compute *pe/mol/tally* calculates a global 4-element vector containing +- Compute *pe/mol/tally* calculates a global four-element vector containing (in this order): *evdwl* and *ecoul* for intramolecular pairs and *evdwl* and *ecoul* for intermolecular pairs. Since molecules are identified by their molecule IDs, the partitioning does not have to be @@ -165,24 +165,24 @@ Output info - Compute *stress/tally* calculates a global scalar (average of the diagonal elements of the stress tensor) and a per atom - vector (the 6 elements of stress tensor contributions from the + vector (the six elements of stress tensor contributions from the individual atom). - As in :doc:`compute heat/flux `, compute *heat/flux/tally* calculates a global vector of length 6, - where the first 3 components are the :math:`x`, :math:`y`, :math:`z` + where the first three components are the :math:`x`, :math:`y`, :math:`z` components of the full heat flow vector, - and the next 3 components are the corresponding components - of just the convective portion of the flow, i.e. the - first term in the equation for :math:`\mathbf{Q}`. + and the next three components are the corresponding components + of just the convective portion of the flow (i.e., the + first term in the equation for :math:`\mathbf{Q}`). - Compute *heat/flux/virial/tally* calculates a global scalar (heat flow) - and a per atom 3-element vector + and a per atom three-element vector (contribution to the force acting over atoms in the first group from individual atoms in both groups). Both the scalar and vector values calculated by this compute are -"extensive". +"extensive." Restrictions """""""""""" diff --git a/doc/src/compute_tdpd_cc_atom.rst b/doc/src/compute_tdpd_cc_atom.rst index d12cca7591..e0a68e6a0a 100644 --- a/doc/src/compute_tdpd_cc_atom.rst +++ b/doc/src/compute_tdpd_cc_atom.rst @@ -6,7 +6,7 @@ compute tdpd/cc/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID tdpd/cc/atom index diff --git a/doc/src/compute_temp.rst b/doc/src/compute_temp.rst index 3163de2272..2e9d4ab362 100644 --- a/doc/src/compute_temp.rst +++ b/doc/src/compute_temp.rst @@ -9,7 +9,7 @@ Accelerator Variants: *temp/kk* Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp @@ -29,19 +29,27 @@ Description Define a computation that calculates the temperature of a group of atoms. A compute of this style can be used by any command that -computes a temperature, e.g. :doc:`thermo_modify `, :doc:`fix temp/rescale `, :doc:`fix npt `, etc. +computes a temperature (e.g., :doc:`thermo_modify `, +:doc:`fix temp/rescale `, :doc:`fix npt `) -The temperature is calculated by the formula KE = dim/2 N k T, where -KE = total kinetic energy of the group of atoms (sum of 1/2 m v\^2), -dim = 2 or 3 = dimensionality of the simulation, N = number of atoms -in the group, k = Boltzmann constant, and T = temperature. +The temperature is calculated by the formula -A kinetic energy tensor, stored as a 6-element vector, is also +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE = total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the simulation, +:math:`N` is the number of atoms in the group, :math:`k_B` is the Boltzmann +constant, and :math:`T` is the absolute temperature. + +A kinetic energy tensor, stored as a six-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. +the above formula, except that :math:`v^2` is replaced by +:math:`v_x v_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`. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the @@ -77,12 +85,13 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length six (KE tensor), which can be accessed by indices 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 +vector values 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 "intensive". The +The scalar value calculated by this compute is "intensive." The vector values are "extensive". The scalar value will be in temperature :doc:`units `. The diff --git a/doc/src/compute_temp_asphere.rst b/doc/src/compute_temp_asphere.rst index 815a42f76c..cef8d573c1 100644 --- a/doc/src/compute_temp_asphere.rst +++ b/doc/src/compute_temp_asphere.rst @@ -6,7 +6,7 @@ compute temp/asphere command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/asphere keyword value ... @@ -42,38 +42,38 @@ usual :doc:`compute temp ` command, which assumes point particles with only translational kinetic energy. Only finite-size particles (aspherical or spherical) can be included -in the group. For 3d finite-size particles, each has 6 degrees of -freedom (3 translational, 3 rotational). For 2d finite-size -particles, each has 3 degrees of freedom (2 translational, 1 +in the group. For 3d finite-size particles, each has six degrees of +freedom (three translational, three rotational). For 2d finite-size +particles, each has three degrees of freedom (two translational, one rotational). .. note:: - This choice for degrees of freedom (dof) assumes that all + This choice for degrees of freedom (DOF) assumes that all finite-size aspherical or spherical particles in your model will - freely rotate, sampling all their rotational dof. It is possible to + freely rotate, sampling all their rotational DOF. It is possible to use a combination of interaction potentials and fixes that induce no torque or otherwise constrain some of all of your particles so that - this is not the case. Then there are less dof and you should use the - :doc:`compute_modify extra ` command to adjust the dof + this is not the case. Then there are fewer DOF and you should use the + :doc:`compute_modify extra ` command to adjust the DOF accordingly. For example, an aspherical particle with all three of its shape parameters the same is a sphere. If it does not rotate, then it -should have 3 dof instead of 6 in 3d (or 2 instead of 3 in 2d). A -uniaxial aspherical particle has two of its three shape parameters the +should have 3 DOF instead of 6 in 3d (or two instead of three in 2d). +A uniaxial aspherical particle has two of its three shape parameters the same. If it does not rotate around the axis perpendicular to its -circular cross section, then it should have 5 dof instead of 6 in 3d. +circular cross section, then it should have 5 DOF instead of 6 in 3d. The latter is the case for uniaxial ellipsoids in a :doc:`GayBerne model ` since there is no induced torque around the -optical axis. It will also be the case for bi-axial ellipsoids when +optical axis. It will also be the case for biaxial ellipsoids when exactly two of the semiaxes have the same length and the corresponding relative well depths are equal. The translational kinetic energy is computed the same as is described by the :doc:`compute temp ` command. The rotational -kinetic energy is computed as 1/2 I w\^2, where I is the inertia tensor -for the aspherical particle and w is its angular velocity, which is -computed from its angular momentum. +kinetic energy is computed as :math:`\frac12 I \omega^2`, where :math:`I` is +the inertia tensor for the aspherical particle and :math:`\omega` is its +angular velocity, which is computed from its angular momentum. .. note:: @@ -81,12 +81,13 @@ computed from its angular momentum. ellipsoids, not ellipses, meaning their moments of inertia will be the same as in 3d. -A kinetic energy tensor, stored as a 6-element vector, is also +A kinetic energy tensor, stored as a six-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 v\^2 and w\^2 are -replaced by vx\*vy and wx\*wy for the xy component, and the appropriate -elements of the inertia tensor are used. The 6 components of the -vector are ordered xx, yy, zz, xy, xz, yz. +tensor is the same as the above formula, except that :math:`v^2` and +:math:`\omega^2` are replaced by :math:`v_x v_y` and :math:`\omega_x \omega_y` +for the :math:`xy` component, and the appropriate elements of the moment of +inertia tensor are used. The six components of the vector are ordered +:math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`, :math:`yz`. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the @@ -111,14 +112,14 @@ For the *bias* keyword, *bias-ID* refers to the ID of a temperature compute that removes a "bias" velocity from each atom. This allows compute temp/sphere to compute its thermal temperature after the translational kinetic energy components have been altered in a -prescribed way, e.g. to remove a flow velocity profile. Thermostats +prescribed way (e.g., to remove a flow velocity profile). Thermostats that use this compute will work with this bias term. See the doc pages for individual computes that calculate a temperature and the doc pages for fixes that perform thermostatting for more details. For the *dof* keyword, a setting of *all* calculates a temperature -that includes both translational and rotational degrees of freedom. A -setting of *rotate* calculates a temperature that includes only +that includes both translational and rotational degrees of freedom. +A setting of *rotate* calculates a temperature that includes only rotational degrees of freedom. ---------- @@ -127,13 +128,14 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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. +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. diff --git a/doc/src/compute_temp_body.rst b/doc/src/compute_temp_body.rst index 72d74d0c4a..42497e34cb 100644 --- a/doc/src/compute_temp_body.rst +++ b/doc/src/compute_temp_body.rst @@ -6,7 +6,7 @@ compute temp/body command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/body keyword value ... @@ -48,32 +48,36 @@ rotational). .. note:: - This choice for degrees of freedom (dof) assumes that all body + This choice for degrees of freedom (DOF) assumes that all body particles in your model will freely rotate, sampling all their - rotational dof. It is possible to use a combination of interaction + rotational DOF. It is possible to use a combination of interaction potentials and fixes that induce no torque or otherwise constrain some of all of your particles so that this is not the case. Then there are - less dof and you should use the :doc:`compute_modify extra ` command to adjust the dof accordingly. + less DOF and you should use the + :doc:`compute_modify extra ` command to adjust the DOF + accordingly. The translational kinetic energy is computed the same as is described by the :doc:`compute temp ` command. The rotational -kinetic energy is computed as 1/2 I w\^2, where I is the inertia tensor -for the aspherical particle and w is its angular velocity, which is -computed from its angular momentum. +kinetic energy is computed as :math:`\frac12 I \omega^2`, where :math:`I` +is the moment of inertia tensor for the aspherical particle and :math:`\omega` +is its angular velocity, which is computed from its angular momentum. -A kinetic energy 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 v\^2 and w\^2 are -replaced by vx\*vy and wx\*wy for the xy component, and the appropriate -elements of the inertia tensor are used. The 6 components of the -vector are ordered xx, yy, zz, xy, xz, yz. +A kinetic energy 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:`v^2` and :math:`\omega^2` are +replaced by :math:`v_x v_y` and :math:`\omega_x \omega_y` for the +math:`xy` component, and the appropriate elements of the inertia tensor are +used. The six components of the vector are ordered :math:`xx`, :math:`yy`, +:math:`zz`, :math:`xy`, :math:`xz`, :math:`yz`. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the :doc:`compute_modify ` command if this is not the case. This compute subtracts out translational degrees-of-freedom due to -fixes that constrain molecular motion, such as :doc:`fix shake ` and :doc:`fix rigid `. This means the +fixes that constrain molecular motion, such as :doc:`fix shake ` +and :doc:`fix rigid `. This means the temperature of groups of atoms that include these constraints will be computed correctly. If needed, the subtracted degrees-of-freedom can be altered using the *extra* option of the @@ -91,7 +95,7 @@ For the *bias* keyword, *bias-ID* refers to the ID of a temperature compute that removes a "bias" velocity from each atom. This allows compute temp/sphere to compute its thermal temperature after the translational kinetic energy components have been altered in a -prescribed way, e.g. to remove a flow velocity profile. Thermostats +prescribed way (e.g., to remove a flow velocity profile). Thermostats that use this compute will work with this bias term. See the doc pages for individual computes that calculate a temperature and the doc pages for fixes that perform thermostatting for more details. @@ -107,22 +111,24 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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. +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." -The scalar value will be in temperature :doc:`units `. The -vector values will be in energy :doc:`units `. +The scalar value will be in temperature :doc:`units `. +The vector values will be in energy :doc:`units `. Restrictions """""""""""" This compute is part of the BODY package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +LAMMPS was built with that package. +See the :doc:`Build package ` page for more info. This compute requires that atoms store angular momentum and a quaternion as defined by the :doc:`atom_style body ` diff --git a/doc/src/compute_temp_chunk.rst b/doc/src/compute_temp_chunk.rst index 1bd5ecbb40..f3d1a83351 100644 --- a/doc/src/compute_temp_chunk.rst +++ b/doc/src/compute_temp_chunk.rst @@ -6,14 +6,14 @@ compute temp/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/chunk chunkID value1 value2 ... keyword value ... * ID, group-ID are documented in :doc:`compute ` command * temp/chunk = style name of this compute command * chunkID = ID of :doc:`compute chunk/atom ` command -* zero or more values can be listed as value1,value2,etc +* zero or more values can be listed as value1,value2,etc. * value = *temp* or *kecom* or *internal* .. parsed-literal:: @@ -55,31 +55,43 @@ center-of-mass velocity of each chunk. By specifying optional values, it can also calculate the per-chunk temperature or energies of the 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. -The temperature is calculated by the formula KE = DOF/2 k T, where KE = -total kinetic energy of all atoms assigned to chunks (sum of 1/2 m -v\^2), DOF = the total number of degrees of freedom for those atoms, k -= Boltzmann constant, and T = temperature. +The temperature is calculated by the formula -The DOF is calculated as N\*adof + Nchunk\*cdof, where N = number of -atoms contributing to the KE, adof = degrees of freedom per atom, and -cdof = degrees of freedom per chunk. By default adof = 2 or 3 = -dimensionality of system, as set via the :doc:`dimension ` -command, and cdof = 0.0. This gives the usual formula for -temperature. +.. math:: -A kinetic energy tensor, stored as a 6-element vector, is also + \text{KE} = \frac{\text{DOF}}{2} k_B T, + +where KE is the total kinetic energy of all atoms assigned to chunks +(sum of :math:`\frac12 m v^2`), DOF is the the total number of degrees of +freedom for those atoms, :math:`k_B` is Boltzmann constant, and :math:`T` is the +absolute temperature. + +The DOF is calculated as :math:`N\times`\ *adof* ++ :math:`N_\text{chunk}\times`\ *cdof*, +where :math:`N` is the number of atoms contributing to the kinetic energy, +*adof* is the number of degrees of freedom per atom, and +*cdof* is the number of degrees of freedom per chunk. +By default, *adof* = 2 or 3 = dimensionality of system, as set via the +:doc:`dimension ` command, and *cdof* = 0.0. +This gives the usual formula for temperature. + +A kinetic energy tensor, stored as a six-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. +the above formula, except that :math:`v^2` is replaced by +:math:`v_x v_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 the number of atoms contributing to the temperature is calculated each time the temperature is evaluated since it is assumed @@ -91,17 +103,24 @@ If any optional values are specified, then per-chunk quantities are also calculated and stored in a global array, as described below. The *temp* value calculates the temperature for each chunk by the -formula KE = DOF/2 k T, where KE = total kinetic energy of the chunk -of atoms (sum of 1/2 m v\^2), DOF = the total number of degrees of -freedom for all atoms in the chunk, k = Boltzmann constant, and T = -temperature. +formula -The DOF in this case is calculated as N\*adof + cdof, where N = number -of atoms in the chunk, adof = degrees of freedom per atom, and cdof = -degrees of freedom per chunk. By default adof = 2 or 3 = -dimensionality of system, as set via the :doc:`dimension ` -command, and cdof = 0.0. This gives the usual formula for -temperature. +.. math:: + + \text{KE} = \frac{\text{DOF}}{2} k_B T, + +where KE is the total kinetic energy of the chunk of atoms (sum of +:math:`\frac12 m v^2`), DOF is the total number of degrees of freedom for all +atoms in the chunk, :math:`k_B` is the Boltzmann constant, and :math:`T` is the +absolute temperature. + +The number of degrees of freedom (DOF) in this case is calculated as +:math:`N\times`\ *adof* + *cdof*, where :math:`N` is the number +of atoms in the chunk, *adof* is the number of degrees of freedom +per atom, and *cdof* is the number of degrees of freedom per +chunk. By default, *cdof* = 2 or 3 = dimensionality of system, as set +via the :doc:`dimension ` command, and *cdof* = 0.0. +This gives the usual formula for temperature. The *kecom* value calculates the kinetic energy of each chunk as if all its atoms were moving with the velocity of the center-of-mass of @@ -118,9 +137,11 @@ Note that currently the global and per-chunk temperatures calculated by this compute only include translational degrees of freedom for each atom. No rotational degrees of freedom are included for finite-size particles. Also no degrees of freedom are subtracted for any velocity -bias or constraints that are applied, such as :doc:`compute temp/partial `, or :doc:`fix shake ` -or :doc:`fix rigid `. This is because those degrees of -freedom (e.g. a constrained bond) could apply to sets of atoms that +bias or constraints that are applied, such as +:doc:`compute temp/partial `, or +:doc:`fix shake ` or :doc:`fix rigid `. +This is because those degrees of +freedom (e.g., a constrained bond) could apply to sets of atoms that are both included and excluded from a specific chunk, and hence the concept is somewhat ill-defined. In some cases, you can use the *adof* and *cdof* keywords to adjust the calculated degrees of freedom @@ -138,16 +159,17 @@ calculating the temperature; fix ave/chunk does not. .. note:: - Only atoms in the specified group contribute to the calculations - performed by this compute. 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 - this command if you simply want to include atoms with non-zero chunk - IDs. + Only atoms in the specified group contribute to the calculations performed + by this compute. 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 this command if you simply want to include atoms with non-zero + chunk IDs. The simplest way to output the per-chunk results of the compute -temp/chunk calculation to a file is to use the :doc:`fix ave/time ` command, for example: +temp/chunk calculation to a file is to use the +:doc:`fix ave/time ` command, for example: .. code-block:: LAMMPS @@ -170,8 +192,8 @@ For the *bias* keyword, *bias-ID* refers to the ID of a temperature compute that removes a "bias" velocity from each atom. This also allows calculation of the global or per-chunk temperature using only the thermal temperature of atoms in each chunk after the translational -kinetic energy components have been altered in a prescribed way, -e.g. to remove a velocity profile. It also applies to the calculation +kinetic energy components have been altered in a prescribed way +(e.g., to remove a velocity profile). It also applies to the calculation of the other per-chunk values, such as *kecom* or *internal*, which involve the center-of-mass velocity of each chunk, which is calculated after the velocity bias is removed from each atom. Note that the @@ -181,12 +203,12 @@ not on a per-chunk basis. The *adof* and *cdof* keywords define the values used in the degree of freedom (DOF) formulas used for the global or per-chunk temperature, as described above. They can be used to calculate a more appropriate -temperature for some kinds of chunks. Here are 3 examples: +temperature for some kinds of chunks. Here are three examples: If spatially binned chunks contain some number of water molecules and :doc:`fix shake ` is used to make each molecule rigid, then -you could calculate a temperature with 6 degrees of freedom (DOF) (3 -translational, 3 rotational) per molecule by setting *adof* to 2.0. +you could calculate a temperature with six degrees of freedom (DOF) (three +translational, three rotational) per molecule by setting *adof* to 2.0. If :doc:`compute temp/partial ` is used with the *bias* keyword to only allow the x component of velocity to contribute @@ -196,8 +218,8 @@ If each chunk consists of a large molecule, with some number of its bonds constrained by :doc:`fix shake ` or the entire molecule by :doc:`fix rigid/small `, *adof* = 0.0 and *cdof* could be set to the remaining degrees of freedom for the entire molecule -(entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid -molecule. +(entire chunk in this case; i.e., 6 for 3d, or 3 for 2d, for a rigid +molecule). ---------- @@ -205,22 +227,23 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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. +vector values from a compute as input. +See the :doc:`Howto output ` page for an overview of LAMMPS +output options. This compute also optionally calculates a global array, if one or more of the optional values are specified. The number of rows in the array -= the number of chunks *Nchunk* as calculated by the specified +is the number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom ` command. The number of columns is the number of specified values (1 or more). These values can be accessed by any command that uses global array values from a compute as input. Again, see the :doc:`Howto output ` doc page for an overview of LAMMPS output options. -The scalar value calculated by this compute is "intensive". The -vector values are "extensive". The array values are "intensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The array values are "intensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. The array values diff --git a/doc/src/compute_temp_com.rst b/doc/src/compute_temp_com.rst index d233029ea0..fde6f701fd 100644 --- a/doc/src/compute_temp_com.rst +++ b/doc/src/compute_temp_com.rst @@ -6,7 +6,7 @@ compute temp/com command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/com @@ -29,20 +29,27 @@ atoms, after subtracting out the center-of-mass velocity of the group. This is useful if the group is expected to have a non-zero net velocity for some reason. A compute of this style can be used by any command that computes a temperature, -e.g. :doc:`thermo_modify `, :doc:`fix temp/rescale `, :doc:`fix npt `, etc. +(e.g., :doc:`thermo_modify `, +:doc:`fix temp/rescale `, :doc:`fix npt `). After the center-of-mass velocity has been subtracted from each atom, -the temperature is calculated by the formula KE = dim/2 N k T, where -KE = total kinetic energy of the group of atoms (sum of 1/2 m v\^2), -dim = 2 or 3 = dimensionality of the simulation, N = number of atoms -in the group, k = Boltzmann constant, and T = temperature. +the temperature is calculated by the formula -A kinetic energy tensor, stored as a 6-element vector, is also +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the +simulation, :math:`N` is number of atoms in the group, :math:`k_B` is +the Boltzmann constant, and :math:`T` is the absolute temperature. + +A kinetic energy tensor, stored as a six-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. +the above formula, except that :math:`v^2` is replaced by :math:`v_x v_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`. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the @@ -54,13 +61,16 @@ velocity of the atoms. If this compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining thermal velocity will be performed, and the bias will be added back in. Thermostatting fixes -that work in this way include :doc:`fix nvt `, :doc:`fix temp/rescale `, :doc:`fix temp/berendsen `, and :doc:`fix langevin `. +that work in this way include :doc:`fix nvt `, +:doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, and +:doc:`fix langevin `. This compute subtracts out degrees-of-freedom due to fixes that constrain molecular motion, such as :doc:`fix shake ` and :doc:`fix rigid `. This means the temperature of groups of -atoms that include these constraints will be computed correctly. If -needed, the subtracted degrees-of-freedom can be altered using the +atoms that include these constraints will be computed correctly. +If needed, the subtracted degrees-of-freedom can be altered using the *extra* option of the :doc:`compute_modify ` command. See the :doc:`Howto thermostat ` page for a @@ -71,16 +81,17 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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 +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." -The scalar value will be in temperature :doc:`units `. The -vector values will be in energy :doc:`units `. +The scalar value will be in temperature :doc:`units `. +The vector values will be in energy :doc:`units `. Restrictions """""""""""" diff --git a/doc/src/compute_temp_cs.rst b/doc/src/compute_temp_cs.rst index 8a7fd0a3a5..3c9503cf4f 100644 --- a/doc/src/compute_temp_cs.rst +++ b/doc/src/compute_temp_cs.rst @@ -6,7 +6,7 @@ compute temp/cs command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/cs group1 group2 @@ -29,14 +29,15 @@ Description Define a computation that calculates the temperature of a system based on the center-of-mass velocity of atom pairs that are bonded to each other. This compute is designed to be used with the adiabatic -core/shell model of :ref:`(Mitchell and Finchham) `. See -the :doc:`Howto coreshell ` page for an overview of +core/shell model of :ref:`(Mitchell and Finchham) `. +See the :doc:`Howto coreshell ` page for an overview of the model as implemented in LAMMPS. Specifically, this compute enables correct temperature calculation and thermostatting of core/shell pairs where it is desirable for the internal degrees of freedom of the core/shell pairs to not be influenced by a thermostat. A compute of this style can be used by any command that computes a -temperature via :doc:`fix_modify ` e.g. :doc:`fix temp/rescale `, :doc:`fix npt `, etc. +temperature via :doc:`fix_modify ` +(e.g., :doc:`fix temp/rescale `, :doc:`fix npt `). Note that this compute does not require all ions to be polarized, hence defined as core/shell pairs. One can mix core/shell pairs and @@ -52,48 +53,56 @@ included in the treated system should not be included into either of these groups, they are taken into account by the *group-ID* (second argument) of the compute. -The temperature is calculated by the formula KE = dim/2 N k T, where -KE = total kinetic energy of the group of atoms (sum of 1/2 m v\^2), -dim = 2 or 3 = dimensionality of the simulation, N = number of atoms -in the group, k = Boltzmann constant, and T = temperature. Note that +The temperature is calculated by the formula + +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the simulation, +:math:`N` is the number of atoms in the group, :math:`k_B` is the Boltzmann +constant, and :math:`T` is the absolute temperature. Note that the velocity of each core or shell atom used in the KE calculation is the velocity of the center-of-mass (COM) of the core/shell pair the atom is part of. -A kinetic energy tensor, stored as a 6-element vector, is also -calculated by this compute for use in the computation of a pressure -tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. In contrast to the temperature, the velocity of -each core or shell atom is taken individually. +A kinetic energy tensor, stored as a six-element vector, is also calculated by +this compute for use in the computation of a pressure tensor. The formula for +the components of the tensor is the same as the above formula, except that +:math:`v^2` is replaced by :math:`v_x v_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`. In contrast to the temperature, +the velocity of each core or shell atom is taken individually. The change this fix makes to core/shell atom velocities is essentially -computing the temperature after a "bias" has been removed from the -velocity of the atoms. This "bias" is the velocity of the atom -relative to the COM velocity of the core/shell pair. If this compute -is used with a fix command that performs thermostatting then this bias -will be subtracted from each atom, thermostatting of the remaining COM -velocity will be performed, and the bias will be added back in. This -means the thermostatting will effectively be performed on the -core/shell pairs, instead of on the individual core and shell atoms. -Thermostatting fixes that work in this way include :doc:`fix nvt `, :doc:`fix temp/rescale `, :doc:`fix temp/berendsen `, and :doc:`fix langevin `. +computing the temperature after a "bias" has been removed from the velocity of +the atoms. This "bias" is the velocity of the atom relative to the +center-of-mass velocity of the core/shell pair. If this compute is used with a +fix command that performs thermostatting then this bias will be subtracted from +each atom, thermostatting of the remaining center-of-mass velocity will be +performed, and the bias will be added back in. This means the thermostatting +will effectively be performed on the core/shell pairs, instead of on the +individual core and shell atoms. Thermostatting fixes that work in this way +include :doc:`fix nvt `, :doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, and +:doc:`fix langevin `. The internal energy of core/shell pairs can be calculated by the -:doc:`compute temp/chunk ` command, if chunks are -defined as core/shell pairs. See the :doc:`Howto coreshell ` page doc page for more discussion -on how to do this. +:doc:`compute temp/chunk ` command, if chunks are defined +as core/shell pairs. See the :doc:`Howto coreshell ` doc +page for more discussion on how to do this. Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 1--6. These values can be used by any command that uses global scalar or vector values from a compute as input. -The scalar value calculated by this compute is "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. @@ -108,7 +117,8 @@ be used which generate new molecules or atoms during a simulation. Related commands """""""""""""""" -:doc:`compute temp `, :doc:`compute temp/chunk ` +:doc:`compute temp `, +:doc:`compute temp/chunk ` Default """"""" diff --git a/doc/src/compute_temp_deform.rst b/doc/src/compute_temp_deform.rst index 6c61f7bc93..b2d6b68b17 100644 --- a/doc/src/compute_temp_deform.rst +++ b/doc/src/compute_temp_deform.rst @@ -9,7 +9,7 @@ Accelerator Variants: *temp/deform/kk* Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/deform @@ -34,17 +34,17 @@ induced by use of the :doc:`fix deform ` command. A compute of this style is created by the :doc:`fix nvt/sllod ` command to compute the thermal temperature of atoms for thermostatting purposes. A compute of this style can also be used by any command -that computes a temperature, e.g. :doc:`thermo_modify `, -:doc:`fix temp/rescale `, :doc:`fix npt `, etc. +that computes a temperature (e.g., :doc:`thermo_modify `, +:doc:`fix temp/rescale `, :doc:`fix npt `). The deformation fix changes the box size and/or shape over time, so each atom in the simulation box can be thought of as having a -"streaming" velocity. For example, if the box is being sheared in x, -relative to y, then atoms at the bottom of the box (low y) have a -small x velocity, while atoms at the top of the box (hi y) have a -large x velocity. This position-dependent streaming velocity is +"streaming" velocity. For example, if the box is being sheared in *x*, +relative to *y*, then atoms at the bottom of the box (low *y*) have a +small *x* velocity, while atoms at the top of the box (high *y*) have a +large *x* velocity. This position-dependent streaming velocity is subtracted from each atom's actual velocity to yield a thermal -velocity which is used to compute the temperature. +velocity, which is then used to compute the temperature. .. note:: @@ -52,7 +52,8 @@ velocity which is used to compute the temperature. atom coordinates or velocities to the changing simulation box. When using this compute in conjunction with a deforming box, fix deform should NOT remap atom positions, but rather should let atoms respond - to the changing box by adjusting their own velocities (or let :doc:`fix deform ` remap the atom velocities, see it's remap + to the changing box by adjusting their own velocities (or let + :doc:`fix deform ` remap the atom velocities; see its remap option). If fix deform does remap atom positions, then they appear to move with the box but their velocity is not changed, and thus they do NOT have the streaming velocity assumed by this compute. LAMMPS will @@ -60,18 +61,25 @@ velocity which is used to compute the temperature. consistent with this compute. After the streaming velocity has been subtracted from each atom, the -temperature is calculated by the formula KE = dim/2 N k T, where KE = -total kinetic energy of the group of atoms (sum of 1/2 m v\^2), dim = 2 -or 3 = dimensionality of the simulation, N = number of atoms in the -group, k = Boltzmann constant, and T = temperature. Note that v in -the kinetic energy formula is the atom's thermal velocity. +temperature is calculated by the formula -A kinetic energy tensor, stored as a 6-element vector, is also +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`, dim = 2 or 3 is the dimensionality of the +simulation, :math:`N` is the number of atoms in the group, :math:`k_B` +is the Boltzmann constant, and :math:`T` is the temperature. Note that +:math:`v` in the kinetic energy formula is the atom's velocity. + +A kinetic energy tensor, stored as a six-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. +the above formula, except that :math:`v^2` is replaced by :math:`v_x v_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`. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the @@ -83,7 +91,10 @@ from the velocity of the atoms. If this compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining thermal velocity will be performed, and the bias will be added back in. Thermostatting -fixes that work in this way include :doc:`fix nvt `, :doc:`fix temp/rescale `, :doc:`fix temp/berendsen `, and :doc:`fix langevin `. +fixes that work in this way include :doc:`fix nvt `, +:doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, and +:doc:`fix langevin `. .. note:: @@ -91,14 +102,16 @@ fixes that work in this way include :doc:`fix nvt `, :doc:`fix temp/resc the atoms are indeed moving with a stream velocity profile that matches the box deformation. If not, then the compute will subtract off an incorrect stream velocity, yielding a bogus thermal - temperature. You should NOT assume that your atoms are streaming at + temperature. You should **not** assume that your atoms are streaming at the same rate the box is deforming. Rather, you should monitor their - velocity profile, e.g. via the :doc:`fix ave/chunk ` - command. And you can compare the results of this compute to :doc:`compute temp/profile `, which actually calculates the - stream profile before subtracting it. If the two computes do not give - roughly the same temperature, then your atoms are not streaming - consistent with the box deformation. See the :doc:`fix deform ` command for more details on ways to get atoms - to stream consistently with the box deformation. + velocity profiles (e.g., via the :doc:`fix ave/chunk ` + command). You can also compare the results of this compute to + :doc:`compute temp/profile `, which actually + calculates the stream profile before subtracting it. If the two computes do + not give roughly the same temperature, then your atoms are not streaming + consistent with the box deformation. See the :doc:`fix deform ` + command for more details on ways to get atoms to stream consistently with + the box deformation. This compute subtracts out degrees-of-freedom due to fixes that constrain molecular motion, such as :doc:`fix shake ` and @@ -115,16 +128,17 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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 +vector values 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 "intensive". The +The scalar value calculated by this compute is "intensive." The vector values are "extensive". -The scalar value will be in temperature :doc:`units `. The -vector values will be in energy :doc:`units `. +The scalar value will be in temperature :doc:`units `. +The vector values will be in energy :doc:`units `. Restrictions """""""""""" @@ -133,7 +147,9 @@ Restrictions Related commands """""""""""""""" -:doc:`compute temp/ramp `, :doc:`compute temp/profile `, :doc:`fix deform `, +:doc:`compute temp/ramp `, +:doc:`compute temp/profile `, +:doc:`fix deform `, :doc:`fix nvt/sllod ` Default diff --git a/doc/src/compute_temp_deform_eff.rst b/doc/src/compute_temp_deform_eff.rst index b03aa00702..3dd1225299 100644 --- a/doc/src/compute_temp_deform_eff.rst +++ b/doc/src/compute_temp_deform_eff.rst @@ -6,7 +6,7 @@ compute temp/deform/eff command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/deform/eff @@ -29,11 +29,11 @@ model, after subtracting out a streaming velocity induced by the simulation box changing size and/or shape, for example in a non-equilibrium MD (NEMD) simulation. The size/shape change is induced by use of the :doc:`fix deform ` command. A -compute of this style is created by the :doc:`fix nvt/sllod/eff ` command to compute the thermal +compute of this style is created by the +:doc:`fix nvt/sllod/eff ` command to compute the thermal temperature of atoms for thermostatting purposes. A compute of this -style can also be used by any command that computes a temperature, -e.g. :doc:`thermo_modify `, :doc:`fix npt/eff `, -etc. +style can also be used by any command that computes a temperature +(e.g., :doc:`thermo_modify `, :doc:`fix npt/eff `). The calculation performed by this compute is exactly like that described by the :doc:`compute temp/deform ` @@ -47,13 +47,14 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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 +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. @@ -62,7 +63,8 @@ Restrictions """""""""""" This compute is part of the EFF package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +LAMMPS was built with that package. See the +:doc:`Build package ` page for more info. Related commands """""""""""""""" diff --git a/doc/src/compute_temp_drude.rst b/doc/src/compute_temp_drude.rst index c2a0479cae..8c50831941 100644 --- a/doc/src/compute_temp_drude.rst +++ b/doc/src/compute_temp_drude.rst @@ -6,7 +6,7 @@ compute temp/drude command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/drude @@ -20,26 +20,28 @@ Examples compute TDRUDE all temp/drude -Example input scripts available: examples/PACKAGES/drude +Example input scripts available: :file:`examples/PACKAGES/drude`. Description """"""""""" -Define a computation that calculates the temperatures of core-Drude -pairs. This compute is designed to be used with the :doc:`thermalized Drude oscillator model `. Polarizable models in LAMMPS -are described on the :doc:`Howto polarizable ` doc -page. +Define a computation that calculates the temperatures of core--Drude +pairs. This compute is designed to be used with the +:doc:`thermalized Drude oscillator model `. +Polarizable models in LAMMPS +are described on the :doc:`Howto polarizable ` doc page. Drude oscillators consist of a core particle and a Drude particle connected by a harmonic bond, and the relative motion of these Drude oscillators is usually maintained cold by a specific thermostat that -acts on the relative motion of the core-Drude particle +acts on the relative motion of the core--Drude particle pairs. Therefore, because LAMMPS considers Drude particles as normal -atoms in its default temperature compute (:doc:`compute temp ` command), the reduced temperature of the -core-Drude particle pairs is not calculated correctly. +atoms in its default temperature compute (:doc:`compute temp ` +command), the reduced temperature of the core--Drude particle pairs is not +calculated correctly. By contrast, this compute calculates the temperature of the cores -using center-of-mass velocities of the core-Drude pairs, and the +using center-of-mass velocities of the core--Drude pairs, and the reduced temperature of the Drude particles using the relative velocities of the Drude particles with respect to their cores. Non-polarizable atoms are considered as cores. Their velocities @@ -49,7 +51,7 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6, which can be accessed by indices 1-6, whose components +vector of length 6, which can be accessed by indices 1--6, whose components are 1. temperature of the centers of mass (temperature units) @@ -60,12 +62,13 @@ are 6. kinetic energy of the dipoles (energy units) 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 value and the first two values of the vector -calculated by this compute are "intensive". The other 4 vector values -are "extensive". +calculated by this compute are "intensive." The other four vector values +are "extensive." Restrictions """""""""""" @@ -77,7 +80,9 @@ assumed to be constant for the duration of the run unless the Related commands """""""""""""""" -:doc:`fix drude `, :doc:`fix langevin/drude `, :doc:`fix drude/transform `, :doc:`pair_style thole `, :doc:`compute temp ` +:doc:`fix drude `, :doc:`fix langevin/drude `, +:doc:`fix drude/transform `, +:doc:`pair_style thole `, :doc:`compute temp ` Default """"""" diff --git a/doc/src/compute_temp_eff.rst b/doc/src/compute_temp_eff.rst index ba139dd547..c76581fa68 100644 --- a/doc/src/compute_temp_eff.rst +++ b/doc/src/compute_temp_eff.rst @@ -6,7 +6,7 @@ compute temp/eff command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/eff @@ -27,20 +27,27 @@ Description Define a computation that calculates the temperature of a group of nuclei and electrons in the :doc:`electron force field ` model. A compute of this style can be used by commands that compute a -temperature, e.g. :doc:`thermo_modify `, :doc:`fix npt/eff `, etc. +temperature (e.g., :doc:`thermo_modify `, +:doc:`fix npt/eff `). -The temperature is calculated by the formula KE = dim/2 N k T, where -KE = total kinetic energy of the group of atoms (sum of 1/2 m v\^2 for -nuclei and sum of 1/2 (m v\^2 + 3/4 m s\^2) for electrons, where s -includes the radial electron velocity contributions), dim = 2 or 3 = -dimensionality of the simulation, N = number of atoms (only total +The temperature is calculated by the formula + +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2` for nuclei and sum of +:math:`\frac12 (m v^2 + \frac34 m s^2`) for electrons, where :math:`s` +includes the radial electron velocity contributions), dim = 2 or 3 is the +dimensionality of the simulation, :math:`N` is the number of atoms (only total number of nuclei in the eFF (see the :doc:`pair_eff ` -command) in the group, k = Boltzmann constant, and T = temperature. -This expression is summed over all nuclear and electronic degrees of -freedom, essentially by setting the kinetic contribution to the heat -capacity to 3/2k (where only nuclei contribute). This subtlety is -valid for temperatures well below the Fermi temperature, which for -densities two to five times the density of liquid H2 ranges from +command) in the group, :math:`k_B` is the Boltzmann constant, and :math:`T` is +the absolute temperature. This expression is summed over all nuclear and +electronic degrees of freedom, essentially by setting the kinetic contribution +to the heat capacity to :math:`\frac32 k` (where only nuclei contribute). This +subtlety is valid for temperatures well below the Fermi temperature, which for +densities two to five times the density of liquid hydrogen ranges from 86,000 to 170,000 K. .. note:: @@ -57,11 +64,11 @@ densities two to five times the density of liquid H2 ranges from thermo_style custom step etotal pe ke temp press thermo_modify temp effTemp -A 6-component kinetic energy tensor is also calculated by this compute +A six-component kinetic energy tensor is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as the above formula, except that -v\^2 is replaced by vx \* vy for the xy component, etc. For the eFF, -again, the radial electronic velocities are also considered. +:math:`v^2` is replaced by :math:`v_x v_y` for the :math:`xy` component, etc. +For the eFF, again, the radial electronic velocities are also considered. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the @@ -81,9 +88,9 @@ thermostatting. Output info """"""""""" -The scalar value calculated by this compute is "intensive", meaning it +The scalar value calculated by this compute is "intensive," meaning it is independent of the number of atoms in the simulation. The vector -values are "extensive", meaning they scale with the number of atoms in +values are "extensive," meaning they scale with the number of atoms in the simulation. Restrictions @@ -95,7 +102,9 @@ LAMMPS was built with that package. See the :doc:`Build package Related commands """""""""""""""" -:doc:`compute temp/partial `, :doc:`compute temp/region `, :doc:`compute pressure ` +:doc:`compute temp/partial `, +:doc:`compute temp/region `, +:doc:`compute pressure ` Default """"""" diff --git a/doc/src/compute_temp_partial.rst b/doc/src/compute_temp_partial.rst index 471f3bcfd4..0512311d8f 100644 --- a/doc/src/compute_temp_partial.rst +++ b/doc/src/compute_temp_partial.rst @@ -6,7 +6,7 @@ compute temp/partial command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/partial xflag yflag zflag @@ -26,23 +26,31 @@ Description Define a computation that calculates the temperature of a group of atoms, after excluding one or more velocity components. A compute of -this style can be used by any command that computes a temperature, -e.g. :doc:`thermo_modify `, :doc:`fix temp/rescale `, :doc:`fix npt `, etc. +this style can be used by any command that computes a temperature +(e.g. :doc:`thermo_modify `, +:doc:`fix temp/rescale `, :doc:`fix npt `). -The temperature is calculated by the formula KE = dim/2 N k T, where -KE = total kinetic energy of the group of atoms (sum of 1/2 m v\^2), -dim = dimensionality of the simulation, N = number of atoms in the -group, k = Boltzmann constant, and T = temperature. The calculation -of KE excludes the x, y, or z dimensions if xflag, yflag, or zflag = -0. The dim parameter is adjusted to give the correct number of +The temperature is calculated by the formula + +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the simulation, +:math:`N` is the number of atoms in the group, :math:`k_B` is the Boltzmann +constant, and :math:`T` = temperature. The calculation of KE excludes the +:math:`x`, :math:`y`, or :math:`z` dimensions if *xflag*, *yflag*, or *zflag* +is 0. The dim parameter is adjusted to give the correct number of degrees of freedom. -A kinetic energy tensor, stored as a 6-element vector, is also +A kinetic energy tensor, stored as a six-element vector, is also calculated by this compute for use in the calculation of a pressure tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. +the above formula, except that :math:`v^2` is replaced by :math:`v_x v_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`. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the @@ -54,7 +62,10 @@ velocity of the atoms. If this compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining thermal velocity will be performed, and the bias will be added back in. Thermostatting fixes -that work in this way include :doc:`fix nvt `, :doc:`fix temp/rescale `, :doc:`fix temp/berendsen `, and :doc:`fix langevin `. +that work in this way include :doc:`fix nvt `, +:doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, and +:doc:`fix langevin `. This compute subtracts out degrees-of-freedom due to fixes that constrain molecular motion, such as :doc:`fix shake ` and @@ -77,13 +88,14 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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. +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. diff --git a/doc/src/compute_temp_profile.rst b/doc/src/compute_temp_profile.rst index e5830f5cf7..9076a6cb14 100644 --- a/doc/src/compute_temp_profile.rst +++ b/doc/src/compute_temp_profile.rst @@ -6,7 +6,7 @@ compute temp/profile command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/profile xflag yflag zflag binstyle args @@ -24,7 +24,7 @@ Syntax *yz* args = Ny Nz *xz* args = Nx Nz *xyz* args = Nx Ny Nz - Nx,Ny,Nz = number of velocity bins in x,y,z dimensions + Nx, Ny, Nz = number of velocity bins in *x*, *y*, *z* dimensions * zero or more keyword/value pairs may be appended * keyword = *out* @@ -49,24 +49,24 @@ Define a computation that calculates the temperature of a group of atoms, after subtracting out a spatially-averaged center-of-mass velocity field, before computing the kinetic energy. This can be useful for thermostatting a collection of atoms undergoing a complex -flow, e.g. via a profile-unbiased thermostat (PUT) as described in -:ref:`(Evans) `. A compute of this style can be used by any command -that computes a temperature, e.g. :doc:`thermo_modify `, -:doc:`fix temp/rescale `, :doc:`fix npt `, etc. +flow (e.g. via a profile-unbiased thermostat (PUT) as described in +:ref:`(Evans) `). A compute of this style can be used by any command +that computes a temperature (e.g. :doc:`thermo_modify `, +:doc:`fix temp/rescale `, :doc:`fix npt `). The *xflag*, *yflag*, *zflag* settings determine which components of average velocity are subtracted out. -The *binstyle* setting and its *Nx*, *Ny*, *Nz* arguments determine -how bins are setup to perform spatial averaging. "Bins" can be 1d -slabs, 2d pencils, or 3d bricks depending on which *binstyle* is used. -The simulation box is partitioned conceptually into *Nx* by *Ny* by -*Nz* bins. Depending on the *binstyle*, you may only specify one or -two of these values; the others are effectively set to 1 (no binning -in that dimension). For non-orthogonal (triclinic) simulation boxes, -the bins are "tilted" slabs or pencils or bricks that are parallel to -the tilted faces of the box. See the :doc:`region prism ` -command for a discussion of the geometry of tilted boxes in LAMMPS. +The *binstyle* setting and its *Nx*, *Ny*, *Nz* arguments determine how bins +are setup to perform spatial averaging. "Bins" can be 1d slabs, 2d pencils, +or 3d bricks depending on which *binstyle* is used. The simulation box is +partitioned conceptually into *Nx* :math:`\times` *Ny* :math:`\times` *Nz* +bins. Depending on the *binstyle*, you may only specify one or two of these +values; the others are effectively set to 1 (no binning in that dimension). +For non-orthogonal (triclinic) simulation boxes, the bins are "tilted" slabs or +pencils or bricks that are parallel to the tilted faces of the box. See the +:doc:`region prism ` command for a discussion of the geometry of tilted +boxes in LAMMPS. When a temperature is computed, the center-of-mass velocity for the set of atoms that are both in the compute group and in the same @@ -77,36 +77,41 @@ bin, its thermal velocity will thus be 0.0. After the spatially-averaged velocity field has been subtracted from each atom, the temperature is calculated by the formula -*KE* = (*dim\*N* - *Ns\*Nx\*Ny\*Nz* - *extra* ) *k* *T*/2, where *KE* = total -kinetic energy of the group of atoms (sum of 1/2 *m* *v*\^2), *dim* = 2 -or 3 = dimensionality of the simulation, *Ns* = 0, 1, 2 or 3 for -streaming velocity subtracted in 0, 1, 2 or 3 dimensions, *extra* = extra -degrees-of-freedom, *N* = number of atoms in the group, *k* = Boltzmann -constant, and *T* = temperature. The *Ns\*Nx\*Ny\*Nz* term is degrees -of freedom subtracted to adjust for the removal of the center-of-mass -velocity in each direction of the *Nx\*Ny\*Nz* bins, as discussed in the -:ref:`(Evans) ` paper. The extra term defaults to (*dim* - *Ns*) -and accounts for overall conservation of center-of-mass velocity across -the group in directions where streaming velocity is *not* subtracted. This -can be altered using the *extra* option of the + +.. math:: + + \text{KE} = \left( \frac{\text{dim}}{N} - N_s N_x N_y N_z + - \text{extra} \right) \frac{k_B T}{2}, + +where KE is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`; dim = 2 or 3 is the dimensionality of the simulation; +:math:`N_s =` 0, 1, 2, or 3 for streaming velocity subtracted in 0, 1, 2, or 3 +dimensions, respectively; *extra* is the number of extra degrees of freedom; +*N* is the number of atoms in the group; :math:`k_B` is the Boltzmann constant, +and :math:`T` is the absolute temperature. The :math:`N_s N_x N_y N_z` term is +the number of degrees of freedom subtracted to adjust for the removal of the +center-of-mass velocity in each direction of the *Nx\*Ny\*Nz* bins, as +discussed in the :ref:`(Evans) ` paper. The extra term defaults to +:math:`\text{dim} - N_s` and accounts for overall conservation of +center-of-mass velocity across the group in directions where streaming velocity +is *not* subtracted. This can be altered using the *extra* option of the :doc:`compute_modify ` command. -If the *out* keyword is used with a *tensor* value, which is the -default, a kinetic energy tensor, stored as a 6-element vector, is -also calculated by this compute for use in the computation of a -pressure tensor. The formula for the components of the tensor is the -same as the above formula, except that *v*\^2 is replaced by *vx\*vy* for -the xy component, etc. The 6 components of the vector are ordered *xx, -yy, zz, xy, xz, yz.* +If the *out* keyword is used with a *tensor* value, which is the default, +a kinetic energy tensor, stored as a six-element vector, is also calculated by +this compute for use in the computation of a pressure tensor. The formula for +the components of the tensor is the same as the above formula, except that +:math:`v^2` is replaced by :math:`v_x v_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`. -If the *out* keyword is used with a *bin* value, the count of atoms -and computed temperature for each bin are stored for output, as an -array of values, as described below. The temperature of each bin is -calculated as described above, where the bias velocity is subtracted -and only the remaining thermal velocity of atoms in the bin -contributes to the temperature. See the note below for how the -temperature is normalized by the degrees-of-freedom of atoms in the -bin. +If the *out* keyword is used with a *bin* value, the count of atoms and +computed temperature for each bin are stored for output, as an array of values, +as described below. The temperature of each bin is calculated as described +above, where the bias velocity is subtracted and only the remaining thermal +velocity of atoms in the bin contributes to the temperature. See the note +below for how the temperature is normalized by the degrees-of-freedom of atoms +in the bin. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the @@ -118,14 +123,17 @@ from the velocity of the atoms. If this compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining thermal velocity will be performed, and the bias will be added back in. Thermostatting -fixes that work in this way include :doc:`fix nvt `, :doc:`fix temp/rescale `, :doc:`fix temp/berendsen `, and :doc:`fix langevin `. +fixes that work in this way include :doc:`fix nvt `, +:doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, +and :doc:`fix langevin `. -This compute subtracts out degrees-of-freedom due to fixes that -constrain molecular motion, such as :doc:`fix shake ` and -:doc:`fix rigid `. This means the temperature of groups of -atoms that include these constraints will be computed correctly. If -needed, the subtracted degrees-of-freedom can be altered using the -*extra* option of the :doc:`compute_modify ` command. +This compute subtracts out degrees-of-freedom due to fixes that constrain +molecular motion, such as :doc:`fix shake ` and +:doc:`fix rigid `. This means the temperature of groups of atoms +that include these constraints will be computed correctly. If needed, the +subtracted degrees-of-freedom can be altered using the *extra* option of the +:doc:`compute_modify ` command. .. note:: @@ -137,11 +145,12 @@ needed, the subtracted degrees-of-freedom can be altered using the by fractionally applying them based on the fraction of atoms in each bin. As a result, the bin degrees-of-freedom summed over all bins exactly equals the degrees-of-freedom used in the scalar temperature calculation, - :math:`\Sigma N_{DOF_i} = N_{DOF}` and the corresponding relation for temperature - is also satisfied :math:`\Sigma N_{DOF_i} T_i = N_{DOF} T`. - These relations will breakdown in cases where the adjustment - exceeds the actual number of degrees-of-freedom in a bin. This could happen - if a bin is empty or in situations where rigid molecules + :math:`\Sigma N_{\text{DOF}_i} = N_\text{DOF}` and the corresponding + relation for temperature is also satisfied + (:math:`\Sigma N_{\text{DOF}_i} T_i = N_\text{DOF} T`). + These relations will break down in cases for which the adjustment + exceeds the actual number of degrees of freedom in a bin. This could happen + if a bin is empty or in situations in which rigid molecules are non-uniformly distributed, in which case the reported temperature within a bin may not be accurate. @@ -157,23 +166,25 @@ Output info This compute calculates a global scalar (the temperature). Depending on the setting of the *out* keyword, it also calculates a global vector or array. For *out* = *tensor*, it calculates a vector of -length 6 (KE tensor), which can be accessed by indices 1-6. For *out* -= *bin* it calculates a global array which has 2 columns and N rows, -where N is the number of bins. The first column contains the number +length 6 (KE tensor), which can be accessed by indices 1--6. For *out* += *bin* it calculates a global array which has 2 columns and :math:`N` rows, +where :math:`N` is the number of bins. The first column contains the number of atoms in that bin. The second contains the temperature of that bin, calculated as described above. The ordering of rows in the array -is as follows. Bins in x vary fastest, then y, then z. Thus for a -10x10x10 3d array of bins, there will be 1000 rows. The bin with -indices ix,iy,iz = 2,3,4 would map to row M = (iz-1)\*10\*10 + (iy-1)\*10 -+ ix = 322, where the rows are numbered from 1 to 1000 and the bin -indices are numbered from 1 to 10 in each dimension. +is as follows. Bins in :math:`x` vary fastest, then :math:`y`, then +:math:`z`. Thus for a :math:`10\times 10\times 10` 3d array of bins, there +will be 1000 rows. The bin with indices :math:`(i_x,i_y,i_z) = (2,3,4)` would +map to row :math:`M = 10^2(i_z-1) + 10(i_y-1) + i_x = 322`, where the rows are +numbered from 1 to 1000 and the bin indices are numbered from 1 to 10 in each +dimension. These values can be used by any command that uses global scalar or -vector or array values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output +vector or array values 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 "intensive". The -vector values are "extensive". The array values are "intensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The array values are "intensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. The first column diff --git a/doc/src/compute_temp_ramp.rst b/doc/src/compute_temp_ramp.rst index 9cda8bef30..13799874ab 100644 --- a/doc/src/compute_temp_ramp.rst +++ b/doc/src/compute_temp_ramp.rst @@ -6,7 +6,7 @@ compute temp/ramp command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/ramp vdim vlo vhi dim clo chi keyword value ... @@ -33,11 +33,11 @@ Examples Description """"""""""" -Define a computation that calculates the temperature of a group of -atoms, after subtracting out an ramped velocity profile before -computing the kinetic energy. A compute of this style can be used by -any command that computes a temperature, -e.g. :doc:`thermo_modify `, :doc:`fix temp/rescale `, :doc:`fix npt `, etc. +Define a computation that calculates the temperature of a group of atoms, +after subtracting out an ramped velocity profile before computing the kinetic +energy. A compute of this style can be used by any command that computes a +temperature (e.g. :doc:`thermo_modify `, +:doc:`fix temp/rescale `, :doc:`fix npt `). The meaning of the arguments for this command which define the velocity ramp are the same as for the :doc:`velocity ramp ` @@ -45,28 +45,33 @@ command which was presumably used to impose the velocity. After the ramp velocity has been subtracted from the specified dimension for each atom, the temperature is calculated by the formula -KE = dim/2 N k T, where KE = total kinetic energy of the group of -atoms (sum of 1/2 m v\^2), dim = 2 or 3 = dimensionality of the -simulation, N = number of atoms in the group, k = Boltzmann constant, -and T = temperature. + +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the simulation, +:math:`N` is the number of atoms in the group, :math:`k_B` is the Boltzmann +constant, and :math:`T` is the absolute temperature. The *units* keyword determines the meaning of the distance units used -for coordinates (c1,c2) and velocities (vlo,vhi). A *box* value +for coordinates (*clo*, *chi*) and velocities (*vlo*, *vhi*). A *box* value selects standard distance units as defined by the :doc:`units ` -command, e.g. Angstroms for units = real or metal. A *lattice* value -means the distance units are in lattice spacings; e.g. velocity = -lattice spacings / tau. The :doc:`lattice ` command must have -been previously used to define the lattice spacing. +command (e.g., :math:`\mathrm{\mathring{A}}` for units = real or metal). A +*lattice* value means the distance units are in lattice spacings (i.e., +velocity in lattice spacings per unit time). The :doc:`lattice ` +command must have been previously used to define the lattice spacing. -A kinetic energy tensor, stored as a 6-element vector, is also -calculated by this compute for use in the computation of a pressure -tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. +A kinetic energy tensor, stored as a six-element vector, is also calculated by +this compute for use in the computation of a pressure tensor. The formula for +the components of the tensor is the same as the above formula, except that +:math:`v^2` is replaced by :math:`v_x v_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`. -The number of atoms contributing to the temperature is assumed to be -constant for the duration of the run; use the *dynamic* option of the +The number of atoms contributing to the temperature is assumed to be constant +for the duration of the run; use the *dynamic* option of the :doc:`compute_modify ` command if this is not the case. The removal of the ramped velocity component by this fix is @@ -75,7 +80,10 @@ from the velocity of the atoms. If this compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining thermal velocity will be performed, and the bias will be added back in. Thermostatting -fixes that work in this way include :doc:`fix nvt `, :doc:`fix temp/rescale `, :doc:`fix temp/berendsen `, and :doc:`fix langevin `. +fixes that work in this way include :doc:`fix nvt `, +:doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, and +:doc:`fix langevin `. This compute subtracts out degrees-of-freedom due to fixes that constrain molecular motion, such as :doc:`fix shake ` and @@ -92,13 +100,14 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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 +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. diff --git a/doc/src/compute_temp_region.rst b/doc/src/compute_temp_region.rst index 86ae03be9b..c8a3075771 100644 --- a/doc/src/compute_temp_region.rst +++ b/doc/src/compute_temp_region.rst @@ -6,7 +6,7 @@ compute temp/region command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/region region-ID @@ -24,30 +24,37 @@ Examples Description """"""""""" -Define a computation that calculates the temperature of a group of -atoms in a geometric region. This can be useful for thermostatting -one portion of the simulation box. E.g. a McDLT simulation where one -side is cooled, and the other side is heated. A compute of this style -can be used by any command that computes a temperature, -e.g. :doc:`thermo_modify `, :doc:`fix temp/rescale `, etc. +Define a computation that calculates the temperature of a group of atoms in a +geometric region. This can be useful for thermostatting one portion of the +simulation box. For example, a McDLT simulation where one side is cooled, and +the other side is heated. A compute of this style can be used by any command +that computes a temperature (e.g., :doc:`thermo_modify `, +:doc:`fix temp/rescale `). Note that a *region*\ -style temperature can be used to thermostat with -:doc:`fix temp/rescale ` or :doc:`fix langevin `, but should probably not be used with -Nose/Hoover style fixes (:doc:`fix nvt `, :doc:`fix npt `, or :doc:`fix nph `), if the -degrees-of-freedom included in the computed T varies with time. +:doc:`fix temp/rescale ` or +:doc:`fix langevin `, but should probably not be used with +Nose--Hoover style fixes (:doc:`fix nvt `, :doc:`fix npt `, +or :doc:`fix nph `) if the degrees of freedom included in the computed +temperature vary with time. -The temperature is calculated by the formula KE = dim/2 N k T, where -KE = total kinetic energy of the group of atoms (sum of 1/2 m v\^2), -dim = 2 or 3 = dimensionality of the simulation, N = number of atoms -in both the group and region, k = Boltzmann constant, and T = -temperature. +The temperature is calculated by the formula -A kinetic energy tensor, stored as a 6-element vector, is also +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE = is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the simulation, +:math:`N` is the number of atoms in both the group and region, :math:`k_B` is +the Boltzmann constant, and :math:`T` temperature. + +A kinetic energy tensor, stored as a six-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. +the above formula, except that :math:`v^2` is replaced by :math:`v_x v_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`. The number of atoms contributing to the temperature is calculated each time the temperature is evaluated since it is assumed atoms can @@ -62,18 +69,19 @@ compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining thermal velocity will be performed, and the bias will be added back in. Thermostatting fixes that work in this way include -:doc:`fix nvt `, :doc:`fix temp/rescale `, :doc:`fix temp/berendsen `, and :doc:`fix langevin `. This means that when this compute +:doc:`fix nvt `, :doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, and +:doc:`fix langevin `. This means that when this compute is used to calculate the temperature for any of the thermostatting fixes via the :doc:`fix modify temp ` command, the thermostat -will operate only on atoms that are currently in the geometric -region. +will operate only on atoms that are currently in the geometric region. Unlike other compute styles that calculate temperature, this compute does not subtract out degrees-of-freedom due to fixes that constrain motion, such as :doc:`fix shake ` and :doc:`fix rigid `. This is because those degrees of freedom -(e.g. a constrained bond) could apply to sets of atoms that straddle +(e.g., a constrained bond) could apply to sets of atoms that straddle the region boundary, and hence the concept is somewhat ill-defined. -If needed the number of subtracted degrees-of-freedom can be set +If needed the number of subtracted degrees of freedom can be set explicitly using the *extra* option of the :doc:`compute_modify ` command. @@ -85,16 +93,17 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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 +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." -The scalar value will be in temperature :doc:`units `. The -vector values will be in energy :doc:`units `. +The scalar value will be in temperature :doc:`units `. +The vector values will be in energy :doc:`units `. Restrictions """""""""""" diff --git a/doc/src/compute_temp_region_eff.rst b/doc/src/compute_temp_region_eff.rst index d6623ec02d..ebfc35cbe6 100644 --- a/doc/src/compute_temp_region_eff.rst +++ b/doc/src/compute_temp_region_eff.rst @@ -6,7 +6,7 @@ compute temp/region/eff command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/region/eff region-ID @@ -26,26 +26,28 @@ Description Define a computation that calculates the temperature of a group of nuclei and electrons in the :doc:`electron force field ` -model, within a geometric region using the electron force field. A -compute of this style can be used by commands that compute a -temperature, e.g. :doc:`thermo_modify `. +model, within a geometric region using the electron force field. +A compute of this style can be used by commands that compute a +temperature (e.g., :doc:`thermo_modify `). The operation of this compute is exactly like that described by the :doc:`compute temp/region ` command, except that the formula for the temperature itself includes the radial electron -velocity contributions, as discussed by the :doc:`compute temp/eff ` command. +velocity contributions, as discussed by the +:doc:`compute temp/eff ` command. Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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 +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. @@ -54,12 +56,15 @@ Restrictions """""""""""" This compute is part of the EFF package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +LAMMPS was built with that package. +See the :doc:`Build package ` page for more info. Related commands """""""""""""""" -:doc:`compute temp/region `, :doc:`compute temp/eff `, :doc:`compute pressure ` +:doc:`compute temp/region `, +:doc:`compute temp/eff `, +:doc:`compute pressure ` Default """"""" diff --git a/doc/src/compute_temp_rotate.rst b/doc/src/compute_temp_rotate.rst index a0e2cb14ac..e760a49b00 100644 --- a/doc/src/compute_temp_rotate.rst +++ b/doc/src/compute_temp_rotate.rst @@ -6,7 +6,7 @@ compute temp/rotate command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/rotate @@ -24,36 +24,46 @@ Description """"""""""" Define a computation that calculates the temperature of a group of -atoms, after subtracting out the center-of-mass velocity and angular velocity of the group. -This is useful if the group is expected to have a non-zero net -velocity and/or global rotation motion for some reason. A compute of this style can be used by any -command that computes a temperature, -e.g. :doc:`thermo_modify `, :doc:`fix temp/rescale `, :doc:`fix npt `, etc. +atoms, after subtracting out the center-of-mass velocity and angular velocity +of the group. This is useful if the group is expected to have a non-zero net +velocity and/or global rotation motion for some reason. A compute of this +style can be used by any command that computes a temperature +(e.g., :doc:`thermo_modify `, +:doc:`fix temp/rescale `, :doc:`fix npt `). -After the center-of-mass velocity and angular velocity has been subtracted from each atom, -the temperature is calculated by the formula KE = dim/2 N k T, where -KE = total kinetic energy of the group of atoms (sum of 1/2 m v\^2), -dim = 2 or 3 = dimensionality of the simulation, N = number of atoms -in the group, k = Boltzmann constant, and T = temperature. +After the center-of-mass velocity and angular velocity has been subtracted from +each atom, the temperature is calculated by the formula -A kinetic energy tensor, stored as a 6-element vector, is also -calculated by this compute for use in the computation of a pressure -tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the simulation, +:math:`N` is the number of atoms in the group, :math:`k_B` is the Boltzmann +constant, and :math:`T` is the absolute temperature. + +A kinetic energy tensor, stored as a six-element vector, is also calculated by +this compute for use in the computation of a pressure tensor. The formula for +the components of the tensor is the same as the above formula, except that +:math:`v^2` is replaced by :math:`v_x v_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`. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the :doc:`compute_modify ` command if this is not the case. -The removal of the center-of-mass velocity and angular velocity by this fix is essentially -computing the temperature after a "bias" has been removed from the +The removal of the center-of-mass velocity and angular velocity by this fix is +essentially computing the temperature after a "bias" has been removed from the velocity of the atoms. If this compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining thermal velocity will be performed, and the bias will be added back in. Thermostatting fixes -that work in this way include :doc:`fix nvt `, :doc:`fix temp/rescale `, :doc:`fix temp/berendsen `, and :doc:`fix langevin `. +that work in this way include :doc:`fix nvt `, +:doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, and +:doc:`fix langevin `. This compute subtracts out degrees-of-freedom due to fixes that constrain molecular motion, such as :doc:`fix shake ` and @@ -72,11 +82,12 @@ Output info This compute calculates a global scalar (the temperature) and a global vector of length 6 (KE tensor), which can be accessed by indices 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 +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. @@ -85,7 +96,8 @@ Restrictions """""""""""" This compute is part of the EXTRA-COMPUTE package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +LAMMPS was built with that package. +See the :doc:`Build package ` page for more info. Related commands """""""""""""""" diff --git a/doc/src/compute_temp_sphere.rst b/doc/src/compute_temp_sphere.rst index b752719741..3f41837013 100644 --- a/doc/src/compute_temp_sphere.rst +++ b/doc/src/compute_temp_sphere.rst @@ -6,7 +6,7 @@ compute temp/sphere command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/sphere keyword value ... @@ -42,26 +42,27 @@ usual :doc:`compute temp ` command, which assumes point particles with only translational kinetic energy. Both point and finite-size particles can be included in the group. -Point particles do not rotate, so they have only 3 translational -degrees of freedom. For 3d spherical particles, each has 6 degrees of -freedom (3 translational, 3 rotational). For 2d spherical particles, -each has 3 degrees of freedom (2 translational, 1 rotational). +Point particles do not rotate, so they have only three translational +degrees of freedom. For 3d spherical particles, each has six degrees of +freedom (three translational, three rotational). For 2d spherical particles, +each has three degrees of freedom (two translational, one rotational). .. note:: - This choice for degrees of freedom (dof) assumes that all + This choice for degrees of freedom (DOF) assumes that all finite-size spherical particles in your model will freely rotate, - sampling all their rotational dof. It is possible to use a + sampling all their rotational DOF. It is possible to use a combination of interaction potentials and fixes that induce no torque or otherwise constrain some of all of your particles so that this is - not the case. Then there are less dof and you should use the - :doc:`compute_modify extra ` command to adjust the dof + not the case. Then there are less DOF and you should use the + :doc:`compute_modify extra ` command to adjust the DOF accordingly. The translational kinetic energy is computed the same as is described by the :doc:`compute temp ` command. The rotational -kinetic energy is computed as 1/2 I w\^2, where I is the moment of -inertia for a sphere and w is the particle's angular velocity. +kinetic energy is computed as :math:`\frac12 I \omega^2`, where :math:`I` is +the moment of inertia for a sphere and :math:`\omega` is the particle's angular +velocity. .. note:: @@ -69,11 +70,12 @@ inertia for a sphere and w is the particle's angular velocity. spheres, not disks, meaning their moment of inertia will be the same as in 3d. -A kinetic energy tensor, stored as a 6-element vector, is also +A kinetic energy tensor, stored as a six-element vector, is also calculated by this compute. The formula for the components of the -tensor is the same as the above formulas, except that v\^2 and w\^2 are -replaced by vx\*vy and wx\*wy for the xy component. The 6 components of -the vector are ordered xx, yy, zz, xy, xz, yz. +tensor is the same as the above formulas, except that :math:`v^2` and +:math:`\omega^2` are replaced by :math:`v_x v_y` and :math:`\omega_x \omega_y` +for the :math:`xy` component. The six components of the vector are ordered +:math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`, :math:`yz`. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the @@ -82,7 +84,7 @@ constant for the duration of the run; use the *dynamic* option of the This compute subtracts out translational degrees-of-freedom due to fixes that constrain molecular motion, such as :doc:`fix shake ` and :doc:`fix rigid `. This means the temperature of groups of atoms that include these constraints will be -computed correctly. If needed, the subtracted degrees-of-freedom can +computed correctly. If needed, the subtracted degrees of freedom can be altered using the *extra* option of the :doc:`compute_modify ` command. @@ -98,14 +100,14 @@ For the *bias* keyword, *bias-ID* refers to the ID of a temperature compute that removes a "bias" velocity from each atom. This allows compute temp/sphere to compute its thermal temperature after the translational kinetic energy components have been altered in a -prescribed way, e.g. to remove a flow velocity profile. Thermostats +prescribed way (e.g., to remove a flow velocity profile). Thermostats that use this compute will work with this bias term. See the doc pages for individual computes that calculate a temperature and the doc pages for fixes that perform thermostatting for more details. For the *dof* keyword, a setting of *all* calculates a temperature -that includes both translational and rotational degrees of freedom. A -setting of *rotate* calculates a temperature that includes only +that includes both translational and rotational degrees of freedom. +A setting of *rotate* calculates a temperature that includes only rotational degrees of freedom. ---------- @@ -114,13 +116,14 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. +vector of length 6 (KE tensor), which can be accessed by indices 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. +vector values 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 "intensive". The -vector values are "extensive". +The scalar value calculated by this compute is "intensive." The +vector values are "extensive." The scalar value will be in temperature :doc:`units `. The vector values will be in energy :doc:`units `. diff --git a/doc/src/compute_temp_uef.rst b/doc/src/compute_temp_uef.rst index 782b5b9acb..fc3b7937ed 100644 --- a/doc/src/compute_temp_uef.rst +++ b/doc/src/compute_temp_uef.rst @@ -6,7 +6,7 @@ compute temp/uef command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID temp/uef @@ -38,8 +38,9 @@ documentation for :doc:`compute temp `. 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. +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. This command can only be used when :doc:`fix nvt/uef ` or :doc:`fix npt/uef ` is active. diff --git a/doc/src/compute_ti.rst b/doc/src/compute_ti.rst index e377042dcf..a32f0d1b18 100644 --- a/doc/src/compute_ti.rst +++ b/doc/src/compute_ti.rst @@ -6,14 +6,14 @@ compute ti command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group ti keyword args ... * ID, group-ID are documented in :doc:`compute ` command * ti = style name of this compute command * one or more attribute/arg pairs may be appended -* keyword = pair style (lj/cut, gauss, born, etc) or *tail* or *kspace* +* keyword = pair style (lj/cut, gauss, born, etc.) or *tail* or *kspace* .. parsed-literal:: @@ -47,81 +47,85 @@ thermodynamic integration. This derivative can be used to infer a free energy difference resulting from an alchemical simulation, as described in :ref:`Eike `. -Typically this compute will be used in conjunction with the :doc:`fix adapt ` command which can perform alchemical +Typically this compute will be used in conjunction with the +:doc:`fix adapt ` command which can perform alchemical transformations by adjusting the strength of an interaction potential as a simulation runs, as defined by one or more :doc:`pair_style ` or :doc:`kspace_style ` commands. This scaling is done via a prefactor on the energy, forces, -virial calculated by the pair or K-Space style. The prefactor is -often a function of a *lambda* parameter which may be adjusted from 0 -to 1 (or vice versa) over the course of a :doc:`run `. The -time-dependent adjustment is what the :doc:`fix adapt ` +virial calculated by the pair or :math:`k`-space style. The prefactor is +often a function of a *lambda* parameter which may be adjusted from 0 to 1 +(or vice versa) over the course of a :doc:`run `. +The time-dependent adjustment is what the :doc:`fix adapt ` command does. Assume that the unscaled energy of a pair_style or kspace_style is -given by U. Then the scaled energy is +given by :math:`U`. Then the scaled energy is -.. parsed-literal:: +.. math:: - Us = f(lambda) U + U_s = f(\lambda) U -where f() is some function of lambda. What this compute calculates is +where :math:`f` is some function of :math:`\lambda`. What this compute +calculates is -.. parsed-literal:: +.. math:: - dUs / d(lambda) = U df(lambda)/dlambda = Us / f(lambda) df(lambda)/dlambda + \frac{dU_s}{d\lambda} = U \frac{df(\lambda)}{d\lambda} + = \frac{U_s}{f(\lambda)} \frac{df(\lambda)}{d\lambda}, -which is the derivative of the system's scaled potential energy Us -with respect to *lambda*\ . +which is the derivative of the system's scaled potential energy :math:`U_s` +with respect to :math:`\lambda`. To perform this calculation, you provide one or more atom types as -*atype*\ . *Atype* can be specified in one of two ways. An explicit -numeric values can be used, as in the first example above. Or a +*atype*\ . The variable *atype* can be specified in one of two ways. +An explicit numeric value can be used, as in the first example above, or a wildcard asterisk can be used in place of or in conjunction with the *atype* argument to select multiple 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 +"\*" 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 N (inclusive). A middle asterisk means all types from m to n (inclusive). -You also specify two functions, as :doc:`equal-style variables `. The first is specified as *v_name1*, where -*name1* is the name of the variable, and is f(lambda) in the notation -above. The second is specified as *v_name2*, where *name2* is the -name of the variable, and is df(lambda) / dlambda in the notation -above. I.e. it is the analytic derivative of f() with respect to -lambda. Note that the *name1* variable is also typically given as an +You also specify two functions, as :doc:`equal-style variables `. +The first is specified as *v_name1*, where *name1* is the name of the +variable, and is :math:`f(\lambda)` in the notation above. The second is +specified as *v_name2*, where *name2* is the name of the variable, and is +:math:`df(\lambda)/d\lambda` in the notation above (i.e., it is the analytic +derivative of :math:`f` with respect to :math:`\lambda`). +Note that the *name1* variable is also typically given as an argument to the :doc:`fix adapt ` command. An alchemical simulation may use several pair potentials together, invoked via the :doc:`pair_style hybrid or hybrid/overlay ` -command. The total dUs/dlambda for the overall system is calculated +command. The total :math:`dU_s/d\lambda` for the overall system is calculated as the sum of each contributing term as listed by the keywords in the -compute ti command. Individual pair potentials can be listed, which -will be sub-styles in the hybrid case. You can also include a K-space -term via the *kspace* keyword. You can also include a pairwise +:doc:`compute ti ` command. Individual pair potentials can be +listed, which will be sub-styles in the hybrid case. You can also include a +:math:`k`-space term via the *kspace* keyword. You can also include a pairwise long-range tail correction to the energy via the *tail* keyword. -For each term you can specify a different (or the same) scale factor +For each term, you can specify a different (or the same) scale factor by the two variables that you list. Again, these will typically correspond toe the scale factors applied to these various potentials -and the K-Space contribution via the :doc:`fix adapt ` +and the :math:`k`-space contribution via the :doc:`fix adapt ` command. More details about the exact functional forms for the computation of -du/dl can be found in the paper by :ref:`Eike `. +:math:`du/dl` can be found in the paper by :ref:`Eike `. ---------- Output info """"""""""" -This compute calculates a global scalar, namely dUs/dlambda. This +This compute calculates a global scalar, namely :math:`dU_s/d\lambda`. This 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 scalar value calculated by this compute is "extensive." The scalar value will be in energy :doc:`units `. @@ -129,7 +133,8 @@ Restrictions """""""""""" This compute is part of the EXTRA-COMPUTE package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +LAMMPS was built with that package. See the +:doc:`Build package ` page for more info. Related commands """""""""""""""" diff --git a/doc/src/compute_torque_chunk.rst b/doc/src/compute_torque_chunk.rst index 61ecdf0e6e..97c9c127b8 100644 --- a/doc/src/compute_torque_chunk.rst +++ b/doc/src/compute_torque_chunk.rst @@ -6,7 +6,7 @@ compute torque/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID torque/chunk chunkID @@ -27,14 +27,17 @@ Description Define a computation that calculates the torque on 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 torque vector for eqch +This compute calculates the three components of the torque vector for eqch chunk, due to the forces on the individual atoms in the chunk around the center-of-mass of the chunk. The calculation includes all effects due to atoms passing through periodic boundaries. @@ -55,7 +58,8 @@ non-zero chunk IDs. "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 torque/chunk calculation to a file is to use the :doc:`fix ave/time ` @@ -70,14 +74,16 @@ 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 torque 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 ` doc page +This compute calculates a global array where the number of rows is equal to the +number of chunks *Nchunk* as calculated by the specified +:doc:`compute chunk/atom ` command. The number of columns +is three for the :math:`x`, :math:`y`, and :math:`z` components of the torque +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 ` doc 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 force-distance :doc:`units `. Restrictions diff --git a/doc/src/compute_vacf.rst b/doc/src/compute_vacf.rst index 7b5ea78a3a..c94277f43b 100644 --- a/doc/src/compute_vacf.rst +++ b/doc/src/compute_vacf.rst @@ -6,7 +6,7 @@ compute vacf command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID vacf @@ -29,13 +29,14 @@ function (VACF), averaged over a group of atoms. Each atom's contribution to the VACF is its current velocity vector dotted into its initial velocity vector at the time the compute was specified. -A vector of four quantities is calculated by this compute. The first 3 -elements of the vector are vx \* vx0 (and similarly for the y and z -components), summed and averaged over atoms in the group. Vx is the -current x-component of velocity for the atom, vx0 is the initial -x-component of velocity for the atom. The fourth element of the vector -is the total VACF, i.e. (vx\*vx0 + vy\*vy0 + vz\*vz0), summed and -averaged over atoms in the group. +A vector of four quantities is calculated by this compute. The first three +elements of the vector are :math:`v_x v_{x,0}` (and similar for the +:math:`y` and :math:`z` components), summed and averaged over atoms in the +group, where :math:`v_x` is the current :math:`x`-component of the velocity of +the atom and :math:`v_{x,0}` is the initial :math:`x`-component of the velocity +of the atom. The fourth element of the vector is the total VACF +(i.e., :math:`(v_x v_{x,0} + v_y v_{y,0} + v_z v_{z,0})`), +summed and averaged over atoms in the group. The integral of the VACF versus time is proportional to the diffusion coefficient of the diffusing atoms. This can be computed in the @@ -61,12 +62,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 -velocity\^2 :doc:`units `. +The vector values are "intensive." The vector values will be in +velocity\ :math:`^2` :doc:`units `. Restrictions """""""""""" diff --git a/doc/src/compute_vcm_chunk.rst b/doc/src/compute_vcm_chunk.rst index 190947b087..5579208766 100644 --- a/doc/src/compute_vcm_chunk.rst +++ b/doc/src/compute_vcm_chunk.rst @@ -6,7 +6,7 @@ compute vcm/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID vcm/chunk chunkID @@ -27,14 +27,15 @@ Description Define a computation that calculates the center-of-mass velocity for multiple chunks of atoms. -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. +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. -This compute calculates the x,y,z components of the center-of-mass +This compute calculates the :math:`(x,y,z)` components of the center-of-mass velocity for each chunk. This is done by summing mass\*velocity for each atom in the chunk and dividing the sum by the total mass of the chunk. @@ -60,19 +61,20 @@ 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 x,y,z center-of-mass velocity coordinates of 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. +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 :math:`(x,y,z)` center-of-mass velocity coordinates of +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. -The array values are "intensive". The array values will be in +The array values are "intensive." The array values will be in velocity :doc:`units `. Restrictions """""""""""" - none +none Related commands """""""""""""""" diff --git a/doc/src/compute_viscosity_cos.rst b/doc/src/compute_viscosity_cos.rst index 2f7a09924c..a3adf3d78b 100644 --- a/doc/src/compute_viscosity_cos.rst +++ b/doc/src/compute_viscosity_cos.rst @@ -7,7 +7,7 @@ Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID viscosity/cos @@ -35,64 +35,69 @@ Description Define a computation that calculates the velocity amplitude of a group of atoms with an cosine-shaped velocity profile and the temperature of them after subtracting out the velocity profile before computing the kinetic energy. -A compute of this style can be used by any command that computes a temperature, -e.g. :doc:`thermo_modify `, :doc:`fix npt `, etc. +A compute of this style can be used by any command that computes a temperature +(e.g., :doc:`thermo_modify `, :doc:`fix npt `). This command together with :doc:`fix_accelerate/cos` enables viscosity calculation with periodic perturbation method, as described by :ref:`Hess`. -An acceleration along the x-direction is applied to the simulation system -by using :doc:`fix_accelerate/cos` command. -The acceleration is a periodic function along the z-direction: +An acceleration along the :math:`x`-direction is applied to the simulation +system by using :doc:`fix_accelerate/cos` command. +The acceleration is a periodic function along the :math:`z`-direction: .. math:: a_{x}(z) = A \cos \left(\frac{2 \pi z}{l_{z}}\right) -where :math:`A` is the acceleration amplitude, :math:`l_z` is the z-length -of the simulation box. At steady state, the acceleration generates -a velocity profile: +where :math:`A` is the acceleration amplitude, :math:`l_z` is the +:math:`z`-length of the simulation box. At steady state, the acceleration +generates a velocity profile: .. math:: v_{x}(z) = V \cos \left(\frac{2 \pi z}{l_{z}}\right) The generated velocity amplitude :math:`V` is related to the -shear viscosity :math:`\eta` by: +shear viscosity :math:`\eta` by .. math:: - V = \frac{A \rho}{\eta}\left(\frac{l_{z}}{2 \pi}\right)^{2} + V = \frac{A \rho}{\eta}\left(\frac{l_{z}}{2 \pi}\right)^{2}, - -and it can be obtained from ensemble average of the velocity profile: +and it can be obtained from ensemble average of the velocity profile via .. math:: - V = \frac{\sum_i 2 m_{i} v_{i, x} \cos \left(\frac{2 \pi z_i}{l_{z}}\right)}{\sum_i m_{i}} - + V = \frac{\sum\limits_i 2 m_{i} v_{i, x} \cos \left(\frac{2 \pi z_i}{l_{z}}\right)}{\sum\limits_i m_{i}} where :math:`m_i`, :math:`v_{i,x}` and :math:`z_i` are the mass, -x-component velocity and z coordinate of a particle. +:math:`x`-component velocity, and :math:`z`-coordinate of a particle, +respectively. -After the cosine-shaped collective velocity in :math:`x` direction -has been subtracted for each atom, the temperature is calculated by the formula -KE = dim/2 N k T, where KE = total kinetic energy of the group of -atoms (sum of 1/2 m v\^2), dim = 2 or 3 = dimensionality of the -simulation, N = number of atoms in the group, k = Boltzmann constant, -and T = temperature. +After the cosine-shaped collective velocity in the :math:`x`-direction has been +subtracted for each atom, the temperature is calculated by the formula -A kinetic energy tensor, stored as a 6-element vector, is also +.. math:: + + \text{KE} = \frac{\text{dim}}{2} N k_B T, + +where KE is the total kinetic energy of the group of atoms (sum of +:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the simulation, +:math:`N` is the number of atoms in the group, :math:`k_B` is the Boltzmann +constant, and :math:`T` is the absolute temperature. + +A kinetic energy tensor, stored as a six-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. +the above formula, except that :math:`v^2` is replaced by :math:`v_x v_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`. The number of atoms contributing to the temperature is assumed to be constant for the duration of the run; use the *dynamic* option of the :doc:`compute_modify ` command if this is not the case. -However, in order to get meaningful result, the group ID of this compute should be all. +However, in order to get meaningful result, the group ID of this compute should +be all. The removal of the cosine-shaped velocity component by this command is essentially computing the temperature after a "bias" has been removed @@ -100,18 +105,20 @@ from the velocity of the atoms. If this compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining thermal velocity will be performed, and the bias will be added back in. Thermostatting -fixes that work in this way include :doc:`fix nvt `, :doc:`fix temp/rescale `, :doc:`fix temp/berendsen `, and :doc:`fix langevin `. +fixes that work in this way include :doc:`fix nvt `, +:doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, and +:doc:`fix langevin `. -This compute subtracts out degrees-of-freedom due to fixes that +This compute subtracts out degrees of freedom due to fixes that constrain molecular motion, such as :doc:`fix shake ` and -:doc:`fix rigid `. This means the temperature of groups of +:doc:`fix rigid `. This means that the temperature of groups of atoms that include these constraints will be computed correctly. If -needed, the subtracted degrees-of-freedom can be altered using the +needed, the subtracted degrees of freedom can be altered using the *extra* option of the :doc:`compute_modify ` command. -See the :doc:`Howto thermostat ` page for a -discussion of different ways to compute temperature and perform -thermostatting. +See the :doc:`Howto thermostat ` page for a discussion of +different ways to compute temperature and perform thermostatting. ---------- @@ -119,28 +126,28 @@ Output info """"""""""" This compute calculates a global scalar (the temperature) and a global -vector of length 7, which can be accessed by indices 1-7. -The first 6 elements of the vector are the KE tensor, -and the 7-th is the cosine-shaped velocity amplitude :math:`V`, +vector of length 7, which can be accessed by indices 1--7. +The first six elements of the vector are the KE tensor, +and the seventh is the cosine-shaped velocity amplitude :math:`V`, which can be used to calculate the reciprocal viscosity, as shown in the example. 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 scalar value calculated by this compute is "intensive". The -first 6 elements of vector values are "extensive", -and the 7-th element of vector values is "intensive". +The scalar value calculated by this compute is "intensive." The +first six elements of vector values are "extensive," +and the seventh element of vector values is "intensive." -The scalar value will be in temperature :doc:`units `. The -first 6 elements of vector values will be in energy :doc:`units `. -The 7-th element of vector value will be in velocity :doc:`units `. +The scalar value will be in temperature :doc:`units `. +The first six elements of vector values will be in energy :doc:`units `. +The seventh element of vector value will be in velocity :doc:`units `. Restrictions """""""""""" This command is only available when LAMMPS was built with the MISC package. -Since this compute depends on :doc:`fix accelerate/cos ` which can -only work for 3d systems, it cannot be used for 2d systems. +Since this compute depends on :doc:`fix accelerate/cos ` +which can only work for 3d systems, it cannot be used for 2d systems. Related commands """""""""""""""" diff --git a/doc/src/compute_voronoi_atom.rst b/doc/src/compute_voronoi_atom.rst index a84590ff02..e1f8de0667 100644 --- a/doc/src/compute_voronoi_atom.rst +++ b/doc/src/compute_voronoi_atom.rst @@ -6,15 +6,14 @@ compute voronoi/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID voronoi/atom keyword arg ... * ID, group-ID are documented in :doc:`compute ` command * voronoi/atom = style name of this compute command * zero or more keyword/value pairs may be appended -* keyword = *only_group* or *surface* or *radius* or *edge_histo* or *edge_threshold* - or *face_threshold* or *neighbors* or *peratom* +* keyword = *only_group* or *surface* or *radius* or *edge_histo* or *edge_threshold* or *face_threshold* or *neighbors* or *peratom* .. parsed-literal:: @@ -80,7 +79,7 @@ In the example above, a precipitate embedded in a matrix, only atoms at the surface of the precipitate will have non-zero surface area, and only the outward facing facets of the Voronoi cells are counted (the hull of the precipitate). The total surface area of the precipitate -can be obtained by running a "reduce sum" compute on c_2[3] +can be obtained by running a "reduce sum" compute on c_2[3]. If the *radius* keyword is specified with an atom style variable as the argument, a poly-disperse Voronoi tessellation is @@ -149,7 +148,8 @@ with areas greater than the threshold are stored. ---------- -The Voronoi calculation is performed by the freely available `Voro++ package `_, written by Chris Rycroft at UC Berkeley and LBL, +The Voronoi calculation is performed by the freely available +`Voro++ package `_, written by Chris Rycroft at UC Berkeley and LBL, which must be installed on your system when building LAMMPS for use with this compute. See instructions on obtaining and installing the Voro++ software in the src/VORONOI/README file. @@ -169,49 +169,51 @@ Voro++ software in the src/VORONOI/README file. :doc:`pair_style ` interactions. The cutoff can be set explicitly via the :doc:`comm_modify cutoff ` command. The Voronoi cells for atoms adjacent to empty regions will extend into - those regions up to the communication cutoff in x, y, or z. In that - situation, an exterior face is created at the cutoff distance normal - to the x, y, or z direction. For triclinic systems, the exterior face - is parallel to the corresponding reciprocal lattice vector. + those regions up to the communication cutoff in :math:`x`, :math:`y`, or + :math:`z`. In that situation, an exterior face is created at the cutoff + distance normal to the :math:`x`, :math:`y`, or :math:`z` direction. + For triclinic systems, the exterior face is parallel to the corresponding + reciprocal lattice vector. .. note:: The Voro++ package performs its calculation in 3d. This will still work for a 2d LAMMPS simulation, provided all the atoms have the - same z coordinate. The Voronoi cell of each atom will be a columnar - polyhedron with constant cross-sectional area along the z direction + same :math:`z`-coordinate. The Voronoi cell of each atom will be a columnar + polyhedron with constant cross-sectional area along the :math:`z`-direction and two exterior faces at the top and bottom of the simulation box. If - the atoms do not all have the same z coordinate, then the columnar + the atoms do not all have the same :math:`z`-coordinate, then the columnar cells will be accordingly distorted. The cross-sectional area of each - Voronoi cell can be obtained by dividing its volume by the z extent of - the simulation box. Note that you define the z extent of the + Voronoi cell can be obtained by dividing its volume by the :math:`z` extent + of the simulation box. Note that you define the :math:`z` extent of the simulation box for 2d simulations when using the :doc:`create_box ` or :doc:`read_data ` commands. Output info """"""""""" -By default, this compute calculates a per-atom array with 2 +By default, this compute calculates a per-atom array with two columns. In regular dynamic tessellation mode the first column is the Voronoi volume, the second is the neighbor count, as described above (read above for the output data in case the *occupation* keyword is specified). These values can be accessed by 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. If the *peratom* keyword is set to "no", the per-atom array +options. If the *peratom* keyword is set to "no," the per-atom array is still created, but it is not accessible. If the *edge_histo* keyword is used, then this compute generates a global vector of length *maxedge*\ +1, containing a histogram of the number of edges per face. -If the *neighbors* value is set to yes, then this compute calculates a -local array with 3 columns. There is one row for each face of each +If the *neighbors* value is set to *yes*, then this compute calculates a +local array with three columns. There is one row for each face of each Voronoi cell. .. note:: - Some LAMMPS commands such as the :doc:`compute reduce ` command can accept either a per-atom or - local quantity. If this compute produces both quantities, the command + Some LAMMPS commands such as the :doc:`compute reduce ` + command can accept either a per-atom or local quantity. If this compute + produces both quantities, the command may access the per-atom quantity, even if you want to access the local quantity. This effect can be eliminated by using the *peratom* keyword to turn off the production of the per-atom quantities. For diff --git a/doc/src/compute_xrd.rst b/doc/src/compute_xrd.rst index 480bee6150..39dc78a314 100644 --- a/doc/src/compute_xrd.rst +++ b/doc/src/compute_xrd.rst @@ -6,7 +6,7 @@ compute xrd command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS compute ID group-ID xrd lambda type1 type2 ... typeN keyword value ... @@ -45,30 +45,31 @@ Examples Description """"""""""" -Define a computation that calculates x-ray diffraction intensity as described +Define a computation that calculates X-ray diffraction intensity as described in :ref:`(Coleman) ` on a mesh of reciprocal lattice nodes defined by the entire simulation domain (or manually) using a simulated radiation -of wavelength lambda. +of wavelength *lambda*. -The x-ray diffraction intensity, I, at each reciprocal lattice point, k, -is computed from the structure factor, F, using the equations: +The X-ray diffraction intensity, :math:`I`, at each reciprocal lattice point, +:math:`k`, is computed from the structure factor, :math:`F`, using the +equations: .. math:: - I = & Lp(\theta)\frac{F^{*}F}{N} \\ - F(\mathbf{k}) = & \sum_{j=1}^{N}f_j(\theta)exp(2\pi i \mathbf{k}\cdot \mathbf{r}_j) \\ - Lp(\theta) = & \frac{1+cos^{2}(2\theta)}{cos(\theta)sin^{2}(\theta)} \\ - \frac{sin(\theta)}{\lambda} = & \frac{\left | \mathbf{k} \right |}{2} + I &= L_p(\theta)\frac{F^{*}F}{N} \\ + F(\mathbf{k}) &= \sum_{j=1}^{N}f_j(\theta)exp(2\pi i \mathbf{k}\cdot \mathbf{r}_j) \\ + L_p(\theta) &= \frac{1+\cos^2(2\theta)}{\cos(\theta)\sin^2(\theta)} \\ + \frac{\sin(\theta)}{\lambda} &= \frac{\left\lVert\mathbf{k}\right\rVert}{2} -Here, K is the location of the reciprocal lattice node, :math:`r_j` is the -position of each atom, :math:`f_j` are atomic scattering factors, *Lp* is the -Lorentz-polarization factor, and :math:`\theta` is the scattering angle of -diffraction. The Lorentz-polarization factor can be turned off using -the optional *LP* keyword. +Here, :math:`\mathbf{k}` is the location of the reciprocal lattice node, +:math:`r_j` is the position of each atom, :math:`f_j` are atomic scattering +factors, *Lp* is the Lorentz-polarization factor, and :math:`\theta` is the +scattering angle of diffraction. The Lorentz-polarization factor can be turned +off using the optional *LP* keyword. Diffraction intensities are calculated on a three-dimensional mesh of -reciprocal lattice nodes. The mesh spacing is defined either (a) -by the entire simulation domain or (b) manually using selected values as +reciprocal lattice nodes. The mesh spacing is defined either (a) by the entire +simulation domain or (b) manually using selected values as shown in the 2D diagram below. .. image:: img/xrd_mesh.jpg @@ -76,29 +77,29 @@ shown in the 2D diagram below. :align: center For a mesh defined by the simulation domain, a rectilinear grid is -constructed with spacing *c*\ \*inv(A) along each reciprocal lattice -axis. Where A are the vectors corresponding to the edges of the -simulation cell. If one or two directions has non-periodic boundary -conditions, then the spacing in these directions is defined from the +constructed with spacing :math:`c A^{-1}` along each reciprocal lattice +axis, where :math:`A` is a matrix containing the vectors corresponding to the +edges of the simulation cell. If one or two directions has non-periodic +boundary conditions, then the spacing in these directions is defined from the average of the (inversed) box lengths with periodic boundary conditions. Meshes defined by the simulation domain must contain at least one periodic boundary. If the *manual* flag is included, the mesh of reciprocal lattice nodes -will defined using the *c* values for the spacing along each +will be defined using the *c* values for the spacing along each reciprocal lattice axis. Note that manual mapping of the reciprocal space mesh is good for comparing diffraction results from multiple -simulations; however it can reduce the likelihood that Bragg -reflections will be satisfied unless small spacing parameters (< 0.05 -Angstrom\^(-1)) are implemented. Meshes with manual spacing do not -require a periodic boundary. +simulations; however, it can reduce the likelihood that Bragg +reflections will be satisfied unless small spacing parameters +(:math:`< 0.05~\mathrm{\mathring{A}}^{-1}`) are implemented. +Meshes with manual spacing do not require a periodic boundary. The limits of the reciprocal lattice mesh are determined by range of -scattering angles explored. The *2Theta* parameters allows the user +scattering angles explored. The *2Theta* parameter allows the user to reduce the scattering angle range to only the region of interest which reduces the cost of the computation. -The atomic scattering factors, fj, accounts for the reduction in +The atomic scattering factor, :math:`f_j`, accounts for the reduction in diffraction intensity due to Compton scattering. Compute xrd uses analytical approximations of the atomic scattering factors that vary for each atom type (type1 type2 ... typeN) and angle of diffraction. @@ -107,8 +108,8 @@ The analytic approximation is computed using the formula .. math:: - f_j\left ( \frac{sin(\theta)}{\lambda} \right )=\sum_{i}^{4} - a_i exp\left ( -b_i \frac{sin^{2}(\theta)}{\lambda^{2}} \right )+c + f_j\left ( \frac{\sin(\theta)}{\lambda} \right )=\sum_{i=1}^{4} + a_i \exp\left ( -b_i \frac{\sin^{2}(\theta)}{\lambda^{2}} \right )+c Coefficients parameterized by :ref:`(Peng) ` are assigned for each atom type designating the chemical symbol and charge of each atom @@ -208,7 +209,7 @@ Output info This compute calculates a global array. The number of rows in the array is the number of reciprocal lattice nodes that are explored -which by the mesh. The global array has 2 columns. +which by the mesh. The global array has two columns. The first column contains the diffraction angle in the units (radians or degrees) provided with the *2Theta* values. The second column contains @@ -218,7 +219,7 @@ The array can be accessed by any command that uses global values from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output options. -All array values calculated by this compute are "intensive". +All array values calculated by this compute are "intensive." Restrictions """""""""""" @@ -237,7 +238,7 @@ Related commands Default """"""" -The option defaults are 2Theta = 1 179 (degrees), c = 1 1 1, LP = 1, +The option defaults are *2Theta* = 1 179 (degrees), *c* = 1 1 1, *LP* = 1, no manual flag, no echo flag. ---------- diff --git a/doc/src/create_atoms.rst b/doc/src/create_atoms.rst index 3834fbb71f..489d4fa5d1 100644 --- a/doc/src/create_atoms.rst +++ b/doc/src/create_atoms.rst @@ -95,16 +95,16 @@ typically created via the :doc:`create_box ` command. Before using this command, a lattice must also be defined using the :doc:`lattice ` command, unless you specify the *single* style with units = box or the *random* style. For the remainder of this doc -page, a created atom or molecule is referred to as a "particle". +page, a created atom or molecule is referred to as a "particle." If created particles are individual atoms, they are assigned the specified atom *type*, though this can be altered via the *basis* keyword as discussed below. If molecules are being created, the type of each atom in the created molecule is specified in the file read by the :doc:`molecule ` command, and those values are added to -the specified atom *type*\ . E.g. if *type* = 2, and the file specifies -atom types 1,2,3, then each created molecule will have atom types -3,4,5. +the specified atom *type* (e.g., if *type* = 2 and the file specifies +atom types 1, 2, and 3, then each created molecule will have atom types +3, 4, and 5). For the *box* style, the create_atoms command fills the entire simulation box with particles on the lattice. If your simulation box @@ -204,7 +204,7 @@ all requested *N* particles, a warning will be output. If the *region-ID* argument is specified as NULL, then the randomly created particles will be anywhere in the simulation box. If a -*region-ID* is specified, a geometric volume is filled which is both +*region-ID* is specified, a geometric volume is filled that is both inside the simulation box and is also consistent with the region volume. See the :doc:`region ` command for details. Note that a region can be specified so that its "volume" is either inside @@ -219,7 +219,7 @@ interleaving the create_atoms command with :doc:`lattice ` commands specifying different orientations. When this command is used, care should be taken to insure the -resulting system does not contain particles which are highly +resulting system does not contain particles that are highly overlapped. Such overlaps will cause many interatomic potentials to compute huge energies and forces, leading to bad dynamics. There are several strategies to avoid this problem: @@ -291,7 +291,7 @@ and inserts all molecules at a specified orientation. optional keywords allowed by the :doc:`create_box ` command for extra bonds (angles,etc) or extra special neighbors. This is because by default, the :doc:`create_box ` command sets up a - non-molecular system which does not allow molecules to be added. + non-molecular system that does not allow molecules to be added. ---------- @@ -308,11 +308,11 @@ The *ratio* and *subset* keywords can be used in conjunction with the *box* or *region* styles to limit the total number of particles inserted. The lattice defines a set of *Nlatt* eligible sites for inserting particles, which may be limited by the *region* style or the -*var* and *set* keywords. For the *ratio* keyword only the specified -fraction of them (0 <= *frac* <= 1) will be assigned particles. For -the *subset* keyword only the specified *Nsubset* of them will be +*var* and *set* keywords. For the *ratio* keyword, only the specified +fraction of them (:math:`0 \le f \le 1`) will be assigned particles. +For the *subset* keyword only the specified *Nsubset* of them will be assigned particles. In both cases the assigned lattice sites are -chosen randomly. An iterative algorithm is used which insures the +chosen randomly. An iterative algorithm is used that insures the correct number of particles are inserted, in a perfectly random fashion. Which lattice sites are selected will change with the number of processors used. @@ -327,23 +327,23 @@ The *var* and *set* keywords can be used together to provide a criterion for accepting or rejecting the addition of an individual atom, based on its coordinates. They apply to all styles except *single*. The *name* specified for the *var* keyword is the name of -an :doc:`equal-style variable ` which should evaluate to a -zero or non-zero value based on one or two or three variables which -will store the x, y, or z coordinates of an atom (one variable per +an :doc:`equal-style variable ` that should evaluate to a +zero or non-zero value based on one or two or three variables that +will store the *x*, *y*, or *z* coordinates of an atom (one variable per coordinate). If used, these other variables must be :doc:`internal-style variables ` defined in the input script; their initial numeric value can be anything. They must be internal-style variables, because this command resets their values directly. The *set* keyword is used to identify the names of these -other variables, one variable for the x-coordinate of a created atom, -one for y, and one for z. +other variables, one variable for the *x*-coordinate of a created atom, +one for *y*, and one for *z*. .. figure:: img/sinusoid.jpg :figwidth: 50% :align: right :target: _images/sinusoid.jpg -When an atom is created, its x,y,z coordinates become the values for +When an atom is created, its :math:`(x,y,z)` coordinates become the values for any *set* variable that is defined. The *var* variable is then evaluated. If the returned value is 0.0, the atom is not created. If it is non-zero, the atom is created. @@ -352,8 +352,8 @@ As an example, these commands can be used in a 2d simulation, to create a sinusoidal surface. Note that the surface is "rough" due to individual lattice points being "above" or "below" the mathematical expression for the sinusoidal curve. If a finer lattice were used, -the sinusoid would appear to be "smoother". Also note the use of the -"xlat" and "ylat" :doc:`thermo_style ` keywords which +the sinusoid would appear to be "smoother." Also note the use of the +"xlat" and "ylat" :doc:`thermo_style ` keywords, which converts lattice spacings to distance. .. only:: html @@ -379,7 +379,7 @@ converts lattice spacings to distance. The *rotate* keyword allows specification of the orientation at which molecules are inserted. The axis of rotation is -determined by the rotation vector (Rx,Ry,Rz) that goes through the +determined by the rotation vector :math:`(R_x,R_y,R_z)` that goes through the insertion point. The specified *theta* determines the angle of rotation around that axis. Note that the direction of rotation for the atoms around the rotation axis is consistent with the right-hand @@ -388,7 +388,7 @@ wrap around the axis in the direction of rotation. The *radscale* keyword only applies to the *mesh* style and adjusts the radius of created particles (see above), provided this is supported by -the atom style. Its value is a prefactor (must be > 0.0, default is +the atom style. Its value is a prefactor (must be :math:`>` 0.0, default is 1.0) that is applied to the atom radius inferred from the size of the individual triangles in the triangle mesh that the particle corresponds to. @@ -406,12 +406,12 @@ non-overlapping criterion. .. note:: - Checking for overlaps is a costly O(N(N+M)) operation for inserting - *N* new particles into a system with *M* existing particles. This - is because distances to all *M* existing particles are computed for + Checking for overlaps is a costly :math:`\mathcal{O}(N(N+M))` operation for + inserting *N* new particles into a system with *M* existing particles. + This is because distances to all *M* existing particles are computed for each new particle that is added. Thus the intended use of this keyword is to add relatively small numbers of particles to systems - which remain at a relatively low density even after the new + that remain at a relatively low density even after the new particles are created. Careful use of the *maxtry* keyword in combination with *overlap* is recommended. See the discussion above about systems with overlapped particles for alternate @@ -422,7 +422,7 @@ the number of attempts to generate valid coordinates for a single new particle that satisfy all requirements imposed by the *region*, *var*, and *overlap* keywords. The default is 10 attempts per particle before the loop over the requested *N* particles advances to the next -particle. Note that if insertion success is unlikely (e.g. inserting +particle. Note that if insertion success is unlikely (e.g., inserting new particles into a dense system using the *overlap* keyword), setting the *maxtry* keyword to a large value may result in this command running for a long time. @@ -447,7 +447,7 @@ Here is an example for the *random* style using these commands to produce a system as shown in the image with 1520 particles (out of 2000 requested) that are moderately dense and which have no overlaps sufficient to prevent the LJ pair_style from running properly (because -the overlap criterion = 1.0). The create_atoms command ran for 0.3 s +the overlap criterion is 1.0). The create_atoms command ran for 0.3 s on a single CPU core. .. only:: html @@ -460,9 +460,9 @@ The *units* keyword determines the meaning of the distance units used to specify the coordinates of the one particle created by the *single* style, or the overlap distance *Doverlap* by the *overlap* keyword. A *box* value selects standard distance units as defined by the -:doc:`units ` command, e.g. Angstroms for units = real or -metal. A *lattice* value means the distance units are in lattice -spacings. +:doc:`units ` command (e.g., :math:`\mathrm{\mathring{A}}` for +units = *real* or *metal*\ . A *lattice* value means the distance units are in +lattice spacings. ---------- @@ -471,15 +471,15 @@ collection of created atoms are assigned consecutive IDs that start immediately following the largest atom ID existing before the create_atoms command was invoked. This is done by the processor's communicating the number of atoms they each own, the first processor -numbering its atoms from 1 to N1, the second processor from N1+1 to -N2, etc. Where N1 = number of atoms owned by the first processor, N2 -= number owned by the second processor, etc. Thus when the same -simulation is performed on different numbers of processors, there is -no guarantee a particular created atom will be assigned the same ID in -both simulations. If molecules are being created, molecule IDs are -assigned to created molecules in a similar fashion. +numbering its atoms from :math:`1` to :math:`N_1`, the second processor from +:math:`N_1+1` to :math:`N_2`, and so on, where :math:`N_1` is the number of +atoms owned by the first processor, :math:`N_2` is the number owned by the +second processor, and so forth. Thus, when the same simulation is performed on +different numbers of processors, there is no guarantee a particular created +atom will be assigned the same ID in both simulations. If molecules are being +created, molecule IDs are assigned to created molecules in a similar fashion. -Aside from their ID, atom type, and xyz position, other properties of +Aside from their ID, atom type, and :math:`xyz` position, other properties of created atoms are set to default values, depending on which quantities are defined by the chosen :doc:`atom style `. See the :doc:`atom style ` command for more details. See the @@ -500,17 +500,17 @@ how to change these values. If molecules are being created, these defaults can be overridden by values specified in the file read by the :doc:`molecule ` -command. E.g. the file typically defines bonds (angles,etc) between +command. That is, the file typically defines bonds (angles, etc.) between atoms in the molecule, and can optionally define charges on each atom. Note that the *sphere* atom style sets the default particle diameter to 1.0 as well as the density. This means the mass for the particle is not -1.0, but is PI/6 \* diameter\^3 = 0.5236. When using the *mesh* style, -the particle diameter is adjusted from the size of the individual -triangles in the triangle mesh. +1.0, but is :math:`\frac{\pi}{6} d^3 = 0.5236`, where :math:`d` is the +diameter. When using the *mesh* style, the particle diameter is adjusted from +the size of the individual triangles in the triangle mesh. Note that the *ellipsoid* atom style sets the default particle shape -to (0.0 0.0 0.0) and the density to 1.0 which means it is a point +to (0.0 0.0 0.0) and the density to 1.0, which means it is a point particle, not an ellipsoid, and has a mass of 1.0. Note that the *peri* style sets the default volume and density to 1.0 @@ -533,8 +533,9 @@ the z-direction for a 2d model. Related commands """""""""""""""" -:doc:`lattice `, :doc:`region `, :doc:`create_box `, -:doc:`read_data `, :doc:`read_restart ` +:doc:`lattice `, :doc:`region `, +:doc:`create_box `, :doc:`read_data `, +:doc:`read_restart ` Default """"""" diff --git a/doc/src/create_bonds.rst b/doc/src/create_bonds.rst index 1f468dd42a..b42d55b246 100644 --- a/doc/src/create_bonds.rst +++ b/doc/src/create_bonds.rst @@ -67,20 +67,20 @@ the :doc:`bond_style `, :doc:`bond_coeff `, :doc:`dihedral_coeff `, :doc:`improper_style `, :doc:`improper_coeff ` commands. -The *many* style is useful for adding bonds to a system, e.g. between -nearest neighbors in a lattice of atoms, without having to enumerate +The *many* style is useful for adding bonds to a system (e.g., between +nearest neighbors in a lattice of atoms) without having to enumerate all the bonds in the data file read by the :doc:`read_data ` command. -The *single* styles are useful for adding bonds, angles, dihedrals, impropers -to a system incrementally, then continuing a simulation. +The *single* styles are useful for adding bonds, angles, dihedrals, and +impropers to a system incrementally, then continuing a simulation. -Note that this command does not auto-create any angle, dihedral or improper -interactions when a bond is added. Nor does it auto-create any bonds -when an angle, dihedral or improper is added. Or auto-create any angles when a -dihedral or improper is added. Thus the flexibility of this command is limited. -It can be used several times to create different types of bond at -different distances. But it cannot typically auto-create all the +Note that this command does not auto-create any angle, dihedral, or improper +interactions when a bond is added, nor does it auto-create any bonds +when an angle, dihedral, or improper is added. It also will not auto-create +any angles when a dihedral or improper is added. Thus, the flexibility of this +command is limited. It can be used several times to create different types of +bond at different distances, but it cannot typically auto-create all the bonds or angles or dihedrals or impropers that would normally be defined in a data file for a complex system of molecules. @@ -88,36 +88,37 @@ data file for a complex system of molecules. If the system has no bonds (angles, dihedrals, impropers) to begin with, or if more bonds per atom are being added than currently exist, then you - must insure that the number of bond types and the maximum number of - bonds per atom are set to large enough values. And similarly for - angles, dihedrals and impropers. Otherwise an error may occur when too many + must ensure that the number of bond types and the maximum number of + bonds per atom are set to large enough values, and similarly for + angles, dihedrals, and impropers, otherwise an error may occur when too many bonds (angles, dihedrals, impropers) are added to an atom. If the :doc:`read_data ` command is used to define the system, these parameters can be set via the "bond types" and "extra bond per atom" fields in the header section of the data file. If the :doc:`create_box ` command is used to define the system, - these 2 parameters can be set via its optional "bond/types" and - "extra/bond/per/atom" arguments. And similarly for angles, dihedrals and - impropers. See the doc pages for these 2 commands for details. + these two parameters can be set via its optional *bond/types* and + *extra/bond/per/atom* arguments, and similarly for angles, dihedrals, and + impropers. See the doc pages for these two commands for details. ---------- -The *many* style will create bonds between pairs of atoms I,J where I -is in one of the two specified groups, and J is in the other. The two -groups can be the same, e.g. group "all". The created bonds will be -of bond type *btype*, where *btype* must be a value between 1 and the +The *many* style will create bonds between pairs of atoms :math:`I,J`, +where :math:`I` is in one of the two specified groups and :math:`J` is in the +other. The two groups can be the same (e.g., group "all"). The created bonds +will be of bond type *btype*, where *btype* must be a value between 1 and the number of bond types defined. -For a bond to be created, an I,J pair of atoms must be a distance D -apart such that *rmin* <= D <= *rmax*\ . +For a bond to be created, an :math:`I,J` pair of atoms must be a distance +:math:`D` apart such that :math:`r_\text{min} \le D \le r_\text{max}`. The following settings must have been made in an input script before this style is used: -* special_bonds weight for 1-2 interactions must be 0.0 +* special_bonds weight for 1--2 interactions must be 0.0 * a :doc:`pair_style ` must be defined * no :doc:`kspace_style ` defined -* minimum :doc:`pair_style ` cutoff + :doc:`neighbor ` skin >= *rmax* +* minimum :doc:`pair_style ` cutoff + :doc:`neighbor ` + skin :math:`\ge r_\text{max}` These settings are required so that a neighbor list can be created to search for nearby atoms. Pairs of atoms that are already bonded @@ -127,12 +128,12 @@ a distance that encompasses the *rmax* for new bonds to create. .. note:: - If you want to create bonds between pairs of 1-3 or 1-4 atoms in + If you want to create bonds between pairs of 1--3 or 1--4 atoms in the current bond topology, then you need to use :doc:`special_bonds lj 0 1 1 ` to insure those pairs appear in the neighbor list. They will not appear with the default special_bonds - settings which are zero for 1-2, 1-3, and 1-4 atoms. 1-3 or 1-4 - atoms are those which are 2 hops or 3 hops apart in the bond + settings, which are zero for 1--2, 1--3, and 1--4 atoms. 1--3 or 1--4 + atoms are those which are two hops or three hops apart in the bond topology. An additional requirement for this style is that your system must be @@ -145,7 +146,7 @@ neighbor list requires initialization and setup of a simulation, similar to what a :doc:`run ` command would require. Note that you can change any of these settings after this command -executes, e.g. if you wish to use long-range Coulombic interactions +executes (e.g., if you wish to use long-range Coulombic interactions) via the :doc:`kspace_style ` command for your subsequent simulation. @@ -158,8 +159,8 @@ between 1 and the number of bond types defined. The *single/angle* style creates a single angle of type *atype* between three atoms with IDs *aatom1*, *aatom2*, and *aatom3*\ . The ordering of the atoms is the same as in the *Angles* section of a data -file read by the :doc:`read_data ` command. I.e. the 3 atoms are -ordered linearly within the angle; the central atom is *aatom2*\ . +file read by the :doc:`read_data ` command (i.e., the three atoms +are ordered linearly within the angle; the central atom is *aatom2*). *Atype* must be a value between 1 and the number of angle types defined. @@ -180,14 +181,14 @@ the number of improper types defined. ---------- The keyword *special* controls whether an internal list of special -bonds is created after one or more bonds, or a single angle, dihedral or +bonds is created after one or more bonds, or a single angle, dihedral, or improper is added to the system. The default value is *yes*\ . A value of *no* cannot be used with the *many* style. This is an expensive operation since the bond topology for the system -must be walked to find all 1-2, 1-3, 1-4 interactions to store in an +must be walked to find all 1--2, 1--3, and 1--4 interactions to store in an internal list, which is used when pairwise interactions are weighted; see the :doc:`special_bonds ` command for details. @@ -204,10 +205,10 @@ bond (or angle, or dihedral, or improper) is added: create_bonds single/bond 5 17 386 special no create_bonds single/bond 4 112 183 special yes -Note that you MUST insure the internal list is re-built after the last -bond (angle, dihedral, improper) is added, before performing a simulation. -Otherwise pairwise interactions will not be properly excluded or -weighted. LAMMPS does NOT check that you have done this correctly. +Note that you **must** ensure the internal list is rebuilt after the last +bond (angle, dihedral, improper) is added, *before* performing a simulation. +Otherwise, pairwise interactions will not be properly excluded or +weighted. LAMMPS does **not** check that you have done this correctly. ---------- diff --git a/doc/src/create_box.rst b/doc/src/create_box.rst index aa01be43cd..889a57605d 100644 --- a/doc/src/create_box.rst +++ b/doc/src/create_box.rst @@ -50,28 +50,33 @@ The argument N is the number of atom types that will be used in the simulation. If the region is not of style *prism*, then LAMMPS encloses the region -(block, sphere, etc) with an axis-aligned orthogonal bounding box +(block, sphere, etc.) with an axis-aligned orthogonal bounding box which becomes the simulation domain. If the region is of style *prism*, LAMMPS creates a non-orthogonal simulation domain shaped as a parallelepiped with triclinic symmetry. As defined by the :doc:`region prism ` command, the -parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by 3 -edge vectors starting from the origin given by A = (xhi-xlo,0,0); B = -(xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). *Xy,xz,yz* can be 0.0 or +parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by three +edge vectors starting from the origin given by +:math:`\vec a = (x_\text{hi}-x_\text{lo},0,0)`; +:math:`\vec b = (xy,y_\text{hi}-y_\text{lo},0)`; and +:math:`\vec c = (xz,yz,z_\text{hi}-z_\text{lo})`. +The parameters *xy*\ , *xz*\ , and *yz* can be 0.0 or positive or negative values and are called "tilt factors" because they are the amount of displacement applied to faces of an originally orthogonal box to transform it into the parallelepiped. By default, a *prism* region used with the create_box command must -have tilt factors (xy,xz,yz) that do not skew the box more than half -the distance of the parallel box length. For example, if xlo = 2 and -xhi = 12, then the x box length is 10 and the xy tilt factor must be -between -5 and 5. Similarly, both xz and yz must be between --(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, -since if the maximum tilt factor is 5 (as in this example), then -configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all -geometrically equivalent. If you wish to define a box with tilt +have tilt factors :math:`(xy,xz,yz)` that do not skew the box more than half +the distance of the parallel box length. For example, if +:math:`x_\text{lo} = 2` and :math:`x_\text{hi} = 12`, then the :math:`x` +box length is 10 and the :math:`xy` tilt factor must be between :math:`-5` and +:math:`5`. Similarly, both :math:`xz` and :math:`yz` must be between +:math:`-(x_\text{hi}-x_\text{lo})/2` and :math:`+(y_\text{hi}-y_\text{lo})/2`. +Note that this is not a limitation, since if the maximum tilt factor is 5 (as +in this example), then configurations with tilt :math:`= \dots, -15`, +:math:`-5`, :math:`5`, :math:`15`, :math:`25, \dots` +are all geometrically equivalent. If you wish to define a box with tilt factors that exceed these limits, you can use the :doc:`box tilt ` command, with a setting of *large*\ ; a setting of *small* is the default. @@ -81,18 +86,19 @@ geometric description of triclinic boxes, as defined by LAMMPS, and how to transform these parameters to and from other commonly used triclinic representations. -When a prism region is used, the simulation domain should normally be -periodic in the dimension that the tilt is applied to, which is given -by the second dimension of the tilt factor (e.g. y for xy tilt). This -is so that pairs of atoms interacting across that boundary will have -one of them shifted by the tilt factor. Periodicity is set by the -:doc:`boundary ` command. For example, if the xy tilt factor -is non-zero, then the y dimension should be periodic. Similarly, the -z dimension should be periodic if xz or yz is non-zero. LAMMPS does -not require this periodicity, but you may lose atoms if this is not +When a prism region is used, the simulation domain should normally be periodic +in the dimension that the tilt is applied to, which is given by the second +dimension of the tilt factor (e.g., :math:`y` for :math:`xy` tilt). This is so +that pairs of atoms interacting across that boundary will have one of them +shifted by the tilt factor. Periodicity is set by the +:doc:`boundary ` command. For example, if the :math:`xy` tilt factor +is non-zero, then the :math:`y` dimension should be periodic. Similarly, the +:math:`z` dimension should be periodic if :math:`xz` or :math:`yz` is non-zero. +LAMMPS does not require this periodicity, but you may lose atoms if this is not the case. -Also note that if your simulation will tilt the box, e.g. via the :doc:`fix deform ` command, the simulation box must be setup to +Note that if your simulation will tilt the box (e.g., via the +:doc:`fix deform ` command), the simulation box must be set up to be triclinic, even if the tilt factors are initially 0.0. You can also change an orthogonal box to a triclinic box or vice versa by using the :doc:`change box ` command with its *ortho* and @@ -103,11 +109,11 @@ using the :doc:`change box ` command with its *ortho* and If the system is non-periodic (in a dimension), then you should not make the lo/hi box dimensions (as defined in your :doc:`region ` command) radically smaller/larger than the extent - of the atoms you eventually plan to create, e.g. via the - :doc:`create_atoms ` command. For example, if your atoms - extend from 0 to 50, you should not specify the box bounds as -10000 - and 10000. This is because as described above, LAMMPS uses the - specified box size to layout the 3d grid of processors. A huge + of the atoms you eventually plan to create (e.g., via the + :doc:`create_atoms ` command). For example, if your atoms + extend from 0 to 50, you should not specify the box bounds as :math:`-10000` + and :math:`10000`. This is because as described above, LAMMPS uses the + specified box size to lay out the 3d grid of processors. A huge (mostly empty) box will be sub-optimal for performance when using "fixed" boundary conditions (see the :doc:`boundary ` command). When using "shrink-wrap" boundary conditions (see the @@ -119,23 +125,25 @@ using the :doc:`change box ` command with its *ortho* and The optional keywords can be used to create a system that allows for bond (angle, dihedral, improper) interactions, or for molecules with -special 1-2,1-3,1-4 neighbors to be added later. These optional +special 1--2, 1--3, or 1--4 neighbors to be added later. These optional keywords serve the same purpose as the analogous keywords that can be used in a data file which are recognized by the :doc:`read_data ` command when it sets up a system. Note that if these keywords are not used, then the create_box command creates an atomic (non-molecular) simulation that does not allow bonds -between pairs of atoms to be defined, or a :doc:`bond potential ` to be specified, or for molecules with +between pairs of atoms to be defined, or a +:doc:`bond potential ` to be specified, or for molecules with special neighbors to be added to the system by commands such as :doc:`create_atoms mol `, :doc:`fix deposit ` or :doc:`fix pour `. As an example, see the examples/deposit/in.deposit.molecule script, which deposits molecules onto a substrate. Initially there are no -molecules in the system, but they are added later by the :doc:`fix deposit ` command. The create_box command in the +molecules in the system, but they are added later by the +:doc:`fix deposit ` command. The create_box command in the script uses the bond/types and extra/bond/per/atom keywords to allow -this. If the added molecule contained more than 1 special bond +this. If the added molecule contained more than one special bond (allowed by default), an extra/special/per/atom keyword would also need to be specified. diff --git a/doc/src/delete_atoms.rst b/doc/src/delete_atoms.rst index f70570c040..3f0295f524 100644 --- a/doc/src/delete_atoms.rst +++ b/doc/src/delete_atoms.rst @@ -62,7 +62,7 @@ Description Delete the specified atoms. This command can be used, for example, to carve out voids from a block of material or to delete created atoms -that are too close to each other (e.g. at a grain boundary). +that are too close to each other (e.g., at a grain boundary). For style *group*, all atoms belonging to the group are deleted. @@ -78,7 +78,7 @@ first group specified and the other atom is in the second group are considered. The atom that is in the first group is the one that is deleted. -Note that it is OK for the two group IDs to be the same (e.g. group +Note that it is OK for the two group IDs to be the same (e.g., group *all*\ ), or for some atoms to be members of both groups. In these cases, either atom in the pair may be deleted. Also note that if there are atoms which are members of both groups, the only guarantee @@ -147,7 +147,7 @@ interactions, is one where the topology of the interactions is typically defined in the data file read by the :doc:`read_data ` command, and where the interactions themselves are defined with the :doc:`bond_style `, :doc:`angle_style -`, etc commands. If you delete atoms from such a system, +`, etc. commands. If you delete atoms from such a system, you must be careful not to end up with bonded interactions that are stored by remaining atoms but which include deleted atoms. This will cause LAMMPS to generate a "missing atoms" error when the bonded @@ -158,7 +158,7 @@ It the *bond* keyword is set to *yes* then any bond or angle or dihedral or improper interaction that includes a deleted atom is also removed from the lists of such interactions stored by non-deleted atoms. Note that simply deleting interactions due to dangling bonds -(e.g. at a surface) may result in a inaccurate or invalid model for +(e.g., at a surface) may result in a inaccurate or invalid model for the remaining atoms. It the *mol* keyword is set to *yes*, then for every atom that is @@ -182,17 +182,17 @@ Restrictions The *overlap* styles requires inter-processor communication to acquire ghost atoms and build a neighbor list. This means that your system must be ready to perform a simulation before using this command (force -fields setup, atom masses set, etc). Since a neighbor list is used to +fields setup, atom masses set, etc.). Since a neighbor list is used to find overlapping atom pairs, it also means that you must define a :doc:`pair style ` with the minimum force cutoff distance between any pair of atoms types (plus the :doc:`neighbor ` -skin) >= the specified overlap cutoff. +skin) :math:`\ge` the specified overlap cutoff. If the :doc:`special_bonds ` command is used with a -setting of 0, then a pair of bonded atoms (1-2, 1-3, or 1-4) will not +setting of 0, then a pair of bonded atoms (1--2, 1--3, or 1--4) will not appear in the neighbor list, and thus will not be considered for -deletion by the *overlap* styles. You probably don't want to be -deleting one atom in a bonded pair anyway. +deletion by the *overlap* styles. You probably do not want to +delete one atom in a bonded pair anyway. The *bond yes* option cannot be used with molecular systems defined using molecule template files via the :doc:`molecule ` and diff --git a/doc/src/delete_bonds.rst b/doc/src/delete_bonds.rst index 5603214b2f..ac2ffb3452 100644 --- a/doc/src/delete_bonds.rst +++ b/doc/src/delete_bonds.rst @@ -39,8 +39,8 @@ Examples Description """"""""""" -Turn off (or on) molecular topology interactions, i.e. bonds, angles, -dihedrals, impropers. This command is useful for deleting +Turn off (or on) molecular topology interactions (i.e., bonds, angles, +dihedrals, and/or impropers). This command is useful for deleting interactions that have been previously turned off by bond-breaking potentials. It is also useful for turning off topology interactions between frozen or rigid atoms. Pairwise interactions can be turned @@ -54,15 +54,15 @@ keyword to change the behavior. Several of the styles (\ *atom*, *bond*, *angle*, *dihedral*, *improper*\ ) take a *type* as an argument. The specified *type* should -be an integer from 0 to N, where N is the number of relevant types -(atom types, bond types, etc). A value of 0 is only relevant for +be an integer from 0 to :math:`N`, where :math:`N` is the number of relevant +types (atom types, bond types, etc.). A value of 0 is only relevant for style *bond*\ ; see details below. In all cases, a wildcard asterisk can be used in place of or in conjunction with the *type* argument to -specify a range of types. This takes the form "\*" or "\*n" or "n\*" or -"m\*n". If N = the number of types, then an asterisk with no numeric -values means all types from 0 to N. A leading asterisk means all +specify a range of types. This takes the form "\*" or "\*n" or "m\*" or +"m\*n". If :math:`N` is the number of types, then an asterisk with no numeric +values means all types from 0 to :math:`N`. A leading asterisk means all types from 0 to n (inclusive). A trailing asterisk means all types -from n to N (inclusive). A middle asterisk means all types from m to +from m to N (inclusive). A middle asterisk means all types from m to n (inclusive). Note that it is fine to include a type of 0 for non-bond styles; it will simply be ignored. @@ -79,7 +79,8 @@ must also be of the specified type. Styles *angle*, *dihedral*, and For style *bond*, you can set the type to 0 to delete bonds that have been previously broken by a bond-breaking potential (which sets the -bond type to 0 when a bond is broken); e.g. see the :doc:`bond_style quartic ` command. +bond type to 0 when a bond is broken); for example, see the +:doc:`bond_style quartic ` command. For style *stats* no interactions are turned off (or on); the status of all interactions in the specified group is simply reported. This @@ -88,19 +89,19 @@ bond-breaking potential during a previous run. The default behavior of the delete_bonds command is to turn off interactions by toggling their type to a negative value, but not to -permanently remove the interaction. E.g. a bond_type of 2 is set to --2. The neighbor list creation routines will not include such an +permanently remove the interaction. For example, a bond_type of 2 is set to +:math:`-2.` The neighbor list creation routines will not include such an interaction in their interaction lists. The default is also to not -alter the list of 1-2, 1-3, 1-4 neighbors computed by the +alter the list of 1--2, 1--3, or 1--4 neighbors computed by the :doc:`special_bonds ` command and used to weight pairwise force and energy calculations. This means that pairwise computations -will proceed as if the bond (or angle, etc) were still turned on. +will proceed as if the bond (or angle, etc.) were still turned on. Several keywords can be appended to the argument list to alter the default behaviors. The *any* keyword changes the requirement that all atoms in the bond -(angle, etc) must be in the specified group in order to turn-off the +(angle, etc) must be in the specified group in order to turn off the interaction. Instead, if any of the atoms in the interaction are in the specified group, it will be turned off (or on if the *undo* keyword is used). @@ -109,42 +110,43 @@ The *undo* keyword inverts the delete_bonds command so that the specified bonds, angles, etc are turned on if they are currently turned off. This means a negative value is toggled to positive. For example, for style *angle*, if *type* is specified as 2, then all -angles with current type = -2, are reset to type = 2. Note that the -:doc:`fix shake ` command also sets bond and angle types -negative, so this option should not be used on those interactions. +angles with current type = :math:`-2` are reset to type = :math:`2`. +Note that the :doc:`fix shake ` command also sets bond and angle +types negative, so this option should not be used on those interactions. The *remove* keyword is invoked at the end of the delete_bonds -operation. It causes turned-off bonds (angles, etc) to be removed +operation. It causes turned-off bonds (angles, etc.) to be removed from each atom's data structure and then adjusts the global bond -(angle, etc) counts accordingly. Removal is a permanent change; +(angle, etc.) counts accordingly. Removal is a permanent change; removed bonds cannot be turned back on via the *undo* keyword. -Removal does not alter the pairwise 1-2, 1-3, 1-4 weighting list. +Removal does not alter the pairwise 1--2, 1--3, or 1--4 weighting list. The *special* keyword is invoked at the end of the delete_bonds -operation, after (optional) removal. It re-computes the pairwise 1-2, -1-3, 1-4 weighting list. The weighting list computation treats +operation, after (optional) removal. It re-computes the pairwise 1--2, +1--3, 1--4 weighting list. The weighting list computation treats turned-off bonds the same as turned-on. Thus, turned-off bonds must be removed if you wish to change the weighting list. Note that the choice of *remove* and *special* options affects how -1-2, 1-3, 1-4 pairwise interactions will be computed across bonds that +1--2, 1--3, 1--4 pairwise interactions will be computed across bonds that have been modified by the delete_bonds command. Restrictions """""""""""" This command requires inter-processor communication to acquire ghost -atoms, to coordinate the deleting of bonds, angles, etc between atoms +atoms, to coordinate the deleting of bonds, angles, etc. between atoms shared by multiple processors. This means that your system must be ready to perform a simulation before using this command (force fields -setup, atom masses set, etc). Just as would be needed to run +setup, atom masses set, etc.). Just as would be needed to run dynamics, the force field you define should define a cutoff -(e.g. through a :doc:`pair_style ` command) which is long +(e.g., through a :doc:`pair_style ` command) which is long enough for a processor to acquire the ghost atoms its needs to compute -bond, angle, etc interactions. +bond, angle, etc. interactions. -If deleted bonds (angles, etc) are removed but the 1-2, 1-3, 1-4 -weighting list is not re-computed, this can cause a later :doc:`fix shake ` command to fail due to an atom's bonds being +If deleted bonds (or angles, etc.) are removed but the 1--2, 1--3, and 1--4 +weighting list is not recomputed, this can cause a later +:doc:`fix shake ` command to fail due to an atom's bonds being inconsistent with the weighting list. This should only happen if the group used in the fix command includes both atoms in the bond, in which case you probably should be recomputing the weighting list. diff --git a/doc/src/dielectric.rst b/doc/src/dielectric.rst index bd4f4dff56..09bd9ef1cf 100644 --- a/doc/src/dielectric.rst +++ b/doc/src/dielectric.rst @@ -6,7 +6,7 @@ dielectric command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS dielectric value @@ -25,9 +25,9 @@ Description Set the dielectric constant for Coulombic interactions (pairwise and long-range) to this value. The constant is unitless, since it is used to reduce the strength of the interactions. The value is used in the -denominator of the formulas for Coulombic interactions - e.g. a value +denominator of the formulas for Coulombic interactions (e.g., a value of 4.0 reduces the Coulombic interactions to 25% of their default -strength. See the :doc:`pair_style ` command for more +strength). See the :doc:`pair_style ` command for more details. Restrictions diff --git a/doc/src/dihedral_coeff.rst b/doc/src/dihedral_coeff.rst index b60c3c3d6c..782f9c5571 100644 --- a/doc/src/dihedral_coeff.rst +++ b/doc/src/dihedral_coeff.rst @@ -33,10 +33,10 @@ Dihedral coefficients can also be set in the data file read by the N can be specified in one of two ways. An explicit numeric value can be used, as in the first example above. Or a wild-card asterisk can be used to set the coefficients for multiple dihedral types. This takes the -form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of dihedral types, -then an asterisk with no numeric values means all types from 1 to N. A -leading asterisk means all types from 1 to n (inclusive). A trailing -asterisk means all types from n to N (inclusive). A middle asterisk +form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N` is the number of dihedral +types, then an asterisk with no numeric values means all types from 1 to +:math:`N`. A leading asterisk means all types from 1 to n (inclusive). A +trailing asterisk means all types from m to N (inclusive). A middle asterisk means all types from m to n (inclusive). Note that using a dihedral_coeff command can override a previous setting @@ -51,7 +51,7 @@ for all dihedral types, then overwrite the coeffs for just dihedral type 2: A line in a data file that specifies dihedral coefficients uses the exact same format as the arguments of the dihedral_coeff command in an input script, except that wild-card asterisks should not be used since -coefficients for all N types must be listed in the file. For example, +coefficients for all :math:`N` types must be listed in the file. For example, under the "Dihedral Coeffs" section of a data file, the line that corresponds to the first example above would be listed as @@ -69,11 +69,11 @@ page for details. When comparing the formulas and coefficients for various LAMMPS dihedral styles with dihedral equations defined by other force fields, note that some force field implementations divide/multiply the energy - prefactor *K* by the multiple number of torsions that contain the J-K - bond in an I-J-K-L torsion. LAMMPS does not do this, i.e. the listed - dihedral equation applies to each individual dihedral. Thus you need - to define *K* appropriately to account for this difference if - necessary. + prefactor *K* by the multiple number of torsions that contain the + *J*\ --\ *K* bond in an *I*\ -\ *J*\ -\ *K*\ -\ *L* torsion. LAMMPS does + not do this (i.e., the listed dihedral equation applies to each individual + dihedral). Thus, you need to define *K* appropriately to account for this + difference, if necessary. ---------- diff --git a/doc/src/dihedral_style.rst b/doc/src/dihedral_style.rst index f037d95226..4e56d1f787 100644 --- a/doc/src/dihedral_style.rst +++ b/doc/src/dihedral_style.rst @@ -10,7 +10,7 @@ Syntax dihedral_style style -* style = *none* or *hybrid* or *charmm* or *class2* or *harmonic* or *helix* or *multi/harmonic* or *opls* +* style = *none* or *zero* or *hybrid* or *charmm* or *charmmfsw* or *class2* or *osine/shift/exp* or *fourier* or *harmonic* or *helix* or *multi/harmonic* or *nharmonic* or *opls* or *spherical* or *table* or *table/cut* Examples """""""" @@ -51,7 +51,7 @@ to be re-specified. When both a dihedral and pair style is defined, the :doc:`special_bonds ` command often needs to be used to turn off (or weight) the pairwise interaction that would otherwise - exist between 4 bonded atoms. + exist between four bonded atoms. In the formulas listed for each dihedral style, *phi* is the torsional angle defined by the quadruplet of atoms. This angle has a sign @@ -60,11 +60,11 @@ convention as shown in this diagram: .. image:: JPG/dihedral_sign.jpg :align: center -where the I,J,K,L ordering of the 4 atoms that define the dihedral +where the :math:`I,J,K,L` ordering of the four atoms that define the dihedral is from left to right. This sign convention effects several of the dihedral styles listed -below (e.g. charmm, helix) in the sense that the energy formula +below (e.g., charmm, helix) in the sense that the energy formula depends on the sign of phi, which may be reflected in the value of the coefficients you specify. @@ -73,10 +73,10 @@ coefficients you specify. When comparing the formulas and coefficients for various LAMMPS dihedral styles with dihedral equations defined by other force fields, note that some force field implementations divide/multiply the energy - prefactor *K* by the multiple number of torsions that contain the J-K - bond in an I-J-K-L torsion. LAMMPS does not do this, i.e. the listed - dihedral equation applies to each individual dihedral. Thus you need - to define *K* appropriately via the + prefactor *K* by the multiple number of torsions that contain the + *J*\ --\ *K* bond in an *I*\ --\ *J*\ --\ *K*\ --\ *L* torsion. LAMMPS does + not do this (i.e., the listed dihedral equation applies to each individual + dihedral). Thus, you need to define *K* appropriately via the :doc:`dihedral_coeff ` command to account for this difference if necessary. @@ -93,8 +93,9 @@ command. There are also additional accelerated pair styles included in the LAMMPS distribution for faster performance on CPUs, GPUs, and KNLs. -The individual style names on the :ref:`Commands dihedral ` page are followed by one or -more of (g,i,k,o,t) to indicate which accelerated styles exist. +The individual style names on the :ref:`Commands dihedral ` page are +followed by one or more of (g,i,k,o,t) to indicate which accelerated styles +exist. * :doc:`none ` - turn off dihedral interactions * :doc:`zero ` - topology but no interactions diff --git a/doc/src/dimension.rst b/doc/src/dimension.rst index d22d3f19fa..bade4dd061 100644 --- a/doc/src/dimension.rst +++ b/doc/src/dimension.rst @@ -6,7 +6,7 @@ dimension command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS dimension N diff --git a/doc/src/displace_atoms.rst b/doc/src/displace_atoms.rst index fb9239d9de..d9bf367ec4 100644 --- a/doc/src/displace_atoms.rst +++ b/doc/src/displace_atoms.rst @@ -56,7 +56,7 @@ can be imposed on the system. Or two groups of atoms can be brought into closer proximity. The *move* style displaces the group of atoms by the specified 3d -displacement vector. Any of the 3 quantities defining the vector +displacement vector. Any of the three quantities defining the vector components can be specified as an equal-style or atom-style :doc:`variable `. If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, @@ -78,20 +78,20 @@ doc page for more details. The *ramp* style displaces atoms a variable amount in one dimension depending on the atom's coordinate in a (possibly) different dimension. For example, the second example command displaces atoms in -the x-direction an amount between 0.0 and 5.0 distance units. Each -atom's displacement depends on the fractional distance its y -coordinate is between 2.0 and 20.5. Atoms with y-coordinates outside +the *x*\ -direction an amount between 0.0 and 5.0 distance units. Each +atom's displacement depends on the fractional distance its *y* +coordinate is between 2.0 and 20.5. Atoms with *y*\ -coordinates outside those bounds will be moved the minimum (0.0) or maximum (5.0) amount. The *random* style independently moves each atom in the group by a -random displacement, uniformly sampled from a value between -dx and -+dx in the x dimension, and similarly for y and z. Random numbers are -used in such a way that the displacement of a particular atom is the -same, regardless of how many processors are being used. +random displacement, uniformly sampled from a value between :math:`-dx` and +:math:`+dx` in the *x* dimension, and similarly for *y* and *z*. +Random numbers are used in such a way that the displacement of a particular +atom is the same, regardless of how many processors are being used. The *rotate* style rotates each atom in the group by the angle *theta* -around a rotation axis *R* = (Rx,Ry,Rz) that goes through a point *P* = -(Px,Py,Pz). The direction of rotation for the atoms around the +around a rotation axis :math:`R = (R_x,R_y,R_z)` that goes through a point +:math:`P = (P_x,P_y,P_z)`. The direction of rotation for the atoms around the rotation axis is consistent with the right-hand rule: if your right-hand thumb points along *R*, then your fingers wrap around the axis in the direction of positive theta. @@ -104,10 +104,10 @@ atom's rotation. Distance units for displacements and the origin point of the *rotate* style are determined by the setting of *box* or *lattice* for the *units* keyword. *Box* means distance units as defined by the -:doc:`units ` command - e.g. Angstroms for *real* units. -*Lattice* means distance units are in lattice spacings. The -:doc:`lattice ` command must have been previously used to -define the lattice spacing. +:doc:`units ` command (e.g., :math:`\mathrm{\mathring A}` for +*real* or *metal* units). *Lattice* means distance units are in lattice +spacings. The :doc:`lattice ` command must have been previously used +to define the lattice spacing. ---------- @@ -139,7 +139,7 @@ Restrictions """""""""""" For a 2d simulation, only rotations around the a vector parallel to -the z-axis are allowed. +the :math:`z`-axis are allowed. Related commands """""""""""""""" diff --git a/doc/src/dump.rst b/doc/src/dump.rst index b0b7b7abae..bd57ef0353 100644 --- a/doc/src/dump.rst +++ b/doc/src/dump.rst @@ -176,10 +176,10 @@ Examples Description """"""""""" -Dump a snapshot of atom quantities to one or more files every N +Dump a snapshot of atom quantities to one or more files every :math:`N` timesteps in one of several styles. The *image* and *movie* styles are the exception: the *image* style renders a JPG, PNG, or PPM image file -of the atom configuration every N timesteps while the *movie* style +of the atom configuration every :math:`N` timesteps while the *movie* style combines and compresses them into a movie file; both are discussed in detail on the :doc:`dump image ` page. The timesteps on which dump output is written can also be controlled by a variable. @@ -188,8 +188,7 @@ See the :doc:`dump_modify every ` command. Only information for atoms in the specified group is dumped. The :doc:`dump_modify thresh and region and refresh ` commands can also alter what atoms are included. Not all styles support -these options; see details on the :doc:`dump_modify ` doc -page. +these options; see details on the :doc:`dump_modify ` doc page. As described below, the filename determines the kind of output (text or binary or gzipped, one big file or one per timestep, one big file @@ -231,7 +230,7 @@ by the regular dump styles, which may be required on clusters where the interface to the high-speed network disallows using the fork() library call (which is needed for a pipe). For the remainder of this page, you should thus consider the *atom* and *atom/gz* styles -(etc) to be inter-changeable, with the exception of the required +(etc.) to be inter-changeable, with the exception of the required filename suffix. Similarly, the *atom/zstd*, *cfg/zstd*, *custom/zstd*, *local/zstd*, @@ -243,9 +242,9 @@ the compression level in both variants. As explained below, the *atom/mpiio*, *cfg/mpiio*, *custom/mpiio*, and *xyz/mpiio* styles are identical in command syntax and in the format of the dump files they create, to the corresponding styles without -"mpiio", except the single dump file they produce is written in +"mpiio," except the single dump file they produce is written in parallel via the MPI-IO library. For the remainder of this page, -you should thus consider the *atom* and *atom/mpiio* styles (etc) to +you should thus consider the *atom* and *atom/mpiio* styles (etc.) to be inter-changeable. The one exception is how the filename is specified for the MPI-IO styles, as explained below. @@ -285,16 +284,16 @@ For an orthogonal simulation box this information is formatted as: zlo zhi where xlo,xhi are the maximum extents of the simulation box in the -x-dimension, and similarly for y and z. The "xx yy zz" represent 6 -characters that encode the style of boundary for each of the 6 -simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi). Each of -the 6 characters is either p = periodic, f = fixed, s = shrink wrap, -or m = shrink wrapped with a minimum value. See the +:math:`x`-dimension, and similarly for :math:`y` and :math:`z`. The +"xx yy zz" terms are six characters that encode the style of boundary for each +of the six simulation box boundaries (xlo,xhi; ylo,yhi; and zlo,zhi). Each of +the six characters is either p (periodic), f (fixed), s (shrink wrap), +or m (shrink wrapped with a minimum value). See the :doc:`boundary ` command for details. For triclinic simulation boxes (non-orthogonal), an orthogonal bounding box which encloses the triclinic simulation box is output, -along with the 3 tilt factors (xy, xz, yz) of the triclinic box, +along with the 3 tilt factors (*xy*, *xz*, *yz*) of the triclinic box, formatted as follows: .. parsed-literal:: @@ -305,15 +304,15 @@ formatted as follows: zlo_bound zhi_bound yz The presence of the text "xy xz yz" in the ITEM line indicates that -the 3 tilt factors will be included on each of the 3 following lines. +the three tilt factors will be included on each of the three following lines. This bounding box is convenient for many visualization programs. The -meaning of the 6 character flags for "xx yy zz" is the same as above. +meaning of the six character flags for "xx yy zz" is the same as above. Note that the first two numbers on each line are now xlo_bound instead -of xlo, etc, since they represent a bounding box. See the :doc:`Howto +of xlo, etc. because they represent a bounding box. See the :doc:`Howto triclinic ` page for a geometric description of -triclinic boxes, as defined by LAMMPS, simple formulas for how the 6 -bounding box extents (xlo_bound,xhi_bound,etc) are calculated from the +triclinic boxes, as defined by LAMMPS, simple formulas for how the six +bounding box extents (xlo_bound, xhi_bound, etc.) are calculated from the triclinic parameters, and how to transform those parameters to and from other commonly used triclinic representations. @@ -324,8 +323,8 @@ attributes you specify in the dump command for the *custom* style. For style *atom*, atom coordinates are written to the file, along with the atom ID and atom type. By default, atom coords are written in a -scaled format (from 0 to 1). I.e. an x value of 0.25 means the atom -is at a location 1/4 of the distance from xlo to xhi of the box +scaled format (from 0 to 1). That is, an :math:`x` value of 0.25 means the +atom is at a location 1/4 of the distance from *xlo* to *xhi* of the box boundaries. The format can be changed to unscaled coords via the :doc:`dump_modify ` settings. Image flags can also be added for each atom via dump_modify. @@ -344,11 +343,11 @@ For style *local*, local output generated by :doc:`computes ` and :doc:`fixes ` is used to generate lines of output that is written to the dump file. This local data is typically calculated by each processor based on the atoms it owns, but there may be zero or -more entities per atom, e.g. a list of bond distances. An explanation +more entities per atom (e.g., a list of bond distances). An explanation of the possible dump local attributes is given below. Note that by using input from the :doc:`compute property/local ` command with dump local, it is possible to -generate information on bonds, angles, etc that can be cut and pasted +generate information on bonds, angles, etc. that can be cut and pasted directly into a data file read by the :doc:`read_data ` command. @@ -408,18 +407,17 @@ The *xyz* style writes XYZ files, which is a simple text-based coordinate format that many codes can read. Specifically it has a line with the number of atoms, then a comment line that is usually ignored followed by one line per atom with the atom type -and the x-, y-, and z-coordinate of that atom. You can use the -:doc:`dump_modify element ` option to change the output -from using the (numerical) atom type to an element name (or some -other label). This will help many visualization programs to guess -bonds and colors. +and the :math:`x`-, :math:`y`-, and :math:`z`-coordinate of that atom. +You can use the :doc:`dump_modify element ` option to change the +output from using the (numerical) atom type to an element name (or some other +label). This will help many visualization programs to guess bonds and colors. .. versionadded:: 4May2022 Dump style *yaml* has the same command syntax as style *custom* and writes YAML format files that can be easily parsed by a variety of data processing tools and programming languages. Each timestep will be -written as a YAML "document" (i.e. starts with "---" and ends with +written as a YAML "document" (i.e., starts with "---" and ends with "..."). The style supports writing one file per timestep through the "\*" wildcard but not multi-processor outputs with the "%" token in the filename. In addition to per-atom data, :doc:`thermo ` data can @@ -435,14 +433,14 @@ Below is an example for a YAML format dump created by the following commands. dump out all yaml 100 dump.yaml id type x y z vx vy vz ix iy iz dump_modify out time yes units yes thermo yes format 1 %5d format "% 10.6e" -The tags "time", "units", and "thermo" are optional and enabled by the -dump_modify command. The list under the "box" tag has 3 lines for -orthogonal boxes and 4 lines with triclinic boxes, where the first 3 are -the box boundaries and the 4th the three tilt factors (xy, xz, yz). The -"thermo" data follows the format of the *yaml* thermo style. The -"keywords" tag lists the per-atom properties contained in the "data" -columns, which contain a list with one line per atom. The keywords may -be renamed using the dump_modify command same as for the *custom* dump +The tags "time," "units," and "thermo" are optional and enabled by the +dump_modify command. The list under the "box" tag has three lines for +orthogonal boxes and four lines for triclinic boxes, where the first three are +the box boundaries and the fourth the three tilt factors (:math:`xy`, +:math:`xz`, :math:`yz`). The "thermo" data follows the format of the *yaml* +thermo style. The "keywords" tag lists the per-atom properties contained in +the "data" columns, which contain a list with one line per atom. The keywords +may be renamed using the dump_modify command same as for the *custom* dump style. .. code-block:: yaml @@ -487,14 +485,14 @@ popular molecular viewing program. ---------- -Dumps are performed on timesteps that are a multiple of N (including +Dumps are performed on timesteps that are a multiple of :math:`N` (including timestep 0) and on the last timestep of a minimization if the minimization converges. Note that this means a dump will not be performed on the initial timestep after the dump command is invoked, -if the current timestep is not a multiple of N. This behavior can be +if the current timestep is not a multiple of :math:`N`. This behavior can be changed via the :doc:`dump_modify first ` command, which can also be useful if the dump command is invoked after a minimization -ended on an arbitrary timestep. N can be changed between runs by +ended on an arbitrary timestep. :math:`N` can be changed between runs by using the :doc:`dump_modify every ` command (not allowed for *dcd* style). The :doc:`dump_modify every ` command also allows a variable to be used to determine the sequence of @@ -515,19 +513,19 @@ For example, tmp.dump.\* becomes tmp.dump.0, tmp.dump.10000, tmp.dump.20000, etc. This option is not available for the *dcd* and *xtc* styles. Note that the :doc:`dump_modify pad ` command can be used to insure all timestep numbers are the same length -(e.g. 00010), which can make it easier to read a series of dump files +(e.g., 00010), which can make it easier to read a series of dump files in order with some post-processing tools. If a "%" character appears in the filename, then each of P processors writes a portion of the dump file, and the "%" character is replaced -with the processor ID from 0 to P-1. For example, tmp.dump.% becomes -tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc. This creates smaller -files and can be a fast mode of output on parallel machines that support -parallel I/O for output. This option is **not** available for the *dcd*, -*xtc*, *xyz*, and *yaml* styles. +with the processor ID from :math:`0` to :math:`P-1`. For example, tmp.dump.% +becomes tmp.dump.0, tmp.dump.1, ... tmp.dump.:math:`P-1`, etc. This creates +smaller files and can be a fast mode of output on parallel machines that +support parallel I/O for output. This option is **not** available for the +*dcd*, *xtc*, *xyz*, and *yaml* styles. -By default, P = the number of processors meaning one file per -processor, but P can be set to a smaller value via the *nfile* or +By default, :math:`P` is the the number of processors, meaning one file per +processor, but :math:`P` can be set to a smaller value via the *nfile* or *fileper* keywords of the :doc:`dump_modify ` command. These options can be the most efficient way of writing out dump files when running on large numbers of processors. @@ -539,15 +537,15 @@ For the *atom/mpiio*, *cfg/mpiio*, *custom/mpiio*, and *xyz/mpiio* styles, a single dump file is written in parallel via the MPI-IO library, which is part of the MPI standard for versions 2.0 and above. Using MPI-IO requires two steps. First, build LAMMPS with its MPIIO -package installed, e.g. +package installed, viz., .. code-block:: bash make yes-mpiio # installs the MPIIO package make mpi # build LAMMPS for your platform -Second, use a dump filename which contains ".mpiio". Note that it -does not have to end in ".mpiio", just contain those characters. +Second, use a dump filename which contains ".mpiio." Note that it +does not have to end in ".mpiio," just contain those characters. Unlike MPI-IO restart files, which must be both written and read using MPI-IO, the dump files produced by these MPI-IO styles are identical in format to the files produced by their non-MPI-IO style @@ -564,42 +562,41 @@ MPI-IO. Note that MPI-IO dump files are one large file which all processors write to. You thus cannot use the "%" wildcard character described above in the filename since that specifies generation of multiple -files. You can use the ".bin" or ".lammpsbin" suffix described below in an MPI-IO -dump file; again this file will be written in parallel and have the +files. You can use the ".bin" or ".lammpsbin" suffix described below in an +MPI-IO dump file; again this file will be written in parallel and have the same binary format as if it were written without MPI-IO. -If the filename ends with ".bin" or ".lammpsbin", the dump file (or files, if "\*" or -"%" is also used) is written in binary format. A binary dump file +If the filename ends with ".bin" or ".lammpsbin", the dump file (or files, if +"\*" or "%" is also used) is written in binary format. A binary dump file will be about the same size as a text version, but will typically write out much faster. Of course, when post-processing, you will need -to convert it back to text format (see the :ref:`binary2txt tool `) or write your own code to read the binary -file. The format of the binary file can be understood by looking at -the tools/binary2txt.cpp file. This option is only available for the -*atom* and *custom* styles. +to convert it back to text format (see the :ref:`binary2txt tool `) or +write your own code to read the binary file. The format of the binary file can +be understood by looking at the :file:`tools/binary2txt.cpp` file. This option +is only available for the *atom* and *custom* styles. If the filename ends with ".gz", the dump file (or files, if "\*" or "%" -is also used) is written in gzipped format. A gzipped dump file will -be about 3x smaller than the text version, but will also take longer -to write. This option is not available for the *dcd* and *xtc* -styles. +is also used) is written in gzipped format. A gzipped dump file will be about +:math:`3\times` smaller than the text version, but will also take longer +to write. This option is not available for the *dcd* and *xtc* styles. ---------- Note that in the discussion which follows, for styles which can reference values from a compute or fix or custom atom property, like -the *custom*\ , *cfg*\ , or *local* styles, the bracketed index I can +the *custom*\ , *cfg*\ , or *local* styles, the bracketed index :math:`i` can be specified using a wildcard asterisk with the index to effectively -specify multiple values. This takes the form "\*" or "\*n" or "n\*" -or "m\*n". If N = the number of columns in the array, then an -asterisk with no numeric values means all column indices from 1 to N. +specify multiple values. This takes the form "\*" or "\*n" or "m\*" +or "m\*n." If :math:`N` is the number of columns in the array, then an +asterisk with no numeric values means all column indices from 1 to :math:`N`. A leading asterisk means all indices from 1 to n (inclusive). A -trailing asterisk means all indices from n to N (inclusive). A middle +trailing asterisk means all indices from m to :math:`N` (inclusive). A middle asterisk means all indices from m to n (inclusive). Using a wildcard is the same as if the individual columns of the array -had been listed one by one. E.g. these 2 dump commands are +had been listed one by one. For example, these two dump commands are equivalent, since the :doc:`compute stress/atom ` -command creates a per-atom array with 6 columns: +command creates a per-atom array with six columns: .. code-block:: LAMMPS @@ -614,13 +611,12 @@ This section explains the local attributes that can be specified as part of the *local* style. The *index* attribute can be used to generate an index number from 1 -to N for each line written into the dump file, where N is the total -number of local datums from all processors, or lines of output that +to :math:`N` for each line written into the dump file, where :math:`N` is the +total number of local datums from all processors, or lines of output that will appear in the snapshot. Note that because data from different processors depend on what atoms they currently own, and atoms migrate between processor, there is no guarantee that the same index will be -used for the same info (e.g. a particular bond) in successive -snapshots. +used for the same info (e.g., a particular bond) in successive snapshots. The *c_ID* and *c_ID[I]* attributes allow local vectors or arrays calculated by a :doc:`compute ` to be output. The ID in the @@ -637,10 +633,10 @@ custom ` command, and per-atom quantities can be output by the dump custom command. If *c_ID* is used as a attribute, then the local vector calculated by -the compute is printed. If *c_ID[I]* is used, then I must be in the -range from 1-M, which will print the Ith column of the local array -with M columns calculated by the compute. See the discussion above -for how I can be specified with a wildcard asterisk to effectively +the compute is printed. If *c_ID[i]* is used, then :math:`i` must be in the +range from :math:`1-M`, which will print the Ith column of the local array +with :math:`M` columns calculated by the compute. See the discussion above +for how :math:`i` can be specified with a wildcard asterisk to effectively specify multiple values. The *f_ID* and *f_ID[I]* attributes allow local vectors or arrays @@ -649,11 +645,11 @@ should be replaced by the actual ID of the fix that has been defined previously in the input script. If *f_ID* is used as a attribute, then the local vector calculated by -the fix is printed. If *f_ID[I]* is used, then I must be in the -range from 1-M, which will print the Ith column of the local with M -columns calculated by the fix. See the discussion above for how I can -be specified with a wildcard asterisk to effectively specify multiple -values. +the fix is printed. If *f_ID[i]* is used, then :math:`i` must be in the +range :math:`1`--:math:`M`, which will print the :math:`i`\ th column of the +local with :math:`M` columns calculated by the fix. See the discussion above +for how :math:`i` can be specified with a wildcard asterisk to effectively +specify multiple values. Here is an example of how to dump bond info for a system, including the distance and energy of each bond: @@ -674,46 +670,47 @@ The *id*, *mol*, *proc*, *procp1*, *type*, *element*, *mass*, *vx*, *Id* is the atom ID. *Mol* is the molecule ID, included in the data file for molecular systems. *Proc* is the ID of the processor (0 to -Nprocs-1) that currently owns the atom. *Procp1* is the proc ID+1, -which can be convenient in place of a *type* attribute (1 to Ntypes) -for coloring atoms in a visualization program. *Type* is the atom -type (1 to Ntypes). *Element* is typically the chemical name of an -element, which you must assign to each type via the :doc:`dump_modify -element ` command. More generally, it can be any string -you wish to associated with an atom type. *Mass* is the atom mass. -*Vx*, *vy*, *vz*, *fx*, *fy*, *fz*, and *q* are components of atom -velocity and force and atomic charge. +:math:`N_\text{procs}-1`) that currently owns the atom. +*Procp1* is the proc ID+1, which can be convenient in place of a *type* +attribute (1 to :math:`N_\text{types}`) for coloring atoms in a visualization +program. *Type* is the atom type (1 to :math:`N_\text{types}`). *Element* is +typically the chemical name of an element, which you must assign to each type +via the :doc:`dump_modify element ` command. More generally, it +can be any string you wish to associated with an atom type. *Mass* is the atom +mass. The quantities *vx*, *vy*, *vz*, *fx*, *fy*, *fz*, and *q* are components +of atom velocity and force and atomic charge. There are several options for outputting atom coordinates. The *x*, -*y*, *z* attributes write atom coordinates "unscaled", in the -appropriate distance :doc:`units ` (Angstroms, sigma, etc). Use -*xs*, *ys*, *zs* if you want the coordinates "scaled" to the box size, -so that each value is 0.0 to 1.0. If the simulation box is triclinic -(tilted), then all atom coords will still be between 0.0 and 1.0. -I.e. actual unscaled (x,y,z) = xs\*A + ys\*B + zs\*C, where (A,B,C) are -the non-orthogonal vectors of the simulation box edges, as discussed -on the :doc:`Howto triclinic ` page. +*y*, and *z* attributes write atom coordinates "unscaled," in the +appropriate distance :doc:`units ` (:math:`\mathrm{\mathring A}`, +:math:`\sigma`, etc.). Use *xs*, *ys*, *zs* if you want the coordinates +"scaled" to the box size, so that each value is 0.0 to 1.0. If the simulation +box is triclinic (tilted), then all atom coords will still be between 0.0 and +1.0. The actual unscaled :math:`(x,y,z)` coordinate is +:math:`x_s a + y_s b + z_s c`, where :math:`(a,b,c)` are the non-orthogonal +vectors of the simulation box edges, as discussed on the +:doc:`Howto triclinic ` page. -Use *xu*, *yu*, *zu* if you want the coordinates "unwrapped" by the +Use *xu*, *yu*, and *zu* if you want the coordinates "unwrapped" by the image flags for each atom. Unwrapped means that if the atom has passed through a periodic boundary one or more times, the value is printed for what the coordinate would be if it had not been wrapped -back into the periodic box. Note that using *xu*, *yu*, *zu* means +back into the periodic box. Note that using *xu*, *yu*, and *zu* means that the coordinate values may be far outside the box bounds printed -with the snapshot. Using *xsu*, *ysu*, *zsu* is similar to using -*xu*, *yu*, *zu*, except that the unwrapped coordinates are scaled by +with the snapshot. Using *xsu*, *ysu*, and *zsu* is similar to using +*xu*, *yu*, and *zu*, except that the unwrapped coordinates are scaled by the box size. Atoms that have passed through a periodic boundary will have the corresponding coordinate increased or decreased by 1.0. -The image flags can be printed directly using the *ix*, *iy*, *iz* +The image flags can be printed directly using the *ix*, *iy*, and *iz* attributes. For periodic dimensions, they specify which image of the simulation box the atom is considered to be in. An image of 0 means it is inside the box as defined. A value of 2 means add 2 box lengths -to get the true value. A value of -1 means subtract 1 box length to +to get the true value. A value of :math:`-1` means subtract 1 box length to get the true value. LAMMPS updates these flags as atoms cross periodic boundaries during the simulation. -The *mux*, *muy*, *muz* attributes are specific to dipolar systems +The *mux*, *muy*, and *muz* attributes are specific to dipolar systems defined with an atom style of *dipole*\ . They give the orientation of the atom's point dipole moment. The *mu* attribute gives the magnitude of the atom's dipole moment. @@ -724,7 +721,7 @@ style of *sphere*\ . The *omegax*, *omegay*, and *omegaz* attributes are specific to finite-size spherical particles that have an angular velocity. Only -certain atom styles, such as *sphere* define this quantity. +certain atom styles, such as *sphere*, define this quantity. The *angmomx*, *angmomy*, and *angmomz* attributes are specific to finite-size aspherical particles that have an angular momentum. Only @@ -749,10 +746,10 @@ command. Instead, global quantities can be output by the can be output by the dump local command. If *c_ID* is used as a attribute, then the per-atom vector calculated -by the compute is printed. If *c_ID[I]* is used, then I must be in -the range from 1-M, which will print the Ith column of the per-atom -array with M columns calculated by the compute. See the discussion -above for how I can be specified with a wildcard asterisk to +by the compute is printed. If *c_ID[i]* is used, then :math:`i` must be in +the range from 1 to :math:`M`, which will print the :math:`i`\ th column of the +per-atom array with :math:`M` columns calculated by the compute. See the +discussion above for how :math:`i` can be specified with a wildcard asterisk to effectively specify multiple values. The *f_ID* and *f_ID[I]* attributes allow vector or array per-atom @@ -766,11 +763,11 @@ Since it can time-average per-atom quantities produced by any be written to a dump file. If *f_ID* is used as a attribute, then the per-atom vector calculated -by the fix is printed. If *f_ID[I]* is used, then I must be in the -range from 1-M, which will print the Ith column of the per-atom array -with M columns calculated by the fix. See the discussion above for -how I can be specified with a wildcard asterisk to effectively specify -multiple values. +by the fix is printed. If *f_ID[i]* is used, then :math:`i` must be in the +range from 1 to :math:`M`, which will print the :math:`i`\ th column of the +per-atom array with :math:`M` columns calculated by the fix. See the +discussion above for how :math:`i` can be specified with a wildcard asterisk to +effectively specify multiple values. The *v_name* attribute allows per-atom vectors calculated by a :doc:`variable ` to be output. The name in the attribute @@ -780,8 +777,7 @@ can be referenced, since it is the only style that generates per-atom values. Variables of style *atom* can reference individual atom attributes, per-atom attributes, thermodynamic keywords, or invoke other computes, fixes, or variables when they are evaluated, so this -is a very general means of creating quantities to output to a dump -file. +is a very general means of creating quantities to output to a dump file. The *i_name*, *d_name*, *i2_name*, *d2_name* attributes refer to per-atom integer and floating-point vectors or arrays that have been @@ -789,10 +785,10 @@ added via the :doc:`fix property/atom ` command. When that command is used specific names are given to each attribute which are the "name" portion of these keywords. For arrays *i2_name* and *d2_name*, the column of the array must also be included following -the name in brackets: e.g. d2_xyz[I], i2_mySpin[I], where I is in the -range from 1-M, where M is the number of columns in the custom array. -See the discussion above for how I can be specified with a wildcard -asterisk to effectively specify multiple values. +the name in brackets (e.g., d2_xyz[i], i2_mySpin[i], where :math:`i` is in the +range from 1 to :math:`M`, where :math:`M` is the number of columns in the +custom array). See the discussion above for how :math:`i` can be specified with +a wildcard asterisk to effectively specify multiple values. See the :doc:`Modify ` page for information on how to add new compute and fix styles to LAMMPS to calculate per-atom quantities @@ -807,9 +803,9 @@ To write gzipped dump files, you must either compile LAMMPS with the -DLAMMPS_GZIP option or use the styles from the COMPRESS package. See the :doc:`Build settings ` page for details. -While a dump command is active (i.e. has not been stopped by using -the undump command), no commands may be used that will change the -timestep (e.g. :doc:`reset_timestep `). LAMMPS +While a dump command is active (i.e., has not been stopped by using +the :doc:`undump command `), no commands may be used that will change +the timestep (e.g., :doc:`reset_timestep `). LAMMPS will terminate with an error otherwise. The *atom/gz*, *cfg/gz*, *custom/gz*, and *xyz/gz* styles are part of @@ -822,7 +818,7 @@ are part of the MPIIO package. They are only enabled if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. -The *xtc*, *dcd* and *yaml* styles are part of the EXTRA-DUMP package. +The *xtc*, *dcd*, and *yaml* styles are part of the EXTRA-DUMP package. They are only enabled if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. @@ -832,7 +828,8 @@ Related commands :doc:`dump atom/adios `, :doc:`dump custom/adios `, :doc:`dump cfg/uef `, :doc:`dump h5md `, :doc:`dump image `, :doc:`dump molfile `, -:doc:`dump_modify `, :doc:`undump `, :doc:`write_dump ` +:doc:`dump_modify `, :doc:`undump `, +:doc:`write_dump ` Default """"""" diff --git a/doc/src/dump_modify.rst b/doc/src/dump_modify.rst index 1fac32e426..d3611e0ba9 100644 --- a/doc/src/dump_modify.rst +++ b/doc/src/dump_modify.rst @@ -33,7 +33,7 @@ Syntax *delay* arg = Dstep Dstep = delay output until this timestep *element* args = E1 E2 ... EN, where N = # of atom types - E1,...,EN = element name, e.g. C or Fe or Ga + E1,...,EN = element name (e.g., C or Fe or Ga) *every* arg = N N = dump every this many timesteps N can be a variable (see below) @@ -53,7 +53,7 @@ Syntax *no* to not write the header *image* arg = *yes* or *no* *label* arg = string - string = character string (e.g. BONDS) to use in header of dump local file + string = character string (e.g., BONDS) to use in header of dump local file *maxfiles* arg = Fmax Fmax = keep only the most recent *Fmax* snapshots (one snapshot per file) *nfile* arg = Nf @@ -111,7 +111,7 @@ Examples dump_modify 1 format line "%d %d %20.15g %g %g" scale yes dump_modify 1 format float %20.15g scale yes dump_modify myDump image yes scale no flush yes - dump_modify 1 region mySphere thresh x < 0.0 thresh epair >= 3.2 + dump_modify 1 region mySphere thresh x < 0.0 thresh fx >= 3.2 dump_modify xtcdump precision 10000 sfactor 0.1 dump_modify 1 every 1000 nfile 20 dump_modify 1 every v_myVar @@ -153,8 +153,8 @@ be used if the *append yes* keyword is also used. The *N* argument is the index of which frame to append to. A negative value can be specified for *N*, which means a frame counted from the end of the file. The *at* keyword can only be used if the dump_modify command is -before the first command that causes dump snapshots to be output, -e.g. a :doc:`run ` or :doc:`minimize ` command. Once the +before the first command that causes dump snapshots to be output +(e.g., a :doc:`run ` or :doc:`minimize ` command). Once the dump file has been opened, this keyword has no further effect. ---------- @@ -185,7 +185,7 @@ during an equilibration phase. ---------- The *element* keyword applies only to the dump *cfg*, *xyz*, and -*image* styles. It associates element names (e.g. H, C, Fe) with +*image* styles. It associates element names (e.g., H, C, Fe) with LAMMPS atom types. See the list of element names at the bottom of this page. @@ -262,7 +262,7 @@ in file tmp.times: When using a file-style variable with the *every* keyword, the file of timesteps must list a first timestep that is beyond the - current timestep (e.g. it cannot be 0). And it must list one or more + current timestep (e.g., it cannot be 0). And it must list one or more timesteps beyond the length of the run you perform. This is because the dump command will generate an error if the next timestep it reads from the file is not a value greater than the current timestep. Thus @@ -275,10 +275,10 @@ in file tmp.times: The *every/time* keyword can be used with any dump style except the *dcd* and *xtc* styles. It does two things. It specifies that the -interval between dump snapshots will be set in simulation time, -i.e. in time units of the :doc:`units ` command. This can be -useful when the timestep size varies during a simulation run, e.g. by -use of the :doc:`fix dt/reset ` command. The default is +interval between dump snapshots will be set in simulation time +(i.e. in time units of the :doc:`units ` command). This can be +useful when the timestep size varies during a simulation run (e.g., by +use of the :doc:`fix dt/reset ` command). The default is to specify the interval in timesteps; see the *every* keyword. The *every/time* command also sets the interval value. @@ -340,7 +340,7 @@ file tmp.times: When using a file-style variable with the *every/time* keyword, the file of timesteps must list a first time that is beyond the time - associated with the current timestep (e.g. it cannot be 0.0). And + associated with the current timestep (e.g., it cannot be 0.0). And it must list one or more times beyond the length of the run you perform. This is because the dump command will generate an error if the next time it reads from the file is not a value greater than @@ -409,16 +409,16 @@ by the text-based dump styles: *atom*, *local*, *custom*, *cfg*, and *xyz* styles, and their MPIIO variants. Only the *line* or *none* options can be used with the *atom* and *xyz* styles. -All the specified format strings are C-style formats, e.g. as used by +All the specified format strings are C-style formats, such as used by the C/C++ printf() command. The *line* keyword takes a single argument which is the format string for an entire line of output for -each atom (do not include a trailing "\n"), with N fields, which you -must enclose in quotes if it is more than one field. The *int* and +each atom (do not include a trailing "\n"), with :math:`N` fields, which you +must enclose in quotes if there is more than one field. The *int* and *float* keywords take a single format argument and are applied to all -integer or floating-point quantities output. The setting for *M -string* also takes a single format argument which is used for the Mth -value output in each line, e.g. the fifth column is output in high -precision for "format 5 %20.15g". +integer or floating-point quantities output. The setting for *M string* +also takes a single format argument which is used for the :math:`M`\ th +value output in each line (e.g., the fifth column is output in high +precision by "format 5 %20.15g"). .. note:: @@ -442,7 +442,7 @@ settings, reverting all values to their default format. corresponding 8-byte form if it is needed when outputting those values. However, when specifying the *line* option or *format M string* option for those values, you should specify a format string - appropriate for an 8-byte signed integer, e.g. one with "%ld", if + appropriate for an 8-byte signed integer (e.g., one with "%ld") if LAMMPS was compiled with the -DLAMMPS_BIGBIG option for 8-byte IDs. .. note:: @@ -462,7 +462,7 @@ settings, reverting all values to their default format. will output the two atom IDs for atoms in each bond as integers. If the dump_modify command were omitted, they would appear as -floating-point values, assuming they were large integers (more than 6 +floating-point values, assuming they were large integers (more than six digits). The "index" keyword should use the "%d" format since it is not generated by a compute or fix, and is stored internally as an integer. @@ -482,43 +482,43 @@ information typically written to the header. ---------- The *image* keyword applies only to the dump *atom* style. If the -image value is *yes*, 3 flags are appended to each atom's coords which +image value is *yes*, three flags are appended to each atom's coords which are the absolute box image of the atom in each dimension. For -example, an x image flag of -2 with a normalized coord of 0.5 means -the atom is in the center of the box, but has passed through the box -boundary 2 times and is really 2 box lengths to the left of its +example, an :math:`x` image flag of :math:`-2` with a normalized coord of 0.5 +means the atom is in the center of the box, but has passed through the box +boundary twice and is really two box lengths to the left of its current coordinate. Note that for dump style *custom* these various values can be printed in the dump file by using the appropriate atom attributes in the dump command itself. ---------- -The *label* keyword applies only to the dump *local* style. When -it writes local information, such as bond or angle topology -to a dump file, it will use the specified *label* to format -the header. By default this includes 2 lines: +The *label* keyword applies only to the dump *local* style. +When it writes local information, such as bond or angle topology +to a dump file, it will use the specified *label* to format the header. +By default this includes two lines: .. parsed-literal:: ITEM: NUMBER OF ENTRIES ITEM: ENTRIES ... -The word "ENTRIES" will be replaced with the string specified, -e.g. BONDS or ANGLES. +The word "ENTRIES" will be replaced with the string specified +(e.g., BONDS or ANGLES). ---------- The *maxfiles* keyword can only be used when a '\*' wildcard is -included in the dump file name, i.e. when writing a new file(s) for -each snapshot. The specified *Fmax* is how many snapshots will be +included in the dump file name (i.e., when writing a new file(s) for +each snapshot). The specified *Fmax* is how many snapshots will be kept. Once this number is reached, the file(s) containing the oldest snapshot is deleted before a new dump file is written. If the -specified *Fmax* <= 0, then all files are retained. +specified :math:`\text{Fmax} \le 0`, then all files are retained. -This can be useful for debugging, especially if you don't know on what -timestep something bad will happen, e.g. when LAMMPS will exit with an -error. You can dump every timestep, and limit the number of dump -files produced, even if you run for 1000s of steps. +This can be useful for debugging, especially if you do not know on what +timestep something bad will happen (e.g., when LAMMPS will exit with an +error). You can dump every time step and limit the number of dump +files produced, even if you run for thousands of steps. ---------- @@ -527,28 +527,29 @@ The *nfile* or *fileper* keywords can be used in conjunction with the styles except the *dcd*, *image*, *movie*, *xtc*, and *xyz* styles (for which "%" is not allowed). As explained on the :doc:`dump ` command doc page, the "%" character causes the dump file to be written -in pieces, one piece for each of P processors. By default P = the -number of processors the simulation is running on. The *nfile* or -*fileper* keyword can be used to set P to a smaller value, which can +in pieces, one piece for each of :math:`P` processors. By default, :math:`P` +is the number of processors the simulation is running on. The *nfile* or +*fileper* keyword can be used to set :math:`P` to a smaller value, which can be more efficient when running on a large number of processors. -The *nfile* keyword sets P to the specified Nf value. For example, if -Nf = 4, and the simulation is running on 100 processors, 4 files will -be written, by processors 0,25,50,75. Each will collect information -from itself and the next 24 processors and write it to a dump file. +The *nfile* keyword sets :math:`P` to the specified :math:`N_f` value. +For example, if :math:`N_f = 4`, and the simulation is running on 100 +processors, four files will be written by processors 0, 25, 50, and 75. +Each will collect information from itself and the next 24 processors and write +it to a dump file. -For the *fileper* keyword, the specified value of Np means write one -file for every Np processors. For example, if Np = 4, every fourth -processor (0,4,8,12,etc) will collect information from itself and the -next 3 processors and write it to a dump file. +For the *fileper* keyword, the specified value of :math:`N_p` means write one +file for every :math:`N_p` processors. For example, if :math:`N_p = 4`, +every fourth processor (0, 4, 8, 12, etc.) will collect information from itself +and the next three processors and write it to a dump file. ---------- The *pad* keyword only applies when the dump filename is specified with a wildcard "\*" character which becomes the timestep. If *pad* is 0, which is the default, the timestep is converted into a string of -unpadded length, e.g. 100 or 12000 or 2000000. When *pad* is -specified with *Nchar* > 0, the string is padded with leading zeroes +unpadded length (e.g., 100 or 12000 or 2000000). When *pad* is +specified with *Nchar* :math:`>` 0, the string is padded with leading zeroes so they are all the same length = *Nchar*\ . For example, pad 7 would yield 0000100, 0012000, 2000000. This can be useful so that post-processing programs can easily read the files in ascending @@ -570,9 +571,9 @@ because it requires no extra computation. ---------- The *precision* keyword only applies to the dump *xtc* style. A -specified value of N means that coordinates are stored to 1/N -nanometer accuracy, e.g. for N = 1000, the coordinates are written to -1/1000 nanometer accuracy. +specified value of :math:`N` means that coordinates are stored to :math:`1/N` +nanometer accuracy (e.g., for :math:`N = 1000`, the coordinates are written to +:math:`1/1000` nanometer accuracy). ---------- @@ -582,7 +583,7 @@ be written, by refreshing a compute that is used as a threshold for determining which atoms are included in a dump snapshot. The specified *c_ID* gives the ID of the compute. It is prefixed by "c\_" to indicate a compute, which is the only current option. At some -point, other options may be added, e.g. fixes or variables. +point, other options may be added (e.g., fixes or variables). .. note:: @@ -615,19 +616,19 @@ commands: The :doc:`compute displace/atom ` command calculates the displacement of each atom from its reference position. -The "4" index is the scalar displacement; 1,2,3 are the xyz components -of the displacement. The :doc:`dump_modify thresh ` -command will cause only atoms that have displaced more than 0.6 -Angstroms to be output on a given snapshot (assuming metal units). -However, note that when an atom is output, we also need to update the -reference position for that atom to its new coordinates. So that it -will not be output in every snapshot thereafter. That reference -position is stored by :doc:`compute displace/atom `. So the dump_modify -*refresh* option triggers a call to compute displace/atom at the end -of every dump to perform that update. The *refresh check* option -shown as part of the :doc:`compute displace/atom ` command enables the compute -to respond to the call from the dump command, and update the -appropriate reference positions. This is done be defining an +The "4" index is the scalar displacement; 1, 2, and 3 are the :math:`xyz` +components of the displacement. The :doc:`dump_modify thresh ` +command will cause only atoms that have displaced more than +:math:`0.6~\mathrm{\mathring A}` to be output on a given snapshot (assuming +metal units). However, note that when an atom is output, we also need to +update the reference position for that atom to its new coordinates. So that it +will not be output in every snapshot thereafter. That reference position is +stored by :doc:`compute displace/atom `. So the +dump_modify *refresh* option triggers a call to compute displace/atom at the +end of every dump to perform that update. The *refresh check* option +shown as part of the :doc:`compute displace/atom ` +command enables the compute to respond to the call from the dump command, and +update the appropriate reference positions. This is done be defining an :doc:`atom-style variable `, *check* in this example, which calculates a Boolean value (0 or 1) for each atom, based on the same criterion used by dump_modify thresh. @@ -661,18 +662,18 @@ value of *yes* means atom coords are written in normalized units from 0.0 to 1.0 in each box dimension. If the simulation box is triclinic (tilted), then all atom coords will still be between 0.0 and 1.0. A value of *no* means they are written in absolute distance units -(e.g. Angstroms or sigma). +(e.g., :math:`\mathrm{\mathring A}` or :math:`\sigma`). ---------- The *sfactor* and *tfactor* keywords only apply to the dump *xtc* style. They allow customization of the unit conversion factors used -when writing to XTC files. By default they are initialized for +when writing to XTC files. By default, they are initialized for whatever :doc:`units ` style is being used, to write out -coordinates in nanometers and time in picoseconds. I.e. for *real* +coordinates in nanometers and time in picoseconds. For example, for *real* units, LAMMPS defines *sfactor* = 0.1 and *tfactor* = 0.001, since the -Angstroms and fs used by *real* units are 0.1 nm and 0.001 ps -respectively. If you are using a units system with distance and time +:math:`\mathrm{\mathring A}` and fs used by *real* units are 0.1 nm and +0.001 ps, respectively. If you are using a units system with distance and time units far from nm and ps, you may wish to write XTC files with different units, since the compression algorithm used in XTC files is most effective when the typical magnitude of position data is between @@ -683,18 +684,19 @@ most effective when the typical magnitude of position data is between The *sort* keyword determines whether lines of per-atom output in a snapshot are sorted or not. A sort value of *off* means they will typically be written in indeterminate order, either in serial or -parallel. This is the case even in serial if the :doc:`atom_modify sort ` option is turned on, which it is by default, to -improve performance. A sort value of *id* means sort the output by -atom ID. A sort value of N or -N means sort the output by the value -in the Nth column of per-atom info in either ascending or descending -order. +parallel. This is the case even in serial if the +:doc:`atom_modify sort ` option is turned on, which it is by +default, to improve performance. A sort value of *id* means sort the output by +atom ID. A sort value of :math:`N` or :math:`-N` means sort the output by the +value in the :math:`N`\ th column of per-atom info in either ascending or +descending order. The dump *local* style cannot be sorted by atom ID, since there are typically multiple lines of output per atom. Some dump styles, such as *dcd* and *xtc*, require sorting by atom ID to format the output file correctly. If multiple processors are writing the dump file, via the "%" wildcard in the dump filename and the *nfile* or *fileper* -keywords are set to non-default values (i.e. the number of dump file +keywords are set to non-default values (i.e., the number of dump file pieces is not equal to the number of procs), then sorting cannot be performed. @@ -729,11 +731,12 @@ are written to the dump file or included in the image. The possible attributes that can be tested for are the same as those that can be specified in the :doc:`dump custom ` command, with the exception of the *element* attribute, since it is not a numeric value. Note -that a different attributes can be used than those output by the :doc:`dump custom ` command. E.g. you can output the coordinates and -stress of atoms whose energy is above some threshold. +that a different attributes can be used than those output by the +:doc:`dump custom ` command. For example, you can output the coordinates +and stress of atoms whose energy is above some threshold. If an atom-style variable is used as the attribute, then it can -produce continuous numeric values or effective Boolean 0/1 values +produce continuous numeric values or effective Boolean 0/1 values, which may be useful for the comparison operator. Boolean values can be generated by variable formulas that use comparison or Boolean math operators or special functions like gmask() and rmask() and grmask(). @@ -749,7 +752,7 @@ Three examples follow. dump_modify ... thresh ix != LAST -This will dump atoms which have crossed the periodic x boundary of the +This will dump atoms which have crossed the periodic :math:`x` boundary of the simulation box since the last dump. (Note that atoms that crossed once and then crossed back between the two dump timesteps would not be included.) @@ -769,9 +772,8 @@ region since the last dump. dump_modify ... thresh v_charge |^ LAST This will dump atoms whose charge has changed from an absolute value -less than 1/2 to greater than 1/2 (or vice versa) since the last dump. -E.g. due to reactions and subsequent charge equilibration in a -reactive force field. +less than :math:`\frac12` to greater than :math:`\frac12` (or vice versa) since the last dump (e.g., due to reactions and subsequent charge equilibration in a +reactive force field). The choice of operators listed above are the usual comparison operators. The XOR operation (exclusive or) is also included as "\|\^". @@ -783,7 +785,7 @@ threshold criterion is met. Otherwise it is not met. The *time* keyword only applies to the dump *atom*, *custom*, *local*, and *xyz* styles (and their COMPRESS package versions *atom/gz*, -*custom/gz* and *local/gz*\ ). For the first 3 styles, if set to +*custom/gz* and *local/gz*\ ). For the first three styles, if set to *yes*, each frame will will contain two extra lines before the "ITEM: TIMESTEP" entry: @@ -798,7 +800,7 @@ as the timestep value. This will output the current elapsed simulation time in current time units equivalent to the :doc:`thermo keyword ` *time*\ . This is to simplify post-processing of trajectories using a variable time -step, e.g. when using :doc:`fix dt/reset `. +step (e.g., when using :doc:`fix dt/reset `). The default setting is *no*\ . ---------- @@ -836,9 +838,8 @@ compression level can be controlled by the :code:`compression_level` keyword. File names with these styles have to end in either :code:`.gz` or :code:`.zst`. -GZ supports compression levels from -1 (default), 0 (no compression), -and 1 to -9. 9 being the best compression. The COMPRESS :code:`/gz` styles use 9 +GZ supports compression levels from :math:`-1` (default), 0 (no compression), +and 1 to 9, 9 being the best compression. The COMPRESS :code:`/gz` styles use 9 as default compression level. Zstd offers a wider range of compression levels, including negative diff --git a/doc/src/echo.rst b/doc/src/echo.rst index 94951e5e79..8846a987c9 100644 --- a/doc/src/echo.rst +++ b/doc/src/echo.rst @@ -6,7 +6,7 @@ echo command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS echo style diff --git a/doc/src/fix.rst b/doc/src/fix.rst index 2ec4437b39..db08e64b14 100644 --- a/doc/src/fix.rst +++ b/doc/src/fix.rst @@ -6,7 +6,7 @@ fix command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID style args @@ -37,7 +37,7 @@ defined in LAMMPS and new ones can be added; see the :doc:`Modify ` page for details. Fixes perform their operations at different stages of the timestep. -If 2 or more fixes operate at the same stage of the timestep, they are +If two or more fixes operate at the same stage of the timestep, they are invoked in the order they were specified in the input script. The ID of a fix can only contain alphanumeric characters and @@ -52,8 +52,8 @@ Fixes can be deleted with the :doc:`unfix ` command. off the first one. This is especially important to realize for integration fixes. For example, using a :doc:`fix nve ` command for a second run after using a :doc:`fix nvt ` command - for the first run, will not cancel out the NVT time integration - invoked by the "fix nvt" command. Thus two time integrators would be + for the first run will not cancel out the NVT time integration + invoked by the "fix nvt" command. Thus, two time integrators would be in place! If you specify a new fix with the same ID and style as an existing @@ -79,10 +79,10 @@ for individual fixes for info on which ones can be restarted. Some fixes calculate one of three styles of quantities: global, per-atom, or local, which can be used by other commands or output as -described below. A global quantity is one or more system-wide values, -e.g. the energy of a wall interacting with particles. A per-atom -quantity is one or more values per atom, e.g. the displacement vector -for each atom since time 0. Per-atom values are set to 0.0 for atoms +described below. A global quantity is one or more system-wide values +(e.g., the energy of a wall interacting with particles). A per-atom +quantity is one or more values per atom (e.g., the displacement vector +for each atom since time 0). Per-atom values are set to 0.0 for atoms not in the specified fix group. Local quantities are calculated by each processor based on the atoms it owns, but there may be zero or more per atoms. @@ -95,30 +95,32 @@ The fix page will explain. Global, per-atom, and local quantities each come in three kinds: a single scalar value, a vector of values, or a 2d array of values. The doc page for each fix describes the style and kind of values it -produces, e.g. a per-atom vector. Some fixes produce more than one -kind of a single style, e.g. a global scalar and a global vector. +produces (e.g., a per-atom vector). Some fixes produce more than one +kind of a single style (e.g., a global scalar and a global vector). When a fix quantity is accessed, as in many of the output commands discussed below, it can be referenced via the following bracket notation, where ID is the ID of the fix: +-------------+--------------------------------------------+ -| f_ID | entire scalar, vector, or array | +| f_ID | entire scalar, vector, or array | +-------------+--------------------------------------------+ -| f_ID[I] | one element of vector, one column of array | +| f_ID[I] | one element of vector, one column of array | +-------------+--------------------------------------------+ -| f_ID[I][J] | one element of array | +| f_ID[I][J] | one element of array | +-------------+--------------------------------------------+ In other words, using one bracket reduces the dimension of the -quantity once (vector -> scalar, array -> vector). Using two brackets -reduces the dimension twice (array -> scalar). Thus a command that -uses scalar fix values as input can also process elements of a vector -or array. +quantity once (vector :math:`\to` scalar, array :math:`\to` vector). Using two +brackets reduces the dimension twice (array :math:`\to` scalar). Thus, a +command that uses scalar fix values as input can also process elements of a +vector or array. -Note that commands and :doc:`variables ` which use fix -quantities typically do not allow for all kinds, e.g. a command may -require a vector of values, not a scalar. This means there is no +Note that commands and :doc:`variables ` that use fix +quantities typically do not allow for all kinds (e.g., a command may +require a vector of values, not a scalar), and even if they do, the context +in which they are called can be used to resolve which output is being +requested. This means there is no ambiguity about referring to a fix quantity as f_ID even if it produces, for example, both a scalar and vector. The doc pages for various commands explain the details. @@ -128,34 +130,37 @@ various commands explain the details. In LAMMPS, the values generated by a fix can be used in several ways: * Global values can be output via the :doc:`thermo_style custom ` or :doc:`fix ave/time ` command. - Or the values can be referenced in a :doc:`variable equal ` or - :doc:`variable atom ` command. -* Per-atom values can be output via the :doc:`dump custom ` command. - Or they can be time-averaged via the :doc:`fix ave/atom ` + Alternatively, the values can be referenced in an + :doc:`equal-style variable ` command. +* Per-atom values can be output via the :doc:`dump custom ` command, + or they can be time-averaged via the :doc:`fix ave/atom ` command or reduced by the :doc:`compute reduce ` - command. Or the per-atom values can be referenced in an :doc:`atom-style variable `. -* Local values can be reduced by the :doc:`compute reduce ` command, or histogrammed by the :doc:`fix ave/histo ` command. + command. Alternatively, per-atom values can be referenced in an + :doc:`atom-style variable `. +* Local values can be reduced by the :doc:`compute reduce ` + command or histogrammed by the :doc:`fix ave/histo ` command. + They can also be output by the :doc:`dump local ` command. See the :doc:`Howto output ` page for a summary of various LAMMPS output options, many of which involve fixes. The results of fixes that calculate global quantities can be either "intensive" or "extensive" values. Intensive means the value is -independent of the number of atoms in the simulation, -e.g. temperature. Extensive means the value scales with the number of -atoms in the simulation, e.g. total rotational kinetic energy. +independent of the number of atoms in the simulation +(e.g., temperature). Extensive means the value scales with the number of +atoms in the simulation (e.g., total rotational kinetic energy). :doc:`Thermodynamic output ` will normalize extensive values by the number of atoms in the system, depending on the "thermo_modify norm" setting. It will not normalize intensive values. -If a fix value is accessed in another way, e.g. by a -:doc:`variable `, you may want to know whether it is an -intensive or extensive value. See the page for individual fixes +If a fix value is accessed in another way (e.g., by a +:doc:`variable `), you may want to know whether it is an +intensive or extensive value. See the page for individual fix styles for further info. ---------- -Each fix style has its own page which describes its arguments and -what it does, as listed below. Here is an alphabetic list of fix +Each fix style has its own page that describes its arguments and +what it does, as listed below. Here is an alphabetical list of fix styles available in LAMMPS. They are also listed in more compact form on the :doc:`Commands fix ` doc page. @@ -179,7 +184,7 @@ accelerated styles exist. * :doc:`ave/atom ` - compute per-atom time-averaged quantities * :doc:`ave/chunk ` - compute per-chunk time-averaged quantities * :doc:`ave/correlate ` - compute/output time correlations -* :doc:`ave/correlate/long ` - +* :doc:`ave/correlate/long ` - alternative to :doc:`ave/correlate ` that allows efficient calculation over long time windows * :doc:`ave/histo ` - compute/output time-averaged histograms * :doc:`ave/histo/weight ` - weighted version of fix ave/histo * :doc:`ave/time ` - compute/output global time-averaged quantities @@ -216,10 +221,10 @@ accelerated styles exist. * :doc:`electrode/thermo ` - apply thermo-potentiostat * :doc:`electron/stopping ` - electronic stopping power as a friction force * :doc:`electron/stopping/fit ` - electronic stopping power as a friction force -* :doc:`enforce2d ` - zero out z-dimension velocity and force -* :doc:`eos/cv ` - -* :doc:`eos/table ` - -* :doc:`eos/table/rx ` - +* :doc:`enforce2d ` - zero out *z*-dimension velocity and force +* :doc:`eos/cv ` - applies a mesoparticle equation of state to relate the particle internal energy to the particle internal temperature +* :doc:`eos/table ` - applies a tabulated mesoparticle equation of state to relate the particle internal energy to the particle internal temperature +* :doc:`eos/table/rx ` - applies a tabulated mesoparticle equation of state to relate the concentration-dependent particle internal energy to the particle internal temperature * :doc:`evaporate ` - remove atoms from simulation periodically * :doc:`external ` - callback to an external driver program * :doc:`ffl ` - apply a Fast-Forward Langevin equation thermostat @@ -243,9 +248,9 @@ accelerated styles exist. * :doc:`langevin/eff ` - Langevin temperature control for the electron force field model * :doc:`langevin/spin ` - Langevin temperature control for a spin or spin-lattice system * :doc:`latte ` - wrapper on LATTE density-functional tight-binding code -* :doc:`lb/fluid ` - -* :doc:`lb/momentum ` - -* :doc:`lb/viscous ` - +* :doc:`lb/fluid ` - lattice-Boltzmann fluid on a uniform mesh +* :doc:`lb/momentum ` - :doc:`fix momentum ` replacement for use with a lattice-Boltzmann fluid +* :doc:`lb/viscous ` - :doc:`fix viscous ` replacement for use with a lattice-Boltzmann fluid * :doc:`lineforce ` - constrain atoms to move in a line * :doc:`manifoldforce ` - restrain atoms to a manifold during minimization * :doc:`mdi/qm ` - LAMMPS operates as driver for a quantum code via the MolSSI Driver Interface (MDI) @@ -286,8 +291,8 @@ accelerated styles exist. * :doc:`nve/eff ` - NVE for nuclei and electrons in the electron force field model * :doc:`nve/limit ` - NVE with limited step length * :doc:`nve/line ` - NVE for line segments -* :doc:`nve/manifold/rattle ` - -* :doc:`nve/noforce ` - NVE without forces (v only) +* :doc:`nve/manifold/rattle ` - NVE time integration for atoms constrained to a curved surface (manifold) +* :doc:`nve/noforce ` - NVE without forces (update positions only) * :doc:`nve/sphere ` - NVE for spherical particles * :doc:`nve/bpm/sphere ` - NVE for spherical particles used in the BPM package * :doc:`nve/spin ` - NVE for a spin or spin-lattice system @@ -297,7 +302,7 @@ accelerated styles exist. * :doc:`nvt/asphere ` - NVT for aspherical particles * :doc:`nvt/body ` - NVT for body particles * :doc:`nvt/eff ` - NVE for nuclei and electrons in the electron force field model -* :doc:`nvt/manifold/rattle ` - +* :doc:`nvt/manifold/rattle ` - NVT time integration for atoms constrained to a curved surface (manifold) * :doc:`nvt/sllod ` - NVT for NEMD with SLLOD equations * :doc:`nvt/sllod/eff ` - NVT for NEMD with SLLOD equations for the electron force field model * :doc:`nvt/sphere ` - NVT for spherical particles @@ -312,17 +317,17 @@ accelerated styles exist. * :doc:`planeforce ` - constrain atoms to move in a plane * :doc:`plumed ` - wrapper on PLUMED free energy library * :doc:`poems ` - constrain clusters of atoms to move as coupled rigid bodies -* :doc:`polarize/bem/gmres ` - -* :doc:`polarize/bem/icc ` - -* :doc:`polarize/functional ` - +* :doc:`polarize/bem/gmres ` - compute induced charges at the interface between impermeable media with different dielectric constants with generalized minimum residual (GMRES) +* :doc:`polarize/bem/icc ` - compute induced charges at the interface between impermeable media with different dielectric constants with the successive over-relaxation algorithm +* :doc:`polarize/functional ` - compute induced charges at the interface between impermeable media with different dielectric constants with the energy variational approach * :doc:`pour ` - pour new atoms/molecules into a granular simulation domain -* :doc:`precession/spin ` - +* :doc:`precession/spin ` - apply a precession torque to each magnetic spin * :doc:`press/berendsen ` - pressure control by Berendsen barostat * :doc:`print ` - print text and variables during a simulation * :doc:`propel/self ` - model self-propelled particles * :doc:`property/atom ` - add customized per-atom values * :doc:`python/invoke ` - call a Python function during a simulation -* :doc:`python/move ` - call a Python function during a simulation run +* :doc:`python/move ` - move particles using a Python function during a simulation run * :doc:`qbmsst ` - quantum bath multi-scale shock technique time integrator * :doc:`qeq/comb ` - charge equilibration for COMB potential * :doc:`qeq/dynamic ` - charge equilibration via dynamic method @@ -350,21 +355,21 @@ accelerated styles exist. * :doc:`rigid/nvt ` - constrain one or more clusters of atoms to move as a rigid body with NVT integration * :doc:`rigid/nvt/small ` - constrain many small clusters of atoms to move as a rigid body with NVT integration * :doc:`rigid/small ` - constrain many small clusters of atoms to move as a rigid body with NVE integration -* :doc:`rx ` - -* :doc:`saed/vtk ` - +* :doc:`rx ` - solve reaction kinetic ODEs for a defined reaction set +* :doc:`saed/vtk ` - time-average the intensities from :doc:`compute saed ` * :doc:`setforce ` - set the force on each atom * :doc:`setforce/spin ` - set magnetic precession vectors on each atom * :doc:`shake ` - SHAKE constraints on bonds and/or angles * :doc:`shardlow ` - integration of DPD equations of motion using the Shardlow splitting * :doc:`smd ` - applied a steered MD force to a group -* :doc:`smd/adjust_dt ` - -* :doc:`smd/integrate_tlsph ` - -* :doc:`smd/integrate_ulsph ` - -* :doc:`smd/move_tri_surf ` - -* :doc:`smd/setvel ` - -* :doc:`smd/wall_surface ` - +* :doc:`smd/adjust_dt ` - calculate a new stable time increment for use with SMD integrators +* :doc:`smd/integrate_tlsph ` - explicit time integration with total Lagrangian SPH pair style +* :doc:`smd/integrate_ulsph ` - explicit time integration with updated Lagrangian SPH pair style +* :doc:`smd/move_tri_surf ` - update position and velocity near rigid surfaces using SPH integrators +* :doc:`smd/setvel ` - sets each velocity component, ignoring forces, for Smooth Mach Dynamics +* :doc:`smd/wall_surface ` - create a rigid wall with a triangulated surface for use in Smooth Mach Dynamics * :doc:`sph ` - time integration for SPH/DPDE particles -* :doc:`sph/stationary ` - +* :doc:`sph/stationary ` - update energy and density but not position or velocity in Smooth Particle Hydrodynamics * :doc:`spring ` - apply harmonic spring force to group of atoms * :doc:`spring/chunk ` - apply harmonic spring force to each chunk of atoms * :doc:`spring/rg ` - spring on radius of gyration of group of atoms @@ -372,7 +377,7 @@ accelerated styles exist. * :doc:`srd ` - stochastic rotation dynamics (SRD) * :doc:`store/force ` - store force on each atom * :doc:`store/state ` - store attributes for each atom -* :doc:`tdpd/source ` - +* :doc:`tdpd/source ` - add external concentration source * :doc:`temp/berendsen ` - temperature control by Berendsen thermostat * :doc:`temp/csld ` - canonical sampling thermostat with Langevin dynamics * :doc:`temp/csvr ` - canonical sampling thermostat with Hamiltonian dynamics @@ -381,27 +386,27 @@ accelerated styles exist. * :doc:`tfmc ` - perform force-bias Monte Carlo with time-stamped method * :doc:`tgnvt/drude ` - NVT time integration for Drude polarizable model via temperature-grouped Nose-Hoover * :doc:`tgnpt/drude ` - NPT time integration for Drude polarizable model via temperature-grouped Nose-Hoover -* :doc:`thermal/conductivity ` - Muller-Plathe kinetic energy exchange for thermal conductivity calculation -* :doc:`ti/spring ` - +* :doc:`thermal/conductivity ` - Mueller-Plathe kinetic energy exchange for thermal conductivity calculation +* :doc:`ti/spring ` - perform thermodynamic integration between a solid and an Einstein crystal * :doc:`tmd ` - guide a group of atoms to a new configuration * :doc:`ttm ` - two-temperature model for electronic/atomic coupling (replicated grid) * :doc:`ttm/grid ` - two-temperature model for electronic/atomic coupling (distributed grid) * :doc:`ttm/mod ` - enhanced two-temperature model with additional options -* :doc:`tune/kspace ` - auto-tune KSpace parameters -* :doc:`vector ` - accumulate a global vector every N timesteps -* :doc:`viscosity ` - Muller-Plathe momentum exchange for viscosity calculation +* :doc:`tune/kspace ` - auto-tune :math:`k`-space parameters +* :doc:`vector ` - accumulate a global vector every *N* timesteps +* :doc:`viscosity ` - Mueller-Plathe momentum exchange for viscosity calculation * :doc:`viscous ` - viscous damping for granular simulations * :doc:`viscous/sphere ` - viscous damping on angular velocity for granular simulations -* :doc:`wall/body/polygon ` - -* :doc:`wall/body/polyhedron ` - +* :doc:`wall/body/polygon ` - time integration for body particles of style :doc:`rounded/polygon ` +* :doc:`wall/body/polyhedron ` - time integration for body particles of style :doc:`rounded/polyhedron ` * :doc:`wall/colloid ` - Lennard-Jones wall interacting with finite-size particles * :doc:`wall/ees ` - wall for ellipsoidal particles * :doc:`wall/gran ` - frictional wall(s) for granular simulations -* :doc:`wall/gran/region ` - +* :doc:`wall/gran/region ` - :doc:`fix wall/region ` equivalent for use with granular particles * :doc:`wall/harmonic ` - harmonic spring wall -* :doc:`wall/lj1043 ` - Lennard-Jones 10-4-3 wall -* :doc:`wall/lj126 ` - Lennard-Jones 12-6 wall -* :doc:`wall/lj93 ` - Lennard-Jones 9-3 wall +* :doc:`wall/lj1043 ` - Lennard-Jones 10--4--3 wall +* :doc:`wall/lj126 ` - Lennard-Jones 12--6 wall +* :doc:`wall/lj93 ` - Lennard-Jones 9--3 wall * :doc:`wall/morse ` - Morse potential wall * :doc:`wall/piston ` - moving reflective piston wall * :doc:`wall/reflect ` - reflecting wall(s) @@ -415,7 +420,8 @@ Restrictions """""""""""" Some fix styles are part of specific packages. They are only enabled -if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. The doc pages for +if LAMMPS was built with that package. See the +:doc:`Build package ` page for more info. The doc pages for individual fixes tell if it is part of a package. Related commands diff --git a/doc/src/fix_ave_chunk.rst b/doc/src/fix_ave_chunk.rst index cda706a217..8165083a83 100644 --- a/doc/src/fix_ave_chunk.rst +++ b/doc/src/fix_ave_chunk.rst @@ -71,23 +71,27 @@ Examples fix 1 flow ave/chunk 100 5 1000 binchunk density/mass ave running fix 1 flow ave/chunk 100 5 1000 binchunk density/mass ave running -**NOTE:** -If you are trying to replace a deprecated fix ave/spatial command -with the newer, more flexible fix ave/chunk and :doc:`compute chunk/atom ` commands, you simply need to split -the fix ave/spatial arguments across the two new commands. For -example, this command: +.. note:: -.. code-block:: LAMMPS + .. versionchanged:: 31May2016 - fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile + If you are trying to replace a deprecated fix ave/spatial command + with the newer, more flexible fix ave/chunk and :doc:`compute + chunk/atom ` commands, you simply need to split + the fix ave/spatial arguments across the two new commands. For + example, this command: -could be replaced by: + .. code-block:: LAMMPS -.. code-block:: LAMMPS + fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile - compute cc1 flow chunk/atom bin/1d y 0.0 1.0 - fix 1 flow ave/chunk 100 10 1000 cc1 vx vz norm sample file vel.profile + could be replaced by: + + .. code-block:: LAMMPS + + compute cc1 flow chunk/atom bin/1d y 0.0 1.0 + fix 1 flow ave/chunk 100 10 1000 cc1 vx vz norm sample file vel.profile Description """"""""""" @@ -236,10 +240,16 @@ bins, the volume is the bin volume. Otherwise it is the volume of the entire simulation box. The *temp* value means the temperature is computed for each chunk, by -the formula KE = DOF/2 k T, where KE = total kinetic energy of the -chunk of atoms (sum of 1/2 m v\^2), DOF = the total number of degrees -of freedom for all atoms in the chunk, k = Boltzmann constant, and T = -temperature. +the formula + +.. math:: + + \text{KE} = \frac{\text{DOF}}{2} k_B T, + +where KE = total kinetic energy of the chunk of atoms (sum of +:math:`\frac{1}{2} m v^2`), DOF = the total number of degrees of freedom +for all atoms in the chunk, :math:`k_B` = Boltzmann constant, and +:math:`T` = temperature. The DOF is calculated as N\*adof + cdof, where N = number of atoms in the chunk, adof = degrees of freedom per atom, and cdof = degrees of diff --git a/doc/src/fix_eos_table_rx.rst b/doc/src/fix_eos_table_rx.rst index 2e91b7dd88..c9f134f985 100644 --- a/doc/src/fix_eos_table_rx.rst +++ b/doc/src/fix_eos_table_rx.rst @@ -45,14 +45,14 @@ computed according to the following relation: .. math:: - U_{i} = \displaystyle\sum_{j=1}^{m} c_{i,j}(u_{j} + \Delta H_{f,j}) + \frac{3k_{b}T}{2} + Nk_{b}T \\ + U_{i} = \displaystyle\sum_{j=1}^{m} c_{i,j}(u_{j} + \Delta H_{f,j}) + \frac{3k_{B}T}{2} + Nk_{B}T \\ where *m* is the number of species, :math:`c_{i,j}` is the concentration of species *j* in particle *i*, :math:`u_j` is the internal energy of species j, :math:`\Delta H_{f,j} is the heat of formation of species *j*, N is the number of molecules represented -by the coarse-grained particle, :math:`k_b` is the Boltzmann constant, -and *T* is the temperature of the system. Additionally, it is +by the coarse-grained particle, :math:`k_B` is the Boltzmann constant, +and :math:`T` is the temperature of the system. Additionally, it is possible to modify the concentration-dependent particle internal energy relation by adding an energy correction, temperature-dependent correction, and/or a molecule-dependent correction. An energy diff --git a/doc/src/fix_gcmc.rst b/doc/src/fix_gcmc.rst index 760f41e186..62b858a0af 100644 --- a/doc/src/fix_gcmc.rst +++ b/doc/src/fix_gcmc.rst @@ -259,9 +259,9 @@ pressure of the fictitious gas reservoir by: .. math:: \mu^{id} = & k T \ln{\rho \Lambda^3} \\ - = & k T \ln{\frac{\phi P \Lambda^3}{k T}} + = & k T \ln{\frac{\phi P \Lambda^3}{k_B T}} -where *k* is Boltzman's constant, *T* is the user-specified +where :math:`k_B` is the Boltzmann constant, :math:`T` is the user-specified temperature, :math:`\rho` is the number density, *P* is the pressure, and :math:`\phi` is the fugacity coefficient. The constant :math:`\Lambda` is required for dimensional consistency. For all unit @@ -269,7 +269,7 @@ styles except *lj* it is defined as the thermal de Broglie wavelength .. math:: - \Lambda = \sqrt{ \frac{h^2}{2 \pi m k T}} + \Lambda = \sqrt{ \frac{h^2}{2 \pi m k_B T}} where *h* is Planck's constant, and *m* is the mass of the exchanged atom or molecule. For unit style *lj*, :math:`\Lambda` is simply set to @@ -320,7 +320,7 @@ this will ensure roughly the same behavior whether or not the *full_energy* option is used. Inserted atoms and molecules are assigned random velocities based on -the specified temperature *T*. Because the relative velocity of all +the specified temperature :math:`T`. Because the relative velocity of all atoms in the molecule is zero, this may result in inserted molecules that are systematically too cold. In addition, the intramolecular potential energy of the inserted molecule may cause the kinetic energy diff --git a/doc/src/fix_langevin.rst b/doc/src/fix_langevin.rst index 5979155799..50c1489d7c 100644 --- a/doc/src/fix_langevin.rst +++ b/doc/src/fix_langevin.rst @@ -81,11 +81,11 @@ the particle's velocity. The proportionality constant for each atom is computed as :math:`\frac{m}{\mathrm{damp}}`, where *m* is the mass of the particle and damp is the damping factor specified by the user. -:math:`F_r` is a force due to solvent atoms at a temperature *T* +:math:`F_r` is a force due to solvent atoms at a temperature :math:`T` randomly bumping into the particle. As derived from the fluctuation/dissipation theorem, its magnitude as shown above is proportional to :math:`\sqrt{\frac{k_B T m}{dt~\mathrm{damp}}}`, where -:math:`k_B` is the Boltzmann constant, *T* is the desired temperature, +:math:`k_B` is the Boltzmann constant, :math:`T` is the desired temperature, *m* is the mass of the particle, *dt* is the timestep size, and damp is the damping factor. Random numbers are used to randomize the direction and magnitude of this force as described in :ref:`(Dunweg) `, diff --git a/doc/src/fix_nh.rst b/doc/src/fix_nh.rst index cb9e6ba61e..5e8f313323 100644 --- a/doc/src/fix_nh.rst +++ b/doc/src/fix_nh.rst @@ -208,9 +208,9 @@ The relaxation rate of the barostat is set by its inertia :math:`W`: .. math:: - W = (N + 1) k T_{\rm target} P_{\rm damp}^2 + W = (N + 1) k_B T_{\rm target} P_{\rm damp}^2 -where :math:`N` is the number of atoms, :math:`k` is the Boltzmann constant, +where :math:`N` is the number of atoms, :math:`k_B` is the Boltzmann constant, and :math:`T_{\rm target}` is the target temperature of the barostat :ref:`(Martyna) `. If a thermostat is defined, :math:`T_{\rm target}` is the target temperature of the thermostat. If a thermostat is not defined, :math:`T_{\rm target}` diff --git a/doc/src/fix_nphug.rst b/doc/src/fix_nphug.rst index b45cfe964f..1cedfa909a 100644 --- a/doc/src/fix_nphug.rst +++ b/doc/src/fix_nphug.rst @@ -88,20 +88,23 @@ target temperature Tt obtained from the following equation: T_t - T = \frac{\left(\frac{1}{2}\left(P + P_0\right)\left(V_0 - V\right) + E_0 - E\right)}{N_{dof} k_B } = \Delta -where *T* and :math:`T_t` are the instantaneous and target temperatures, -*P* and :math:`P_0` are the instantaneous and reference pressures or axial stresses, -depending on whether hydrostatic or uniaxial compression is being -performed, *V* and :math:`V_0` are the instantaneous and reference volumes, -*E* and :math:`E_0` are the instantaneous and reference internal energy (potential -plus kinetic), :math:`N_{dof}` is the number of degrees of freedom used in the -definition of temperature, and :math:`k_B` is the Boltzmann constant. :math:`\Delta` is the -negative deviation of the instantaneous temperature from the target temperature. -When the system reaches a stable equilibrium, the value of :math:`\Delta` should -fluctuate about zero. +where :math:`T` and :math:`T_t` are the instantaneous and target +temperatures, *P* and :math:`P_0` are the instantaneous and reference +pressures or axial stresses, depending on whether hydrostatic or +uniaxial compression is being performed, *V* and :math:`V_0` are the +instantaneous and reference volumes, *E* and :math:`E_0` are the +instantaneous and reference internal energy (potential plus kinetic), +:math:`N_{dof}` is the number of degrees of freedom used in the +definition of temperature, and :math:`k_B` is the Boltzmann +constant. :math:`\Delta` is the negative deviation of the instantaneous +temperature from the target temperature. When the system reaches a +stable equilibrium, the value of :math:`\Delta` should fluctuate about +zero. -The values of :math:`E_0`, :math:`V_0`, and :math:`P_0` are the instantaneous values at the start of -the simulation. These can be overridden using the fix_modify keywords *e0*, -*v0*, and *p0* described below. +The values of :math:`E_0`, :math:`V_0`, and :math:`P_0` are the +instantaneous values at the start of the simulation. These can be +overridden using the fix_modify keywords *e0*, *v0*, and *p0* described +below. ---------- diff --git a/doc/src/fix_nve_dotc_langevin.rst b/doc/src/fix_nve_dotc_langevin.rst index c2835aaccd..e47e8f4a2a 100644 --- a/doc/src/fix_nve_dotc_langevin.rst +++ b/doc/src/fix_nve_dotc_langevin.rst @@ -73,11 +73,11 @@ the particle's velocity. The proportionality constant for each atom is computed as :math:`\frac{m}{\mathrm{damp}}`, where *m* is the mass of the particle and damp is the damping factor specified by the user. -:math:`F_r` is a force due to solvent atoms at a temperature *T* +:math:`F_r` is a force due to solvent atoms at a temperature :math:`T` randomly bumping into the particle. As derived from the fluctuation/dissipation theorem, its magnitude as shown above is proportional to :math:`\sqrt{\frac{k_B T m}{dt~\mathrm{damp}}}`, where -:math:`k_B` is the Boltzmann constant, *T* is the desired temperature, +:math:`k_B` is the Boltzmann constant, :math:`T` is the desired temperature, *m* is the mass of the particle, *dt* is the timestep size, and damp is the damping factor. Random numbers are used to randomize the direction and magnitude of this force as described in :ref:`(Dunweg) `, diff --git a/doc/src/fix_viscous.rst b/doc/src/fix_viscous.rst index 45c31e10cf..6c48cb5f12 100644 --- a/doc/src/fix_viscous.rst +++ b/doc/src/fix_viscous.rst @@ -57,12 +57,12 @@ multiple times to adjust :math:`\gamma` for several atom types. self-consistent. In a Brownian dynamics context, :math:`\gamma = \frac{k_B T}{D}`, where -:math:`k_B =` Boltzmann's constant, *T* = temperature, and *D* = particle -diffusion coefficient. *D* can be written as :math:`\frac{k_B T}{3 \pi -\eta d}`, where :math:`\eta =` dynamic viscosity of the frictional fluid -and d = diameter of particle. This means :math:`\gamma = 3 \pi \eta d`, -and thus is proportional to the viscosity of the fluid and the particle -diameter. +:math:`k_B =` Boltzmann's constant, :math:`T` = temperature, and *D* = +particle diffusion coefficient. *D* can be written as :math:`\frac{k_B +T}{3 \pi \eta d}`, where :math:`\eta =` dynamic viscosity of the +frictional fluid and d = diameter of particle. This means :math:`\gamma += 3 \pi \eta d`, and thus is proportional to the viscosity of the fluid +and the particle diameter. In the current implementation, rather than have the user specify a viscosity, :math:`\gamma` is specified directly in force/velocity units. diff --git a/doc/src/fix_widom.rst b/doc/src/fix_widom.rst index 34b9ae44f6..5be93100b3 100644 --- a/doc/src/fix_widom.rst +++ b/doc/src/fix_widom.rst @@ -100,11 +100,11 @@ The excess chemical potential mu_ex is defined as: .. math:: - \mu_{ex} = -kT \ln(<\exp(-(U_{N+1}-U_{N})/{kT})>) + \mu_{ex} = -kT \ln(<\exp(-(U_{N+1}-U_{N})/{k_B T})>) -where *k* is Boltzman's constant, *T* is the user-specified temperature, -U_N and U_{N+1} is the potential energy of the system with N and N+1 -particles. +where :math:`k_B` is the Boltzmann constant, :math:`T` is the +user-specified temperature, :math:`U_N` and :math:`U_{N+1}` is the +potential energy of the system with :math:`N` and :math:`N+1` particles. The *full_energy* option means that the fix calculates the total potential energy of the entire simulated system, instead of just the diff --git a/doc/src/group.rst b/doc/src/group.rst index 9d93e949f9..5cdbfb5c13 100644 --- a/doc/src/group.rst +++ b/doc/src/group.rst @@ -6,12 +6,12 @@ group command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS group ID style args * ID = user-defined name of the group -* style = *delete* or *clear* or *empty* or *region* or *type* or *id* or *molecule* or *variable* or *include* or *subtract* or *union* or *intersect* or *dynamic* or *static* +* style = *delete* or *clear* or *empty* or *region* or *type* or *id* or *molecule* or *variable* or *include* or *subtract* or *union* or *intersect* or *dynamic* or *static* .. parsed-literal:: @@ -87,8 +87,8 @@ atoms to the group. LAMMPS commands operate on groups of atoms, you should think carefully about whether making a group dynamic makes sense for your model. -A group with the ID *all* is predefined. All atoms belong to this -group. This group cannot be deleted, or made dynamic. +A group with the ID *all* is predefined. All atoms belong to this group. +This group cannot be deleted, or made dynamic. The *delete* style removes the named group and un-assigns all atoms that were assigned to that group. Since there is a restriction (see @@ -99,9 +99,9 @@ been used to define a current :doc:`fix ` or :doc:`compute ` or :doc:`dump `. The *clear* style un-assigns all atoms that were assigned to that -group. This may be dangerous to do during a simulation run, -e.g. using the :doc:`run every ` command if a fix or compute or -other operation expects the atoms in the group to remain constant, but +group. This may be dangerous to do during a simulation run +(e.g., using the :doc:`run every ` command if a fix or compute or +other operation expects the atoms in the group to remain constant), but LAMMPS does not check for this. The *empty* style creates an empty group, which is useful for commands @@ -115,7 +115,7 @@ the region volume. The *type*, *id*, and *molecule* styles put all atoms with the specified atom types, atom IDs, or molecule IDs into the group. These -3 styles can use arguments specified in one of two formats. +three styles can use arguments specified in one of two formats. The first format is a list of values (types or IDs). For example, the second command in the examples above puts all atoms of type 3 or 4 into @@ -124,15 +124,15 @@ colon-separated sequence ``A:B`` or ``A:B:C``, as in two of the examples above. A "sequence" generates a sequence of values (types or IDs), with an optional increment. The first example with ``500:1000`` has the default increment of 1 and would add all atom IDs from 500 to 1000 -(inclusive) to the group sub, along with 10,25,50 since they also +(inclusive) to the group sub, along with 10, 25, and 50 since they also appear in the list of values. The second example with ``100:10000:10`` uses an increment of 10 and would thus would add atoms IDs -100,110,120, ... 9990,10000 to the group sub. +:math:`100, 110, 120, \dots, 9990, 10000` to the group sub. The second format is a *logical* followed by one or two values (type or ID). The 7 valid logicals are listed above. All the logicals -except <> take a single argument. The third example above adds all -atoms with IDs from 1 to 150 to the group named *sub*\ . The logical <> +except ``<>`` take a single argument. The third example above adds all +atoms with IDs from 1 to 150 to the group named *sub*\ . The logical ``<>`` means "between" and takes 2 arguments. The fourth example above adds all atoms belonging to molecules with IDs from 50 to 250 (inclusive) to the group named polyA. @@ -146,14 +146,14 @@ to the specified group. Atom-style variables can specify formulas that include thermodynamic quantities, per-atom values such as atom coordinates, or per-atom quantities calculated by computes, fixes, or other variables. They -can also include Boolean logic where 2 numeric values are compared to -yield a 1 or 0 (effectively a true or false). Thus using the -*variable* style, is a general way to flag specific atoms to include +can also include Boolean logic where two numeric values are compared to +yield a 1 or 0 (effectively a true or false). Thus, using the +*variable* style is a general way to flag specific atoms to include or exclude from a group. For example, these lines define a variable "eatom" that calculates the potential energy of each atom and includes it in the group if its -potential energy is above the threshold value -3.0. +potential energy is above the threshold value :math:`-3.0`. .. code-block:: LAMMPS @@ -252,7 +252,7 @@ arrays as arguments. The assignment of atoms to a dynamic group is done at the beginning of each run and on every timestep that is a multiple of *N*\ , which is -the argument for the *every* keyword (N = 1 is the default). For an +the argument for the *every* keyword (:math:`N = 1` is the default). For an energy minimization, via the :doc:`minimize ` command, an assignment is made at the beginning of the minimization, but not during the iterations of the minimizer. @@ -265,8 +265,8 @@ lists and ghost atoms are current, and both intermolecular and intramolecular forces have been calculated based on the new coordinates. Thus the region criterion, if applied, should be accurate. Also, any computes invoked by an atom-style variable should -use updated information for that timestep, e.g. potential energy/atom -or coordination number/atom. Similarly, fixes or computes which are +use updated information for that timestep (e.g., potential energy/atom +or coordination number/atom). Similarly, fixes or computes which are invoked after that point in the timestep, should operate on the new group of atoms. @@ -277,7 +277,7 @@ group of atoms. between reneighboring events. Thus if you want to include all atoms on the left side of the simulation box, you probably want to set the left boundary of the region to be outside the simulation box by some - reasonable amount (e.g. up to the cutoff of the potential), else they + reasonable amount (e.g., up to the cutoff of the potential), else they may be excluded from the dynamic region. Here is an example of using a dynamic group to shrink the set of atoms @@ -318,7 +318,7 @@ Restrictions """""""""""" There can be no more than 32 groups defined at one time, including -"all". +"all." The parent group of a dynamic group cannot itself be a dynamic group. diff --git a/doc/src/if.rst b/doc/src/if.rst index d40eca0ba8..e717457425 100644 --- a/doc/src/if.rst +++ b/doc/src/if.rst @@ -6,7 +6,7 @@ if command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS if boolean then t1 t2 ... elif boolean f1 f2 ... elif boolean f1 f2 ... else e1 e2 ... @@ -58,14 +58,14 @@ Boolean expression is FALSE, then no commands are executed. The syntax for Boolean expressions is described below. -Each command (t1, f1, e1, etc) can be any valid LAMMPS input script +Each command (t1, f1, e1, etc.) can be any valid LAMMPS input script command. If the command is more than one word, it must enclosed in quotes, so it will be treated as a single argument, as in the examples above. .. note:: - If a command itself requires a quoted argument (e.g. a + If a command itself requires a quoted argument (e.g., a :doc:`print ` command), then double and single quotes can be used and nested in the usual manner, as in the examples above and below. The :doc:`Commands parse ` page has more details on @@ -153,33 +153,33 @@ and Boolean operators: A == B, A != B, A < B, A <= B, A > B, A >= B, A && B, A \|\| B, A \|\^ B, !A -Each A and B is a number or string or a variable reference like $a or -${abc}, or A or B can be another Boolean expression. +Each A and B is a number or string or a variable reference like ``$a`` or +``${abc}``, or A or B can be another Boolean expression. Note that all variables used will be substituted for before the Boolean expression in evaluated. A variable can produce a number, -like an :doc:`equal-style variable `. Or it can produce a +like an :doc:`equal-style variable `, or it can produce a string, like an :doc:`index-style variable `. -The Boolean operators "==" and "!=" can operate on a pair or strings +The Boolean operators ``==`` and ``!=`` can operate on a pair or strings or numbers. They cannot compare a number to a string. All the other Boolean operations can only operate on numbers. Expressions are evaluated left to right and have the usual C-style -precedence: the unary logical NOT operator "!" has the highest -precedence, the 4 relational operators "<", "<=", ">", and ">=" are -next; the two remaining relational operators "==" and "!=" are next; -then the logical AND operator "&&"; and finally the logical OR -operator "\|\|" and logical XOR (exclusive or) operator "\|\^" have +precedence: the unary logical NOT operator ``!`` has the highest +precedence, the 4 relational operators ``<``, ``<=``, ``>``, and ``>=`` are +next; the two remaining relational operators ``==`` and ``!=`` are next; +then the logical AND operator ``&&``; and finally the logical OR +operator ``||`` and logical XOR (exclusive or) operator ``|^`` have the lowest precedence. Parenthesis can be used to group one or more portions of an expression and/or enforce a different order of evaluation than what would occur with the default precedence. -When the 6 relational operators (first 6 in list above) compare 2 +When the six relational operators (first six in list above) compare two numbers, they return either a 1.0 or 0.0 depending on whether the relationship between A and B is TRUE or FALSE. -When the 3 logical operators (last 3 in list above) compare 2 numbers, +When the three logical operators (last three in list above) compare two numbers, they also return either a 1.0 or 0.0 depending on whether the relationship between A and B is TRUE or FALSE (or just A). The logical AND operator will return 1.0 if both its arguments are diff --git a/doc/src/pair_dpd_ext.rst b/doc/src/pair_dpd_ext.rst index 88395f1c73..54d1e4bca3 100644 --- a/doc/src/pair_dpd_ext.rst +++ b/doc/src/pair_dpd_ext.rst @@ -80,8 +80,8 @@ the corresponding cutoff, :math:`w_{\alpha} ( r ) = ( 1 - r / \bar{r}_c )^{s_{\alpha}}`, :math:`\alpha \equiv ( \parallel, \perp )`, are weight functions with coefficients :math:`s_\alpha` that vary between 0 and 1, :math:`\bar{r}_c` is the corresponding cutoff, :math:`\mathbf{I}` is the -unit matrix, :math:`\sigma_{\alpha} = \sqrt{2 k T \gamma_{\alpha}}`, -where :math:`k` is the Boltzmann constant and :math:`T` is the +unit matrix, :math:`\sigma_{\alpha} = \sqrt{2 k_B T \gamma_{\alpha}}`, +where :math:`k_B` is the Boltzmann constant and :math:`T` is the temperature in the pair\_style command. For the style *dpd/ext/tstat*, the force on atom I due to atom J is @@ -121,7 +121,7 @@ as in the examples above: The last coefficient is optional. If not specified, the global DPD cutoff is used. Note that :math:`\sigma`'s are set equal to -:math:`\sqrt{2 k T \gamma}`, where :math:`T` is the temperature set by +:math:`\sqrt{2 k_B T \gamma}`, where :math:`T` is the temperature set by the :doc:`pair_style ` command so it does not need to be specified. diff --git a/doc/src/pair_ufm.rst b/doc/src/pair_ufm.rst index 22438d559b..5de0b91ee7 100644 --- a/doc/src/pair_ufm.rst +++ b/doc/src/pair_ufm.rst @@ -43,7 +43,7 @@ Style *ufm* computes pairwise interactions using the Uhlenbeck-Ford model (UFM) where :math:`r_c` is the cutoff, :math:`\sigma` is a distance-scale and :math:`\epsilon` is an energy-scale, i.e., a product of Boltzmann constant -:math:`k_B`, temperature *T* and the Uhlenbeck-Ford p-parameter which +:math:`k_B`, temperature :math:`T` and the Uhlenbeck-Ford p-parameter which is responsible to control the softness of the interactions :ref:`(Paula Leite2017) `. This model is useful as a reference system for fluid-phase free-energy calculations :ref:`(Paula Leite2016) `. 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 diff --git a/doc/utils/sphinx-config/conf.py.in b/doc/utils/sphinx-config/conf.py.in index 6b95da5a7e..c89aa8b4ae 100644 --- a/doc/utils/sphinx-config/conf.py.in +++ b/doc/utils/sphinx-config/conf.py.in @@ -385,7 +385,7 @@ from sphinx.highlighting import lexers lexers['LAMMPS'] = LAMMPSLexer.LAMMPSLexer(startinline=True) -sys.path.append(LAMMPS_PYTHON_DIR) +sys.path.insert(1,LAMMPS_PYTHON_DIR) # avoid syntax highlighting in blocks that don't specify language highlight_language = 'none' diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index a324f41941..8b3689c367 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -257,6 +257,7 @@ Bfrac bgq Bh Bialke +biaxial bicrystal Biersack bigbig @@ -304,7 +305,6 @@ Bogaerts Bogusz Bohrs boltz -Boltzman BondAngle BondBond bondchk @@ -3645,6 +3645,7 @@ Vandenbrande Vanduyfhuys varargs varavg +variational Varshalovich Varshney vashishta diff --git a/src/change_box.cpp b/src/change_box.cpp index 08af5f11c9..b26d7803ed 100644 --- a/src/change_box.cpp +++ b/src/change_box.cpp @@ -46,14 +46,14 @@ void ChangeBox::command(int narg, char **arg) if (domain->box_exist == 0) error->all(FLERR,"Change_box command before simulation box is defined"); - if (narg < 2) error->all(FLERR,"Illegal change_box command"); + if (narg < 2) utils::missing_cmd_args(FLERR, "change_box", error); if (comm->me == 0) utils::logmesg(lmp,"Changing box ...\n"); // group int igroup = group->find(arg[0]); - if (igroup == -1) error->all(FLERR,"Could not find change_box group ID"); + if (igroup == -1) error->all(FLERR,"Could not find change_box group ID {}", arg[0]); int groupbit = group->bitmask[igroup]; // parse operation arguments @@ -70,7 +70,7 @@ void ChangeBox::command(int narg, char **arg) while (iarg < narg) { if (strcmp(arg[iarg],"x") == 0 || strcmp(arg[iarg],"y") == 0 || strcmp(arg[iarg],"z") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal change_box command"); + if (iarg+2 > narg) error->all(FLERR, "Illegal change_box {} command: missing argument(s)", arg[iarg]); ops[nops].style = XYZ; if (strcmp(arg[iarg],"x") == 0) ops[nops].dim = X; else if (strcmp(arg[iarg],"y") == 0) ops[nops].dim = Y; @@ -80,7 +80,7 @@ void ChangeBox::command(int narg, char **arg) error->all(FLERR,"Cannot change_box in z dimension for 2d simulation"); if (strcmp(arg[iarg+1],"final") == 0) { - if (iarg+4 > narg) error->all(FLERR,"Illegal change_box command"); + if (iarg+4 > narg) error->all(FLERR, "Illegal change_box {} final command: missing argument(s)", arg[iarg]); ops[nops].flavor = FINAL; ops[nops].flo = utils::numeric(FLERR,arg[iarg+2],false,lmp); ops[nops].fhi = utils::numeric(FLERR,arg[iarg+3],false,lmp); @@ -88,7 +88,7 @@ void ChangeBox::command(int narg, char **arg) nops++; iarg += 4; } else if (strcmp(arg[iarg+1],"delta") == 0) { - if (iarg+4 > narg) error->all(FLERR,"Illegal change_box command"); + if (iarg+4 > narg) error->all(FLERR, "Illegal change_box {} delta command: missing argument(s)", arg[iarg]); ops[nops].flavor = DELTA; ops[nops].dlo = utils::numeric(FLERR,arg[iarg+2],false,lmp); ops[nops].dhi = utils::numeric(FLERR,arg[iarg+3],false,lmp); @@ -96,7 +96,7 @@ void ChangeBox::command(int narg, char **arg) nops++; iarg += 4; } else if (strcmp(arg[iarg+1],"scale") == 0) { - if (iarg+3 > narg) error->all(FLERR,"Illegal change_box command"); + if (iarg+3 > narg) error->all(FLERR, "Illegal change_box {} scale command: missing argument(s)", arg[iarg]); ops[nops].flavor = SCALE; ops[nops].scale = utils::numeric(FLERR,arg[iarg+2],false,lmp); ops[nops].vdim1 = ops[nops].vdim2 = -1; @@ -112,11 +112,11 @@ void ChangeBox::command(int narg, char **arg) else ops[nops-1].vdim1 = ops[nops].dim; iarg += 2; - } else error->all(FLERR,"Illegal change_box command"); + } else error->all(FLERR, "Unknown change_box {} argument: {}", arg[iarg], arg[iarg+1]); } else if (strcmp(arg[iarg],"xy") == 0 || strcmp(arg[iarg],"xz") == 0 || strcmp(arg[iarg],"yz") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal change_box command"); + if (iarg+2 > narg) error->all(FLERR, "Illegal change_box {} command: missing argument(s)", arg[iarg]); ops[nops].style = TILT; if (strcmp(arg[iarg],"xy") == 0) ops[nops].dim = XY; else if (strcmp(arg[iarg],"xz") == 0) ops[nops].dim = XZ; @@ -126,21 +126,21 @@ void ChangeBox::command(int narg, char **arg) error->all(FLERR,"Cannot change_box in xz or yz for 2d simulation"); if (strcmp(arg[iarg+1],"final") == 0) { - if (iarg+3 > narg) error->all(FLERR,"Illegal change_box command"); + if (iarg+3 > narg) error->all(FLERR, "Illegal change_box {} final command: missing argument(s)", arg[iarg]); ops[nops].flavor = FINAL; ops[nops].ftilt = utils::numeric(FLERR,arg[iarg+2],false,lmp); nops++; iarg += 3; } else if (strcmp(arg[iarg+1],"delta") == 0) { - if (iarg+3 > narg) error->all(FLERR,"Illegal change_box command"); + if (iarg+3 > narg) error->all(FLERR, "Illegal change_box {} delta command: missing argument(s)", arg[iarg]); ops[nops].flavor = DELTA; ops[nops].dtilt = utils::numeric(FLERR,arg[iarg+2],false,lmp); nops++; iarg += 3; - } else error->all(FLERR,"Illegal change_box command"); + } else error->all(FLERR, "Unknown change_box {} argument: {}", arg[iarg], arg[iarg+1]); } else if (strcmp(arg[iarg],"boundary") == 0) { - if (iarg+4 > narg) error->all(FLERR,"Illegal change_box command"); + if (iarg+4 > narg) utils::missing_cmd_args(FLERR, "change_box boundary", error); ops[nops].style = BOUNDARY; ops[nops].boundindex = iarg+1; nops++; @@ -157,7 +157,6 @@ void ChangeBox::command(int narg, char **arg) iarg += 1; } else if (strcmp(arg[iarg],"set") == 0) { - if (iarg+1 > narg) error->all(FLERR,"Illegal change_box command"); ops[nops].style = SET; nops++; iarg += 1; @@ -170,7 +169,7 @@ void ChangeBox::command(int narg, char **arg) } else break; } - if (nops == 0) error->all(FLERR,"Illegal change_box command"); + if (nops == 0) error->all(FLERR, "Unknown change_box keyword: {}", arg[iarg]); // move_atoms = 1 if need to move atoms to new procs after box changes // anything other than ORTHO or TRICLINIC may cause atom movement @@ -393,19 +392,19 @@ void ChangeBox::command(int narg, char **arg) void ChangeBox::options(int narg, char **arg) { - if (narg < 0) error->all(FLERR,"Illegal change_box command"); + if (narg < 0) utils::missing_cmd_args(FLERR, "change_box", error); scaleflag = 1; int iarg = 0; while (iarg < narg) { if (strcmp(arg[iarg],"units") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal change_box command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "change_box units", error); if (strcmp(arg[iarg+1],"box") == 0) scaleflag = 0; else if (strcmp(arg[iarg+1],"lattice") == 0) scaleflag = 1; - else error->all(FLERR,"Illegal change_box command"); + else error->all(FLERR, "Invalid change_box units argument: {}", arg[iarg+1]); iarg += 2; - } else error->all(FLERR,"Illegal change_box command"); + } else error->all(FLERR,"Unknown change_box keyword: {}", arg[iarg]); } } diff --git a/src/comm.cpp b/src/comm.cpp index 5175af28e5..1679cc3c41 100644 --- a/src/comm.cpp +++ b/src/comm.cpp @@ -282,12 +282,12 @@ void Comm::init_exchange() void Comm::modify_params(int narg, char **arg) { - if (narg < 1) error->all(FLERR,"Illegal comm_modify command"); + if (narg < 1) utils::missing_cmd_args(FLERR, "comm_modify", error); int iarg = 0; while (iarg < narg) { if (strcmp(arg[iarg],"mode") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal comm_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "comm_modify mode", error); if (strcmp(arg[iarg+1],"single") == 0) { // need to reset cutghostuser when switching comm mode if (mode == Comm::MULTI) cutghostuser = 0.0; @@ -311,26 +311,27 @@ void Comm::modify_params(int narg, char **arg) if (mode == Comm::MULTI) cutghostuser = 0.0; memory->destroy(cutusermulti); mode = Comm::MULTIOLD; - } else error->all(FLERR,"Illegal comm_modify command"); + } else error->all(FLERR,"Unknown comm_modify mode argument: {}", arg[iarg+1]); iarg += 2; } else if (strcmp(arg[iarg],"group") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal comm_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "comm_modify group", error); bordergroup = group->find(arg[iarg+1]); if (bordergroup < 0) - error->all(FLERR,"Invalid group in comm_modify command"); - if (bordergroup && (atom->firstgroupname == nullptr || - strcmp(arg[iarg+1],atom->firstgroupname) != 0)) - error->all(FLERR,"Comm_modify group != atom_modify first group"); + error->all(FLERR, "Invalid comm_modify keyword: group {} not found", arg[iarg+1]); + if (atom->firstgroupname == nullptr) + error->all(FLERR, "Invalid comm_modify keyword: atom_modify first command must be used"); + if (strcmp(arg[iarg+1],atom->firstgroupname) != 0) + error->all(FLERR, "comm_modify group != atom_modify first group: {}", atom->firstgroupname); iarg += 2; } else if (strcmp(arg[iarg],"cutoff") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal comm_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "comm_modify cutoff", error); if (mode == Comm::MULTI) error->all(FLERR, "Use cutoff/multi keyword to set cutoff in multi mode"); if (mode == Comm::MULTIOLD) error->all(FLERR, "Use cutoff/multi/old keyword to set cutoff in multi mode"); cutghostuser = utils::numeric(FLERR,arg[iarg+1],false,lmp); if (cutghostuser < 0.0) - error->all(FLERR,"Invalid cutoff in comm_modify command"); + error->all(FLERR,"Invalid cutoff {} in comm_modify command", arg[iarg+1]); iarg += 2; } else if (strcmp(arg[iarg],"cutoff/multi") == 0) { int i,nlo,nhi; @@ -355,7 +356,7 @@ void Comm::modify_params(int narg, char **arg) cut = utils::numeric(FLERR,arg[iarg+2],false,lmp); cutghostuser = MAX(cutghostuser,cut); if (cut < 0.0) - error->all(FLERR,"Invalid cutoff in comm_modify command"); + error->all(FLERR,"Invalid cutoff {} in comm_modify command", arg[iarg+2]); // collections use 1-based indexing externally and 0-based indexing internally for (i=nlo; i<=nhi; ++i) cutusermulti[i-1] = cut; @@ -370,8 +371,7 @@ void Comm::modify_params(int narg, char **arg) if (domain->box_exist == 0) error->all(FLERR, "Cannot set cutoff/multi before simulation box is defined"); const int ntypes = atom->ntypes; - if (iarg+3 > narg) - error->all(FLERR,"Illegal comm_modify command"); + if (iarg+3 > narg) utils::missing_cmd_args(FLERR, "comm_modify cutoff/multi/old", error); if (cutusermultiold == nullptr) { memory->create(cutusermultiold,ntypes+1,"comm:cutusermultiold"); for (i=0; i < ntypes+1; ++i) @@ -381,7 +381,7 @@ void Comm::modify_params(int narg, char **arg) cut = utils::numeric(FLERR,arg[iarg+2],false,lmp); cutghostuser = MAX(cutghostuser,cut); if (cut < 0.0) - error->all(FLERR,"Invalid cutoff in comm_modify command"); + error->all(FLERR,"Invalid cutoff {} in comm_modify command", arg[iarg+2]); for (i=nlo; i<=nhi; ++i) cutusermultiold[i] = cut; iarg += 3; @@ -391,10 +391,10 @@ void Comm::modify_params(int narg, char **arg) multi_reduce = 1; iarg += 1; } else if (strcmp(arg[iarg],"vel") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal comm_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "comm_modify vel", error); ghost_velocity = utils::logical(FLERR,arg[iarg+1],false,lmp); iarg += 2; - } else error->all(FLERR,"Illegal comm_modify command"); + } else error->all(FLERR,"Unknown comm_modify keyword: {}", arg[iarg]); } } diff --git a/src/create_box.cpp b/src/create_box.cpp index cd6a63ca44..b05bfe0825 100644 --- a/src/create_box.cpp +++ b/src/create_box.cpp @@ -35,7 +35,7 @@ CreateBox::CreateBox(LAMMPS *lmp) : Command(lmp) {} void CreateBox::command(int narg, char **arg) { - if (narg < 2) error->all(FLERR, "Illegal create_box command"); + if (narg < 2) utils::missing_cmd_args(FLERR, "create_box", error); if (domain->box_exist) error->all(FLERR, "Cannot create_box after simulation box is defined"); if (domain->dimension == 2 && domain->zperiodic == 0) @@ -107,56 +107,56 @@ void CreateBox::command(int narg, char **arg) int iarg = 2; while (iarg < narg) { if (strcmp(arg[iarg], "bond/types") == 0) { - if (iarg + 2 > narg) error->all(FLERR, "Illegal create_box command"); + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "create_box bond/type", error); if (!atom->avec->bonds_allow) error->all(FLERR, "No bonds allowed with this atom style"); atom->nbondtypes = utils::inumeric(FLERR, arg[iarg + 1], false, lmp); iarg += 2; } else if (strcmp(arg[iarg], "angle/types") == 0) { - if (iarg + 2 > narg) error->all(FLERR, "Illegal create_box command"); + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "create_box angle/types", error); if (!atom->avec->angles_allow) error->all(FLERR, "No angles allowed with this atom style"); atom->nangletypes = utils::inumeric(FLERR, arg[iarg + 1], false, lmp); iarg += 2; } else if (strcmp(arg[iarg], "dihedral/types") == 0) { - if (iarg + 2 > narg) error->all(FLERR, "Illegal create_box command"); + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "create_box dihedral/types", error); if (!atom->avec->dihedrals_allow) error->all(FLERR, "No dihedrals allowed with this atom style"); atom->ndihedraltypes = utils::inumeric(FLERR, arg[iarg + 1], false, lmp); iarg += 2; } else if (strcmp(arg[iarg], "improper/types") == 0) { - if (iarg + 2 > narg) error->all(FLERR, "Illegal create_box command"); + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "create_box improper/types", error); if (!atom->avec->impropers_allow) error->all(FLERR, "No impropers allowed with this atom style"); atom->nimpropertypes = utils::inumeric(FLERR, arg[iarg + 1], false, lmp); iarg += 2; } else if (strcmp(arg[iarg], "extra/bond/per/atom") == 0) { - if (iarg + 2 > narg) error->all(FLERR, "Illegal create_box command"); + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "create_box extra/bond/per/atom", error); if (!atom->avec->bonds_allow) error->all(FLERR, "No bonds allowed with this atom style"); atom->bond_per_atom = utils::inumeric(FLERR, arg[iarg + 1], false, lmp); iarg += 2; } else if (strcmp(arg[iarg], "extra/angle/per/atom") == 0) { - if (iarg + 2 > narg) error->all(FLERR, "Illegal create_box command"); + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "create_box extra/angle/per/atom", error); if (!atom->avec->angles_allow) error->all(FLERR, "No angles allowed with this atom style"); atom->angle_per_atom = utils::inumeric(FLERR, arg[iarg + 1], false, lmp); iarg += 2; } else if (strcmp(arg[iarg], "extra/dihedral/per/atom") == 0) { - if (iarg + 2 > narg) error->all(FLERR, "Illegal create_box command"); + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "create_box extra/dihedral/per/atom", error); if (!atom->avec->dihedrals_allow) error->all(FLERR, "No dihedrals allowed with this atom style"); atom->dihedral_per_atom = utils::inumeric(FLERR, arg[iarg + 1], false, lmp); iarg += 2; } else if (strcmp(arg[iarg], "extra/improper/per/atom") == 0) { - if (iarg + 2 > narg) error->all(FLERR, "Illegal create_box command"); + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "create_box extra/improper/per/atom", error); if (!atom->avec->impropers_allow) error->all(FLERR, "No impropers allowed with this atom style"); atom->improper_per_atom = utils::inumeric(FLERR, arg[iarg + 1], false, lmp); iarg += 2; } else if (strcmp(arg[iarg], "extra/special/per/atom") == 0) { - if (iarg + 2 > narg) error->all(FLERR, "Illegal create_box command"); + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "create_box extra/special/per/atom", error); force->special_extra = utils::inumeric(FLERR, arg[iarg + 1], false, lmp); atom->maxspecial += force->special_extra; iarg += 2; } else - error->all(FLERR, "Illegal create_box command"); + error->all(FLERR, "Unknown create_box keyword: {}", arg[iarg]); } // problem setup using info from header diff --git a/src/domain.cpp b/src/domain.cpp index 86dbf260ee..48631a0899 100644 --- a/src/domain.cpp +++ b/src/domain.cpp @@ -1744,7 +1744,7 @@ void Domain::set_lattice(int narg, char **arg) void Domain::add_region(int narg, char **arg) { - if (narg < 2) error->all(FLERR,"Illegal region command"); + if (narg < 2) utils::missing_cmd_args(FLERR, "region", error); if (strcmp(arg[1],"delete") == 0) { delete_region(arg[0]); @@ -1856,7 +1856,7 @@ const std::vector Domain::get_region_list() void Domain::set_boundary(int narg, char **arg, int flag) { - if (narg != 3) error->all(FLERR,"Illegal boundary command"); + if (narg != 3) error->all(FLERR,"Illegal boundary command: expected 3 arguments but found {}", narg); char c; for (int idim = 0; idim < 3; idim++) @@ -1870,8 +1870,8 @@ void Domain::set_boundary(int narg, char **arg, int flag) else if (c == 's') boundary[idim][iside] = 2; else if (c == 'm') boundary[idim][iside] = 3; else { - if (flag == 0) error->all(FLERR,"Illegal boundary command"); - if (flag == 1) error->all(FLERR,"Illegal change_box command"); + if (flag == 0) error->all(FLERR,"Unknown boundary keyword: {}", c); + if (flag == 1) error->all(FLERR,"Unknown change_box keyword: {}", c); } } @@ -1935,17 +1935,17 @@ void Domain::set_boundary(int narg, char **arg, int flag) void Domain::set_box(int narg, char **arg) { - if (narg < 1) error->all(FLERR,"Illegal box command"); + if (narg < 1) utils::missing_cmd_args(FLERR, "box", error); int iarg = 0; while (iarg < narg) { if (strcmp(arg[iarg],"tilt") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal box command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "box tilt", error); if (strcmp(arg[iarg+1],"small") == 0) tiltsmall = 1; else if (strcmp(arg[iarg+1],"large") == 0) tiltsmall = 0; - else error->all(FLERR,"Illegal box command"); + else error->all(FLERR,"Unknown box tilt argument: {}", arg[iarg+1]); iarg += 2; - } else error->all(FLERR,"Illegal box command"); + } else error->all(FLERR,"Unknown box keyword: {}", arg[iarg]); } } diff --git a/src/input.cpp b/src/input.cpp index 2979503d30..ef125d3145 100644 --- a/src/input.cpp +++ b/src/input.cpp @@ -860,7 +860,7 @@ int Input::execute_command() void Input::clear() { - if (narg > 0) error->all(FLERR,"Illegal clear command"); + if (narg > 0) error->all(FLERR,"Illegal clear command: unexpected arguments but found {}", narg); lmp->destroy(); lmp->create(); lmp->post_create(); @@ -870,7 +870,7 @@ void Input::clear() void Input::echo() { - if (narg != 1) error->all(FLERR,"Illegal echo command"); + if (narg != 1) error->all(FLERR,"Illegal echo command: expected 1 argument but found {}", narg); if (strcmp(arg[0],"none") == 0) { echo_screen = 0; @@ -884,14 +884,14 @@ void Input::echo() } else if (strcmp(arg[0],"both") == 0) { echo_screen = 1; echo_log = 1; - } else error->all(FLERR,"Illegal echo command"); + } else error->all(FLERR,"Unknown echo keyword: {}", arg[0]); } /* ---------------------------------------------------------------------- */ void Input::ifthenelse() { - if (narg < 3) error->all(FLERR,"Illegal if command"); + if (narg < 3) utils::missing_cmd_args(FLERR, "if", error); // substitute for variables in Boolean expression for "if" // in case expression was enclosed in quotes @@ -908,7 +908,7 @@ void Input::ifthenelse() // bound "then" commands - if (strcmp(arg[1],"then") != 0) error->all(FLERR,"Illegal if command"); + if (strcmp(arg[1],"then") != 0) error->all(FLERR,"Illegal if command: expected \"then\" but found \"{}\"", arg[1]); int first = 2; int iarg = first; @@ -923,13 +923,13 @@ void Input::ifthenelse() if (btest != 0.0) { int ncommands = last-first + 1; - if (ncommands <= 0) error->all(FLERR,"Illegal if command"); + if (ncommands <= 0) utils::missing_cmd_args(FLERR, "if then", error); auto commands = new char*[ncommands]; ncommands = 0; for (int i = first; i <= last; i++) { n = strlen(arg[i]) + 1; - if (n == 1) error->all(FLERR,"Illegal if command"); + if (n == 1) error->all(FLERR,"Illegal if then command: execute command is empty"); commands[ncommands] = new char[n]; strcpy(commands[ncommands],arg[i]); ncommands++; @@ -954,7 +954,7 @@ void Input::ifthenelse() // bound and execute "elif" or "else" commands while (iarg != narg) { - if (iarg+2 > narg) error->all(FLERR,"Illegal if command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "if then", error); if (strcmp(arg[iarg],"elif") == 0) { n = strlen(arg[iarg+1]) + 1; if (n > maxline) reallocate(line,maxline,n); @@ -976,13 +976,13 @@ void Input::ifthenelse() if (btest == 0.0) continue; int ncommands = last-first + 1; - if (ncommands <= 0) error->all(FLERR,"Illegal if command"); + if (ncommands <= 0) utils::missing_cmd_args(FLERR, "if elif/else", error); auto commands = new char*[ncommands]; ncommands = 0; for (int i = first; i <= last; i++) { n = strlen(arg[i]) + 1; - if (n == 1) error->all(FLERR,"Illegal if command"); + if (n == 1) error->all(FLERR,"Illegal if elif/else command: execute command is empty"); commands[ncommands] = new char[n]; strcpy(commands[ncommands],arg[i]); ncommands++; @@ -1038,7 +1038,7 @@ void Input::include() void Input::jump() { - if (narg < 1 || narg > 2) error->all(FLERR,"Illegal jump command"); + if (narg < 1 || narg > 2) error->all(FLERR,"Illegal jump command: expected 1 or 2 argument(s) but found {}", narg); if (jump_skip) { jump_skip = 0; @@ -1069,7 +1069,7 @@ void Input::jump() void Input::label() { - if (narg != 1) error->all(FLERR,"Illegal label command"); + if (narg != 1) error->all(FLERR,"Illegal label command: expected 1 argument but found {}", narg); if (label_active && strcmp(labelstr,arg[0]) == 0) label_active = 0; } @@ -1077,12 +1077,12 @@ void Input::label() void Input::log() { - if ((narg < 1) || (narg > 2)) error->all(FLERR,"Illegal log command"); + if ((narg < 1) || (narg > 2)) error->all(FLERR,"Illegal log command: expected 1 or 2 argument(s) but found {}", narg); int appendflag = 0; if (narg == 2) { if (strcmp(arg[1],"append") == 0) appendflag = 1; - else error->all(FLERR,"Illegal log command"); + else error->all(FLERR,"Unknown log keyword: {}", arg[1]); } if (me == 0) { @@ -1112,7 +1112,7 @@ void Input::next_command() void Input::partition() { - if (narg < 3) error->all(FLERR,"Illegal partition command"); + if (narg < 3) utils::missing_cmd_args(FLERR, "partition", error); int ilo,ihi; int yesflag = utils::logical(FLERR,arg[0],false,lmp); @@ -1138,7 +1138,7 @@ void Input::partition() void Input::print() { - if (narg < 1) error->all(FLERR,"Illegal print command"); + if (narg < 1) utils::missing_cmd_args(FLERR, "print", error); // copy 1st arg back into line (copy is being used) // check maxline since arg[0] could have been expanded by variables @@ -1158,7 +1158,7 @@ void Input::print() int iarg = 1; while (iarg < narg) { if (strcmp(arg[iarg],"file") == 0 || strcmp(arg[iarg],"append") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal print command"); + if (iarg+2 > narg) error->all(FLERR,"Illegal print {} command: missing argument(s)", arg[iarg]); if (me == 0) { if (fp != nullptr) fclose(fp); if (strcmp(arg[iarg],"file") == 0) fp = fopen(arg[iarg+1],"w"); @@ -1168,14 +1168,14 @@ void Input::print() } iarg += 2; } else if (strcmp(arg[iarg],"screen") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal print command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "print screen", error); screenflag = utils::logical(FLERR,arg[iarg+1],false,lmp); iarg += 2; } else if (strcmp(arg[iarg],"universe") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal print command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "print universe", error); universeflag = utils::logical(FLERR,arg[iarg+1],false,lmp); iarg += 2; - } else error->all(FLERR,"Illegal print command"); + } else error->all(FLERR,"Unknown print keyword: {}", arg[iarg]); } if (me == 0) { @@ -1205,7 +1205,7 @@ void Input::quit() { if (narg == 0) error->done(0); // 1 would be fully backwards compatible if (narg == 1) error->done(utils::inumeric(FLERR,arg[0],false,lmp)); - error->all(FLERR,"Illegal quit command"); + error->all(FLERR,"Illegal quit command: expected 0 or 1 argument but found {}", narg); } /* ---------------------------------------------------------------------- */ @@ -1214,10 +1214,10 @@ void Input::shell() { int rv,err; - if (narg < 1) error->all(FLERR,"Illegal shell command"); + if (narg < 1) utils::missing_cmd_args(FLERR, "shell", error); if (strcmp(arg[0],"cd") == 0) { - if (narg != 2) error->all(FLERR,"Illegal shell cd command"); + if (narg != 2) error->all(FLERR,"Illegal shell command: expected 2 argument but found {}", narg); rv = (platform::chdir(arg[1]) < 0) ? errno : 0; MPI_Reduce(&rv,&err,1,MPI_INT,MPI_MAX,0,world); errno = err; @@ -1225,7 +1225,7 @@ void Input::shell() error->warning(FLERR, "Shell command 'cd {}' failed with error '{}'", arg[1], utils::getsyserror()); } } else if (strcmp(arg[0],"mkdir") == 0) { - if (narg < 2) error->all(FLERR,"Illegal shell mkdir command"); + if (narg < 2) utils::missing_cmd_args(FLERR, "shell mkdir", error); if (me == 0) { for (int i = 1; i < narg; i++) { rv = (platform::mkdir(arg[i]) < 0) ? errno : 0; @@ -1235,7 +1235,7 @@ void Input::shell() } } } else if (strcmp(arg[0],"mv") == 0) { - if (narg != 3) error->all(FLERR,"Illegal shell mv command"); + if (narg != 3) error->all(FLERR,"Illegal shell command: expected 3 argument but found {}", narg); if (me == 0) { if (platform::path_is_directory(arg[2])) { if (system(fmt::format("mv {} {}", arg[1], arg[2]).c_str())) @@ -1248,7 +1248,7 @@ void Input::shell() } } } else if (strcmp(arg[0],"rm") == 0) { - if (narg < 2) error->all(FLERR,"Illegal shell rm command"); + if (narg < 2) utils::missing_cmd_args(FLERR, "shell rm", error); if (me == 0) { int i = 1; bool warn = true; @@ -1264,7 +1264,7 @@ void Input::shell() } } } else if (strcmp(arg[0],"rmdir") == 0) { - if (narg < 2) error->all(FLERR,"Illegal shell rmdir command"); + if (narg < 2) utils::missing_cmd_args(FLERR, "shell rmdir", error); if (me == 0) { for (int i = 1; i < narg; i++) { if (platform::rmdir(arg[i]) < 0) @@ -1273,7 +1273,7 @@ void Input::shell() } } } else if (strcmp(arg[0],"putenv") == 0) { - if (narg < 2) error->all(FLERR,"Illegal shell putenv command"); + if (narg < 2) utils::missing_cmd_args(FLERR, "shell putenv", error); for (int i = 1; i < narg; i++) { rv = 0; if (arg[i]) rv = platform::putenv(arg[i]); @@ -1351,7 +1351,7 @@ void Input::atom_modify() void Input::atom_style() { - if (narg < 1) error->all(FLERR,"Illegal atom_style command"); + if (narg < 1) utils::missing_cmd_args(FLERR, "atom_style", error); if (domain->box_exist) error->all(FLERR,"Atom_style command after simulation box is defined"); atom->create_avec(arg[0],narg-1,&arg[1],1); @@ -1488,12 +1488,12 @@ void Input::dihedral_style() void Input::dimension() { - if (narg != 1) error->all(FLERR,"Illegal dimension command"); + if (narg != 1) error->all(FLERR,"Illegal dimension command: expected 1 argument but found {}", narg); if (domain->box_exist) error->all(FLERR,"Dimension command after simulation box is defined"); domain->dimension = utils::inumeric(FLERR,arg[0],false,lmp); if (domain->dimension != 2 && domain->dimension != 3) - error->all(FLERR,"Illegal dimension command"); + error->all(FLERR, "Invalid dimension argument: {}", arg[0]); // must reset default extra_dof of all computes // since some were created before dimension command is encountered @@ -1589,7 +1589,7 @@ void Input::lattice() void Input::mass() { - if (narg != 2) error->all(FLERR,"Illegal mass command"); + if (narg != 2) error->all(FLERR,"Illegal mass command: expected 2 arguments but found {}", narg); if (domain->box_exist == 0) error->all(FLERR,"Mass command before simulation box is defined"); atom->set_mass(FLERR,narg,arg); @@ -1731,7 +1731,7 @@ void Input::pair_modify() void Input::pair_style() { - if (narg < 1) error->all(FLERR,"Illegal pair_style command"); + if (narg < 1) utils::missing_cmd_args(FLERR, "pair_style", error); if (force->pair) { std::string style = arg[0]; int match = 0; @@ -1948,7 +1948,7 @@ void Input::unfix() void Input::units() { - if (narg != 1) error->all(FLERR,"Illegal units command"); + if (narg != 1) error->all(FLERR,"Illegal units command: expected 1 argument but found {}", narg); if (domain->box_exist) error->all(FLERR,"Units command after simulation box is defined"); update->set_units(arg[0]); diff --git a/src/lattice.cpp b/src/lattice.cpp index be69fc1821..65864f66d8 100644 --- a/src/lattice.cpp +++ b/src/lattice.cpp @@ -36,7 +36,7 @@ Lattice::Lattice(LAMMPS *lmp, int narg, char **arg) : Pointers(lmp) // parse style arg - if (narg < 1) error->all(FLERR,"Illegal lattice command"); + if (narg < 1) utils::missing_cmd_args(FLERR, "lattice", error); if (strcmp(arg[0],"none") == 0) style = NONE; else if (strcmp(arg[0],"sc") == 0) style = SC; @@ -48,10 +48,10 @@ Lattice::Lattice(LAMMPS *lmp, int narg, char **arg) : Pointers(lmp) else if (strcmp(arg[0],"sq2") == 0) style = SQ2; else if (strcmp(arg[0],"hex") == 0) style = HEX; else if (strcmp(arg[0],"custom") == 0) style = CUSTOM; - else error->all(FLERR,"Illegal lattice command"); + else error->all(FLERR,"Unknown lattice keyword: {}", arg[0]); if (style == NONE) { - if (narg != 2) error->all(FLERR,"Illegal lattice command"); + if (narg != 2) error->all(FLERR,"Illegal lattice command: expected 2 arguments but found {}", narg); // Domain creates a default lattice of style "none" // before Force class is instantiated, just use atof() in that case @@ -61,7 +61,7 @@ Lattice::Lattice(LAMMPS *lmp, int narg, char **arg) : Pointers(lmp) else xlattice = ylattice = zlattice = atof(arg[1]); - if (xlattice <= 0.0) error->all(FLERR,"Illegal lattice command"); + if (xlattice <= 0.0) error->all(FLERR, "Invalid lattice none argument: {}", arg[1]); return; } @@ -81,9 +81,9 @@ Lattice::Lattice(LAMMPS *lmp, int narg, char **arg) : Pointers(lmp) // scale = conversion factor between lattice and box units - if (narg < 2) error->all(FLERR,"Illegal lattice command"); + if (narg < 2) utils::missing_cmd_args(FLERR, "lattice", error); scale = utils::numeric(FLERR,arg[1],false,lmp); - if (scale <= 0.0) error->all(FLERR,"Illegal lattice command"); + if (scale <= 0.0) error->all(FLERR, "Invalid lattice {} argument: {}", arg[0], arg[1]); // set basis atoms for each style // x,y,z = fractional coords within unit cell @@ -148,23 +148,25 @@ Lattice::Lattice(LAMMPS *lmp, int narg, char **arg) : Pointers(lmp) int iarg = 2; while (iarg < narg) { if (strcmp(arg[iarg],"origin") == 0) { - if (iarg+4 > narg) error->all(FLERR,"Illegal lattice command"); + if (iarg+4 > narg) utils::missing_cmd_args(FLERR, "lattice origin", error); origin[0] = utils::numeric(FLERR,arg[iarg+1],false,lmp); origin[1] = utils::numeric(FLERR,arg[iarg+2],false,lmp); origin[2] = utils::numeric(FLERR,arg[iarg+3],false,lmp); - if (origin[0] < 0.0 || origin[0] >= 1.0 || - origin[1] < 0.0 || origin[1] >= 1.0 || - origin[2] < 0.0 || origin[2] >= 1.0) - error->all(FLERR,"Illegal lattice command"); + if (origin[0] < 0.0 || origin[0] >= 1.0) + error->all(FLERR, "Invalid lattice origin argument: {}", origin[0]); + if (origin[1] < 0.0 || origin[1] >= 1.0) + error->all(FLERR, "Invalid lattice origin argument: {}", origin[1]); + if (origin[2] < 0.0 || origin[2] >= 1.0) + error->all(FLERR, "Invalid lattice origin argument: {}", origin[2]); iarg += 4; } else if (strcmp(arg[iarg],"orient") == 0) { - if (iarg+5 > narg) error->all(FLERR,"Illegal lattice command"); + if (iarg+5 > narg) utils::missing_cmd_args(FLERR, "lattice orient", error); int dim = -1; if (strcmp(arg[iarg+1],"x") == 0) dim = 0; else if (strcmp(arg[iarg+1],"y") == 0) dim = 1; else if (strcmp(arg[iarg+1],"z") == 0) dim = 2; - else error->all(FLERR,"Illegal lattice command"); + else error->all(FLERR,"Unknown lattice orient argument: {}", arg[iarg+1]); int *orient = nullptr; if (dim == 0) orient = orientx; else if (dim == 1) orient = orienty; @@ -175,7 +177,7 @@ Lattice::Lattice(LAMMPS *lmp, int narg, char **arg) : Pointers(lmp) iarg += 5; } else if (strcmp(arg[iarg],"spacing") == 0) { - if (iarg+4 > narg) error->all(FLERR,"Illegal lattice command"); + if (iarg+4 > narg) utils::missing_cmd_args(FLERR, "lattice spacing", error); spaceflag = 1; xlattice = utils::numeric(FLERR,arg[iarg+1],false,lmp); ylattice = utils::numeric(FLERR,arg[iarg+2],false,lmp); @@ -183,46 +185,50 @@ Lattice::Lattice(LAMMPS *lmp, int narg, char **arg) : Pointers(lmp) iarg += 4; } else if (strcmp(arg[iarg],"a1") == 0) { - if (iarg+4 > narg) error->all(FLERR,"Illegal lattice command"); + if (iarg+4 > narg) utils::missing_cmd_args(FLERR, "lattice a1", error); if (style != CUSTOM) error->all(FLERR, - "Invalid option in lattice command for non-custom style"); + "Invalid a1 option in lattice command for non-custom style"); a1[0] = utils::numeric(FLERR,arg[iarg+1],false,lmp); a1[1] = utils::numeric(FLERR,arg[iarg+2],false,lmp); a1[2] = utils::numeric(FLERR,arg[iarg+3],false,lmp); iarg += 4; } else if (strcmp(arg[iarg],"a2") == 0) { - if (iarg+4 > narg) error->all(FLERR,"Illegal lattice command"); + if (iarg+4 > narg) utils::missing_cmd_args(FLERR, "lattice a2", error); if (style != CUSTOM) error->all(FLERR, - "Invalid option in lattice command for non-custom style"); + "Invalid a2 option in lattice command for non-custom style"); a2[0] = utils::numeric(FLERR,arg[iarg+1],false,lmp); a2[1] = utils::numeric(FLERR,arg[iarg+2],false,lmp); a2[2] = utils::numeric(FLERR,arg[iarg+3],false,lmp); iarg += 4; } else if (strcmp(arg[iarg],"a3") == 0) { - if (iarg+4 > narg) error->all(FLERR,"Illegal lattice command"); + if (iarg+4 > narg) utils::missing_cmd_args(FLERR, "lattice a3", error); if (style != CUSTOM) error->all(FLERR, - "Invalid option in lattice command for non-custom style"); + "Invalid a3 option in lattice command for non-custom style"); a3[0] = utils::numeric(FLERR,arg[iarg+1],false,lmp); a3[1] = utils::numeric(FLERR,arg[iarg+2],false,lmp); a3[2] = utils::numeric(FLERR,arg[iarg+3],false,lmp); iarg += 4; } else if (strcmp(arg[iarg],"basis") == 0) { - if (iarg+4 > narg) error->all(FLERR,"Illegal lattice command"); + if (iarg+4 > narg) utils::missing_cmd_args(FLERR, "lattice basis", error); if (style != CUSTOM) error->all(FLERR, - "Invalid option in lattice command for non-custom style"); + "Invalid basis option in lattice command for non-custom style"); double x = utils::numeric(FLERR,arg[iarg+1],false,lmp); double y = utils::numeric(FLERR,arg[iarg+2],false,lmp); double z = utils::numeric(FLERR,arg[iarg+3],false,lmp); - if (x < 0.0 || x >= 1.0 || y < 0.0 || y >= 1.0 || z < 0.0 || z >= 1.0) - error->all(FLERR,"Illegal lattice command"); + if (x < 0.0 || x >= 1.0) + error->all(FLERR, "Invalid lattice basis argument: {}", x); + if (y < 0.0 || y >= 1.0) + error->all(FLERR, "Invalid lattice basis argument: {}", y); + if (z < 0.0 || z >= 1.0) + error->all(FLERR, "Invalid lattice basis argument: {}", z); add_basis(x,y,z); iarg += 4; - } else error->all(FLERR,"Illegal lattice command"); + } else error->all(FLERR,"Unknown lattice keyword: {}", arg[iarg]); } // check settings for errors diff --git a/src/neighbor.cpp b/src/neighbor.cpp index ac0c7921d8..e5e378ff6b 100644 --- a/src/neighbor.cpp +++ b/src/neighbor.cpp @@ -2527,10 +2527,10 @@ void Neighbor::build_one(class NeighList *mylist, int preflag) void Neighbor::set(int narg, char **arg) { - if (narg != 2) error->all(FLERR,"Illegal neighbor command"); + if (narg != 2) error->all(FLERR,"Illegal neighbor command: expected 2 arguments but found {}", narg); skin = utils::numeric(FLERR,arg[0],false,lmp); - if (skin < 0.0) error->all(FLERR,"Illegal neighbor command"); + if (skin < 0.0) error->all(FLERR, "Invalid neighbor argument: {}", arg[0]); if (strcmp(arg[1],"nsq") == 0) style = Neighbor::NSQ; else if (strcmp(arg[1],"bin") == 0) style = Neighbor::BIN; @@ -2538,7 +2538,7 @@ void Neighbor::set(int narg, char **arg) style = Neighbor::MULTI; ncollections = atom->ntypes; } else if (strcmp(arg[1],"multi/old") == 0) style = Neighbor::MULTI_OLD; - else error->all(FLERR,"Illegal neighbor command"); + else error->all(FLERR,"Unknown neighbor {} argument: {}", arg[0], arg[1]); if (style == Neighbor::MULTI_OLD && lmp->citeme) lmp->citeme->add(cite_neigh_multi_old); if (style == Neighbor::MULTI && lmp->citeme) lmp->citeme->add(cite_neigh_multi); diff --git a/src/pair.cpp b/src/pair.cpp index 4d42035fd1..81f231bb31 100644 --- a/src/pair.cpp +++ b/src/pair.cpp @@ -159,57 +159,57 @@ Pair::~Pair() void Pair::modify_params(int narg, char **arg) { - if (narg == 0) error->all(FLERR,"Illegal pair_modify command"); + if (narg == 0) utils::missing_cmd_args(FLERR, "pair_modify", error); int iarg = 0; while (iarg < narg) { if (strcmp(arg[iarg],"mix") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal pair_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "pair_modify mix", error); if (strcmp(arg[iarg+1],"geometric") == 0) mix_flag = GEOMETRIC; else if (strcmp(arg[iarg+1],"arithmetic") == 0) mix_flag = ARITHMETIC; else if (strcmp(arg[iarg+1],"sixthpower") == 0) mix_flag = SIXTHPOWER; - else error->all(FLERR,"Illegal pair_modify command"); + else error->all(FLERR,"Unknown pair_modify mix argument: {}", arg[iarg+1]); iarg += 2; } else if (strcmp(arg[iarg],"shift") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal pair_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "pair_modify shift", error); offset_flag = utils::logical(FLERR,arg[iarg+1],false,lmp); iarg += 2; } else if (strcmp(arg[iarg],"table") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal pair_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "pair_modify table", error); ncoultablebits = utils::inumeric(FLERR,arg[iarg+1],false,lmp); if (ncoultablebits > (int)sizeof(float)*CHAR_BIT) error->all(FLERR,"Too many total bits for bitmapped lookup table"); iarg += 2; } else if (strcmp(arg[iarg],"table/disp") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal pair_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "pair_modify table/disp", error); ndisptablebits = utils::inumeric(FLERR,arg[iarg+1],false,lmp); if (ndisptablebits > (int)sizeof(float)*CHAR_BIT) error->all(FLERR,"Too many total bits for bitmapped lookup table"); iarg += 2; } else if (strcmp(arg[iarg],"tabinner") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal pair_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "pair_modify tabinner", error); tabinner = utils::numeric(FLERR,arg[iarg+1],false,lmp); iarg += 2; } else if (strcmp(arg[iarg],"tabinner/disp") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal pair_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "pair_modify tabinner/disp", error); tabinner_disp = utils::numeric(FLERR,arg[iarg+1],false,lmp); iarg += 2; } else if (strcmp(arg[iarg],"tail") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal pair_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "pair_modify tail", error); tail_flag = utils::logical(FLERR,arg[iarg+1],false,lmp); iarg += 2; } else if (strcmp(arg[iarg],"compute") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal pair_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "pair_modify compute", error); compute_flag = utils::logical(FLERR,arg[iarg+1],false,lmp); iarg += 2; } else if (strcmp(arg[iarg],"nofdotr") == 0) { no_virial_fdotr_compute = 1; ++iarg; } else if (strcmp(arg[iarg],"neigh/trim") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal pair_modify command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "pair_modify neigh/trim", error); trim_flag = utils::logical(FLERR,arg[iarg+1],false,lmp); iarg += 2; - } else error->all(FLERR,"Illegal pair_modify command"); + } else error->all(FLERR,"Unknown pair_modify keyword: {}", arg[iarg]); } } diff --git a/src/region.cpp b/src/region.cpp index 307513add6..d63fe25017 100644 --- a/src/region.cpp +++ b/src/region.cpp @@ -66,27 +66,27 @@ void Region::init() { if (xstr) { xvar = input->variable->find(xstr); - if (xvar < 0) error->all(FLERR, "Variable name for region does not exist"); + if (xvar < 0) error->all(FLERR, "Variable {} for region does not exist", xstr); if (!input->variable->equalstyle(xvar)) - error->all(FLERR, "Variable for region is invalid style"); + error->all(FLERR, "Variable {} for region is invalid style", xstr); } if (ystr) { yvar = input->variable->find(ystr); - if (yvar < 0) error->all(FLERR, "Variable name for region does not exist"); + if (yvar < 0) error->all(FLERR, "Variable {} for region does not exist", ystr); if (!input->variable->equalstyle(yvar)) - error->all(FLERR, "Variable for region is not equal style"); + error->all(FLERR, "Variable {} for region is not equal style", ystr); } if (zstr) { zvar = input->variable->find(zstr); - if (zvar < 0) error->all(FLERR, "Variable name for region does not exist"); + if (zvar < 0) error->all(FLERR, "Variable {} for region does not exist", zstr); if (!input->variable->equalstyle(zvar)) - error->all(FLERR, "Variable for region is not equal style"); + error->all(FLERR, "Variable {} for region is not equal style", zstr); } if (tstr) { tvar = input->variable->find(tstr); - if (tvar < 0) error->all(FLERR, "Variable name for region does not exist"); + if (tvar < 0) error->all(FLERR, "Variable {} for region does not exist", tstr); if (!input->variable->equalstyle(tvar)) - error->all(FLERR, "Variable for region is not equal style"); + error->all(FLERR, "Variable {} for region is not equal style", tstr); } vel_timestep = -1; } diff --git a/src/run.cpp b/src/run.cpp index a026580c83..3a9a4dc32e 100644 --- a/src/run.cpp +++ b/src/run.cpp @@ -36,7 +36,7 @@ Run::Run(LAMMPS *lmp) : Command(lmp) {} void Run::command(int narg, char **arg) { - if (narg < 1) error->all(FLERR,"Illegal run command"); + if (narg < 1) utils::missing_cmd_args(FLERR, "run", error); if (domain->box_exist == 0) error->all(FLERR,"Run command before simulation box is defined"); @@ -62,25 +62,25 @@ void Run::command(int narg, char **arg) int iarg = 1; while (iarg < narg) { if (strcmp(arg[iarg],"upto") == 0) { - if (iarg+1 > narg) error->all(FLERR,"Illegal run command"); + if (iarg+1 > narg) utils::missing_cmd_args(FLERR, "run upto", error); uptoflag = 1; iarg += 1; } else if (strcmp(arg[iarg],"start") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal run command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "run start", error); startflag = 1; start = utils::bnumeric(FLERR,arg[iarg+1],false,lmp); iarg += 2; } else if (strcmp(arg[iarg],"stop") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal run command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "run stop", error); stopflag = 1; stop = utils::bnumeric(FLERR,arg[iarg+1],false,lmp); iarg += 2; } else if (strcmp(arg[iarg],"pre") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal run command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "run pre", error); preflag = utils::logical(FLERR,arg[iarg+1],false,lmp); iarg += 2; } else if (strcmp(arg[iarg],"post") == 0) { - if (iarg+2 > narg) error->all(FLERR,"Illegal run command"); + if (iarg+2 > narg) utils::missing_cmd_args(FLERR, "run post", error); postflag = utils::logical(FLERR,arg[iarg+1],false,lmp); iarg += 2; @@ -89,15 +89,15 @@ void Run::command(int narg, char **arg) // set ncommands = 0 if single command and it is "NULL" } else if (strcmp(arg[iarg],"every") == 0) { - if (iarg+3 > narg) error->all(FLERR,"Illegal run command"); + if (iarg+3 > narg) utils::missing_cmd_args(FLERR, "run every", error); nevery = utils::inumeric(FLERR,arg[iarg+1],false,lmp); - if (nevery <= 0) error->all(FLERR,"Illegal run command"); + if (nevery <= 0) error->all(FLERR, "Invalid run every argument: {}", nevery); first = iarg+2; last = narg-1; ncommands = last-first + 1; if (ncommands == 1 && strcmp(arg[first],"NULL") == 0) ncommands = 0; iarg = narg; - } else error->all(FLERR,"Illegal run command"); + } else error->all(FLERR,"Unknown run keyword: {}", arg[iarg]); } // set nsteps as integer, using upto value if specified @@ -105,12 +105,12 @@ void Run::command(int narg, char **arg) int nsteps; if (!uptoflag) { if (nsteps_input < 0 || nsteps_input > MAXSMALLINT) - error->all(FLERR,"Invalid run command N value"); + error->all(FLERR,"Invalid run command N value: {}", nsteps_input); nsteps = static_cast (nsteps_input); } else { bigint delta = nsteps_input - update->ntimestep; if (delta < 0 || delta > MAXSMALLINT) - error->all(FLERR,"Invalid run command upto value"); + error->all(FLERR,"Invalid run command upto value: {}", delta); nsteps = static_cast (delta); } @@ -118,13 +118,13 @@ void Run::command(int narg, char **arg) if (startflag) { if (start < 0) - error->all(FLERR,"Invalid run command start/stop value"); + error->all(FLERR,"Invalid run command start value: {}", start); if (start > update->ntimestep) error->all(FLERR,"Run command start value is after start of run"); } if (stopflag) { if (stop < 0) - error->all(FLERR,"Invalid run command start/stop value"); + error->all(FLERR,"Invalid run command stop value: {}", stop); if (stop < update->ntimestep + nsteps) error->all(FLERR,"Run command stop value is before end of run"); } diff --git a/src/variable.cpp b/src/variable.cpp index 979b0e4c64..da90e8a66f 100644 --- a/src/variable.cpp +++ b/src/variable.cpp @@ -162,7 +162,7 @@ Variable::~Variable() void Variable::set(int narg, char **arg) { - if (narg < 2) error->all(FLERR,"Illegal variable command"); + if (narg < 2) utils::missing_cmd_args(FLERR, "variable", error); int replaceflag = 0; @@ -170,7 +170,8 @@ void Variable::set(int narg, char **arg) // doesn't matter if variable no longer exists if (strcmp(arg[1],"delete") == 0) { - if (narg != 2) error->all(FLERR,"Illegal variable command"); + if (narg != 2) + error->all(FLERR,"Illegal variable delete command: expected 2 arguments but found {}", narg); if (find(arg[0]) >= 0) remove(find(arg[0])); return; @@ -178,7 +179,7 @@ void Variable::set(int narg, char **arg) // num = listed args, which = 1st value, data = copied args } else if (strcmp(arg[1],"index") == 0) { - if (narg < 3) error->all(FLERR,"Illegal variable command"); + if (narg < 3) utils::missing_cmd_args(FLERR, "variable index", error); if (find(arg[0]) >= 0) return; if (nvar == maxvar) grow(); style[nvar] = INDEX; @@ -193,6 +194,7 @@ void Variable::set(int narg, char **arg) // 2 args + pad: num = N2, which = N1, data = single string } else if (strcmp(arg[1],"loop") == 0) { + if (narg < 3) utils::missing_cmd_args(FLERR, "variable loop", error); if (find(arg[0]) >= 0) return; if (nvar == maxvar) grow(); style[nvar] = LOOP; @@ -200,7 +202,7 @@ void Variable::set(int narg, char **arg) if (narg == 3 || (narg == 4 && strcmp(arg[3],"pad") == 0)) { nfirst = 1; nlast = utils::inumeric(FLERR,arg[2],false,lmp); - if (nlast <= 0) error->all(FLERR,"Illegal variable command"); + if (nlast <= 0) error->all(FLERR, "Invalid variable loop argument: {}", nlast); if (narg == 4 && strcmp(arg[3],"pad") == 0) { pad[nvar] = fmt::format("{}",nlast).size(); } else pad[nvar] = 0; @@ -208,11 +210,11 @@ void Variable::set(int narg, char **arg) nfirst = utils::inumeric(FLERR,arg[2],false,lmp); nlast = utils::inumeric(FLERR,arg[3],false,lmp); if (nfirst > nlast || nlast < 0) - error->all(FLERR,"Illegal variable command"); + error->all(FLERR,"Illegal variable loop command: {} > {}", nfirst,nlast); if (narg == 5 && strcmp(arg[4],"pad") == 0) { pad[nvar] = fmt::format("{}",nlast).size(); } else pad[nvar] = 0; - } else error->all(FLERR,"Illegal variable command"); + } else error->all(FLERR,"Illegal variable loop command: too much arguments"); num[nvar] = nlast; which[nvar] = nfirst-1; data[nvar] = new char*[1]; @@ -223,7 +225,7 @@ void Variable::set(int narg, char **arg) // error check that num = # of worlds in universe } else if (strcmp(arg[1],"world") == 0) { - if (narg < 3) error->all(FLERR,"Illegal variable command"); + if (narg < 3) utils::missing_cmd_args(FLERR, "variable world", error); if (find(arg[0]) >= 0) return; if (nvar == maxvar) grow(); style[nvar] = WORLD; @@ -244,7 +246,7 @@ void Variable::set(int narg, char **arg) } else if (strcmp(arg[1],"universe") == 0 || strcmp(arg[1],"uloop") == 0) { if (strcmp(arg[1],"universe") == 0) { - if (narg < 3) error->all(FLERR,"Illegal variable command"); + if (narg < 3) utils::missing_cmd_args(FLERR, "variable universe", error); if (find(arg[0]) >= 0) return; if (nvar == maxvar) grow(); style[nvar] = UNIVERSE; @@ -253,8 +255,10 @@ void Variable::set(int narg, char **arg) data[nvar] = new char*[num[nvar]]; copy(num[nvar],&arg[2],data[nvar]); } else if (strcmp(arg[1],"uloop") == 0) { - if (narg < 3 || narg > 4 || (narg == 4 && strcmp(arg[3],"pad") != 0)) - error->all(FLERR,"Illegal variable command"); + if (narg < 3 || narg > 4) + error->all(FLERR,"Illegal variable command: expected 3 or 4 arguments but found {}", narg); + if (narg == 4 && strcmp(arg[3],"pad") != 0) + error->all(FLERR, "Invalid variable uloop argument: {}", arg[3]); if (find(arg[0]) >= 0) return; if (nvar == maxvar) grow(); style[nvar] = ULOOP; @@ -292,7 +296,7 @@ void Variable::set(int narg, char **arg) // data = 1 value, string to eval } else if (strcmp(arg[1],"string") == 0) { - if (narg != 3) error->all(FLERR,"Illegal variable command"); + if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg); int maxcopy = strlen(arg[2]) + 1; int maxwork = maxcopy; @@ -326,7 +330,7 @@ void Variable::set(int narg, char **arg) // data = 1 value, string to eval } else if (strcmp(arg[1],"getenv") == 0) { - if (narg != 3) error->all(FLERR,"Illegal variable command"); + if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg); if (find(arg[0]) >= 0) { if (style[find(arg[0])] != GETENV) error->all(FLERR,"Cannot redefine variable as a different style"); @@ -346,7 +350,7 @@ void Variable::set(int narg, char **arg) // data = 1 value, string to eval } else if (strcmp(arg[1],"file") == 0) { - if (narg != 3) error->all(FLERR,"Illegal variable command"); + if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg); if (find(arg[0]) >= 0) return; if (nvar == maxvar) grow(); style[nvar] = SCALARFILE; @@ -364,7 +368,7 @@ void Variable::set(int narg, char **arg) // data = nullptr } else if (strcmp(arg[1],"atomfile") == 0) { - if (narg != 3) error->all(FLERR,"Illegal variable command"); + if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg); if (find(arg[0]) >= 0) return; if (nvar == maxvar) grow(); style[nvar] = ATOMFILE; @@ -384,7 +388,7 @@ void Variable::set(int narg, char **arg) // 3rd is filled on retrieval } else if (strcmp(arg[1],"format") == 0) { - if (narg != 4) error->all(FLERR,"Illegal variable command"); + if (narg != 4) error->all(FLERR,"Illegal variable command: expected 4 arguments but found {}", narg); if (find(arg[0]) >= 0) return; if (nvar == maxvar) grow(); style[nvar] = FORMAT; @@ -404,7 +408,7 @@ void Variable::set(int narg, char **arg) // data = 2 values, 1st is string to eval, 2nd is filled on retrieval } else if (strcmp(arg[1],"equal") == 0) { - if (narg != 3) error->all(FLERR,"Illegal variable command"); + if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg); int ivar = find(arg[0]); if (ivar >= 0) { if (style[ivar] != EQUAL) @@ -430,7 +434,7 @@ void Variable::set(int narg, char **arg) // data = 1 value, string to eval } else if (strcmp(arg[1],"atom") == 0) { - if (narg != 3) error->all(FLERR,"Illegal variable command"); + if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg); int ivar = find(arg[0]); if (ivar >= 0) { if (style[ivar] != ATOM) @@ -454,7 +458,7 @@ void Variable::set(int narg, char **arg) // data = 1 value, string to eval } else if (strcmp(arg[1],"vector") == 0) { - if (narg != 3) error->all(FLERR,"Illegal variable command"); + if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg); int ivar = find(arg[0]); if (ivar >= 0) { if (style[ivar] != VECTOR) @@ -478,7 +482,7 @@ void Variable::set(int narg, char **arg) // data = 2 values, 1st is Python func to invoke, 2nd is filled by invoke } else if (strcmp(arg[1],"python") == 0) { - if (narg != 3) error->all(FLERR,"Illegal variable command"); + if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg); if (!python->is_enabled()) error->all(FLERR,"LAMMPS is not built with Python embedded"); int ivar = find(arg[0]); @@ -507,7 +511,7 @@ void Variable::set(int narg, char **arg) // dvalue = numeric initialization via platform::walltime() } else if (strcmp(arg[1],"timer") == 0) { - if (narg != 2) error->all(FLERR,"Illegal variable command"); + if (narg != 2) error->all(FLERR,"Illegal variable command: expected 2 arguments but found {}", narg); int ivar = find(arg[0]); if (ivar >= 0) { if (style[ivar] != TIMER) @@ -531,7 +535,7 @@ void Variable::set(int narg, char **arg) // dvalue = numeric initialization from 2nd arg, reset by internal_set() } else if (strcmp(arg[1],"internal") == 0) { - if (narg != 3) error->all(FLERR,"Illegal variable command"); + if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg); int ivar = find(arg[0]); if (ivar >= 0) { if (style[ivar] != INTERNAL) @@ -551,7 +555,7 @@ void Variable::set(int narg, char **arg) // unrecognized variable style - } else error->all(FLERR,"Illegal variable command"); + } else error->all(FLERR,"Unknown variable keyword: {}", arg[1]); // set name of variable, if not replacing one flagged with replaceflag // name must be all alphanumeric chars or underscores diff --git a/unittest/commands/test_lattice_region.cpp b/unittest/commands/test_lattice_region.cpp index 4f314b1669..cc22509dcd 100644 --- a/unittest/commands/test_lattice_region.cpp +++ b/unittest/commands/test_lattice_region.cpp @@ -45,7 +45,9 @@ protected: { testbinary = "LatticeRegionTest"; LAMMPSTest::SetUp(); - command("units metal"); + HIDE_OUTPUT([&] { + command("units metal"); + }); } }; @@ -63,7 +65,7 @@ TEST_F(LatticeRegionTest, lattice_none) ASSERT_EQ(lattice->basis, nullptr); TEST_FAILURE(".*ERROR: Illegal lattice command.*", command("lattice");); - TEST_FAILURE(".*ERROR: Illegal lattice command.*", command("lattice xxx");); + TEST_FAILURE(".*ERROR: Unknown lattice keyword: xxx.*", command("lattice xxx");); TEST_FAILURE(".*ERROR: Illegal lattice command.*", command("lattice none 1.0 origin");); TEST_FAILURE(".*ERROR: Expected floating point.*", command("lattice none xxx");); @@ -114,10 +116,11 @@ TEST_F(LatticeRegionTest, lattice_sc) ASSERT_EQ(lattice->basis[0][1], 0.0); ASSERT_EQ(lattice->basis[0][2], 0.0); - TEST_FAILURE(".*ERROR: Illegal lattice command.*", + TEST_FAILURE(".*ERROR: Invalid lattice origin argument: 1.*", command("lattice sc 1.0 origin 1.0 1.0 1.0");); - TEST_FAILURE(".*ERROR: Illegal lattice command.*", command("lattice sc 1.0 origin 1.0");); - TEST_FAILURE(".*ERROR: Illegal lattice command.*", + TEST_FAILURE(".*ERROR: Illegal lattice origin command: missing argument.*", + command("lattice sc 1.0 origin 1.0");); + TEST_FAILURE(".*ERROR: Unknown lattice keyword: xxx.*", command("lattice sc 1.0 origin 0.0 0.0 0.0 xxx");); TEST_FAILURE(".*ERROR: Expected floating point.*", command("lattice sc 1.0 origin xxx 1.0 1.0");); @@ -195,11 +198,12 @@ TEST_F(LatticeRegionTest, lattice_fcc) ASSERT_EQ(lattice->basis[3][1], 0.5); ASSERT_EQ(lattice->basis[3][2], 0.5); - TEST_FAILURE(".*ERROR: Invalid option in lattice command for non-custom style.*", + TEST_FAILURE(".*ERROR: Invalid basis option in lattice command for non-custom style.*", command("lattice fcc 1.0 basis 0.0 0.0 0.0");); - TEST_FAILURE(".*ERROR: Invalid option in lattice command for non-custom style.*", + TEST_FAILURE(".*ERROR: Invalid a1 option in lattice command for non-custom style.*", command("lattice fcc 1.0 a1 0.0 1.0 0.0");); - TEST_FAILURE(".*ERROR: Illegal lattice command.*", command("lattice fcc 1.0 orient w 1 0 0");); + TEST_FAILURE(".*ERROR: Unknown lattice orient argument: w.*", + command("lattice fcc 1.0 orient w 1 0 0");); BEGIN_HIDE_OUTPUT(); command("dimension 2"); @@ -241,9 +245,9 @@ TEST_F(LatticeRegionTest, lattice_hcp) ASSERT_EQ(lattice->a3[1], 0.0); ASSERT_DOUBLE_EQ(lattice->a3[2], sqrt(8.0 / 3.0)); - TEST_FAILURE(".*ERROR: Invalid option in lattice command for non-custom style.*", + TEST_FAILURE(".*ERROR: Invalid a2 option in lattice command for non-custom style.*", command("lattice hcp 1.0 a2 0.0 1.0 0.0");); - TEST_FAILURE(".*ERROR: Invalid option in lattice command for non-custom style.*", + TEST_FAILURE(".*ERROR: Invalid a3 option in lattice command for non-custom style.*", command("lattice hcp 1.0 a3 0.0 1.0 0.0");); BEGIN_HIDE_OUTPUT(); command("dimension 2"); @@ -452,9 +456,9 @@ TEST_F(LatticeRegionTest, lattice_custom) ASSERT_DOUBLE_EQ(lattice->a3[1], 0.0); ASSERT_DOUBLE_EQ(lattice->a3[2], 4.34 * sqrt(8.0 / 3.0)); - TEST_FAILURE(".*ERROR: Illegal lattice command.*", + TEST_FAILURE(".*ERROR: Invalid lattice basis argument: -0.1.*", command("lattice custom 1.0 basis -0.1 0 0");); - TEST_FAILURE(".*ERROR: Illegal lattice command.*", + TEST_FAILURE(".*ERROR: Invalid lattice basis argument: 1.*", command("lattice custom 1.0 basis 0.0 1.0 0");); BEGIN_HIDE_OUTPUT(); diff --git a/unittest/commands/test_simple_commands.cpp b/unittest/commands/test_simple_commands.cpp index c58efcd9ea..2563c09848 100644 --- a/unittest/commands/test_simple_commands.cpp +++ b/unittest/commands/test_simple_commands.cpp @@ -81,7 +81,7 @@ TEST_F(SimpleCommandsTest, Echo) ASSERT_EQ(lmp->input->echo_log, 1); TEST_FAILURE(".*ERROR: Illegal echo command.*", command("echo");); - TEST_FAILURE(".*ERROR: Illegal echo command.*", command("echo xxx");); + TEST_FAILURE(".*ERROR: Unknown echo keyword: xxx.*", command("echo xxx");); } TEST_F(SimpleCommandsTest, Log) diff --git a/unittest/commands/test_variables.cpp b/unittest/commands/test_variables.cpp index 60a9f44095..fe39daf43b 100644 --- a/unittest/commands/test_variables.cpp +++ b/unittest/commands/test_variables.cpp @@ -197,11 +197,11 @@ TEST_F(VariableTest, CreateDelete) ASSERT_EQ(variable->internalstyle(variable->find("ten")), 1); TEST_FAILURE(".*ERROR: Illegal variable command.*", command("variable");); - TEST_FAILURE(".*ERROR: Illegal variable command.*", command("variable dummy index");); - TEST_FAILURE(".*ERROR: Illegal variable command.*", command("variable dummy delete xxx");); - TEST_FAILURE(".*ERROR: Illegal variable command.*", command("variable dummy loop -1");); - TEST_FAILURE(".*ERROR: Illegal variable command.*", command("variable dummy loop 10 1");); - TEST_FAILURE(".*ERROR: Illegal variable command.*", command("variable dummy xxxx");); + TEST_FAILURE(".*ERROR: Illegal variable index command.*", command("variable dummy index");); + TEST_FAILURE(".*ERROR: Illegal variable delete command: expected 2 arguments but found 3.*", command("variable dummy delete xxx");); + TEST_FAILURE(".*ERROR: Invalid variable loop argument: -1.*", command("variable dummy loop -1");); + TEST_FAILURE(".*ERROR: Illegal variable loop command.*", command("variable dummy loop 10 1");); + TEST_FAILURE(".*ERROR: Unknown variable keyword: xxx.*", command("variable dummy xxxx");); TEST_FAILURE(".*ERROR: Cannot redefine variable as a different style.*", command("variable two string xxx");); TEST_FAILURE(".*ERROR: Cannot redefine variable as a different style.*",