diff --git a/doc/src/compute.rst b/doc/src/compute.rst index 317efa4f41..226dc6373b 100644 --- a/doc/src/compute.rst +++ b/doc/src/compute.rst @@ -43,8 +43,8 @@ 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 +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 diff --git a/doc/src/thermo_style.rst b/doc/src/thermo_style.rst index 63ad59e553..c3c607a479 100644 --- a/doc/src/thermo_style.rst +++ b/doc/src/thermo_style.rst @@ -385,19 +385,20 @@ creates a global vector with 6 values. The *c_ID* and *c_ID[I]* and *c_ID[I][J]* keywords allow global values calculated by a compute to be output. As discussed on the :doc:`compute ` doc page, computes can calculate global, -per-atom, or local values. Only global values can be referenced by -this command. However, per-atom compute values for an individual atom -can be referenced in a :doc:`variable ` and the variable -referenced by thermo_style custom, as discussed below. See the -discussion above for how the I in *c_ID[I]* can be specified with a -wildcard asterisk to effectively specify multiple values from a global -compute vector. +per-atom, local, and per-grid values. Only global values can be +referenced by this command. However, per-atom compute values for an +individual atom can be referenced in a :doc:`equal-style variable +` and the variable referenced by thermo_style custom, as +discussed below. See the discussion above for how the I in *c_ID[I]* +can be specified with a wildcard asterisk to effectively specify +multiple values from a global compute vector. The ID in the keyword should be replaced by the actual ID of a compute that has been defined elsewhere in the input script. See the -:doc:`compute ` command for details. If the compute calculates -a global scalar, vector, or array, then the keyword formats with 0, 1, -or 2 brackets will reference a scalar value from the compute. +:doc:`compute ` command for details. If the compute +calculates a global scalar, vector, or array, then the keyword formats +with 0, 1, or 2 brackets will reference a scalar value from the +compute. Note that some computes calculate "intensive" global quantities like temperature; others calculate "extensive" global quantities like @@ -410,13 +411,14 @@ norm ` option being used. The *f_ID* and *f_ID[I]* and *f_ID[I][J]* keywords allow global values calculated by a fix to be output. As discussed on the :doc:`fix -` doc page, fixes can calculate global, per-atom, or local -values. Only global values can be referenced by this command. -However, per-atom fix values can be referenced for an individual atom -in a :doc:`variable ` and the variable referenced by -thermo_style custom, as discussed below. See the discussion above for -how the I in *f_ID[I]* can be specified with a wildcard asterisk to -effectively specify multiple values from a global fix vector. +` doc page, fixes can calculate global, per-atom, local, and +per-grid values. Only global values can be referenced by this +command. However, per-atom fix values can be referenced for an +individual atom in a :doc:`equal-style variable ` and the +variable referenced by thermo_style custom, as discussed below. See +the discussion above for how the I in *f_ID[I]* can be specified with +a wildcard asterisk to effectively specify multiple values from a +global fix vector. The ID in the keyword should be replaced by the actual ID of a fix that has been defined elsewhere in the input script. See the @@ -438,14 +440,15 @@ output. The name in the keyword should be replaced by the variable name that has been defined elsewhere in the input script. Only equal-style and vector-style variables can be referenced; the latter requires a bracketed term to specify the Ith element of the vector -calculated by the variable. However, an atom-style variable can be -referenced for an individual atom by an equal-style variable and that -variable referenced. See the :doc:`variable ` command for -details. Variables of style *equal* and *vector* and *atom* define a -formula which can reference per-atom properties or thermodynamic -keywords, or they can invoke other computes, fixes, or variables when -evaluated, so this is a very general means of creating thermodynamic -output. +calculated by the variable. However, an equal-style variable can use +an atom-style variable in its formula indexed by the ID of an +individual atom. This is a way to output a speciic atom's per-atom +coordinates or other per-atom properties in thermo output. See the +:doc:`variable ` command for details. Note that variables +of style *equal* and *vector* and *atom* define a formula which can +reference per-atom properties or thermodynamic keywords, or they can +invoke other computes, fixes, or variables when evaluated, so this is +a very general means of creating thermodynamic output. Note that equal-style and vector-style variables are assumed to produce "intensive" global quantities, which are thus printed as-is, diff --git a/doc/src/variable.rst b/doc/src/variable.rst index 28c0d29799..38e423b632 100644 --- a/doc/src/variable.rst +++ b/doc/src/variable.rst @@ -550,12 +550,11 @@ variables. Most of the formula elements produce a scalar value. Some produce a global or per-atom vector of values. Global vectors can be produced by computes or fixes or by other vector-style variables. Per-atom -vectors are produced by atom vectors, compute references that -represent a per-atom vector, fix references that represent a per-atom -vector, and variables that are atom-style variables. Math functions -that operate on scalar values produce a scalar value; math function -that operate on global or per-atom vectors do so element-by-element -and produce a global or per-atom vector. +vectors are produced by atom vectors, computes or fixes which output a +per-atom vector or array, and variables that are atom-style variables. +Math functions that operate on scalar values produce a scalar value; +math function that operate on global or per-atom vectors do so +element-by-element and produce a global or per-atom vector. A formula for equal-style variables cannot use any formula element that produces a global or per-atom vector. A formula for a @@ -564,12 +563,13 @@ scalar value or a global vector value, but cannot use a formula element that produces a per-atom vector. A formula for an atom-style variable can use formula elements that produce either a scalar value or a per-atom vector, but not one that produces a global vector. + Atom-style variables are evaluated by other commands that define a -:doc:`group ` on which they operate, e.g. a :doc:`dump ` or -:doc:`compute ` or :doc:`fix ` command. When they invoke -the atom-style variable, only atoms in the group are included in the -formula evaluation. The variable evaluates to 0.0 for atoms not in -the group. +:doc:`group ` on which they operate, e.g. a :doc:`dump ` +or :doc:`compute ` or :doc:`fix ` command. When they +invoke the atom-style variable, only atoms in the group are included +in the formula evaluation. The variable evaluates to 0.0 for atoms +not in the group. ---------- @@ -1138,69 +1138,74 @@ only defined if an :doc:`atom_style ` is being used that defines molecule IDs. Note that many other atom attributes can be used as inputs to a -variable by using the :doc:`compute property/atom ` command and then specifying -a quantity from that compute. +variable by using the :doc:`compute property/atom +` command and then specifying a quantity from +that compute. ---------- Compute References ------------------ -Compute references access quantities calculated by a -:doc:`compute `. The ID in the reference should be replaced by -the ID of a compute defined elsewhere in the input script. As -discussed in the page for the :doc:`compute ` command, -computes can produce global, per-atom, or local values. Only global -and per-atom values can be used in a variable. Computes can also -produce a scalar, vector, or array. +Compute references access quantities calculated by a :doc:`compute +`. The ID in the reference should be replaced by the ID of a +compute defined elsewhere in the input script. -An equal-style variable can only use scalar values, which means a -global scalar, or an element of a global or per-atom vector or array. -A vector-style variable can use scalar values or a global vector of -values, or a column of a global array of values. Atom-style variables -can use global scalar values. They can also use per-atom vector -values, or a column of a per-atom array. See the doc pages for -individual computes to see what kind of values they produce. +As discussed on the page for the :doc:`compute ` command, +computes can produce global, per-atom, local, and per-grid values. +Only global and per-atom values can be used in a variable. Computes +can also produce scalars (global only), vectors, and arrays. See the +doc pages for individual computes to see what different kinds of data +they produce. -Examples of different kinds of compute references are as follows. -There is typically no ambiguity (see exception below) as to what a -reference means, since computes only produce either global or per-atom -quantities, never both. +An equal-style variable can only use scalar values, either from global +or per-atom data. In the case of per-atom data, this would be a value +for a specific atom. -+-------------+-------------------------------------------------------------------------------------------------------+ -| c_ID | global scalar, or per-atom vector | -+-------------+-------------------------------------------------------------------------------------------------------+ -| c_ID[I] | Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array | -+-------------+-------------------------------------------------------------------------------------------------------+ -| c_ID[I][J] | I,J element of global array, or atom I's Jth value in per-atom array | -+-------------+-------------------------------------------------------------------------------------------------------+ +A vector-style variable can use scalar values (same as for equal-style +variables), or global vectors of values. The latter can also be a +column of a global array. -For I and J indices, integers can be specified or a variable name, -specified as v_name, where name is the name of the variable. The -rules for this syntax are the same as for the "Atom Values and -Vectors" discussion above. +Atom-style variables can use scalar values (same as for equal-style +varaibles), or per-atom vectors of values. The latter can also be a +column of a per-atom array. -One source of ambiguity for compute references is when a vector-style -variable refers to a compute that produces both a global scalar and a -global vector. Consider a compute with ID "foo" that does this, -referenced as follows by variable "a", where "myVec" is another -vector-style variable: +The various allowed compute references in the variable formulas for +equal-, vector-, and atom-style variables are listed in the following +table: -.. code-block:: LAMMPS ++--------+------------+--------------------------------------------+ +| equal | c_ID | global scalar | +| equal | c_ID[I] | element of global vector | +| equal | c_ID[I][J] | element of global array | +| equal | C_ID[I] | element of per-atom vector, I = ID of atom | +| equal | C_ID{i}[J] | element of per-atom array, I = ID of atom | ++--------+------------+--------------------------------------------| +| vector | c_ID | global vector | +| vector | c_ID[I] | column of global array | +---------+------------+--------------------------------------------+ +| atom | c_ID | per-atom vector | +| atom | c_ID[I] | column of per-atom array | ++--------+------------+--------------------------------------------+ - variable a vector c_foo*v_myVec +Note that if an equal-style variable formula wishes to access per-atom +data from a compute, it must use capital "C" as the ID prefix and not +lower-case "c". -The reference "c_foo" could refer to either the global scalar or -global vector produced by compute "foo". In this case, "c_foo" will -always refer to the global scalar, and "C_foo" can be used to -reference the global vector. Similarly if the compute produces both a -global vector and global array, then "c_foo[I]" will always refer to -an element of the global vector, and "C_foo[I]" can be used to -reference the Ith column of the global array. +Also note that if a vector- or atom-style variable formula needs to +access a scalar value from a compute (i.e. the 5 kinds of values in +the first 5 lines of the table), it can not do so directly. Instead, +it can use a reference to an equal-style variable which stores the +scalar value from the compute. -Note that if a variable containing a compute is evaluated directly in -an input script (not during a run), then the values accessed by the -compute must be current. See the discussion below about "Variable +The I and J indices in these compute references can be integers or can +be a variable name, specified as v_name, where name is the name of the +variable. The rules for this syntax are the same as for indices in +the "Atom Values and Vectors" discussion above. + +If a variable containing a compute is evaluated directly in an input +script (not during a run), then the values accessed by the compute +should be current. See the discussion below about "Variable Accuracy". ---------- @@ -1208,51 +1213,60 @@ Accuracy". Fix References -------------- -Fix references access quantities calculated by a :doc:`fix `. +Fix references access quantities calculated by a :doc:`fix `. The ID in the reference should be replaced by the ID of a fix defined -elsewhere in the input script. As discussed in the page for the -:doc:`fix ` command, fixes can produce global, per-atom, or local -values. Only global and per-atom values can be used in a variable. -Fixes can also produce a scalar, vector, or array. An equal-style -variable can only use scalar values, which means a global scalar, or -an element of a global or per-atom vector or array. Atom-style -variables can use the same scalar values. They can also use per-atom -vector values. A vector value can be a per-atom vector itself, or a -column of an per-atom array. See the doc pages for individual fixes -to see what kind of values they produce. +elsewhere in the input script. -The different kinds of fix references are exactly the same as the -compute references listed in the above table, where "c\_" is replaced -by "f\_". Again, there is typically no ambiguity (see exception below) -as to what a reference means, since fixes only produce either global -or per-atom quantities, never both. +As discussed on the page for the :doc:`fix ` command, fixes can +produce global, per-atom, local, and per-grid values. Only global and +per-atom values can be used in a variable. Fixes can also produce +scalars (global only), vectors, and arrays. See the doc pages for +individual fixes to see what different kinds of data they produce. -+-------------+-------------------------------------------------------------------------------------------------------+ -| f_ID | global scalar, or per-atom vector | -+-------------+-------------------------------------------------------------------------------------------------------+ -| f_ID[I] | Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array | -+-------------+-------------------------------------------------------------------------------------------------------+ -| f_ID[I][J] | I,J element of global array, or atom I's Jth value in per-atom array | -+-------------+-------------------------------------------------------------------------------------------------------+ +An equal-style variable can only use scalar values, either from global +or per-atom data. In the case of per-atom data, this would be a value +for a specific atom. -For I and J indices, integers can be specified or a variable name, -specified as v_name, where name is the name of the variable. The -rules for this syntax are the same as for the "Atom Values and -Vectors" discussion above. +A vector-style variable can use scalar values (same as for equal-style +variables), or global vectors of values. The latter can also be a +column of a global array. -One source of ambiguity for fix references is the same ambiguity -discussed for compute references above. Namely when a vector-style -variable refers to a fix that produces both a global scalar and a -global vector. The solution is the same as for compute references. -For a fix with ID "foo", "f_foo" will always refer to the global -scalar, and "F_foo" can be used to reference the global vector. And -similarly for distinguishing between a fix's global vector versus -global array with "f_foo[I]" versus "F_foo[I]". +Atom-style variables can use scalar values (same as for equal-style +varaibles), or per-atom vectors of values. The latter can also be a +column of a per-atom array. -Note that if a variable containing a fix is evaluated directly in an -input script (not during a run), then the values accessed by the fix -should be current. See the discussion below about "Variable -Accuracy". +The various allowed fix references in the variable formulas for +equal-, vector-, and atom-style variables are listed in the following +table: + ++--------+------------+--------------------------------------------+ +| equal | f_ID | global scalar | +| equal | f_ID[I] | element of global vector | +| equal | f_ID[I][J] | element of global array | +| equal | F_ID[I] | element of per-atom vector, I = ID of atom | +| equal | F_ID{i}[J] | element of per-atom array, I = ID of atom | ++--------+------------+--------------------------------------------| +| vector | f_ID | global vector | +| vector | f_ID[I] | column of global array | +---------+------------+--------------------------------------------+ +| atom | f_ID | per-atom vector | +| atom | f_ID[I] | column of per-atom array | ++--------+------------+--------------------------------------------+ + +Note that if an equal-style variable formula wishes to access per-atom +data from a fix, it must use capital "F" as the ID prefix and not +lower-case "f". + +Also note that if a vector- or atom-style variable formula needs to +access a scalar value from a fix (i.e. the 5 kinds of values in the +first 5 lines of the table), it can not do so directly. Instead, it +can use a reference to an equal-style variable which stores the scalar +value from the fix. + +The I and J indices in these fix references can be integers or can be +a variable name, specified as v_name, where name is the name of the +variable. The rules for this syntax are the same as for indices in +the "Atom Values and Vectors" discussion above. Note that some fixes only generate quantities on certain timesteps. If a variable attempts to access the fix on non-allowed timesteps, an @@ -1260,6 +1274,10 @@ error is generated. For example, the :doc:`fix ave/time ` command may only generate averaged quantities every 100 steps. See the doc pages for individual fix commands for details. +If a variable containing a fix is evaluated directly in an input +script (not during a run), then the values accessed by the fix should +be current. See the discussion below about "Variable Accuracy". + ---------- Variable References @@ -1312,8 +1330,8 @@ produce only a global scalar or global vector or per-atom vector. For the I index, an integer can be specified or a variable name, specified as v_name, where name is the name of the variable. The -rules for this syntax are the same as for the "Atom Values and -Vectors" discussion above. +rules for this syntax are the same as for indices in the "Atom Values +and Vectors" discussion above. ----------