Merge pull request lammps#3896 from lammps/compute-fix-variable-outputs

Standardize how computes and fixes can produce multiple kinds of output

doc/src/Howto_output.rst

@@ -1,7 +1,7 @@
 Output from LAMMPS (thermo, dumps, computes, fixes, variables)
 ==============================================================
 
-There are four basic kinds of LAMMPS output:
+There are four basic forms of LAMMPS output:
 
 * :doc:`Thermodynamic output <thermo_style>`, which is a list of
   quantities printed every few timesteps to the screen and logfile.
@@ -20,18 +20,17 @@ output files, depending on what :doc:`dump <dump>` and :doc:`fix <fix>`
 commands you specify.
 
 As discussed below, LAMMPS gives you a variety of ways to determine
-what quantities are computed and printed when the thermodynamics,
+what quantities are calculated and printed when the thermodynamics,
 dump, or fix commands listed above perform output.  Throughout this
 discussion, note that users can also :doc:`add their own computes and
-fixes to LAMMPS <Modify>` which can then generate values that can then
-be output with these commands.
+fixes to LAMMPS <Modify>` which can generate values that can then be
+output with these commands.
 
 The following subsections discuss different LAMMPS commands related
 to output and the kind of data they operate on and produce:
 
 * :ref:`Global/per-atom/local/per-grid data <global>`
 * :ref:`Scalar/vector/array data <scalar>`
-* :ref:`Per-grid data <grid>`
 * :ref:`Disambiguation <disambiguation>`
 * :ref:`Thermodynamic output <thermo>`
 * :ref:`Dump file output <dump>`
@@ -48,34 +47,65 @@ to output and the kind of data they operate on and produce:
 Global/per-atom/local/per-grid data
 -----------------------------------
 
-Various output-related commands work with four different styles of
+Various output-related commands work with four different "styles" of
 data: global, per-atom, local, and per-grid.  A global datum is one or
 more system-wide values, e.g. the temperature of the system.  A
 per-atom datum is one or more values per atom, e.g. the kinetic energy
 of each atom.  Local datums are calculated by each processor based on
-the atoms it owns, but there may be zero or more per atom, e.g. a list
+the atoms it owns, and there may be zero or more per atom, e.g. a list
 of bond distances.
 
 A per-grid datum is one or more values per grid cell, for a grid which
-overlays the simulation domain.  The grid cells and the data they
-store are distributed across processors; each processor owns the grid
-cells whose center point falls within its subdomain.
+overlays the simulation domain.  Similar to atoms and per-atom data,
+the grid cells and the data they store are distributed across
+processors; each processor owns the grid cells whose center points
+fall within its subdomain.
 
 .. _scalar:
 
 Scalar/vector/array data
 ------------------------
 
-Global, per-atom, and local datums can come in three kinds: a single
-scalar value, a vector of values, or a 2d array of values.  The doc
-page for a "compute" or "fix" or "variable" that generates data will
-specify both the style and kind of data it produces, e.g. a per-atom
-vector.
-
-When a quantity is accessed, as in many of the output commands
-discussed below, it can be referenced via the following bracket
-notation, where ID in this case is the ID of a compute.  The leading
-"c\_" would be replaced by "f\_" for a fix, or "v\_" for a variable:
+Global, per-atom, local, and per-grid datums can come in three
+"kinds": a single scalar value, a vector of values, or a 2d array of
+values.  More specifically these are the valid kinds for each style:
+
+* global scalar
+* global vector
+* global array
+* per-atom vector
+* per-atom array
+* local vector
+* local array
+* per-grid vector
+* per-grid array
+
+A per-atom vector means a single value per atom; the "vector" is the
+length of the number of atoms.  A per-atom array means multiple values
+per atom.  Similarly a local vector or array means one or multiple
+values per entity (e.g. per bond in the system).  And a per-grid
+vector or array means one or multiple values per grid cell.
+
+The doc page for a compute or fix or variable that generates data will
+specify both the styles and kinds of data it produces, e.g. a per-atom
+vector.  Note that a compute or fix may generate multiple styles and
+kinds of output.  However, for per-atom data only a vector or array is
+output, never both.  Likewise for per-local and per-grid data.  An
+example of a fix which generates multiple styles and kinds of data is
+the :doc:`fix mdi/qm <fix_mdi_qm>` command.  It outputs a global
+scalar, global vector, and per-atom array for the quantum mechanical
+energy and virial of the system and forces on each atom.
+
+By contrast, different variable styles generate only a single kind of
+data: a global scalar for an equal-style variable, global vector for a
+vector-style variable, and a per-atom vector for an atom-style
+variable.
+
+When data is accessed by another command, as in many of the output
+commands discussed below, it can be referenced via the following
+bracket notation, where ID in this case is the ID of a compute.  The
+leading "c\_" would be replaced by "f\_" for a fix, or "v\_" for a
+variable (and ID would be the name of the variable):
 
 +-------------+--------------------------------------------+
 | c_ID        | entire scalar, vector, or array            |
@@ -85,40 +115,56 @@ notation, where ID in this case is the ID of a compute.  The leading
 | c_ID[I][J]  | one element of array                       |
 +-------------+--------------------------------------------+
 
-In other words, using one bracket reduces the dimension of the data
-once (vector -> scalar, array -> vector).  Using two brackets reduces
-the dimension twice (array -> scalar).  Thus a command that uses
-scalar values as input can typically also process elements of a vector
-or array.
-
-.. _grid:
-
-Per-grid data
-------------------------
+Note that using one bracket reduces the dimension of the data once
+(vector -> scalar, array -> vector).  Using two brackets reduces the
+dimension twice (array -> scalar).  Thus a command that uses scalar
+values as input can also conceptually operate on an element of a
+vector or array.
 
-Per-grid data can come in two kinds: a vector of values (one per grid
-cekk), or a 2d array of values (multiple values per grid ckk).  The
-doc page for a "compute" or "fix" that generates data will specify
-names for both the grid(s) and datum(s) it produces, e.g. per-grid
-vectors or arrays, which can be referenced by other commands.  See the
-:doc:`Howto grid <Howto_grid>` doc page for more details.
+Per-grid vectors or arrays are accessed similarly, except that the ID
+for the compute or fix includes a grid name and a data name.  This is
+because a fix or compute can create multiple grids (of different
+sizes) and multiple sets of data (for each grid).  The fix or compute
+defines names for each grid and for each data set, so that all of them
+can be accessed by other commands.  See the :doc:`Howto grid
+<Howto_grid>` doc page for more details.
 
 .. _disambiguation:
 
 Disambiguation
 --------------
 
-Some computes and fixes produce data in multiple styles, e.g. a global
-scalar and a per-atom vector. Usually the context in which the input
-script references the data determines which style is meant. Example:
-if a compute provides both a global scalar and a per-atom vector, the
-former will be accessed by using ``c_ID`` in an equal-style variable,
-while the latter will be accessed by using ``c_ID`` in an atom-style
-variable.  Note that atom-style variable formulas can also access
-global scalars, but in this case it is not possible to do this
-directly because of the ambiguity.  Instead, an equal-style variable
-can be defined which accesses the global scalar, and that variable can
-be used in the atom-style variable formula in place of ``c_ID``.
+When a compute or fix produces data in multiple styles, e.g. global
+and per-atom, a reference to the data can sometimes be ambiguous.
+Usually the context in which the input script references the data
+determines which style is meant.
+
+For example, if a compute outputs a global vector and a per-atom
+array, an element of the global vector will be accessed by using
+``c_ID[I]`` in :doc:`thermodynamic output <thermo_style>`, while a
+column of the per-atom array will be accessed by using ``c_ID[I]`` in
+a :doc:`dump custom <dump>` command.
+
+However, if a :doc:`atom-style variable <variable>` references
+``c_ID[I]``, then it could be intended to refer to a single element of
+the global vector or a column of the per-atom array.  The doc page for
+any command that has a potential ambiguity (variables are the most
+common) will explain how to resolve the ambiguity.
+
+In this case, an atom-style variables references per-atom data if it
+exists.  If access to an element of a global vector is needed (as in
+this example), an equal-style variable which references the value can
+be defined and used in the atom-style variable formula instead.
+
+Similarly, :doc:`thermodynamic output <thermo_style>` can only
+reference global data from a compute or fix.  But you can indirectly
+access per-atom data as follows.  The reference ``c_ID[245][2]`` for
+the ID of a :doc:`compute displace/atom <compute_displace_atom>`
+command, refers to the y-component of displacement for the atom with
+ID 245.  While you cannot use that reference directly in the
+:doc:`thermo_style <thermo_style>` command, you can use it an
+equal-style variable formula, and then reference the variable in
+thermodynamic output.
 
 .. _thermo:
 
@@ -389,7 +435,7 @@ output and input data types must match, e.g. global/per-atom/local
 data and scalar/vector/array data.
 
 Also note that, as described above, when a command takes a scalar as
-input, that could be an element of a vector or array.  Likewise a
+input, that could also be an element of a vector or array.  Likewise a
 vector input could be a column of an array.
 
 +--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+

doc/src/compute.rst

@@ -27,58 +27,62 @@ Examples
 Description
 """""""""""
 
-Define a computation that will be performed on a group of atoms.
-Quantities calculated by a compute are instantaneous values, meaning
-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).
-See the :doc:`Howto output <Howto_output>` page for a summary of
-various LAMMPS output options, many of which involve computes.
+Define a diagnostic computation that will be performed on a group of
+atoms.  Quantities calculated by a compute are instantaneous values,
+meaning they are calculated from information about atoms on the
+current timestep or iteration, though internally a compute may store
+some information about a previous state of the system.  Defining a
+compute does not perform the 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).  See the :doc:`Howto output <Howto_output>` page
+for a summary of various LAMMPS output options, many of which involve
+computes.
 
 The ID of a compute can only contain alphanumeric characters and
 underscores.
 
 ----------
 
-Computes calculate one or more of four styles of quantities: global,
-per-atom, local, or per-atom.  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.  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.  Per-grid quantities are
-calculated on a regular 2d or 3d grid which overlays a 2d or 3d
-simulation domain.  The grid points and the data they store are
-distributed across processors; each processor owns the grid points
-which fall within its subdomain.
-
-Computes that produce per-atom quantities have the word "atom" at the
-end of their style, e.g. *ke/atom*\ .  Computes that produce local
-quantities have the word "local" at the end of their style,
-e.g. *bond/local*\ .  Computes that produce per-grid quantities have
-the word "grid" at the end of their style, e.g. *property/grid*\ .
-Styles with neither "atom" or "local" or "grid" at the end of their
-style name produce global quantities.
-
-Note that a single compute typically produces either global or
-per-atom or local or per-grid values.  It does not compute both global
-and per-atom values.  It can produce local values or per-grid values
-in tandem with global or per-atom quantities.  The compute doc page
-will explain the details.
-
-Global, per-atom, local, and per-grid quantities 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.
-
-When a compute 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 compute:
+Computes calculate and store any of four *styles* of quantities:
+global, per-atom, local, or per-grid.
+
+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.  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.  Per-grid quantities are calculated on a regular 2d or 3d
+grid which overlays a 2d or 3d simulation domain.  The grid points and
+the data they store are distributed across processors; each processor
+owns the grid points which fall within its subdomain.
+
+As a general rule of thumb, computes that produce per-atom quantities
+have the word "atom" at the end of their style, e.g. *ke/atom*\ .
+Computes that produce local quantities have the word "local" at the
+end of their style, e.g. *bond/local*\ .  Computes that produce
+per-grid quantities have the word "grid" at the end of their style,
+e.g. *property/grid*\ .  And styles with neither "atom" or "local" or
+"grid" at the end of their style name produce global quantities.
+
+Global, per-atom, local, and per-grid quantities can also be of three
+*kinds*: a single scalar value (global only), a vector of values, or a
+2d array of values.  For per-atom, local, and per-grid quantities, a
+"vector" means a single value for each atom, each local entity
+(e.g. bond), or grid cell.  Likewise an "array", means multiple values
+for each atom, each local entity, or each grid cell.
+
+Note that a single compute can produce any combination of global,
+per-atom, local, or per-grid values.  Likewise it can prouduce any
+combination of scalar, vector, or array output for each style.  The
+exception is that for per-atom, local, and per-grid output, either a
+vector or array can be produced, but not both.  The doc page for each
+compute explains the values it produces.
+
+When a compute output is accessed by another input script command it
+is referenced via the following bracket notation, where ID is the ID
+of the compute:
 
 +-------------+--------------------------------------------+
 | c_ID        | entire scalar, vector, or array            |
@@ -89,17 +93,23 @@ notation, where ID is the ID of the compute:
 +-------------+--------------------------------------------+
 
 In other words, using one bracket reduces the dimension of the
-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 <variable>` 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
-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.
+quantity once (vector :math:`\to` scalar, array :math:`\to` vector).
+Using two brackets reduces the dimension twice (array :math:`\to`
+scalar).  Thus, for example, a command that uses global scalar compute
+values as input can also process elements of a vector or array.
+Depending on the command, this can either be done directly using the
+syntax in the table, or by first defining a :doc:`variable <variable>`
+of the appropriate style to store the quantity, then using the
+variable as an input to the command.
+
+Note that commands and :doc:`variables <variable>` which take compute
+outputs as input typically do not allow for all styles and kinds of
+data (e.g., a command may require global but not per-atom values, or
+it may require a vector of values, not a scalar).  This means there is
+typically no ambiguity about referring to a compute output as c_ID
+even if it produces, for example, both a scalar and vector.  The doc
+pages for various commands explain the details, including how any
+ambiguities are resolved.
 
 ----------