From c67331a3bcce8c80274d9b5e0c0d1fd61d75ce88 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Tue, 1 Mar 2016 22:30:28 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14711 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/Section_commands.html | 26 +- doc/Section_commands.txt | 1 + doc/_sources/Section_commands.txt | 50 ++-- doc/_sources/compute_slice.txt | 29 ++- doc/_sources/fix_ave_correlate.txt | 28 ++- doc/_sources/fix_ave_histo.txt | 31 ++- doc/_sources/fix_ave_time.txt | 32 ++- doc/_sources/fix_vector.txt | 31 +-- doc/_sources/thermo_style.txt | 25 +- doc/_sources/variable.txt | 387 +++++++++++++++++------------ doc/compute_slice.html | 28 ++- doc/compute_slice.txt | 31 ++- doc/fix_ave_correlate.html | 28 ++- doc/fix_ave_correlate.txt | 31 +-- doc/fix_ave_histo.html | 30 ++- doc/fix_ave_histo.txt | 31 ++- doc/fix_ave_time.html | 31 ++- doc/fix_ave_time.txt | 32 ++- doc/fix_vector.html | 31 +-- doc/fix_vector.txt | 31 +-- doc/searchindex.js | 2 +- doc/thermo_style.html | 25 +- doc/thermo_style.txt | 25 +- doc/variable.html | 380 ++++++++++++++++------------ doc/variable.txt | 381 ++++++++++++++++------------ 25 files changed, 1023 insertions(+), 734 deletions(-) diff --git a/doc/Section_commands.html b/doc/Section_commands.html index ca23d91307..39b4b3aa79 100644 --- a/doc/Section_commands.html +++ b/doc/Section_commands.html @@ -1168,10 +1168,10 @@ KOKKOS, o = USER-OMP, t = OPT.

if LAMMPS is built with the appropriate package.

---+++ @@ -1209,28 +1209,28 @@ if LAMMPS - + + - - + + - - + + - - + + - - - + + diff --git a/doc/Section_commands.txt b/doc/Section_commands.txt index 1961cc942f..f5f6992cae 100644 --- a/doc/Section_commands.txt +++ b/doc/Section_commands.txt @@ -941,6 +941,7 @@ package"_Section_start.html#start_3. "meam/spline"_pair_meam_spline.html, "meam/sw/spline"_pair_meam_sw_spline.html, "mgpt"_pair_mgpt.html, +"morse/smooth/linear"_pair_morse.html, "quip"_pair_quip.html, "reax/c"_pair_reax_c.html, "smd/hertz"_pair_smd_hertz.html, diff --git a/doc/_sources/Section_commands.txt b/doc/_sources/Section_commands.txt index 5102a45d0c..f65a267094 100644 --- a/doc/_sources/Section_commands.txt +++ b/doc/_sources/Section_commands.txt @@ -644,31 +644,31 @@ KOKKOS, o = USER-OMP, t = OPT. These are additional pair styles in USER packages, which can be used if :ref:`LAMMPS is built with the appropriate package `. -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`awpmd/cut ` | :doc:`buck/mdf ` | :doc:`coul/cut/soft (o) ` | :doc:`coul/diel (o) ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`coul/long/soft (o) ` | :doc:`dpd/conservative ` | :doc:`dpd/fdt ` | :doc:`dpd/fdt/energy ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`eam/cd (o) ` | :doc:`edip (o) ` | :doc:`eff/cut ` | :doc:`gauss/cut ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`lennard/mdf ` | :doc:`list ` | :doc:`lj/charmm/coul/long/soft (o) ` | :doc:`lj/cut/coul/cut/soft (o) ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`lj/cut/coul/long/soft (o) ` | :doc:`lj/cut/dipole/sf (go) ` | :doc:`lj/cut/soft (o) ` | :doc:`lj/cut/tip4p/long/soft (o) ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`lj/mdf ` | :doc:`lj/sdk (gko) ` | :doc:`lj/sdk/coul/long (go) ` | :doc:`lj/sdk/coul/msm (o) ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`lj/sf (o) ` | :doc:`meam/spline ` | :doc:`meam/sw/spline ` | :doc:`mgpt ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`quip ` | :doc:`reax/c ` | :doc:`smd/hertz ` | :doc:`smd/tlsph ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`smd/triangulated/surface ` | :doc:`smd/ulsph ` | :doc:`smtbq ` | :doc:`sph/heatconduction ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`sph/idealgas ` | :doc:`sph/lj ` | :doc:`sph/rhosum ` | :doc:`sph/taitwater ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`sph/taitwater/morris ` | :doc:`srp ` | :doc:`tersoff/table (o) ` | :doc:`thole ` | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ -| :doc:`tip4p/long/soft (o) ` | | | | -+-----------------------------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+ ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`awpmd/cut ` | :doc:`buck/mdf ` | :doc:`coul/cut/soft (o) ` | :doc:`coul/diel (o) ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`coul/long/soft (o) ` | :doc:`dpd/conservative ` | :doc:`dpd/fdt ` | :doc:`dpd/fdt/energy ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`eam/cd (o) ` | :doc:`edip (o) ` | :doc:`eff/cut ` | :doc:`gauss/cut ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`lennard/mdf ` | :doc:`list ` | :doc:`lj/charmm/coul/long/soft (o) ` | :doc:`lj/cut/coul/cut/soft (o) ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`lj/cut/coul/long/soft (o) ` | :doc:`lj/cut/dipole/sf (go) ` | :doc:`lj/cut/soft (o) ` | :doc:`lj/cut/tip4p/long/soft (o) ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`lj/mdf ` | :doc:`lj/sdk (gko) ` | :doc:`lj/sdk/coul/long (go) ` | :doc:`lj/sdk/coul/msm (o) ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`lj/sf (o) ` | :doc:`meam/spline ` | :doc:`meam/sw/spline ` | :doc:`mgpt ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`morse/smooth/linear ` | :doc:`quip ` | :doc:`reax/c ` | :doc:`smd/hertz ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`smd/tlsph ` | :doc:`smd/triangulated/surface ` | :doc:`smd/ulsph ` | :doc:`smtbq ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`sph/heatconduction ` | :doc:`sph/idealgas ` | :doc:`sph/lj ` | :doc:`sph/rhosum ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`sph/taitwater ` | :doc:`sph/taitwater/morris ` | :doc:`srp ` | :doc:`tersoff/table (o) ` | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ +| :doc:`thole ` | :doc:`tip4p/long/soft (o) ` | | | ++-----------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+ ---------- diff --git a/doc/_sources/compute_slice.txt b/doc/_sources/compute_slice.txt index c4fe7b4708..2aa93bf0a5 100644 --- a/doc/_sources/compute_slice.txt +++ b/doc/_sources/compute_slice.txt @@ -22,6 +22,7 @@ Syntax c_ID[I] = Ith column of global array calculated by a compute with ID f_ID = global vector calculated by a fix with ID f_ID[I] = Ith column of global array calculated by a fix with ID + v_name = vector calculated by an vector-style variable with name @@ -31,7 +32,7 @@ Examples .. parsed-literal:: compute 1 all slice 1 100 10 c_msdmol[4] - compute 1 all slice 301 400 1 c_msdmol[4] + compute 1 all slice 301 400 1 c_msdmol[4] v_myVec Description """"""""""" @@ -39,9 +40,9 @@ Description Define a calculation that "slices" one or more vector inputs into smaller vectors, one per listed input. The inputs can be global quantities; they cannot be per-atom or local quantities. -:doc:`Computes ` and :doc:`fixes ` may generate any of the -three kinds of quantities. :doc:`Variables ` do not generate -global vectors. The group specified with this command is ignored. +:doc:`Computes ` and :doc:`fixes ` and vector-style +:doc:`variables ` can generate such global quantities. The +group specified with this command is ignored. The values extracted from the input vector(s) are determined by the *Nstart*, *Nstop*, and *Nskip* parameters. The elements of an input @@ -73,6 +74,15 @@ 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 `. +If an input value begins with "v_", a variable name must follow which +has been previously defined in the input script. Only vector-style +variables can be referenced. See the :doc:`variable ` command +for details. Note that variables of style *vector* define a formula +which can reference individual atom properties or thermodynamic +keywords, or they can invoke other computes, fixes, or variables when +they are evaluated, so this is a very general means of specifying +quantities to slice. + If a single input is specified this compute produces a global vector, even if the length of the vector is 1. If multiple inputs are specified, then a global array of values is produced, with the number @@ -93,15 +103,16 @@ array values from a compute as input. See :ref:`this section ` for an options. The vector or array values calculated by this compute are simply -copies of values generated by computes or fixes that are input vectors -to this compute. If there is a single input vector of intensive -and/or extensive values, then each value in the vector of values -calculated by this compute will be "intensive" or "extensive", +copies of values generated by computes or fixes or variables that are +input vectors to this compute. If there is a single input vector of +intensive and/or extensive values, then each value in the vector of +values calculated by this compute will be "intensive" or "extensive", depending on the corresponding input value. If there are multiple input vectors, and all the values in them are intensive, then the array values calculated by this compute are "intensive". If there are multiple input vectors, and any value in them is extensive, then the -array values calculated by this compute are "extensive". +array values calculated by this compute are "extensive". Values +produced by a variable are treated as intensive. The vector or array values will be in whatever :doc:`units ` the input quantities are in. diff --git a/doc/_sources/fix_ave_correlate.txt b/doc/_sources/fix_ave_correlate.txt index 53e74246a7..08cc696e7b 100644 --- a/doc/_sources/fix_ave_correlate.txt +++ b/doc/_sources/fix_ave_correlate.txt @@ -24,6 +24,7 @@ Syntax f_ID = global scalar calculated by a fix with ID f_ID[I] = Ith component of global vector calculated by a fix with ID v_name = global value calculated by an equal-style variable with name + v_name[I] = Ith component of a vector-style variable with name * zero or more keyword/arg pairs may be appended * keyword = *type* or *ave* or *start* or *prefactor* or *file* or *overwrite* or *title1* or *title2* or *title3* @@ -82,21 +83,22 @@ specified values may represent calculations performed by computes and fixes which store their own "group" definitions. Each listed value can be the result of a :doc:`compute ` or -:doc:`fix ` or the evaluation of an equal-style +:doc:`fix ` or the evaluation of an equal-style or vector-style :doc:`variable `. In each case, the compute, fix, or variable must produce a global quantity, not a per-atom or local quantity. If you wish to spatial- or time-average or histogram per-atom quantities from a compute, fix, or variable, then see the :doc:`fix ave/spatial `, :doc:`fix ave/atom `, -or :doc:`fix ave/histo ` commands. If you wish to sum a -per-atom quantity into a single global quantity, see the :doc:`compute reduce ` command. +or :doc:`fix ave/histo ` commands. If you wish to +convert a per-atom quantity into a single global value, see the +:doc:`compute reduce ` command. :doc:`Computes ` that produce global quantities are those which do not have the word *atom* in their style name. Only a few :doc:`fixes ` produce global quantities. See the doc pages for individual fixes for info on which ones produce such values. -:doc:`Variables ` of style *equal* are the only ones that can -be used with this fix. Variables of style *atom* cannot be used, -since they produce per-atom values. +:doc:`Variables ` of style *equal* and *vector* are the only +ones that can be used with this fix. Variables of style *atom* cannot +be used, since they produce per-atom values. The input values must either be all scalars. What kinds of correlations between input values are calculated is determined by the @@ -172,9 +174,11 @@ which must be compatible with *Nevery*, else an error will result. Users can also write code for their own fix styles and :doc:`add them to LAMMPS `. If a value begins with "v_", a variable name must follow which has -been previously defined in the input script. Only equal-style -variables can be referenced. See the :doc:`variable ` command -for details. Note that variables of style *equal* define a formula +been previously defined in the input script. Only equal-style or +vector-style variables can be referenced; the latter requires a +bracketed term to specify the Ith element of the vector calculated by +the variable. See the :doc:`variable ` command for details. +Note that variables of style *equal* or *vector* define a formula which can reference individual atom properties or thermodynamic keywords, or they can invoke other computes, fixes, or variables when they are evaluated, so this is a very general means of specifying @@ -320,9 +324,9 @@ above. * For *type* = *full*, the Npair = N^2 columns are ordered: C11, C12, ..., C1N, C21, C22, ..., C2N, C31, ..., C3N, ..., CN1, ..., CNN-1, CNN. -The array values calculated by this fix are treated as "intensive". -If you need to divide them by the number of atoms, you must do this in -a later processing step, e.g. when using them in a +The array values calculated by this fix are treated as intensive. If +you need to divide them by the number of atoms, you must do this in a +later processing step, e.g. when using them in a :doc:`variable `. No parameter of this fix can be used with the *start/stop* keywords of diff --git a/doc/_sources/fix_ave_histo.txt b/doc/_sources/fix_ave_histo.txt index 9851fe22a2..40c93e21dc 100644 --- a/doc/_sources/fix_ave_histo.txt +++ b/doc/_sources/fix_ave_histo.txt @@ -29,7 +29,8 @@ Syntax c_ID[I] = Ith component of vector or Ith column of array calculated by a compute with ID f_ID = scalar or vector calculated by a fix with ID f_ID[I] = Ith component of vector or Ith column of array calculated by a fix with ID - v_name = value(s) calculated by an equal-style or atom-style variable with name + v_name = value(s) calculated by an equal-style or vector-style or atom-style variable with name + v_name[I] = value calculated by a vector-style variable with name * zero or more keyword/arg pairs may be appended * keyword = *mode* or *file* or *ave* or *start* or *beyond* or *overwrite* or *title1* or *title2* or *title3* @@ -93,12 +94,13 @@ different ways; see the discussion of the *beyond* keyword below. Each input value can be an atom attribute (position, velocity, force component) or can be the result of a :doc:`compute ` or -:doc:`fix ` or the evaluation of an equal-style or atom-style -:doc:`variable `. The set of input values can be either all -global, all per-atom, or all local quantities. Inputs of different -kinds (e.g. global and per-atom) cannot be mixed. Atom attributes are -per-atom vector values. See the doc page for individual "compute" and -"fix" commands to see what kinds of quantities they generate. +:doc:`fix ` or the evaluation of an equal-style or vector-style or +atom-style :doc:`variable `. The set of input values can be +either all global, all per-atom, or all local quantities. Inputs of +different kinds (e.g. global and per-atom) cannot be mixed. Atom +attributes are per-atom vector values. See the doc page for +individual "compute" and "fix" commands to see what kinds of +quantities they generate. The input values must either be all scalars or all vectors (or arrays), depending on the setting of the *mode* keyword. @@ -195,10 +197,15 @@ Users can also write code for their own fix styles and :doc:`add them to LAMMPS If a value begins with "v_", a variable name must follow which has been previously defined in the input script. If *mode* = scalar, then -only equal-style variables can be used, which produce a global value. -If *mode* = vector, then only atom-style variables can be used, which -produce a per-atom vector. See the :doc:`variable ` command -for details. Note that variables of style *equal* and *atom* define a +only equal-style or vector-style variables can be used, which both +produce global values. In this mode, a vector-style variable requires +a bracketed term to specify the Ith element of the vector calculated +by the variable. If *mode* = vector, then only vector-style or +atom-style variables can be used, which produce a global or per-atom +vector respectively. The vector-style variable must be used without a +bracketed term. See the :doc:`variable ` command for details. + +Note that variables of style *equal*, *vector*, and *atom* define a formula which can reference individual atom properties or thermodynamic keywords, or they can invoke other computes, fixes, or variables when they are evaluated, so this is a very general means of @@ -325,7 +332,7 @@ divided by the total count (not including missing counts), so that the values in the 3rd column sum to 1.0. The vector and array values calculated by this fix are all treated as -"intensive". If this is not the case, e.g. due to histogramming +intensive. If this is not the case, e.g. due to histogramming per-atom input values, then you will need to account for that when interpreting the values produced by this fix. diff --git a/doc/_sources/fix_ave_time.txt b/doc/_sources/fix_ave_time.txt index db8e9074cb..b69d17597c 100644 --- a/doc/_sources/fix_ave_time.txt +++ b/doc/_sources/fix_ave_time.txt @@ -23,7 +23,8 @@ Syntax c_ID[I] = Ith component of global vector or Ith column of global array calculated by a compute with ID f_ID = global scalar, vector, or array calculated by a fix with ID f_ID[I] = Ith component of global vector or Ith column of global array calculated by a fix with ID - v_name = global value calculated by an equal-style variable with name + v_name = value(s) calculated by an equal-style or vector-style variable with name + v_name[I] = value calculated by a vector-style variable with name * zero or more keyword/arg pairs may be appended * keyword = *mode* or *file* or *ave* or *start* or *off* or *overwrite* or *title1* or *title2* or *title3* @@ -80,7 +81,7 @@ specified values may represent calculations performed by computes and fixes which store their own "group" definitions. Each listed value can be the result of a :doc:`compute ` or -:doc:`fix ` or the evaluation of an equal-style +:doc:`fix ` or the evaluation of an equal-style or vector-style :doc:`variable `. In each case, the compute, fix, or variable must produce a global quantity, not a per-atom or local quantity. If you wish to spatial- or time-average or histogram per-atom quantities @@ -92,9 +93,9 @@ per-atom quantity into a single global quantity, see the :doc:`compute reduce ` produce global quantities. See the doc pages for individual fixes for info on which ones produce such values. -:doc:`Variables ` of style *equal* are the only ones that can -be used with this fix. Variables of style *atom* cannot be used, -since they produce per-atom values. +:doc:`Variables ` of style *equal* and *vector* are the only +ones that can be used with this fix. Variables of style *atom* cannot +be used, since they produce per-atom values. The input values must either be all scalars or all vectors (or arrays), depending on the setting of the *mode* keyword. In both @@ -176,14 +177,19 @@ which must be compatible with *Nevery*, else an error will result. Users can also write code for their own fix styles and :doc:`add them to LAMMPS `. If a value begins with "v_", a variable name must follow which has -been previously defined in the input script. Variables can only be -used as input for *mode* = scalar. Only equal-style variables can be -referenced. See the :doc:`variable ` command for details. -Note that variables of style *equal* define a formula which can -reference individual atom properties or thermodynamic keywords, or -they can invoke other computes, fixes, or variables when they are -evaluated, so this is a very general means of specifying quantities to -time average. +been previously defined in the input script. If *mode* = scalar, then +only equal-style or vector-style variables can be used, which both +produce global values. In this mode, a vector-style variable requires +a bracketed term to specify the Ith element of the vector calculated +by the variable. If *mode* = vector, then only a vector-style +variable can be used, without a bracketed term. See the +:doc:`variable ` command for details. + +Note that variables of style *equal* and *vector* define a formula +which can reference individual atom properties or thermodynamic +keywords, or they can invoke other computes, fixes, or variables when +they are evaluated, so this is a very general means of specifying +quantities to time average. ---------- diff --git a/doc/_sources/fix_vector.txt b/doc/_sources/fix_vector.txt index 51c4d51798..4fd320ce58 100644 --- a/doc/_sources/fix_vector.txt +++ b/doc/_sources/fix_vector.txt @@ -21,7 +21,8 @@ Syntax c_ID[I] = Ith component of global vector calculated by a compute with ID f_ID = global scalar calculated by a fix with ID f_ID[I] = Ith component of global vector calculated by a fix with ID - v_name = global value calculated by an equal-style variable with name + v_name = value calculated by an equal-style variable with name + v_name[I] = Ith component of vector-style variable with name @@ -60,18 +61,18 @@ specified values may represent calculations performed by computes and fixes which store their own "group" definitions. Each listed value can be the result of a :doc:`compute ` or -:doc:`fix ` or the evaluation of an equal-style +:doc:`fix ` or the evaluation of an equal-style or vector-style :doc:`variable `. In each case, the compute, fix, or variable -must produce a global quantity, not a per-atom or local quantity. -And the global quantity must be a scalar, not a vector or array. +must produce a global quantity, not a per-atom or local quantity. And +the global quantity must be a scalar, not a vector or array. :doc:`Computes ` that produce global quantities are those which do not have the word *atom* in their style name. Only a few :doc:`fixes ` produce global quantities. See the doc pages for individual fixes for info on which ones produce such values. -:doc:`Variables ` of style *equal* are the only ones that can -be used with this fix. Variables of style *atom* cannot be used, -since they produce per-atom values. +:doc:`Variables ` of style *equal* or *vector* are the only +ones that can be used with this fix. Variables of style *atom* cannot +be used, since they produce per-atom values. The *Nevery* argument specifies on what timesteps the input values will be used in order to be stored. Only timesteps that are a @@ -113,13 +114,15 @@ which must be compatible with *Nevery*, else an error will result. Users can also write code for their own fix styles and :doc:`add them to LAMMPS `. If a value begins with "v_", a variable name must follow which has -been previously defined in the input script. Only equal-style -variables can be referenced. See the :doc:`variable ` command -for details. Note that variables of style *equal* define a formula -which can reference individual atom properties or thermodynamic -keywords, or they can invoke other computes, fixes, or variables when -they are evaluated, so this is a very general means of specifying -quantities to be stored by fix vector. +been previously defined in the input script. An equal-style or +vector-style variable can be referenced; the latter requires a +bracketed term to use the Ith element of the vector calculated by the +variable. See the :doc:`variable ` command for details. Note +that variables of style *equal* and *vector* define a formula which +can reference individual atom properties or thermodynamic keywords, or +they can invoke other computes, fixes, or variables when they are +evaluated, so this is a very general means of specifying quantities to +be stored by fix vector. ---------- diff --git a/doc/_sources/thermo_style.txt b/doc/_sources/thermo_style.txt index 0fcaa1c360..ea5c5a8431 100644 --- a/doc/_sources/thermo_style.txt +++ b/doc/_sources/thermo_style.txt @@ -30,7 +30,7 @@ Syntax cella, cellb, cellc, cellalpha, cellbeta, cellgamma, c_ID, c_ID[I], c_ID[I][J], f_ID, f_ID[I], f_ID[I][J], - v_name + v_name, v_name[I] step = timestep elapsed = timesteps since start of this run elaplong = timesteps since start of initial run in a series of runs @@ -78,7 +78,8 @@ Syntax f_ID = global scalar value calculated by a fix with ID f_ID[I] = Ith component of global vector calculated by a fix with ID f_ID[I][J] = I,J component of global array calculated by a fix with ID - v_name = scalar value calculated by an equal-style variable with name + v_name = value calculated by an equal-style variable with name + v_name[I] = value calculated by a vector-style variable with name @@ -348,16 +349,18 @@ option being used. The *v_name* keyword allow the current value of a variable to be 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 variables can be referenced. See the -:doc:`variable ` command for details. Variables of style -*equal* 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. +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. See the :doc:`variable ` command +for details. Variables of style *equal* and *vector* 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 variables are assumed to be "intensive" global -quantities, which are thus printed as-is, without normalization by -thermo_style custom. You can include a division by "natoms" in the -variable formula if this is not the case. +Note that equal-style and vector-style variables are assumed to +produce "intensive" global quantities, which are thus printed as-is, +without normalization by thermo_style custom. You can include a +division by "natoms" in the variable formula if this is not the case. ---------- diff --git a/doc/_sources/variable.txt b/doc/_sources/variable.txt index 24c4116437..773c3559e1 100644 --- a/doc/_sources/variable.txt +++ b/doc/_sources/variable.txt @@ -11,7 +11,7 @@ Syntax variable name style args ... * name = name of variable to define -* style = *delete* or *index* or *loop* or *world* or *universe* or *uloop* or *string* or *format* or *getenv* or *file* or *atomfile* or *python* or *equal* or *atom* +* style = *delete* or *index* or *loop* or *world* or *universe* or *uloop* or *string* or *format* or *getenv* or *file* or *atomfile* or *python* or *equal* or *vector* or *atom* .. parsed-literal:: *delete* = no args @@ -41,7 +41,7 @@ Syntax *file* arg = filename *atomfile* arg = filename *python* arg = function - *equal* or *atom* args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references + *equal* or *vector* or *atom* args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references numbers = 0.0, 100, -5.4, 2.8e-4, etc constants = PI, version, on, off, true, false, yes, no thermo keywords = vol, ke, press, etc from :doc:`thermo_style ` @@ -67,8 +67,8 @@ Syntax feature functions = is_active(category,feature,exact), is_defined(category,id,exact) atom value = id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i] atom vector = id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q - compute references = c_ID, c_ID[i], c_ID[i][j] - fix references = f_ID, f_ID[i], f_ID[i][j] + compute references = c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i] + fix references = f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i] variable references = v_name, v_name[i] @@ -109,15 +109,19 @@ string is assigned to the variable. Variables of style *equal* store a formula which when evaluated produces a single numeric value which can be output either directly (see the :doc:`print `, :doc:`fix print `, and :doc:`run every ` commands) or as part of thermodynamic output (see the :doc:`thermo_style ` -command), or used as input to an averaging fix (see the :doc:`fix ave/time ` command). Variables of style *atom* store -a formula which when evaluated produces one numeric value per atom -which can be output to a dump file (see the :doc:`dump custom ` -command) or used as input to an averaging fix (see the :doc:`fix ave/spatial ` and :doc:`fix ave/atom ` +command), or used as input to an averaging fix (see the :doc:`fix ave/time ` command). Variables of style *vector* +store a formula which produces a vector of such values which can be +used as input to various averaging fixes, or elements of which can be +part of thermodynamic output. Variables of style *atom* store a +formula which when evaluated produces one numeric value per atom which +can be output to a dump file (see the :doc:`dump custom ` command) +or used as input to an averaging fix (see the :doc:`fix ave/chunk ` and :doc:`fix ave/atom ` commands). Variables of style *atomfile* can be used anywhere in an input script that atom-style variables are used; they get their -per-atom values from a file rather than from a formula. Variables can -be hooked to Python functions using code you provide, so that the -variable gets its value from the evaluation of the Python code. +per-atom values from a file rather than from a formula. Variables of +style *python* can be hooked to Python functions using code you +provide, so that the variable gets its value from the evaluation of +the Python code. .. note:: @@ -143,27 +147,27 @@ simulation. .. note:: When the input script line is encountered that defines a - variable of style *equal* or *atom* or *python* that contains a - formula or Python code, the formula is NOT immediately evaluated. It - will be evaluated every time when the variable is **used** instead. If - you simply want to evaluate a formula in place you can use as - so-called. See the section below about "Immediate Evaluation of - Variables" for more details on the topic. This is also true of a - *format* style variable since it evaluates another variable when it is - invoked. + variable of style *equal* or *vector* or *atom* or *python* that + contains a formula or Python code, the formula is NOT immediately + evaluated. It will be evaluated every time when the variable is + **used** instead. If you simply want to evaluate a formula in place you + can use as so-called. See the section below about "Immediate + Evaluation of Variables" for more details on the topic. This is also + true of a *format* style variable since it evaluates another variable + when it is invoked. .. note:: - Variables of style *equal* and *atom* can be used as inputs to - various other LAMMPS commands which evaluate their formulas as needed, - e.g. at different timesteps during a :doc:`run `. Variables of - style *python* can be used in place of an equal-style variable so long - as the associated Python function, as defined by the - :doc:`python ` command, returns a numeric value. Thus any - command that states it can use an equal-style variable as an argument, - can also use such a python-style variable. This means that when the - LAMMPS command evaluates the variable, the Python function will be - executed. + Variables of style *equal* and *vector* and *atom* can be used + as inputs to various other LAMMPS commands which evaluate their + formulas as needed, e.g. at different timesteps during a + :doc:`run `. Variables of style *python* can be used in place of + an equal-style variable so long as the associated Python function, as + defined by the :doc:`python ` command, returns a numeric value. + Thus any command that states it can use an equal-style variable as an + argument, can also use such a python-style variable. This means that + when the LAMMPS command evaluates the variable, the Python function + will be executed. .. note:: @@ -178,12 +182,12 @@ simulation. script. There are two exceptions to this rule. First, variables of style -*string*, *getenv*, *equal*, *atom*, and *python* ARE redefined each -time the command is encountered. This allows these style of variables -to be redefined multiple times in an input script. In a loop, this -means the formula associated with an *equal* or *atom* style variable -can change if it contains a substitution for another variable, e.g. $x -or v_x. +*string*, *getenv*, *equal*, *vector*, *atom*, and *python* ARE +redefined each time the command is encountered. This allows these +style of variables to be redefined multiple times in an input script. +In a loop, this means the formula associated with an *equal* or *atom* +style variable can change if it contains a substitution for another +variable, e.g. $x or v_x. Second, as described below, if a variable is iterated on to the end of its list of strings via the :doc:`next ` command, it is removed @@ -232,8 +236,8 @@ commands before the variable would become exhausted. For example, This section describes how all the various variable styles are defined -and what they store. Except for the *equal* and *atom* styles, -which are explaine in the next section. +and what they store. Except for the *equal* and *vector* and *atom* +styles, which are explained in the next section. Many of the styles store one or more strings. Note that a single string can contain spaces (multiple words), if it is enclosed in @@ -402,31 +406,34 @@ that allows for equal-style variables. ---------- -For the *equal* and *atom* styles, a single string is specified which -represents a formula that will be evaluated afresh each time the -variable is used. If you want spaces in the string, enclose it in -double quotes so the parser will treat it as a single argument. For -*equal* style variables the formula computes a scalar quantity, which -becomes the value of the variable whenever it is evaluated. For -*atom* style variables the formula computes one quantity for each -atom whenever it is evaluated. +For the *equal* and *vector* and *atom* styles, a single string is +specified which represents a formula that will be evaluated afresh +each time the variable is used. If you want spaces in the string, +enclose it in double quotes so the parser will treat it as a single +argument. For *equal*-style variables the formula computes a scalar +quantity, which becomes the value of the variable whenever it is +evaluated. For *vector*-style variables the formula computes a vector +of quantities, which becomes the value of the variable whenever it is +evaluated. For *atom*-style variables the formula computes one +quantity for each atom whenever it is evaluated. -Note that *equal* and *atom* variables can produce different values at -different stages of the input script or at different times during a -run. For example, if an *equal* variable is used in a :doc:`fix print ` command, different values could be printed each -timestep it was invoked. If you want a variable to be evaluated -immediately, so that the result is stored by the variable instead of -the string, see the section below on "Immediate Evaluation of -Variables". +Note that *equal*, *vector*, and *atom* variables can produce +different values at different stages of the input script or at +different times during a run. For example, if an *equal* variable is +used in a :doc:`fix print ` command, different values could +be printed each timestep it was invoked. If you want a variable to be +evaluated immediately, so that the result is stored by the variable +instead of the string, see the section below on "Immediate Evaluation +of Variables". -The next command cannot be used with *equal* or *atom* style -variables, since there is only one string. +The next command cannot be used with *equal* or *vector* or *atom* +style variables, since there is only one string. -The formula for an *equal* or *atom* variable can contain a variety -of quantities. The syntax for each kind of quantity is simple, but -multiple quantities can be nested and combined in various ways to -build up formulas of arbitrary complexity. For example, this is a -valid (though strange) variable formula: +The formula for an *equal*, *vector*, or *atom* variable can contain a +variety of quantities. The syntax for each kind of quantity is +simple, but multiple quantities can be nested and combined in various +ways to build up formulas of arbitrary complexity. For example, this +is a valid (though strange) variable formula: .. parsed-literal:: @@ -460,30 +467,36 @@ references, and references to other variables. +--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Atom vectors | id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q | +--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Compute references | c_ID, c_ID[i], c_ID[i][j] | +| Compute references | c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i] | +--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Fix references | f_ID, f_ID[i], f_ID[i][j] | +| Fix references | f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i] | +--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Other variables | v_name, v_name[i] | +--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -Most of the formula elements produce a scalar value. A few produce a -per-atom vector of values. These are the 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 per-atom vectors do so -element-by-element and produce a per-atom vector. +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. A formula for equal-style variables cannot use any 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. 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 -inlcuded in the formula evaluation. The variable evaluates to 0.0 for -atoms not in the group. +that produces a global or per-atom vector. A formula for a +vector-style variable can use formula elements that produce either a +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. ---------- @@ -583,11 +596,11 @@ Math Functions Math functions are specified as keywords followed by one or more parenthesized arguments "x", "y", "z", each of which can themselves be arbitrarily complex formulas. In this syntax, the arguments can -represent scalar values or per-atom vectors. In the latter case, the -math operation is performed on each element of the vector. For -example, "sqrt(natoms)" is the sqrt() of a scalar, where "sqrt(y*z)" -yields a per-atom vector with each element being the sqrt() of the -product of one atom's y and z coordinates. +represent scalar values or global vectors or per-atom vectors. In the +latter case, the math operation is performed on each element of the +vector. For example, "sqrt(natoms)" is the sqrt() of a scalar, where +"sqrt(y*z)" yields a per-atom vector with each element being the +sqrt() of the product of one atom's y and z coordinates. Most of the math functions perform obvious operations. The ln() is the natural log; log() is the base 10 log. @@ -598,20 +611,22 @@ normal(x,y,z) function also takes 3 arguments: x = mu, y = sigma, and z = seed. It generates a Gaussian variate centered on mu with variance sigma^2. In both cases the seed is used the first time the internal random number generator is invoked, to initialize it. For -equal-style variables, every processor uses the same seed so that they -each generate the same sequence of random numbers. For atom-style -variables, a unique seed is created for each processor, based on the -specified seed. This effectively generates a different random number -for each atom being looped over in the atom-style variable. +equal-style and vector-style variables, every processor uses the same +seed so that they each generate the same sequence of random numbers. +For atom-style variables, a unique seed is created for each processor, +based on the specified seed. This effectively generates a different +random number for each atom being looped over in the atom-style +variable. .. note:: Internally, there is just one random number generator for all - equal-style variables and one for all atom-style variables. If you - define multiple variables (of each style) which use the random() or - normal() math functions, then the internal random number generators - will only be initialized once, which means only one of the specified - seeds will determine the sequence of generated random numbers. + equal-style and vector-style variables and another one for all + atom-style variables. If you define multiple variables (of each + style) which use the random() or normal() math functions, then the + internal random number generators will only be initialized once, which + means only one of the specified seeds will determine the sequence of + generated random numbers. The ceil(), floor(), and round() functions are those in the C math library. Ceil() is the smallest integer not less than its argument. @@ -785,19 +800,21 @@ arguments cannot be formulas themselves. The sum(x), min(x), max(x), ave(x), trap(x), and slope(x) functions each take 1 argument which is of the form "c_ID" or "c_ID[N]" or -"f_ID" or "f_ID[N]". The first two are computes and the second two -are fixes; the ID in the reference should be replaced by the ID of a -compute or fix defined elsewhere in the input script. The compute or -fix must produce either a global vector or array. If it produces a -global vector, then the notation without "[N]" should be used. If -it produces a global array, then the notation with "[N]" should be -used, when N is an integer, to specify which column of the global -array is being referenced. +"f_ID" or "f_ID[N]" or "v_name". The first two are computes and the +second two are fixes; the ID in the reference should be replaced by +the ID of a compute or fix defined elsewhere in the input script. The +compute or fix must produce either a global vector or array. If it +produces a global vector, then the notation without "[N]" should be +used. If it produces a global array, then the notation with "[N]" +should be used, when N is an integer, to specify which column of the +global array is being referenced. The last form of argument "v_name" +is for a vector-style variable where "name" is replaced by the name of +the variable. -These functions operate on the global vector of inputs and reduce it -to a single scalar value. This is analagous to the operation of the -:doc:`compute reduce ` command, which invokes the same -functions on per-atom and local vectors. +These functions operate on a global vector of inputs and reduce it to +a single scalar value. This is analagous to the operation of the +:doc:`compute reduce ` command, which performs similar +operations on per-atom and local vectors. The sum() function calculates the sum of all the vector elements. The min() and max() functions find the minimum and maximum element @@ -935,13 +952,13 @@ Atom values take an integer argument I from 1 to N, where I is the atom-ID, e.g. x[243], which means use the x coordinate of the atom with ID = 243. Or they can take a variable name, specified as v_name, where name is the name of the variable, like x[v_myIndex]. The -variable can be of any style except atom or atom-file variables. The -variable is evaluated and the result is expected to be numeric and is -cast to an integer (i.e. 3.4 becomes 3), to use an an index, which -must be a value from 1 to N. Note that a "formula" cannot be used as -the argument between the brackets, e.g. x[243+10] or -x[v_myIndex+1] are not allowed. To do this a single variable can be -defined that contains the needed formula. +variable can be of any style except *vector* or *atom* or *atomfile* +variables. The variable is evaluated and the result is expected to be +numeric and is cast to an integer (i.e. 3.4 becomes 3), to use an an +index, which must be a value from 1 to N. Note that a "formula" +cannot be used as the argument between the brackets, e.g. x[243+10] +or x[v_myIndex+1] are not allowed. To do this a single variable can +be defined that contains the needed formula. Note that the 0 < atom-ID <= N, where N is the largest atom ID in the system. If an ID is specified for an atom that does not @@ -952,7 +969,7 @@ Atom vectors generate one value per atom, so that a reference like evaluating the variable. The meaning of the different atom values and vectors is mostly -self-explanatory. Mol refers to the molecule ID of an atom, and is +self-explanatory. *Mol* refers to the molecule ID of an atom, and is only defined if an :doc:`atom_style ` is being used that defines molecule IDs. @@ -973,17 +990,21 @@ the ID of a compute defined elsewhere in the input script. As discussed in the doc 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. 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 computes to see what -kind of values they produce. +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. +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. A vector value can be a per-atom vector itself, or a column +of a per-atom array. See the doc pages for individual computes to see +what kind of values they produce. Examples of different kinds of compute references are as follows. -There is no ambiguity as to what a reference means, since computes -only produce global or per-atom quantities, never both. +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. +------------+-------------------------------------------------------------------------------------------------------+ | c_ID | global scalar, or per-atom vector | @@ -993,14 +1014,33 @@ only produce global or per-atom quantities, never both. | c_ID[I][J] | I,J element of global array, or atom I's Jth value in per-atom array | +------------+-------------------------------------------------------------------------------------------------------+ -For I and J, 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. +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. -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 Accuracy". +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: + +.. parsed-literal:: + + variable a vector c_foo*v_myVec + +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. + +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 +Accuracy". ---------- @@ -1024,8 +1064,9 @@ to see what kind of values they produce. 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 no ambiguity as to what a reference means, -since fixes only produce global or per-atom quantities, never both. +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. +------------+-------------------------------------------------------------------------------------------------------+ | f_ID | global scalar, or per-atom vector | @@ -1035,14 +1076,24 @@ since fixes only produce global or per-atom quantities, never both. | f_ID[I][J] | I,J element of global array, or atom I's Jth value in per-atom array | +------------+-------------------------------------------------------------------------------------------------------+ -For I and J, 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. +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. -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". +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]". + +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". Note that some fixes only generate quantities on certain timesteps. If a variable attempts to access the fix on non-allowed timesteps, an @@ -1062,32 +1113,47 @@ variables, which will cause those variables to be evaluated. The name in the reference should be replaced by the name of a variable defined elsewhere in the input script. -As discussed on this doc page, equal-style variables generate a global -scalar numeric value; atom-style and atomfile-style variables generate -a per-atom vector of numeric values; all other variables store a -string. The formula for an equal-style variable can use any style of -variable except an atom-style or atomfile-style (unless only a single -value from the variable is accessed via a subscript). If a -string-storing variable is used, the string is converted to a numeric -value. Note that this will typically produce a 0.0 if the string is -not a numeric string, which is likely not what you want. The formula -for an atom-style variable can use any style of variable, including -other atom-style or atomfile-style variables. +As discussed on this doc page, equal-style variables generate a single +global numeric value, vector-style variables gerarate a vector of +global numeric values, and atom-style and atomfile-style variables +generate a per-atom vector of numeric values. All other variables +store one or more strings. A vector-style variable can be referenced +wtih a + +The formula for an equal-style variable can use any style of variable +including a vector_style or atom-style or atomfile-style. In these +latter cases, a subscript must be used to access a single value from +the vector-, atom-, or atomfile-style variable. If a string-storing +variable is used, the string is converted to a numeric value. Note +that this will typically produce a 0.0 if the string is not a numeric +string, which is likely not what you want. + +The formula for an atom-style variable can use any style of variable, +including other atom-style or atomfile-style variables. + +The formula for an atom-style variable can use any style of variable, +including other atom-style or atomfile-style variables. Examples of different kinds of variable references are as follows. There is no ambiguity as to what a reference means, since variables -produce only a global scalar or a per-atom vector, never both. +produce only a global scalar or global vector or per-atom vector. -+-----------+-----------------------------------+ -| v_name | scalar, or per-atom vector | -+-----------+-----------------------------------+ -| v_name[I] | atom I's value in per-atom vector | -+-----------+-----------------------------------+ ++-----------+----------------------------------------------------------------------+ +| v_name | global scalar from equal-style variable | ++-----------+----------------------------------------------------------------------+ +| v_name | global vector from vector-style variable | ++-----------+----------------------------------------------------------------------+ +| v_name | per-atom vector from atom-style or atomfile-style variable | ++-----------+----------------------------------------------------------------------+ +| v_name[I] | Ith element of a global vector from vector-style variable | ++-----------+----------------------------------------------------------------------+ +| v_name[I] | value of atom with ID = I from atom-style or atomfile-style variable | ++-----------+----------------------------------------------------------------------+ -For I, 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. +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. ---------- @@ -1308,9 +1374,10 @@ Restrictions Indexing any formula element by global atom ID, such as an atom value, -requires the atom style to use a global mapping in order to look up -the vector indices. By default, only atom styles with molecular -information create global maps. The :doc:`atom_modify map ` command can override the default. +requires the :doc:`atom style ` to use a global mapping in +order to look up the vector indices. By default, only atom styles +with molecular information create global maps. The :doc:`atom_modify map ` command can override the default, e.g. for +atomic-style atom styles. All *universe*- and *uloop*-style variables defined in an input script must have the same number of values. diff --git a/doc/compute_slice.html b/doc/compute_slice.html index ae0f2aebd3..5f266a55d0 100644 --- a/doc/compute_slice.html +++ b/doc/compute_slice.html @@ -143,13 +143,14 @@ c_ID[I] = Ith column of global array calculated by a compute with ID f_ID = global vector calculated by a fix with ID f_ID[I] = Ith column of global array calculated by a fix with ID +v_name = vector calculated by an vector-style variable with name

Examples

compute 1 all slice 1 100 10 c_msdmol[4]
-compute 1 all slice 301 400 1 c_msdmol[4]
+compute 1 all slice 301 400 1 c_msdmol[4] v_myVec
@@ -158,9 +159,9 @@ compute 1 all slice 301 400 1 c_msdmol[4]

Define a calculation that “slices” one or more vector inputs into smaller vectors, one per listed input. The inputs can be global quantities; they cannot be per-atom or local quantities. -Computes and fixes may generate any of the -three kinds of quantities. Variables do not generate -global vectors. The group specified with this command is ignored.

+Computes and fixes and vector-style +variables can generate such global quantities. The +group specified with this command is ignored.

The values extracted from the input vector(s) are determined by the Nstart, Nstop, and Nskip parameters. The elements of an input vector of length N are indexed from 1 to N. Starting at element @@ -187,6 +188,14 @@ 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 add them to LAMMPS.

+

If an input value begins with “v_”, a variable name must follow which +has been previously defined in the input script. Only vector-style +variables can be referenced. See the variable command +for details. Note that variables of style vector define a formula +which can reference individual atom properties or thermodynamic +keywords, or they can invoke other computes, fixes, or variables when +they are evaluated, so this is a very general means of specifying +quantities to slice.

If a single input is specified this compute produces a global vector, even if the length of the vector is 1. If multiple inputs are specified, then a global array of values is produced, with the number @@ -201,15 +210,16 @@ These values can be used by any command that uses global vector or array values from a compute as input. See this section for an overview of LAMMPS output options.

The vector or array values calculated by this compute are simply -copies of values generated by computes or fixes that are input vectors -to this compute. If there is a single input vector of intensive -and/or extensive values, then each value in the vector of values -calculated by this compute will be “intensive” or “extensive”, +copies of values generated by computes or fixes or variables that are +input vectors to this compute. If there is a single input vector of +intensive and/or extensive values, then each value in the vector of +values calculated by this compute will be “intensive” or “extensive”, depending on the corresponding input value. If there are multiple input vectors, and all the values in them are intensive, then the array values calculated by this compute are “intensive”. If there are multiple input vectors, and any value in them is extensive, then the -array values calculated by this compute are “extensive”.

+array values calculated by this compute are “extensive”. Values +produced by a variable are treated as intensive.

The vector or array values will be in whatever units the input quantities are in.

diff --git a/doc/compute_slice.txt b/doc/compute_slice.txt index ee832fc374..e89c05a0f9 100644 --- a/doc/compute_slice.txt +++ b/doc/compute_slice.txt @@ -21,22 +21,23 @@ input = c_ID, c_ID\[N\], f_ID, f_ID\[N\] :l c_ID = global vector calculated by a compute with ID c_ID\[I\] = Ith column of global array calculated by a compute with ID f_ID = global vector calculated by a fix with ID - f_ID\[I\] = Ith column of global array calculated by a fix with ID :pre + f_ID\[I\] = Ith column of global array calculated by a fix with ID + v_name = vector calculated by an vector-style variable with name :pre :ule [Examples:] compute 1 all slice 1 100 10 c_msdmol\[4\] -compute 1 all slice 301 400 1 c_msdmol\[4\] :pre +compute 1 all slice 301 400 1 c_msdmol\[4\] v_myVec :pre [Description:] Define a calculation that "slices" one or more vector inputs into smaller vectors, one per listed input. The inputs can be global quantities; they cannot be per-atom or local quantities. -"Computes"_compute.html and "fixes"_fix.html may generate any of the -three kinds of quantities. "Variables"_variable.html do not generate -global vectors. The group specified with this command is ignored. +"Computes"_compute.html and "fixes"_fix.html and vector-style +"variables"_variable.html can generate such global quantities. The +group specified with this command is ignored. The values extracted from the input vector(s) are determined by the {Nstart}, {Nstop}, and {Nskip} parameters. The elements of an input @@ -70,6 +71,15 @@ 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 "add them to LAMMPS"_Section_modify.html. +If an input value begins with "v_", a variable name must follow which +has been previously defined in the input script. Only vector-style +variables can be referenced. See the "variable"_variable.html command +for details. Note that variables of style {vector} define a formula +which can reference individual atom properties or thermodynamic +keywords, or they can invoke other computes, fixes, or variables when +they are evaluated, so this is a very general means of specifying +quantities to slice. + If a single input is specified this compute produces a global vector, even if the length of the vector is 1. If multiple inputs are specified, then a global array of values is produced, with the number @@ -89,15 +99,16 @@ section"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The vector or array values calculated by this compute are simply -copies of values generated by computes or fixes that are input vectors -to this compute. If there is a single input vector of intensive -and/or extensive values, then each value in the vector of values -calculated by this compute will be "intensive" or "extensive", +copies of values generated by computes or fixes or variables that are +input vectors to this compute. If there is a single input vector of +intensive and/or extensive values, then each value in the vector of +values calculated by this compute will be "intensive" or "extensive", depending on the corresponding input value. If there are multiple input vectors, and all the values in them are intensive, then the array values calculated by this compute are "intensive". If there are multiple input vectors, and any value in them is extensive, then the -array values calculated by this compute are "extensive". +array values calculated by this compute are "extensive". Values +produced by a variable are treated as intensive. The vector or array values will be in whatever "units"_units.html the input quantities are in. diff --git a/doc/fix_ave_correlate.html b/doc/fix_ave_correlate.html index 87a5eb82c1..a5de6b1dc3 100644 --- a/doc/fix_ave_correlate.html +++ b/doc/fix_ave_correlate.html @@ -145,6 +145,7 @@ c_ID[I] = Ith component of global vector calculated by a compute with ID f_ID = global scalar calculated by a fix with ID f_ID[I] = Ith component of global vector calculated by a fix with ID v_name = global value calculated by an equal-style variable with name +v_name[I] = Ith component of a vector-style variable with name -

The array values calculated by this fix are treated as “intensive”. -If you need to divide them by the number of atoms, you must do this in -a later processing step, e.g. when using them in a +

The array values calculated by this fix are treated as intensive. If +you need to divide them by the number of atoms, you must do this in a +later processing step, e.g. when using them in a variable.

No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

diff --git a/doc/fix_ave_correlate.txt b/doc/fix_ave_correlate.txt index 6ad218c464..2394185b5d 100644 --- a/doc/fix_ave_correlate.txt +++ b/doc/fix_ave_correlate.txt @@ -23,7 +23,8 @@ value = c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :l c_ID\[I\] = Ith component of global vector calculated by a compute with ID f_ID = global scalar calculated by a fix with ID f_ID\[I\] = Ith component of global vector calculated by a fix with ID - v_name = global value calculated by an equal-style variable with name :pre + v_name = global value calculated by an equal-style variable with name + v_name\[I\] = Ith component of a vector-style variable with name :pre zero or more keyword/arg pairs may be appended :l keyword = {type} or {ave} or {start} or {prefactor} or {file} or {overwrite} or {title1} or {title2} or {title3} :l @@ -77,23 +78,23 @@ specified values may represent calculations performed by computes and fixes which store their own "group" definitions. Each listed value can be the result of a "compute"_compute.html or -"fix"_fix.html or the evaluation of an equal-style +"fix"_fix.html or the evaluation of an equal-style or vector-style "variable"_variable.html. In each case, the compute, fix, or variable must produce a global quantity, not a per-atom or local quantity. If you wish to spatial- or time-average or histogram per-atom quantities from a compute, fix, or variable, then see the "fix ave/spatial"_fix_ave_spatial.html, "fix ave/atom"_fix_ave_atom.html, -or "fix ave/histo"_fix_ave_histo.html commands. If you wish to sum a -per-atom quantity into a single global quantity, see the "compute -reduce"_compute_reduce.html command. +or "fix ave/histo"_fix_ave_histo.html commands. If you wish to +convert a per-atom quantity into a single global value, see the +"compute reduce"_compute_reduce.html command. "Computes"_compute.html that produce global quantities are those which do not have the word {atom} in their style name. Only a few "fixes"_fix.html produce global quantities. See the doc pages for individual fixes for info on which ones produce such values. -"Variables"_variable.html of style {equal} are the only ones that can -be used with this fix. Variables of style {atom} cannot be used, -since they produce per-atom values. +"Variables"_variable.html of style {equal} and {vector} are the only +ones that can be used with this fix. Variables of style {atom} cannot +be used, since they produce per-atom values. The input values must either be all scalars. What kinds of correlations between input values are calculated is determined by the @@ -164,9 +165,11 @@ Users can also write code for their own fix styles and "add them to LAMMPS"_Section_modify.html. If a value begins with "v_", a variable name must follow which has -been previously defined in the input script. Only equal-style -variables can be referenced. See the "variable"_variable.html command -for details. Note that variables of style {equal} define a formula +been previously defined in the input script. Only equal-style or +vector-style variables can be referenced; the latter requires a +bracketed term to specify the Ith element of the vector calculated by +the variable. See the "variable"_variable.html command for details. +Note that variables of style {equal} or {vector} define a formula which can reference individual atom properties or thermodynamic keywords, or they can invoke other computes, fixes, or variables when they are evaluated, so this is a very general means of specifying @@ -314,9 +317,9 @@ For {type} = {full}, the Npair = N^2 columns are ordered: C11, C12, ..., C1N, C21, C22, ..., C2N, C31, ..., C3N, ..., CN1, ..., CNN-1, CNN. :l,ule -The array values calculated by this fix are treated as "intensive". -If you need to divide them by the number of atoms, you must do this in -a later processing step, e.g. when using them in a +The array values calculated by this fix are treated as intensive. If +you need to divide them by the number of atoms, you must do this in a +later processing step, e.g. when using them in a "variable"_variable.html. No parameter of this fix can be used with the {start/stop} keywords of diff --git a/doc/fix_ave_histo.html b/doc/fix_ave_histo.html index 50bbffaeec..d7f35da086 100644 --- a/doc/fix_ave_histo.html +++ b/doc/fix_ave_histo.html @@ -150,7 +150,8 @@ c_ID = scalar or vector calculated by a compute with ID c_ID[I] = Ith component of vector or Ith column of array calculated by a compute with ID f_ID = scalar or vector calculated by a fix with ID f_ID[I] = Ith component of vector or Ith column of array calculated by a fix with ID -v_name = value(s) calculated by an equal-style or atom-style variable with name +v_name = value(s) calculated by an equal-style or vector-style or atom-style variable with name +v_name[I] = value calculated by a vector-style variable with name - + - +
awpmd/cutmeam/sw/spline mgpt
quip
morse/smooth/linearquip reax/c smd/hertzsmd/tlsph
smd/triangulated/surface
smd/tlsphsmd/triangulated/surface smd/ulsph smtbqsph/heatconduction
sph/idealgas
sph/heatconductionsph/idealgas sph/lj sph/rhosumsph/taitwater
sph/taitwater/morris
sph/taitwatersph/taitwater/morris srp tersoff/table (o)thole
tip4p/long/soft (o) 
tholetip4p/long/soft (o)    
id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q
Compute referencesc_ID, c_ID[i], c_ID[i][j]c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i]
Fix referencesf_ID, f_ID[i], f_ID[i][j]f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i]
Other variables v_name, v_name[i]
-

Most of the formula elements produce a scalar value. A few produce a -per-atom vector of values. These are the 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 per-atom vectors do so -element-by-element and produce a per-atom vector.

+

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.

A formula for equal-style variables cannot use any 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. Atom-style variables are evaluated by other commands -that define a group on which they operate, e.g. a -dump or compute or fix command. -When they invoke the atom-style variable, only atoms in the group are -inlcuded in the formula evaluation. The variable evaluates to 0.0 for -atoms not in the group.

+that produces a global or per-atom vector. A formula for a +vector-style variable can use formula elements that produce either a +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 +group on which they operate, e.g. a dump or +compute or 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.

Numers, constants, and thermo keywords

@@ -654,11 +667,11 @@ to the compute redu

Math functions are specified as keywords followed by one or more parenthesized arguments “x”, “y”, “z”, each of which can themselves be arbitrarily complex formulas. In this syntax, the arguments can -represent scalar values or per-atom vectors. In the latter case, the -math operation is performed on each element of the vector. For -example, “sqrt(natoms)” is the sqrt() of a scalar, where “sqrt(y*z)” -yields a per-atom vector with each element being the sqrt() of the -product of one atom’s y and z coordinates.

+represent scalar values or global vectors or per-atom vectors. In the +latter case, the math operation is performed on each element of the +vector. For example, “sqrt(natoms)” is the sqrt() of a scalar, where +“sqrt(y*z)” yields a per-atom vector with each element being the +sqrt() of the product of one atom’s y and z coordinates.

Most of the math functions perform obvious operations. The ln() is the natural log; log() is the base 10 log.

The random(x,y,z) function takes 3 arguments: x = lo, y = hi, and z = @@ -667,19 +680,21 @@ normal(x,y,z) function also takes 3 arguments: x = mu, y = sigma, and z = seed. It generates a Gaussian variate centered on mu with variance sigma^2. In both cases the seed is used the first time the internal random number generator is invoked, to initialize it. For -equal-style variables, every processor uses the same seed so that they -each generate the same sequence of random numbers. For atom-style -variables, a unique seed is created for each processor, based on the -specified seed. This effectively generates a different random number -for each atom being looped over in the atom-style variable.

+equal-style and vector-style variables, every processor uses the same +seed so that they each generate the same sequence of random numbers. +For atom-style variables, a unique seed is created for each processor, +based on the specified seed. This effectively generates a different +random number for each atom being looped over in the atom-style +variable.

Note

Internally, there is just one random number generator for all -equal-style variables and one for all atom-style variables. If you -define multiple variables (of each style) which use the random() or -normal() math functions, then the internal random number generators -will only be initialized once, which means only one of the specified -seeds will determine the sequence of generated random numbers.

+equal-style and vector-style variables and another one for all +atom-style variables. If you define multiple variables (of each +style) which use the random() or normal() math functions, then the +internal random number generators will only be initialized once, which +means only one of the specified seeds will determine the sequence of +generated random numbers.

The ceil(), floor(), and round() functions are those in the C math library. Ceil() is the smallest integer not less than its argument. @@ -821,18 +836,20 @@ inclusion is that it be in the region.

arguments cannot be formulas themselves.

The sum(x), min(x), max(x), ave(x), trap(x), and slope(x) functions each take 1 argument which is of the form “c_ID” or “c_ID[N]” or -“f_ID” or “f_ID[N]”. The first two are computes and the second two -are fixes; the ID in the reference should be replaced by the ID of a -compute or fix defined elsewhere in the input script. The compute or -fix must produce either a global vector or array. If it produces a -global vector, then the notation without “[N]” should be used. If -it produces a global array, then the notation with “[N]” should be -used, when N is an integer, to specify which column of the global -array is being referenced.

-

These functions operate on the global vector of inputs and reduce it -to a single scalar value. This is analagous to the operation of the -compute reduce command, which invokes the same -functions on per-atom and local vectors.

+“f_ID” or “f_ID[N]” or “v_name”. The first two are computes and the +second two are fixes; the ID in the reference should be replaced by +the ID of a compute or fix defined elsewhere in the input script. The +compute or fix must produce either a global vector or array. If it +produces a global vector, then the notation without “[N]” should be +used. If it produces a global array, then the notation with “[N]” +should be used, when N is an integer, to specify which column of the +global array is being referenced. The last form of argument “v_name” +is for a vector-style variable where “name” is replaced by the name of +the variable.

+

These functions operate on a global vector of inputs and reduce it to +a single scalar value. This is analagous to the operation of the +compute reduce command, which performs similar +operations on per-atom and local vectors.

The sum() function calculates the sum of all the vector elements. The min() and max() functions find the minimum and maximum element respectively. The ave() function is the same as sum() except that it @@ -945,13 +962,13 @@ active suffixes is tried before reporting failure.

atom-ID, e.g. x[243], which means use the x coordinate of the atom with ID = 243. Or they can take a variable name, specified as v_name, where name is the name of the variable, like x[v_myIndex]. The -variable can be of any style except atom or atom-file variables. The -variable is evaluated and the result is expected to be numeric and is -cast to an integer (i.e. 3.4 becomes 3), to use an an index, which -must be a value from 1 to N. Note that a “formula” cannot be used as -the argument between the brackets, e.g. x[243+10] or -x[v_myIndex+1] are not allowed. To do this a single variable can be -defined that contains the needed formula.

+variable can be of any style except vector or atom or atomfile +variables. The variable is evaluated and the result is expected to be +numeric and is cast to an integer (i.e. 3.4 becomes 3), to use an an +index, which must be a value from 1 to N. Note that a “formula” +cannot be used as the argument between the brackets, e.g. x[243+10] +or x[v_myIndex+1] are not allowed. To do this a single variable can +be defined that contains the needed formula.

Note that the 0 < atom-ID <= N, where N is the largest atom ID in the system. If an ID is specified for an atom that does not currently exist, then the generated value is 0.0.

@@ -959,7 +976,7 @@ currently exist, then the generated value is 0.0.

“vx” means the x-component of each atom’s velocity will be used when evaluating the variable.

The meaning of the different atom values and vectors is mostly -self-explanatory. Mol refers to the molecule ID of an atom, and is +self-explanatory. Mol refers to the molecule ID of an atom, and is only defined if an atom_style is being used that defines molecule IDs.

Note that many other atom attributes can be used as inputs to a @@ -975,16 +992,19 @@ the ID of a compute defined elsewhere in the input script. As discussed in the doc page for the 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. 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 computes to see what -kind of values they produce.

+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. +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. A vector value can be a per-atom vector itself, or a column +of a per-atom array. See the doc pages for individual computes to see +what kind of values they produce.

Examples of different kinds of compute references are as follows. -There is no ambiguity as to what a reference means, since computes -only produce global or per-atom quantities, never both.

+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.

@@ -1002,13 +1022,29 @@ only produce global or per-atom quantities, never both.

-

For I and J, 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.

-

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 Accuracy”.

+

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.

+

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:

+
variable a vector c_foo*v_myVec
+
+
+

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.

+

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 +Accuracy”.

@@ -1027,8 +1063,9 @@ column of an per-atom array. See the doc pages for individual fixes to see what kind of values they produce.

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 no ambiguity as to what a reference means, -since fixes only produce global or per-atom quantities, never both.

+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.

@@ -1046,13 +1083,22 @@ since fixes only produce global or per-atom quantities, never both.

-

For I and J, 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.

-

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”.

+

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.

+

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]”.

+

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”.

Note that some fixes only generate quantities on certain timesteps. If a variable attempts to access the fix on non-allowed timesteps, an error is generated. For example, the fix ave/time @@ -1066,38 +1112,53 @@ the doc pages for individual fix commands for details.

variables, which will cause those variables to be evaluated. The name in the reference should be replaced by the name of a variable defined elsewhere in the input script.

-

As discussed on this doc page, equal-style variables generate a global -scalar numeric value; atom-style and atomfile-style variables generate -a per-atom vector of numeric values; all other variables store a -string. The formula for an equal-style variable can use any style of -variable except an atom-style or atomfile-style (unless only a single -value from the variable is accessed via a subscript). If a -string-storing variable is used, the string is converted to a numeric -value. Note that this will typically produce a 0.0 if the string is -not a numeric string, which is likely not what you want. The formula -for an atom-style variable can use any style of variable, including -other atom-style or atomfile-style variables.

+

As discussed on this doc page, equal-style variables generate a single +global numeric value, vector-style variables gerarate a vector of +global numeric values, and atom-style and atomfile-style variables +generate a per-atom vector of numeric values. All other variables +store one or more strings. A vector-style variable can be referenced +wtih a

+

The formula for an equal-style variable can use any style of variable +including a vector_style or atom-style or atomfile-style. In these +latter cases, a subscript must be used to access a single value from +the vector-, atom-, or atomfile-style variable. If a string-storing +variable is used, the string is converted to a numeric value. Note +that this will typically produce a 0.0 if the string is not a numeric +string, which is likely not what you want.

+

The formula for an atom-style variable can use any style of variable, +including other atom-style or atomfile-style variables.

+

The formula for an atom-style variable can use any style of variable, +including other atom-style or atomfile-style variables.

Examples of different kinds of variable references are as follows. There is no ambiguity as to what a reference means, since variables -produce only a global scalar or a per-atom vector, never both.

+produce only a global scalar or global vector or per-atom vector.

--++ - + + + + + + + - + + + +
v_namescalar, or per-atom vectorglobal scalar from equal-style variable
v_nameglobal vector from vector-style variable
v_nameper-atom vector from atom-style or atomfile-style variable
v_name[I]atom I’s value in per-atom vectorIth element of a global vector from vector-style variable
v_name[I]value of atom with ID = I from atom-style or atomfile-style variable
-

For I, 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.

+

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.

Immediate Evaluation of Variables:

If you want an equal-style variable to be evaluated immediately, it @@ -1275,9 +1336,10 @@ print "Final potential energy = $e"

Restrictions

Indexing any formula element by global atom ID, such as an atom value, -requires the atom style to use a global mapping in order to look up -the vector indices. By default, only atom styles with molecular -information create global maps. The atom_modify map command can override the default.

+requires the atom style to use a global mapping in +order to look up the vector indices. By default, only atom styles +with molecular information create global maps. The atom_modify map command can override the default, e.g. for +atomic-style atom styles.

All universe- and uloop-style variables defined in an input script must have the same number of values.

diff --git a/doc/variable.txt b/doc/variable.txt index 7525871c42..3df9b561b7 100644 --- a/doc/variable.txt +++ b/doc/variable.txt @@ -13,7 +13,7 @@ variable command :h3 variable name style args ... :pre name = name of variable to define :ulb,l -style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {string} or {format} or {getenv} or {file} or {atomfile} or {python} or {equal} or {atom} :l +style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {string} or {format} or {getenv} or {file} or {atomfile} or {python} or {equal} or {vector} or {atom} :l {delete} = no args {index} args = one or more strings {loop} args = N @@ -41,7 +41,7 @@ style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {st {file} arg = filename {atomfile} arg = filename {python} arg = function - {equal} or {atom} args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references + {equal} or {vector} or {atom} args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references numbers = 0.0, 100, -5.4, 2.8e-4, etc constants = PI, version, on, off, true, false, yes, no thermo keywords = vol, ke, press, etc from "thermo_style"_thermo_style.html @@ -67,8 +67,8 @@ style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {st feature functions = is_active(category,feature,exact), is_defined(category,id,exact) atom value = id\[i\], mass\[i\], type\[i\], mol\[i\], x\[i\], y\[i\], z\[i\], vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\], q\[i\] atom vector = id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q - compute references = c_ID, c_ID\[i\], c_ID\[i\]\[j\] - fix references = f_ID, f_ID\[i\], f_ID\[i\]\[j\] + compute references = c_ID, c_ID\[i\], c_ID\[i\]\[j\], C_ID, C_ID\[i\] + fix references = f_ID, f_ID\[i\], f_ID\[i\]\[j\], F_ID, F_ID\[i\] variable references = v_name, v_name\[i\] :pre :ule @@ -106,16 +106,20 @@ can be output either directly (see the "print"_print.html, "fix print"_fix_print.html, and "run every"_run.html commands) or as part of thermodynamic output (see the "thermo_style"_thermo_style.html command), or used as input to an averaging fix (see the "fix -ave/time"_fix_ave_time.html command). Variables of style {atom} store -a formula which when evaluated produces one numeric value per atom -which can be output to a dump file (see the "dump custom"_dump.html -command) or used as input to an averaging fix (see the "fix -ave/spatial"_fix_ave_spatial.html and "fix ave/atom"_fix_ave_atom.html +ave/time"_fix_ave_time.html command). Variables of style {vector} +store a formula which produces a vector of such values which can be +used as input to various averaging fixes, or elements of which can be +part of thermodynamic output. Variables of style {atom} store a +formula which when evaluated produces one numeric value per atom which +can be output to a dump file (see the "dump custom"_dump.html command) +or used as input to an averaging fix (see the "fix +ave/chunk"_fix_ave_chunk.html and "fix ave/atom"_fix_ave_atom.html commands). Variables of style {atomfile} can be used anywhere in an input script that atom-style variables are used; they get their -per-atom values from a file rather than from a formula. Variables can -be hooked to Python functions using code you provide, so that the -variable gets its value from the evaluation of the Python code. +per-atom values from a file rather than from a formula. Variables of +style {python} can be hooked to Python functions using code you +provide, so that the variable gets its value from the evaluation of +the Python code. NOTE: As discussed in "Section 3.2"_Section_commands.html#cmd_2 of the manual, an input script can use "immediate" variables, specified as @@ -137,25 +141,25 @@ different values when it is evaluated at different times during a simulation. NOTE: When the input script line is encountered that defines a -variable of style {equal} or {atom} or {python} that contains a -formula or Python code, the formula is NOT immediately evaluated. It -will be evaluated every time when the variable is [used] instead. If -you simply want to evaluate a formula in place you can use as -so-called. See the section below about "Immediate Evaluation of -Variables" for more details on the topic. This is also true of a -{format} style variable since it evaluates another variable when it is -invoked. +variable of style {equal} or {vector} or {atom} or {python} that +contains a formula or Python code, the formula is NOT immediately +evaluated. It will be evaluated every time when the variable is +[used] instead. If you simply want to evaluate a formula in place you +can use as so-called. See the section below about "Immediate +Evaluation of Variables" for more details on the topic. This is also +true of a {format} style variable since it evaluates another variable +when it is invoked. -NOTE: Variables of style {equal} and {atom} can be used as inputs to -various other LAMMPS commands which evaluate their formulas as needed, -e.g. at different timesteps during a "run"_run.html. Variables of -style {python} can be used in place of an equal-style variable so long -as the associated Python function, as defined by the -"python"_python.html command, returns a numeric value. Thus any -command that states it can use an equal-style variable as an argument, -can also use such a python-style variable. This means that when the -LAMMPS command evaluates the variable, the Python function will be -executed. +NOTE: Variables of style {equal} and {vector} and {atom} can be used +as inputs to various other LAMMPS commands which evaluate their +formulas as needed, e.g. at different timesteps during a +"run"_run.html. Variables of style {python} can be used in place of +an equal-style variable so long as the associated Python function, as +defined by the "python"_python.html command, returns a numeric value. +Thus any command that states it can use an equal-style variable as an +argument, can also use such a python-style variable. This means that +when the LAMMPS command evaluates the variable, the Python function +will be executed. NOTE: When a variable command is encountered in the input script and the variable name has already been specified, the command is ignored. @@ -168,12 +172,12 @@ will override a corresponding index variable setting in the input script. There are two exceptions to this rule. First, variables of style -{string}, {getenv}, {equal}, {atom}, and {python} ARE redefined each -time the command is encountered. This allows these style of variables -to be redefined multiple times in an input script. In a loop, this -means the formula associated with an {equal} or {atom} style variable -can change if it contains a substitution for another variable, e.g. $x -or v_x. +{string}, {getenv}, {equal}, {vector}, {atom}, and {python} ARE +redefined each time the command is encountered. This allows these +style of variables to be redefined multiple times in an input script. +In a loop, this means the formula associated with an {equal} or {atom} +style variable can change if it contains a substitution for another +variable, e.g. $x or v_x. Second, as described below, if a variable is iterated on to the end of its list of strings via the "next"_next.html command, it is removed @@ -216,8 +220,8 @@ variable a delete :pre :line This section describes how all the various variable styles are defined -and what they store. Except for the {equal} and {atom} styles, -which are explaine in the next section. +and what they store. Except for the {equal} and {vector} and {atom} +styles, which are explained in the next section. Many of the styles store one or more strings. Note that a single string can contain spaces (multiple words), if it is enclosed in @@ -380,32 +384,34 @@ that allows for equal-style variables. :line -For the {equal} and {atom} styles, a single string is specified which -represents a formula that will be evaluated afresh each time the -variable is used. If you want spaces in the string, enclose it in -double quotes so the parser will treat it as a single argument. For -{equal} style variables the formula computes a scalar quantity, which -becomes the value of the variable whenever it is evaluated. For -{atom} style variables the formula computes one quantity for each -atom whenever it is evaluated. +For the {equal} and {vector} and {atom} styles, a single string is +specified which represents a formula that will be evaluated afresh +each time the variable is used. If you want spaces in the string, +enclose it in double quotes so the parser will treat it as a single +argument. For {equal}-style variables the formula computes a scalar +quantity, which becomes the value of the variable whenever it is +evaluated. For {vector}-style variables the formula computes a vector +of quantities, which becomes the value of the variable whenever it is +evaluated. For {atom}-style variables the formula computes one +quantity for each atom whenever it is evaluated. -Note that {equal} and {atom} variables can produce different values at -different stages of the input script or at different times during a -run. For example, if an {equal} variable is used in a "fix -print"_fix_print.html command, different values could be printed each -timestep it was invoked. If you want a variable to be evaluated -immediately, so that the result is stored by the variable instead of -the string, see the section below on "Immediate Evaluation of -Variables". +Note that {equal}, {vector}, and {atom} variables can produce +different values at different stages of the input script or at +different times during a run. For example, if an {equal} variable is +used in a "fix print"_fix_print.html command, different values could +be printed each timestep it was invoked. If you want a variable to be +evaluated immediately, so that the result is stored by the variable +instead of the string, see the section below on "Immediate Evaluation +of Variables". -The next command cannot be used with {equal} or {atom} style -variables, since there is only one string. +The next command cannot be used with {equal} or {vector} or {atom} +style variables, since there is only one string. -The formula for an {equal} or {atom} variable can contain a variety -of quantities. The syntax for each kind of quantity is simple, but -multiple quantities can be nested and combined in various ways to -build up formulas of arbitrary complexity. For example, this is a -valid (though strange) variable formula: +The formula for an {equal}, {vector}, or {atom} variable can contain a +variety of quantities. The syntax for each kind of quantity is +simple, but multiple quantities can be nested and combined in various +ways to build up formulas of arbitrary complexity. For example, this +is a valid (though strange) variable formula: variable x equal "pe + c_MyTemp / vol^(1/3)" :pre @@ -440,27 +446,33 @@ Special functions: sum(x), min(x), max(x), ave(x), trap(x), \ Atom values: id\[i\], mass\[i\], type\[i\], mol\[i\], x\[i\], y\[i\], z\[i\], \ vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\], q\[i\] Atom vectors: id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q -Compute references: c_ID, c_ID\[i\], c_ID\[i\]\[j\] -Fix references: f_ID, f_ID\[i\], f_ID\[i\]\[j\] +Compute references: c_ID, c_ID\[i\], c_ID\[i\]\[j\], C_ID, C_ID\[i\] +Fix references: f_ID, f_ID\[i\], f_ID\[i\]\[j\], F_ID, F_ID\[i\] Other variables: v_name, v_name\[i\] :tb(s=:) -Most of the formula elements produce a scalar value. A few produce a -per-atom vector of values. These are the 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 per-atom vectors do so -element-by-element and produce a per-atom vector. +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. A formula for equal-style variables cannot use any 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. Atom-style variables are evaluated by other commands -that define a "group"_group.html on which they operate, e.g. a -"dump"_dump.html or "compute"_compute.html or "fix"_fix.html command. -When they invoke the atom-style variable, only atoms in the group are -inlcuded in the formula evaluation. The variable evaluates to 0.0 for -atoms not in the group. +that produces a global or per-atom vector. A formula for a +vector-style variable can use formula elements that produce either a +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 +"group"_group.html on which they operate, e.g. a "dump"_dump.html or +"compute"_compute.html or "fix"_fix.html 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. :line @@ -547,11 +559,11 @@ Math Functions :h4 Math functions are specified as keywords followed by one or more parenthesized arguments "x", "y", "z", each of which can themselves be arbitrarily complex formulas. In this syntax, the arguments can -represent scalar values or per-atom vectors. In the latter case, the -math operation is performed on each element of the vector. For -example, "sqrt(natoms)" is the sqrt() of a scalar, where "sqrt(y*z)" -yields a per-atom vector with each element being the sqrt() of the -product of one atom's y and z coordinates. +represent scalar values or global vectors or per-atom vectors. In the +latter case, the math operation is performed on each element of the +vector. For example, "sqrt(natoms)" is the sqrt() of a scalar, where +"sqrt(y*z)" yields a per-atom vector with each element being the +sqrt() of the product of one atom's y and z coordinates. Most of the math functions perform obvious operations. The ln() is the natural log; log() is the base 10 log. @@ -562,18 +574,20 @@ normal(x,y,z) function also takes 3 arguments: x = mu, y = sigma, and z = seed. It generates a Gaussian variate centered on mu with variance sigma^2. In both cases the seed is used the first time the internal random number generator is invoked, to initialize it. For -equal-style variables, every processor uses the same seed so that they -each generate the same sequence of random numbers. For atom-style -variables, a unique seed is created for each processor, based on the -specified seed. This effectively generates a different random number -for each atom being looped over in the atom-style variable. +equal-style and vector-style variables, every processor uses the same +seed so that they each generate the same sequence of random numbers. +For atom-style variables, a unique seed is created for each processor, +based on the specified seed. This effectively generates a different +random number for each atom being looped over in the atom-style +variable. NOTE: Internally, there is just one random number generator for all -equal-style variables and one for all atom-style variables. If you -define multiple variables (of each style) which use the random() or -normal() math functions, then the internal random number generators -will only be initialized once, which means only one of the specified -seeds will determine the sequence of generated random numbers. +equal-style and vector-style variables and another one for all +atom-style variables. If you define multiple variables (of each +style) which use the random() or normal() math functions, then the +internal random number generators will only be initialized once, which +means only one of the specified seeds will determine the sequence of +generated random numbers. The ceil(), floor(), and round() functions are those in the C math library. Ceil() is the smallest integer not less than its argument. @@ -727,19 +741,21 @@ arguments cannot be formulas themselves. The sum(x), min(x), max(x), ave(x), trap(x), and slope(x) functions each take 1 argument which is of the form "c_ID" or "c_ID\[N\]" or -"f_ID" or "f_ID\[N\]". The first two are computes and the second two -are fixes; the ID in the reference should be replaced by the ID of a -compute or fix defined elsewhere in the input script. The compute or -fix must produce either a global vector or array. If it produces a -global vector, then the notation without "\[N\]" should be used. If -it produces a global array, then the notation with "\[N\]" should be -used, when N is an integer, to specify which column of the global -array is being referenced. +"f_ID" or "f_ID\[N\]" or "v_name". The first two are computes and the +second two are fixes; the ID in the reference should be replaced by +the ID of a compute or fix defined elsewhere in the input script. The +compute or fix must produce either a global vector or array. If it +produces a global vector, then the notation without "\[N\]" should be +used. If it produces a global array, then the notation with "\[N\]" +should be used, when N is an integer, to specify which column of the +global array is being referenced. The last form of argument "v_name" +is for a vector-style variable where "name" is replaced by the name of +the variable. -These functions operate on the global vector of inputs and reduce it -to a single scalar value. This is analagous to the operation of the -"compute reduce"_compute_reduce.html command, which invokes the same -functions on per-atom and local vectors. +These functions operate on a global vector of inputs and reduce it to +a single scalar value. This is analagous to the operation of the +"compute reduce"_compute_reduce.html command, which performs similar +operations on per-atom and local vectors. The sum() function calculates the sum of all the vector elements. The min() and max() functions find the minimum and maximum element @@ -867,13 +883,13 @@ Atom values take an integer argument I from 1 to N, where I is the atom-ID, e.g. x\[243\], which means use the x coordinate of the atom with ID = 243. Or they can take a variable name, specified as v_name, where name is the name of the variable, like x\[v_myIndex\]. The -variable can be of any style except atom or atom-file variables. The -variable is evaluated and the result is expected to be numeric and is -cast to an integer (i.e. 3.4 becomes 3), to use an an index, which -must be a value from 1 to N. Note that a "formula" cannot be used as -the argument between the brackets, e.g. x\[243+10\] or -x\[v_myIndex+1\] are not allowed. To do this a single variable can be -defined that contains the needed formula. +variable can be of any style except {vector} or {atom} or {atomfile} +variables. The variable is evaluated and the result is expected to be +numeric and is cast to an integer (i.e. 3.4 becomes 3), to use an an +index, which must be a value from 1 to N. Note that a "formula" +cannot be used as the argument between the brackets, e.g. x\[243+10\] +or x\[v_myIndex+1\] are not allowed. To do this a single variable can +be defined that contains the needed formula. Note that the 0 < atom-ID <= N, where N is the largest atom ID in the system. If an ID is specified for an atom that does not @@ -884,7 +900,7 @@ Atom vectors generate one value per atom, so that a reference like evaluating the variable. The meaning of the different atom values and vectors is mostly -self-explanatory. Mol refers to the molecule ID of an atom, and is +self-explanatory. {Mol} refers to the molecule ID of an atom, and is only defined if an "atom_style"_atom_style.html is being used that defines molecule IDs. @@ -903,30 +919,51 @@ the ID of a compute defined elsewhere in the input script. As discussed in the doc page for the "compute"_compute.html 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. 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 computes to see what -kind of values they produce. +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. +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. A vector value can be a per-atom vector itself, or a column +of a per-atom array. See the doc pages for individual computes to see +what kind of values they produce. Examples of different kinds of compute references are as follows. -There is no ambiguity as to what a reference means, since computes -only produce global or per-atom quantities, never both. +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. 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 :tb(s=:) -For I and J, 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. +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. -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 Accuracy". +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: + +variable a vector c_foo*v_myVec :pre + +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. + +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 +Accuracy". :line @@ -947,21 +984,32 @@ to see what kind of values they produce. 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 no ambiguity as to what a reference means, -since fixes only produce global or per-atom quantities, never both. +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. 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 :tb(s=:) -For I and J, 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. +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. -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". +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\]". + +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". Note that some fixes only generate quantities on certain timesteps. If a variable attempts to access the fix on non-allowed timesteps, an @@ -978,29 +1026,41 @@ variables, which will cause those variables to be evaluated. The name in the reference should be replaced by the name of a variable defined elsewhere in the input script. -As discussed on this doc page, equal-style variables generate a global -scalar numeric value; atom-style and atomfile-style variables generate -a per-atom vector of numeric values; all other variables store a -string. The formula for an equal-style variable can use any style of -variable except an atom-style or atomfile-style (unless only a single -value from the variable is accessed via a subscript). If a -string-storing variable is used, the string is converted to a numeric -value. Note that this will typically produce a 0.0 if the string is -not a numeric string, which is likely not what you want. The formula -for an atom-style variable can use any style of variable, including -other atom-style or atomfile-style variables. +As discussed on this doc page, equal-style variables generate a single +global numeric value, vector-style variables gerarate a vector of +global numeric values, and atom-style and atomfile-style variables +generate a per-atom vector of numeric values. All other variables +store one or more strings. A vector-style variable can be referenced +wtih a + +The formula for an equal-style variable can use any style of variable +including a vector_style or atom-style or atomfile-style. In these +latter cases, a subscript must be used to access a single value from +the vector-, atom-, or atomfile-style variable. If a string-storing +variable is used, the string is converted to a numeric value. Note +that this will typically produce a 0.0 if the string is not a numeric +string, which is likely not what you want. + +The formula for an atom-style variable can use any style of variable, +including other atom-style or atomfile-style variables. + +The formula for an atom-style variable can use any style of variable, +including other atom-style or atomfile-style variables. Examples of different kinds of variable references are as follows. There is no ambiguity as to what a reference means, since variables -produce only a global scalar or a per-atom vector, never both. +produce only a global scalar or global vector or per-atom vector. -v_name: scalar, or per-atom vector -v_name\[I\]: atom I's value in per-atom vector :tb(s=:) +v_name: global scalar from equal-style variable +v_name: global vector from vector-style variable +v_name: per-atom vector from atom-style or atomfile-style variable +v_name\[I\]: Ith element of a global vector from vector-style variable +v_name\[I\]: value of atom with ID = I from atom-style or atomfile-style variable :tb(s=:) -For I, 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. +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. :line @@ -1204,10 +1264,11 @@ print "Final potential energy = $e" :pre [Restrictions:] Indexing any formula element by global atom ID, such as an atom value, -requires the atom style to use a global mapping in order to look up -the vector indices. By default, only atom styles with molecular -information create global maps. The "atom_modify -map"_atom_modify.html command can override the default. +requires the "atom style"_atom_style.html to use a global mapping in +order to look up the vector indices. By default, only atom styles +with molecular information create global maps. The "atom_modify +map"_atom_modify.html command can override the default, e.g. for +atomic-style atom styles. All {universe}- and {uloop}-style variables defined in an input script must have the same number of values.