From b3b9d032fa1a83e3806b19f0f528c0be53f08ca5 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 13 Oct 2024 18:56:41 -0400 Subject: [PATCH] cleanup, clarification and re-wrap of doc file sections --- doc/src/Howto_chunk.rst | 67 ++++++++++++----------- doc/src/compute_reduce.rst | 10 ++-- doc/src/compute_reduce_chunk.rst | 91 +++++++++++++++++--------------- doc/src/group.rst | 4 +- 4 files changed, 93 insertions(+), 79 deletions(-) diff --git a/doc/src/Howto_chunk.rst b/doc/src/Howto_chunk.rst index f8655b745d..ea000eb22f 100644 --- a/doc/src/Howto_chunk.rst +++ b/doc/src/Howto_chunk.rst @@ -58,28 +58,30 @@ chunk ID for an individual atom can also be static (e.g. a molecule ID), or dynamic (e.g. what spatial bin an atom is in as it moves). Note that this compute allows the per-atom output of other -:doc:`computes `, :doc:`fixes `, and -:doc:`variables ` to be used to define chunk IDs for each -atom. This means you can write your own compute or fix to output a -per-atom quantity to use as chunk ID. See the :doc:`Modify ` -doc pages for info on how to do this. You can also define a :doc:`per-atom variable ` in the input script that uses a formula to -generate a chunk ID for each atom. +:doc:`computes `, :doc:`fixes `, and :doc:`variables +` to be used to define chunk IDs for each atom. This means +you can write your own compute or fix to output a per-atom quantity to +use as chunk ID. See the :doc:`Modify ` doc pages for info on +how to do this. You can also define a :doc:`per-atom variable +` in the input script that uses a formula to generate a chunk +ID for each atom. Fix ave/chunk command: ---------------------- -This fix takes the ID of a :doc:`compute chunk/atom ` command as input. For each chunk, -it then sums one or more specified per-atom values over the atoms in -each chunk. The per-atom values can be any atom property, such as -velocity, force, charge, potential energy, kinetic energy, stress, -etc. Additional keywords are defined for per-chunk properties like -density and temperature. More generally any per-atom value generated -by other :doc:`computes `, :doc:`fixes `, and :doc:`per-atom variables `, can be summed over atoms in each chunk. +This fix takes the ID of a :doc:`compute chunk/atom +` command as input. For each chunk, it then sums +one or more specified per-atom values over the atoms in each chunk. The +per-atom values can be any atom property, such as velocity, force, +charge, potential energy, kinetic energy, stress, etc. Additional +keywords are defined for per-chunk properties like density and +temperature. More generally any per-atom value generated by other +:doc:`computes `, :doc:`fixes `, and :doc:`per-atom +variables `, can be summed over atoms in each chunk. Similar to other averaging fixes, this fix allows the summed per-chunk values to be time-averaged in various ways, and output to a file. The -fix produces a global array as output with one row of values per -chunk. +fix produces a global array as output with one row of values per chunk. Compute \*/chunk commands: -------------------------- @@ -97,17 +99,20 @@ category: * :doc:`compute torque/chunk ` * :doc:`compute vcm/chunk ` -They each take the ID of a :doc:`compute chunk/atom ` command as input. As their names -indicate, they calculate the center-of-mass, radius of gyration, -moments of inertia, mean-squared displacement, temperature, torque, -and velocity of center-of-mass for each chunk of atoms. The :doc:`compute property/chunk ` command can tally the -count of atoms in each chunk and extract other per-chunk properties. +They each take the ID of a :doc:`compute chunk/atom +` command as input. As their names indicate, they +calculate the center-of-mass, radius of gyration, moments of inertia, +mean-squared displacement, temperature, torque, and velocity of +center-of-mass for each chunk of atoms. The :doc:`compute +property/chunk ` command can tally the count of +atoms in each chunk and extract other per-chunk properties. -The reason these various calculations are not part of the :doc:`fix ave/chunk command `, is that each requires a more +The reason these various calculations are not part of the :doc:`fix +ave/chunk command `, is that each requires a more complicated operation than simply summing and averaging over per-atom -values in each chunk. For example, many of them require calculation -of a center of mass, which requires summing mass\*position over the -atoms and then dividing by summed mass. +values in each chunk. For example, many of them require calculation of +a center of mass, which requires summing mass\*position over the atoms +and then dividing by summed mass. All of these computes produce a global vector or global array as output, with one or more values per chunk. The output can be used in @@ -118,9 +123,10 @@ various ways: * As input to the :doc:`fix ave/histo ` command to histogram values across chunks. E.g. a histogram of cluster sizes or molecule diffusion rates. -* As input to special functions of :doc:`equal-style variables `, like sum() and max() and ave(). E.g. to - find the largest cluster or fastest diffusing molecule or average - radius-of-gyration of a set of molecules (chunks). +* As input to special functions of :doc:`equal-style variables + `, like sum() and max() and ave(). E.g. to find the largest + cluster or fastest diffusing molecule or average radius-of-gyration of + a set of molecules (chunks). Other chunk commands: --------------------- @@ -138,9 +144,10 @@ spatially average per-chunk values calculated by a per-chunk compute. The :doc:`compute reduce/chunk ` command reduces a peratom value across the atoms in each chunk to produce a value per -chunk. When used with the :doc:`compute chunk/spread/atom ` command it can -create peratom values that induce a new set of chunks with a second -:doc:`compute chunk/atom ` command. +chunk. When used with the :doc:`compute chunk/spread/atom +` command it can create peratom values that +induce a new set of chunks with a second :doc:`compute chunk/atom +` command. Example calculations with chunks -------------------------------- diff --git a/doc/src/compute_reduce.rst b/doc/src/compute_reduce.rst index 9eafe7cd5a..f25a994764 100644 --- a/doc/src/compute_reduce.rst +++ b/doc/src/compute_reduce.rst @@ -206,11 +206,13 @@ IDs and the bond stretch will be printed with thermodynamic output. The *inputs* keyword allows selection of whether all the inputs are per-atom or local quantities. As noted above, all the inputs must be -the same kind (per-atom or local). Per-atom is the default setting. -If a compute or fix is specified as an input, it must produce per-atom -or local data to match this setting. If it produces both, e.g. for +the same kind (per-atom or local). Per-atom is the default setting. If +a compute or fix is specified as an input, it must produce per-atom or +local data to match this setting. If it produces both, like for example the :doc:`compute voronoi/atom ` command, then -this keyword selects between them. +this keyword selects between them. If a compute *only* produces local +data, like for example the :doc:`compute bond/local +command`, the setting "inputs local" is *required*. ---------- diff --git a/doc/src/compute_reduce_chunk.rst b/doc/src/compute_reduce_chunk.rst index 8ec19ade66..091604c0b2 100644 --- a/doc/src/compute_reduce_chunk.rst +++ b/doc/src/compute_reduce_chunk.rst @@ -37,55 +37,57 @@ Description Define a calculation that reduces one or more per-atom vectors into per-chunk values. This can be useful for diagnostic output. Or when -used in conjunction with the :doc:`compute chunk/spread/atom ` command it can be -used to create per-atom values that induce a new set of chunks with a -second :doc:`compute chunk/atom ` command. An -example is given below. +used in conjunction with the :doc:`compute chunk/spread/atom +` command it can be used to create per-atom +values that induce a new set of chunks with a second :doc:`compute +chunk/atom ` command. An example is given below. -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. For each atom, this compute accesses its chunk ID from the specified -*chunkID* compute. The per-atom value from an input contributes -to a per-chunk value corresponding the the chunk ID. +*chunkID* compute. The per-atom value from an input contributes to a +per-chunk value corresponding the the chunk ID. The reduction operation is specified by the *mode* setting and is performed over all the per-atom values from the atoms in each chunk. The *sum* option adds the pre-atom values to a per-chunk total. The -*min* or *max* options find the minimum or maximum value of the -per-atom values for each chunk. +*min* or *max* options find the minimum or maximum value of the 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 -: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 -it returns. For example, a compute with return a zero value for atoms -that are not in the group specified for that compute. +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 :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 it returns. +For example, a compute with return a zero value for atoms that are not +in the group specified for that compute. Each listed input is operated on independently. Each input can be the -result of a :doc:`compute ` or :doc:`fix ` or the evaluation -of an atom-style :doc:`variable `. +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 -be specified using a wildcard asterisk with the index to effectively +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 "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 :math:`N`. A leading -asterisk means all indices from 1 to n (inclusive). A trailing -asterisk means all indices from n to :math:`N` (inclusive). A middle asterisk -means all indices from m to n (inclusive). +"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 :math:`N`. +A leading asterisk means all indices from 1 to n (inclusive). A +trailing 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. For example, the following two 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 @@ -164,13 +166,14 @@ Output info """"""""""" This compute calculates a global vector if a single input value is -specified, otherwise a global array is output. The number of columns -in the array is the number of inputs provided. The length of the -vector or the number of vector elements or array rows = the number of -chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom ` command. 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. +specified, otherwise a global array is output. The number of columns in +the array is the number of inputs provided. The length of the vector or +the number of vector elements or array rows = the number of chunks +*Nchunk* as calculated by the specified :doc:`compute chunk/atom +` command. 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. The per-atom values for the vector or each column of the array will be in whatever :doc:`units ` the corresponding input value is in. @@ -183,7 +186,9 @@ Restrictions Related commands """""""""""""""" -:doc:`compute chunk/atom `, :doc:`compute reduce `, :doc:`compute chunk/spread/atom ` +:doc:`compute chunk/atom `, +:doc:`compute reduce `, +:doc:`compute chunk/spread/atom ` Default """"""" diff --git a/doc/src/group.rst b/doc/src/group.rst index 15ab0c9dc8..a7a29467ff 100644 --- a/doc/src/group.rst +++ b/doc/src/group.rst @@ -162,7 +162,7 @@ potential energy is above the threshold value :math:`-3.0`. compute 1 all pe/atom compute 2 all reduce sum c_1 thermo_style custom step temp pe c_2 - run 0 + run 0 post no variable eatom atom "c_1 > -3.0" group hienergy variable eatom @@ -173,7 +173,7 @@ Note that these lines compute 2 all reduce sum c_1 thermo_style custom step temp pe c_2 - run 0 + run 0 post no are necessary to ensure that the "eatom" variable is current when the group command invokes it. Because the eatom variable computes the