From d5334c038fc749f9c45dd1e66dd68f0985b3fc42 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Wed, 9 Dec 2009 21:20:59 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@3513 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/compute.html | 120 +++++++++++++++++++-------- doc/compute.txt | 118 +++++++++++++++++++-------- doc/compute_reduce.html | 86 +++++++++++++------- doc/compute_reduce.txt | 86 +++++++++++++------- doc/fix.html | 105 ++++++++++++++++++------ doc/fix.txt | 103 +++++++++++++++++------ doc/fix_ave_atom.html | 55 +++++++------ doc/fix_ave_atom.txt | 55 +++++++------ doc/fix_ave_spatial.html | 84 ++++++++++++------- doc/fix_ave_spatial.txt | 85 ++++++++++++------- doc/thermo_style.html | 100 +++++++++++------------ doc/thermo_style.txt | 100 +++++++++++------------ doc/variable.html | 170 +++++++++++++++++++++----------------- doc/variable.txt | 171 +++++++++++++++++++++------------------ 14 files changed, 890 insertions(+), 548 deletions(-) diff --git a/doc/compute.html b/doc/compute.html index beca436ef9..af262457a9 100644 --- a/doc/compute.html +++ b/doc/compute.html @@ -28,40 +28,90 @@ compute 3 all ke/atom

Description:

-

Create a computation that will be performed on a group of atoms. +

Define a computation that will be performed on a group of atoms. Quantities calculated by a compute are instantaneous values, meaning they are calculated from information about atoms on the current -timestep or iteration. There are two kinds of computes, "global" -computes that calculate one or more values for the entire group of -atoms, and "per-atom" computes that calculate one or more values for -each atom in the group. The latter has the word "atom" in its style -name. -

-

In LAMMPS, a "compute" can be used in several ways. The results of -global computes can be output via the thermo_style -custom or fix ave/time command. -Or the values can be referenced in a variable equal or -variable atom command. The results of computes that -calculate a global temperature or pressure can be used by fixes that -do thermostatting or barostatting and when atom velocities are -created. -

-

The results of per-atom computes that calculate a per-atom vector or -array can be output via the dump custom command or the -fix ave/spatial command. Or the per-atom -values can be time-averaged via the fix ave/atom -command and then output via the dump custom or fix -ave/spatial commands. Or the per-atom values -can be referenced in a variable atom command. Note -that the value of per-atom computes will be 0.0 for atoms not in the -specified compute group. -

-

See this howto section for a summary of -various LAMMPS output options, many of which involve computes. +timestep or iteration, though a compute may internally store some +information about a previous state of the system.

The ID of a compute can only contain alphanumeric characters and underscores.

+
+ +

Computes calculate one of three styles of quantities: global, +per-atom, or local. A global quantity is one or more system-wide +values, e.g. the temperature of the system. A per-atom quantity is +one or more values per atom, e.g. the kinetic energy of each atom. +Per-atom values are set to 0.0 for atoms not in the specified compute +group. Local quantities are calculated by each processor based on the +atoms it owns, but there may be zero or more per atom, e.g. a list of +bond distances. Computes that produce per-atom quantities have the +word "atom" in their style, e.g. ke/atom. Computes that produce +local quantities have the word "local" in their style, +e.g. bond/local. Styles with neither "atom" or "local" in their +style produce global quantities. +

+

Note that a single compute produces either global or per-atom or local +quantities, but never more than one of these. +

+

Global, per-atom, and local quantities each come in three kinds: a +single scalar value, a vector of values, or a 2d array of values. The +doc page for each compute describes the style and kind of values it +produces, e.g. a per-atom vector. Some computes produce more than one +kind of a single style, e.g. a global scalar and a global vector. +

+

When a compute quantity is accessed, as in many of the output commands +discussed below, it can be referenced via the following bracket +notation, where ID is the ID of the compute: +

+
+ + +
c_ID entire scalar, vector, or array
c_ID[I] one element of vector, one column of array
c_ID[I][J] one element of array +
+ +

In other words, using one bracket reduces the dimension of the +quantity once (vector -> scalar, array -> vector). Using two brackets +reduces the dimension twice (array -> scalar). Thus a command that +uses scalar compute values as input can also process elements of a +vector or array. +

+

Note that commands and variables which use compute +quantities typically do not allow for all kinds, e.g. a command may +require a vector of values, not a scalar. This means there is no +ambiguity about referring to a compute quantity as c_ID even if it +produces, for example, both a scalar and vector. The doc pages for +various commands explain the details. +

+
+ +

In LAMMPS, the values generated by a compute can be used in several +ways: +

+ +

See this howto section for a summary of +various LAMMPS output options, many of which involve computes. +

The results of computes that calculate global quantities can be either "intensive" or "extensive" values. Intensive means the value is independent of the number of atoms in the simulation, @@ -74,7 +124,9 @@ compute value is accessed in another way, e.g. by a intensive or extensive value. See the doc page for individual computes for further info.

-

LAMMPS creates its own global computes for thermodynamic output. +

+ +

LAMMPS creates its own computes internally for thermodynamic output. Three computes are always created, named "thermo_temp", "thermo_press", and "thermo_pe", as if these commands had been invoked in the input script: @@ -91,10 +143,10 @@ style requires it. See the documentation for the or barostatting, may also create computes. These are discussed in the documentation for specific fix commands.

-

In all these cases, the default computes can be replaced by computes -defined by the user in the input script, as described by the -thermo_modify and fix modify -commands. +

In all these cases, the default computes LAMMPS creates can be +replaced by computes defined by the user in the input script, as +described by the thermo_modify and fix +modify commands.

Properties of either a default or user-defined compute can be modified via the compute_modify command. @@ -105,6 +157,8 @@ via the compute_modify command. section of the manual) and the results of their calculations accessed in the various ways described above.

+
+

Each compute style has its own doc page which describes its arguments and what it does. Here is an alphabetic list of compute styles available in LAMMPS: diff --git a/doc/compute.txt b/doc/compute.txt index b834ccfba6..ebda6a834f 100644 --- a/doc/compute.txt +++ b/doc/compute.txt @@ -25,40 +25,88 @@ compute 3 all ke/atom :pre [Description:] -Create a computation that will be performed on a group of atoms. +Define a computation that will be performed on a group of atoms. Quantities calculated by a compute are instantaneous values, meaning they are calculated from information about atoms on the current -timestep or iteration. There are two kinds of computes, "global" -computes that calculate one or more values for the entire group of -atoms, and "per-atom" computes that calculate one or more values for -each atom in the group. The latter has the word "atom" in its style -name. - -In LAMMPS, a "compute" can be used in several ways. The results of -global computes can be output via the "thermo_style -custom"_thermo_style.html or "fix ave/time"_fix_ave_time.html command. -Or the values can be referenced in a "variable equal"_variable.html or -"variable atom"_variable.html command. The results of computes that -calculate a global temperature or pressure can be used by fixes that -do thermostatting or barostatting and when atom velocities are -created. - -The results of per-atom computes that calculate a per-atom vector or -array can be output via the "dump custom"_dump.html command or the -"fix ave/spatial"_fix_ave_spatial.html command. Or the per-atom -values can be time-averaged via the "fix ave/atom"_fix_ave_atom.html -command and then output via the "dump custom"_dump.html or "fix -ave/spatial"_fix_ave_spatial.html commands. Or the per-atom values -can be referenced in a "variable atom"_variable.html command. Note -that the value of per-atom computes will be 0.0 for atoms not in the -specified compute group. - -See this "howto section"_Section_howto.html#4_15 for a summary of -various LAMMPS output options, many of which involve computes. +timestep or iteration, though a compute may internally store some +information about a previous state of the system. The ID of a compute can only contain alphanumeric characters and underscores. +:line + +Computes calculate one of three styles of quantities: global, +per-atom, or local. A global quantity is one or more system-wide +values, e.g. the temperature of the system. A per-atom quantity is +one or more values per atom, e.g. the kinetic energy of each atom. +Per-atom values are set to 0.0 for atoms not in the specified compute +group. Local quantities are calculated by each processor based on the +atoms it owns, but there may be zero or more per atom, e.g. a list of +bond distances. Computes that produce per-atom quantities have the +word "atom" in their style, e.g. {ke/atom}. Computes that produce +local quantities have the word "local" in their style, +e.g. {bond/local}. Styles with neither "atom" or "local" in their +style produce global quantities. + +Note that a single compute produces either global or per-atom or local +quantities, but never more than one of these. + +Global, per-atom, and local quantities each come in three kinds: a +single scalar value, a vector of values, or a 2d array of values. The +doc page for each compute describes the style and kind of values it +produces, e.g. a per-atom vector. Some computes produce more than one +kind of a single style, e.g. a global scalar and a global vector. + +When a compute quantity is accessed, as in many of the output commands +discussed below, it can be referenced via the following bracket +notation, where ID is the ID of the compute: + +c_ID | entire scalar, vector, or array +c_ID\[I\] | one element of vector, one column of array +c_ID\[I\]\[J\] | one element of array :tb(s=|) + +In other words, using one bracket reduces the dimension of the +quantity once (vector -> scalar, array -> vector). Using two brackets +reduces the dimension twice (array -> scalar). Thus a command that +uses scalar compute values as input can also process elements of a +vector or array. + +Note that commands and "variables"_variable.html which use compute +quantities typically do not allow for all kinds, e.g. a command may +require a vector of values, not a scalar. This means there is no +ambiguity about referring to a compute quantity as c_ID even if it +produces, for example, both a scalar and vector. The doc pages for +various commands explain the details. + +:line + +In LAMMPS, the values generated by a compute can be used in several +ways: + +The results of computes that calculate a global temperature or +pressure can be used by fixes that do thermostatting or barostatting +or when atom velocities are created. :ulb,l + +Global values can be output via the "thermo_style +custom"_thermo_style.html or "fix ave/time"_fix_ave_time.html command. +Or the values can be referenced in a "variable equal"_variable.html or +"variable atom"_variable.html command. :l + +Per-atom values can be output via the "dump custom"_dump.html command +or the "fix ave/spatial"_fix_ave_spatial.html command. Or they can be +time-averaged via the "fix ave/atom"_fix_ave_atom.html command or +reduced by the "compute reduce"_compute_reduce.html command. Or the +per-atom values can be referenced in an "atom-style +variable"_variable.html. :l + +Local values can be reduced by the "compute +reduce"_compute_reduce.html command, or histogrammed by the "fix +ave/histo"_fix_ave_histo.html command. :l,ule + +See this "howto section"_Section_howto.html#4_15 for a summary of +various LAMMPS output options, many of which involve computes. + The results of computes that calculate global quantities can be either "intensive" or "extensive" values. Intensive means the value is independent of the number of atoms in the simulation, @@ -71,7 +119,9 @@ compute value is accessed in another way, e.g. by a intensive or extensive value. See the doc page for individual computes for further info. -LAMMPS creates its own global computes for thermodynamic output. +:line + +LAMMPS creates its own computes internally for thermodynamic output. Three computes are always created, named "thermo_temp", "thermo_press", and "thermo_pe", as if these commands had been invoked in the input script: @@ -88,10 +138,10 @@ Fixes that calculate temperature or pressure, i.e. for thermostatting or barostatting, may also create computes. These are discussed in the documentation for specific "fix"_fix.html commands. -In all these cases, the default computes can be replaced by computes -defined by the user in the input script, as described by the -"thermo_modify"_thermo_modify.html and "fix modify"_fix_modify.html -commands. +In all these cases, the default computes LAMMPS creates can be +replaced by computes defined by the user in the input script, as +described by the "thermo_modify"_thermo_modify.html and "fix +modify"_fix_modify.html commands. Properties of either a default or user-defined compute can be modified via the "compute_modify"_compute_modify.html command. @@ -102,6 +152,8 @@ Code for new computes can be added to LAMMPS (see "this section"_Section_modify.html of the manual) and the results of their calculations accessed in the various ways described above. +:line + Each compute style has its own doc page which describes its arguments and what it does. Here is an alphabetic list of compute styles available in LAMMPS: diff --git a/doc/compute_reduce.html b/doc/compute_reduce.html index 6970993bca..b9036bab4a 100644 --- a/doc/compute_reduce.html +++ b/doc/compute_reduce.html @@ -25,17 +25,17 @@ reduce/region arg = region-ID region-ID = ID of region to use for choosing atoms -

  • mode = sum or min or max +
  • mode = sum or min or max or ave
  • one or more inputs can be listed
  • input = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID[N], f_ID, f_ID[N], v_name 
      x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force component)
-  c_ID = per-atom vector value calculated by a compute with ID
-  c_ID[N] = Nth column of per-atom array calculated by a compute with ID
-  f_ID = per-atom vector value calculated by a fix with ID
-  f_ID[N] = Nth column of per-atom array calculated by a fix with ID
+  c_ID = vector calculated by a compute with ID
+  c_ID[I] = Ith column of array calculated by a compute with ID
+  f_ID = vector calculated by a fix with ID
+  f_ID[I] = Ith column of array calculated by a fix with ID
   v_name = per-atom vector calculated by an atom-style variable with name
    @@ -48,37 +48,63 @@ compute 2 all reduce min c_press2 f_ave v_myKE

    Description:

    -

    Define a calculation that "reduces" one or more per-atom inputs across -all atoms in the group to yield a single global scalar for each listed -input. If the compute reduce/region command is used, the selection of -atoms is limited to atoms in the region as well as in the group. +

    Define a calculation that "reduces" one or more vector inputs into +scalar values, one per listed input. The inputs can be global, +per-atom, or local quantities. Atom attributes are per-atom +quantities, computes and fixes may generate +any of the three kinds of quantities, and atom-style +variables generate per-atom quantities.

    The reduction operation is specified by the mode setting. The sum -option adds the per-atom quantities into a global total. The min or -max options find the minimum or maximum value across all per-atom -quantities. +option adds the values in the vector into a global total. The min +or max options find the minimum or maximum value across all vector +values. The ave setting adds the vector values into a global total, +then divides by the number of values in the vector.

    -

    Each listed input is operated on independently. The group specified -with the command means only atoms within the group contribute to the -result. If the compute reduce/region command is used, the atoms must -also be within the region. Note that the input that produces the -per-atom quantities may define its own group which affects the -quantities it returns. For example, if a per-atom compute is used as -an input, it will generate values of 0.0 for atoms that are not in the +

    Each listed input is operated on independently. For per-atom inputs, +the group specified with this command means only atoms within the +group contribute to the result. For per-atom inputs, if the compute +reduce/region command is used, the atoms must also currently be within +the region. Note that an input that produces per-atom quantities may +define its own group which affects the quantities it returns. For +example, if a compute is used as an input which generates a per-atom +vector, it will generate values of 0.0 for atoms that are not in the group specified for that compute.

    Each listed input can be an atom attribute (position, velocity, force component) or can be the result of a compute or fix or the evaluation of an atom-style -variable. In the latter cases, the compute, fix, or -variable must produce per-atom quantities, not a global quantity. +variable.

    -

    Computes that produce per-atom quantities are those -which have the word atom in their style name. See the doc pages for -individual fixes to determine which ones produce per-atom -quantities. Variables of style atom are the only -ones that can be used with this compute since all other variable -styles produce global quantities. +

    Atom attributes are per-atom inputs. +

    +

    If a value begins with "c_", a compute ID must follow which has been +previously defined in the input script. Computes can generate global, +per-atom, or local quantities. See the individual +compute doc page for details. If no bracketed integer +is appended, the vector calculated by the compute is used. If a +bracketed interger is appended, the Ith column of the array calculated +by the compute is used. Users can also write code for their own +compute styles and add them to LAMMPS. +

    +

    If a value begins with "f_", a fix ID must follow which has been +previously defined in the input script. Fixes can generate global, +per-atom, or local quantities. See the individual fix doc +page for details. Note that some fixes only produce their values on +certain timesteps, which must be compatible with when compute reduce +references the values, else an error results. If no bracketed integer +is appended, the vector calculated by the fix is used. If a bracketed +integer is appended, the Ith column of the array calculated by the fix +is used. Users can also write code for their own fix style and add +them to LAMMPS. +

    +

    If a value begins with "v_", a variable name must follow which has +been previously defined in the input script. It must be an +atom-style variable. Atom-style variables can +reference thermodynamic keywords and various per-atom attributes, or +invoke other computes, fixes, or variables when they are evaluated, so +this is a very general means of generating per-atom quantities to +reduce.

    If a single input is specified this compute produces a global scalar value. If multiple inputs are specified, this compute produces a @@ -97,15 +123,15 @@ divides by the appropriate atom count.

    This compute calculates a global scalar or global vector of length N where N is the number of inputs, and which can be accessed by indices -1-6. These values can be used by any command that uses global scalar +1-N. These values can be used by any command that uses global scalar or vector values from a compute as input. See this section for an overview of LAMMPS output options.

    For sum mode, the scalar and vector values calculated by this compute are "extensive", meaning they scale with the number of atoms -in the simulation. For min and max modes, the value(s) are -intensive. +in the simulation. For min or max or ave modes, the value(s) +are intensive.

    Restrictions: none

    diff --git a/doc/compute_reduce.txt b/doc/compute_reduce.txt index e7e208653b..90069cc284 100644 --- a/doc/compute_reduce.txt +++ b/doc/compute_reduce.txt @@ -18,14 +18,14 @@ style = {reduce} or {reduce/region} :l {reduce} arg = none {reduce/region} arg = region-ID region-ID = ID of region to use for choosing atoms :pre -mode = {sum} or {min} or {max} :l +mode = {sum} or {min} or {max} or {ave} :l one or more inputs can be listed :l input = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :l x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force component) - c_ID = per-atom vector value calculated by a compute with ID - c_ID\[N\] = Nth column of per-atom array calculated by a compute with ID - f_ID = per-atom vector value calculated by a fix with ID - f_ID\[N\] = Nth column of per-atom array calculated by a fix with ID + c_ID = vector calculated by a compute with ID + c_ID\[I\] = Ith column of array calculated by a compute with ID + f_ID = vector calculated by a fix with ID + f_ID\[I\] = Ith column of array calculated by a fix with ID v_name = per-atom vector calculated by an atom-style variable with name :pre :ule @@ -37,37 +37,63 @@ compute 2 all reduce min c_press[2] f_ave v_myKE :pre [Description:] -Define a calculation that "reduces" one or more per-atom inputs across -all atoms in the group to yield a single global scalar for each listed -input. If the compute reduce/region command is used, the selection of -atoms is limited to atoms in the region as well as in the group. +Define a calculation that "reduces" one or more vector inputs into +scalar values, one per listed input. The inputs can be global, +per-atom, or local quantities. Atom attributes are per-atom +quantities, "computes"_compute.html and "fixes"_fix.html may generate +any of the three kinds of quantities, and "atom-style +variables"_variable.html generate per-atom quantities. The reduction operation is specified by the {mode} setting. The {sum} -option adds the per-atom quantities into a global total. The {min} or -{max} options find the minimum or maximum value across all per-atom -quantities. +option adds the values in the vector into a global total. The {min} +or {max} options find the minimum or maximum value across all vector +values. The {ave} setting adds the vector values into a global total, +then divides by the number of values in the vector. -Each listed input is operated on independently. The group specified -with the command means only atoms within the group contribute to the -result. If the compute reduce/region command is used, the atoms must -also be within the region. Note that the input that produces the -per-atom quantities may define its own group which affects the -quantities it returns. For example, if a per-atom compute is used as -an input, it will generate values of 0.0 for atoms that are not in the +Each listed input is operated on independently. For per-atom inputs, +the group specified with this command means only atoms within the +group contribute to the result. For per-atom inputs, if the compute +reduce/region command is used, the atoms must also currently be within +the region. Note that an input that produces per-atom quantities may +define its own group which affects the quantities it returns. For +example, if a compute is used as an input which generates a per-atom +vector, it will generate values of 0.0 for atoms that are not in the group specified for that compute. Each listed input can be an atom attribute (position, velocity, force component) or can be the result of a "compute"_compute.html or "fix"_fix.html or the evaluation of an atom-style -"variable"_variable.html. In the latter cases, the compute, fix, or -variable must produce per-atom quantities, not a global quantity. +"variable"_variable.html. -"Computes"_compute.html that produce per-atom quantities are those -which have the word {atom} in their style name. See the doc pages for -individual "fixes"_fix.html to determine which ones produce per-atom -quantities. "Variables"_variable.html of style {atom} are the only -ones that can be used with this compute since all other variable -styles produce global quantities. +Atom attributes are per-atom inputs. + +If a value begins with "c_", a compute ID must follow which has been +previously defined in the input script. Computes can generate global, +per-atom, or local quantities. See the individual +"compute"_compute.html doc page for details. If no bracketed integer +is appended, the vector calculated by the compute is used. If a +bracketed interger is appended, the Ith column of the array calculated +by the compute is used. Users can also write code for their own +compute styles and "add them to LAMMPS"_Section_modify.html. + +If a value begins with "f_", a fix ID must follow which has been +previously defined in the input script. Fixes can generate global, +per-atom, or local quantities. See the individual "fix"_fix.html doc +page for details. Note that some fixes only produce their values on +certain timesteps, which must be compatible with when compute reduce +references the values, else an error results. If no bracketed integer +is appended, the vector calculated by the fix is used. If a bracketed +integer is appended, the Ith column of the array calculated by the fix +is used. Users can also write code for their own fix style and "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. It must be an +"atom-style variable"_variable.html. Atom-style variables can +reference thermodynamic keywords and various per-atom attributes, or +invoke other computes, fixes, or variables when they are evaluated, so +this is a very general means of generating per-atom quantities to +reduce. If a single input is specified this compute produces a global scalar value. If multiple inputs are specified, this compute produces a @@ -86,15 +112,15 @@ divides by the appropriate atom count. This compute calculates a global scalar or global vector of length N where N is the number of inputs, and which can be accessed by indices -1-6. These values can be used by any command that uses global scalar +1-N. These values can be used by any command that uses global scalar or vector values from a compute as input. See "this section"_Section_howto.html#4_15 for an overview of LAMMPS output options. For {sum} mode, the scalar and vector values calculated by this compute are "extensive", meaning they scale with the number of atoms -in the simulation. For {min} and {max} modes, the value(s) are -intensive. +in the simulation. For {min} or {max} or {ave} modes, the value(s) +are intensive. [Restrictions:] none diff --git a/doc/fix.html b/doc/fix.html index 57f5b0753e..4f64038390 100644 --- a/doc/fix.html +++ b/doc/fix.html @@ -66,31 +66,6 @@ made to the old fix via the fix_modify command.

    The fix modify command allows settings for some fixes to be reset. See the doc page for individual fixes for details.

    -

    Some fixes calculate a global scalar or vector quantity which can be -accessed by various commands for output, including equal- and -atom-style variables, thermo_style -custom, and fix ave/time. -

    -

    Some fixes calculate a per-atom vector or array quantity which can be -accessed by various commands for output, including atom-style -variables, dump_style custom, and fix -ave/spatial. -

    -

    The results of fixes that calculate global quantities can be either -"intensive" or "extensive" values. Intensive means the value is -independent of the number of atoms in the simulation, e.g. timestep -size. Extensive means the value scales with the number of atoms in -the simulation, e.g. total force applied by the fix. Thermodynamic -output will normalize extensive values depending on -the "thermo_modify norm" setting. But if a fix value is accessed in -another way, e.g. by a variable, you may need to know -whether it is an intensive or extensive value. See the doc page for -individual fixes for further info. -

    -

    See this howto section for a summary of -various LAMMPS output options. See the doc pages for individual fixes -for info on which ones calculate these quantities. -

    Some fixes store an internal "state" which is written to binary restart files via the restart or write_restart commands. This allows the fix to @@ -99,6 +74,86 @@ continue on with its calculations in a restarted simulation. See the a fix in an input script that reads a restart file. See the doc pages for individual fixes for info on which ones can be restarted.

    +
    + +

    Some fixes calculate one of three styles of quantities: global, +per-atom, or local, which can be used by other commands or output as +described below. A global quantity is one or more system-wide values, +e.g. the energy of a wall interacting with particles. A per-atom +quantity is one or more values per atom, e.g. the displacement vector +for each atom since time 0. Per-atom values are set to 0.0 for atoms +not in the specified fix group. Local quantities are calculated by +each processor based on the atoms it owns, but there may be zero or +more per atoms. +

    +

    Note that a single fix may produces either global or per-atom or local +quantities (or none at all), but never more than one of these. +

    +

    Global, per-atom, and local quantities each come in three kinds: a +single scalar value, a vector of values, or a 2d array of values. The +doc page for each fix describes the style and kind of values it +produces, e.g. a per-atom vector. Some fixes produce more than one +kind of a single style, e.g. a global scalar and a global vector. +

    +

    When a fix quantity is accessed, as in many of the output commands +discussed below, it can be referenced via the following bracket +notation, where ID is the ID of the fix: +

    +
    + + +
    f_ID entire scalar, vector, or array
    f_ID[I] one element of vector, one column of array
    f_ID[I][J] one element of array +
    + +

    In other words, using one bracket reduces the dimension of the +quantity once (vector -> scalar, array -> vector). Using two brackets +reduces the dimension twice (array -> scalar). Thus a command that +uses scalar fix values as input can also process elements of a vector +or array. +

    +

    Note that commands and variables which use fix +quantities typically do not allow for all kinds, e.g. a command may +require a vector of values, not a scalar. This means there is no +ambiguity about referring to a fix quantity as f_ID even if it +produces, for example, both a scalar and vector. The doc pages for +various commands explain the details. +

    +
    + +

    In LAMMPS, the values generated by a fix can be used in several ways: +

    + +

    See this howto section for a summary of +various LAMMPS output options, many of which involve fixes. +

    +

    The results of fixes that calculate global quantities can be either +"intensive" or "extensive" values. Intensive means the value is +independent of the number of atoms in the simulation, +e.g. temperature. Extensive means the value scales with the number of +atoms in the simulation, e.g. total rotational kinetic energy. +Thermodynamic output will normalize extensive +values depending on the "thermo_modify norm" setting. But if a fix +value is accessed in another way, e.g. by a variable, +you may need to know whether it is an intensive or extensive value. +See the doc page for individual fixes for further info. +

    +
    +

    Each fix style has its own documentation page which describes its arguments and what it does, as listed below. Here is an alphabetic list of fix styles available in LAMMPS: diff --git a/doc/fix.txt b/doc/fix.txt index fb9cf4722e..1423ef2f5c 100644 --- a/doc/fix.txt +++ b/doc/fix.txt @@ -63,31 +63,6 @@ made to the old fix via the "fix_modify"_fix_modify.html command. The "fix modify"_fix_modify.html command allows settings for some fixes to be reset. See the doc page for individual fixes for details. -Some fixes calculate a global scalar or vector quantity which can be -accessed by various commands for output, including "equal- and -atom-style variables"_variable.html, "thermo_style -custom"_thermo_style.html, and "fix ave/time"_fix_ave_time.html. - -Some fixes calculate a per-atom vector or array quantity which can be -accessed by various commands for output, including "atom-style -variables"_variable.html, "dump_style custom"_dump.html, and "fix -ave/spatial"_fix_ave_spatial.html. - -The results of fixes that calculate global quantities can be either -"intensive" or "extensive" values. Intensive means the value is -independent of the number of atoms in the simulation, e.g. timestep -size. Extensive means the value scales with the number of atoms in -the simulation, e.g. total force applied by the fix. "Thermodynamic -output"_thermo_style.html will normalize extensive values depending on -the "thermo_modify norm" setting. But if a fix value is accessed in -another way, e.g. by a "variable"_variable.html, you may need to know -whether it is an intensive or extensive value. See the doc page for -individual fixes for further info. - -See this "howto section"_Section_howto.html#4_15 for a summary of -various LAMMPS output options. See the doc pages for individual fixes -for info on which ones calculate these quantities. - Some fixes store an internal "state" which is written to binary restart files via the "restart"_restart.html or "write_restart"_write_restart.html commands. This allows the fix to @@ -96,6 +71,84 @@ continue on with its calculations in a restarted simulation. See the a fix in an input script that reads a restart file. See the doc pages for individual fixes for info on which ones can be restarted. +:line + +Some fixes calculate one of three styles of quantities: global, +per-atom, or local, which can be used by other commands or output as +described below. A global quantity is one or more system-wide values, +e.g. the energy of a wall interacting with particles. A per-atom +quantity is one or more values per atom, e.g. the displacement vector +for each atom since time 0. Per-atom values are set to 0.0 for atoms +not in the specified fix group. Local quantities are calculated by +each processor based on the atoms it owns, but there may be zero or +more per atoms. + +Note that a single fix may produces either global or per-atom or local +quantities (or none at all), but never more than one of these. + +Global, per-atom, and local quantities each come in three kinds: a +single scalar value, a vector of values, or a 2d array of values. The +doc page for each fix describes the style and kind of values it +produces, e.g. a per-atom vector. Some fixes produce more than one +kind of a single style, e.g. a global scalar and a global vector. + +When a fix quantity is accessed, as in many of the output commands +discussed below, it can be referenced via the following bracket +notation, where ID is the ID of the fix: + +f_ID | entire scalar, vector, or array +f_ID\[I\] | one element of vector, one column of array +f_ID\[I\]\[J\] | one element of array :tb(s=|) + +In other words, using one bracket reduces the dimension of the +quantity once (vector -> scalar, array -> vector). Using two brackets +reduces the dimension twice (array -> scalar). Thus a command that +uses scalar fix values as input can also process elements of a vector +or array. + +Note that commands and "variables"_variable.html which use fix +quantities typically do not allow for all kinds, e.g. a command may +require a vector of values, not a scalar. This means there is no +ambiguity about referring to a fix quantity as f_ID even if it +produces, for example, both a scalar and vector. The doc pages for +various commands explain the details. + +:line + +In LAMMPS, the values generated by a fix can be used in several ways: + +Global values can be output via the "thermo_style +custom"_thermo_style.html or "fix ave/time"_fix_ave_time.html command. +Or the values can be referenced in a "variable equal"_variable.html or +"variable atom"_variable.html command. :ulb,l + +Per-atom values can be output via the "dump custom"_dump.html command +or the "fix ave/spatial"_fix_ave_spatial.html command. Or they can be +time-averaged via the "fix ave/atom"_fix_ave_atom.html command or +reduced by the "compute reduce"_compute_reduce.html command. Or the +per-atom values can be referenced in an "atom-style +variable"_variable.html. :l + +Local values can be reduced by the "compute +reduce"_compute_reduce.html command, or histogrammed by the "fix +ave/histo"_fix_ave_histo.html command. :l,ule + +See this "howto section"_Section_howto.html#4_15 for a summary of +various LAMMPS output options, many of which involve fixes. + +The results of fixes that calculate global quantities can be either +"intensive" or "extensive" values. Intensive means the value is +independent of the number of atoms in the simulation, +e.g. temperature. Extensive means the value scales with the number of +atoms in the simulation, e.g. total rotational kinetic energy. +"Thermodynamic output"_thermo_style.html will normalize extensive +values depending on the "thermo_modify norm" setting. But if a fix +value is accessed in another way, e.g. by a "variable"_variable.html, +you may need to know whether it is an intensive or extensive value. +See the doc page for individual fixes for further info. + +:line + Each fix style has its own documentation page which describes its arguments and what it does, as listed below. Here is an alphabetic list of fix styles available in LAMMPS: diff --git a/doc/fix_ave_atom.html b/doc/fix_ave_atom.html index a0c232f1b6..3436e8b520 100644 --- a/doc/fix_ave_atom.html +++ b/doc/fix_ave_atom.html @@ -27,13 +27,13 @@

  • one or more values can be listed -
  • value = x, y, z, xu, yu, zu, vx, vy, vz, fx, fy, fz, c_ID, c_ID[N], f_ID, f_ID[N], v_name +
  • value = x, y, z, xu, yu, zu, vx, vy, vz, fx, fy, fz, c_ID, c_ID[i], f_ID, f_ID[i], v_name 
      x,y,z,xu,yu,zu,vx,vy,vz,fx,fy,fz = atom attribute (position, unwrapped position, velocity, force component)
-  c_ID = per-atom vector value calculated by a compute with ID
-  c_ID[N] = Nth column of per-atom array calculated by a compute with ID
-  f_ID = per-atom vector value calculated by a fix with ID
-  f_ID[N] = Nth column of per-atom array calculated by a fix with ID
+  c_ID = per-atom vector calculated by a compute with ID
+  c_ID[I] = Ith column of per-atom array calculated by a compute with ID
+  f_ID = per-atom vector calculated by a fix with ID
+  f_ID[I] = Ith column of per-atom array calculated by a fix with ID
   v_name = per-atom vector calculated by an atom-style variable with name
    @@ -59,17 +59,17 @@ computed. Atoms not in the group have their result(s) set to 0.0. position, velocity, force component) or can be the result of a compute or fix or the evaluation of an atom-style variable. In the latter cases, the -compute, fix, or variable must produce a per-atom quantity, not a -global quantity. If you wish to time-average global quantities from a -compute, fix, or variable, then see the fix +compute, fix, or variable must produce a per-atom vector, not a global +scalar or vector or array. If you wish to time-average global +quantities from a compute, fix, or variable, then see the fix ave/time command.

    -

    Computes that produce per-atom quantities are those -which have the word atom in their style name. See the doc pages for -individual fixes to determine which ones produce per-atom -quantities. Variables of style atom are the only -ones that can be used with this fix since all other styles of variable -produce global quantities. +

    Computes that produce per-atom vectors or arrays are +those which have the word atom in their style name. See the doc +pages for individual fixes to determine which ones produce +per-atom vectors or arrays. Variables of style atom +are the only ones that can be used with this fix since they are the +only ones that produce per-atom vectors.

    @@ -102,24 +102,27 @@ is meant by image flags.

    If a value begins with "c_", a compute ID must follow which has been previously defined in the input script. If no bracketed term is appended, the per-atom vector calculated by the compute is used. If a -bracketed term is appended, the Nth columnd of the per-atom array -calculated by the compute is used. Users can also write code for -their own compute styles and add them to LAMMPS. +bracketed term containing an index I is appended, the Ith column of +the per-atom array calculated by the compute is used. Users can also +write code for their own compute styles and add them to +LAMMPS.

    If a value begins with "f_", a fix ID must follow which has been previously defined in the input script. If no bracketed term is appended, the per-atom vector calculated by the fix is used. If a -bracketed term is appended, the Nth column of the per-atom array -calculated by the fix is used. Note that some fixes only produce -their values on certain timesteps, which must be compatible with -Nevery, else an error will results. Users can also write code for -their own fix styles and add them to LAMMPS. +bracketed term containing an index I is appended, the Ith column of +the per-atom array calculated by the fix is used. Note that some +fixes only produce their values on certain timesteps, which must be +compatible with Nevery, else an error will result. Users can also +write code for their own fix styles and 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 of style -atom can reference thermodynamic keywords, or invoke other computes, -fixes, or variables when they are evaluated, so this is a very general -means of generating per-atom quantities to time average. +been previously defined in the input script as an atom-style +variable Variables of style atom can reference +thermodynamic keywords, or invoke other computes, fixes, or variables +when they are evaluated, so this is a very general means of generating +per-atom quantities to time average.

    diff --git a/doc/fix_ave_atom.txt b/doc/fix_ave_atom.txt index 309efb6d2e..323eee4507 100644 --- a/doc/fix_ave_atom.txt +++ b/doc/fix_ave_atom.txt @@ -18,12 +18,12 @@ Nevery = calculate property every this many timesteps :l Nrepeat = # of times to repeat the Nevery calculation before averaging :l Nfreq = timestep frequency at which the average value is calculated :l one or more values can be listed :l -value = x, y, z, xu, yu, zu, vx, vy, vz, fx, fy, fz, c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :l +value = x, y, z, xu, yu, zu, vx, vy, vz, fx, fy, fz, c_ID, c_ID\[i\], f_ID, f_ID\[i\], v_name :l x,y,z,xu,yu,zu,vx,vy,vz,fx,fy,fz = atom attribute (position, unwrapped position, velocity, force component) - c_ID = per-atom vector value calculated by a compute with ID - c_ID\[N\] = Nth column of per-atom array calculated by a compute with ID - f_ID = per-atom vector value calculated by a fix with ID - f_ID\[N\] = Nth column of per-atom array calculated by a fix with ID + c_ID = per-atom vector calculated by a compute with ID + c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID + f_ID = per-atom vector calculated by a fix with ID + f_ID\[I\] = Ith column of per-atom array calculated by a fix with ID v_name = per-atom vector calculated by an atom-style variable with name :pre :ule @@ -48,17 +48,17 @@ Each listed value can be an atom attribute (position, unwrapped position, velocity, force component) or can be the result of a "compute"_compute.html or "fix"_fix.html or the evaluation of an atom-style "variable"_variable.html. In the latter cases, the -compute, fix, or variable must produce a per-atom quantity, not a -global quantity. If you wish to time-average global quantities from a -compute, fix, or variable, then see the "fix +compute, fix, or variable must produce a per-atom vector, not a global +scalar or vector or array. If you wish to time-average global +quantities from a compute, fix, or variable, then see the "fix ave/time"_fix_ave_time.html command. -"Computes"_compute.html that produce per-atom quantities are those -which have the word {atom} in their style name. See the doc pages for -individual "fixes"_fix.html to determine which ones produce per-atom -quantities. "Variables"_variable.html of style {atom} are the only -ones that can be used with this fix since all other styles of variable -produce global quantities. +"Computes"_compute.html that produce per-atom vectors or arrays are +those which have the word {atom} in their style name. See the doc +pages for individual "fixes"_fix.html to determine which ones produce +per-atom vectors or arrays. "Variables"_variable.html of style {atom} +are the only ones that can be used with this fix since they are the +only ones that produce per-atom vectors. :line @@ -91,24 +91,27 @@ is meant by image flags. If a value begins with "c_", a compute ID must follow which has been previously defined in the input script. If no bracketed term is appended, the per-atom vector calculated by the compute is used. If a -bracketed term is appended, the Nth columnd of the per-atom array -calculated by the compute is used. Users can also write code for -their own compute styles and "add them to LAMMPS"_Section_modify.html. +bracketed term containing an index I is appended, the Ith column of +the per-atom array calculated by the compute is used. Users can also +write code for their own compute styles and "add them to +LAMMPS"_Section_modify.html. If a value begins with "f_", a fix ID must follow which has been previously defined in the input script. If no bracketed term is appended, the per-atom vector calculated by the fix is used. If a -bracketed term is appended, the Nth column of the per-atom array -calculated by the fix is used. Note that some fixes only produce -their values on certain timesteps, which must be compatible with -{Nevery}, else an error will results. Users can also write code for -their own fix styles and "add them to LAMMPS"_Section_modify.html. +bracketed term containing an index I is appended, the Ith column of +the per-atom array calculated by the fix is used. Note that some +fixes only produce their values on certain timesteps, which must be +compatible with {Nevery}, else an error will result. 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. Variables of style -{atom} can reference thermodynamic keywords, or invoke other computes, -fixes, or variables when they are evaluated, so this is a very general -means of generating per-atom quantities to time average. +been previously defined in the input script as an "atom-style +variable"_variable.html Variables of style {atom} can reference +thermodynamic keywords, or invoke other computes, fixes, or variables +when they are evaluated, so this is a very general means of generating +per-atom quantities to time average. :line diff --git a/doc/fix_ave_spatial.html b/doc/fix_ave_spatial.html index 406ad0b3f6..e37b0e16e1 100644 --- a/doc/fix_ave_spatial.html +++ b/doc/fix_ave_spatial.html @@ -33,19 +33,19 @@
  • one or more values can be listed -
  • value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[N], f_ID, f_ID[N], v_name +
  • value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[I], f_ID, f_ID[I], v_name 
      x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
   density/number, density/mass = number or mass density
-  c_ID = per-atom vector value calculated by a compute with ID
-  c_ID[N] = Nth column of per-atom array calculated by a compute with ID
-  f_ID = per-atom vector value calculated by a fix with ID
-  f_ID[N] = Nth column of per-atom array calculated by a fix with ID
+  c_ID = per-atom vector calculated by a compute with ID
+  c_ID[I] = Ith column of per-atom array calculated by a compute with ID
+  f_ID = per-atom vector calculated by a fix with ID
+  f_ID[I] = Ith column of per-atom array calculated by a fix with ID
   v_name = per-atom vector calculated by an atom-style variable with name
  • zero or more keyword/arg pairs may be appended -
  • keyword = norm or units or file or ave +
  • keyword = norm or units or file or ave or title1 or title2 or title3 
      units arg = box or lattice or reduced
   norm arg = all or sample
@@ -54,13 +54,20 @@
   ave args = one or running or window M
     one = output new average value every Nfreq steps
     running = output cumulative average of all previous Nfreq steps
-    window M = output average of M most recent Nfreq steps 
+    window M = output average of M most recent Nfreq steps
+  title1 arg = string
+    string = text to print as 1st line of output file = title
+  title2 arg = string
+    string = text to print as 2nd line of output file = timestep, # of layers
+  title3 arg = string
+    string = text to print as 3rd line of output file = values

    Examples:

    -
    fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced
+
    fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced &
+                      title1 "My output values"
 fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile
 fix 1 flow ave/spatial 100 5 1000 y 0.0 2.5 density/mass ave running 
 
    
@@ -155,16 +162,16 @@ volume of the layer so that units of number/volume or mass/volume are
 output.
 
    
 
    If a value begins with "c_", a compute ID must follow which has been
-previously defined in the input script.  If no bracketed term is
+previously defined in the input script.  If no bracketed integer is
 appended, the per-atom vector calculated by the compute is used.  If a
-bracketed term is appended, the Nth column of the per-atom array
+bracketed interger is appended, the Ith column of the per-atom array
 calculated by the compute is used.  Users can also write code for
 their own compute styles and add them to LAMMPS.
 
    
 
    If a value begins with "f_", a fix ID must follow which has been
-previously defined in the input script.  If no bracketed term is
+previously defined in the input script.  If no bracketed integer is
 appended, the per-atom vector calculated by the fix is used.  If a
-bracketed term is appended, the Nth column of the per-atom array
+bracketed integer is appended, the Ith column of the per-atom array
 calculated by the fix is used.  Note that some fixes only produce
 their values on certain timesteps, which must be compatible with
 Nevery, else an error results.  Users can also write code for their
@@ -172,9 +179,10 @@ own fix styles and 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 of style
-atom can reference thermodynamic keywords, or invoke other computes,
-fixes, or variables when they are evaluated, so this is a very general
-means of generating per-atom quantities to spatially average.
+atom can reference thermodynamic keywords and various per-atom
+attributes, or invoke other computes, fixes, or variables when they
+are evaluated, so this is a very general means of generating per-atom
+quantities to spatially average.
 
    
 
    
 
@@ -255,6 +263,24 @@ then the output on step 10000 will be the average of the individual
 layer values on steps 8000,9000,10000.  Outputs on early steps will
 average over less than M values if they are not available.
 
    
+
    The title1 and title2 and title3 keywords allow specification of
+the strings that will be printed as the first 3 lines of the output
+file, assuming the file keyword was used.  LAMMPS uses default
+values for each of these, so they do not need to be specified.  By
+default, theses lines are as follows:
+
    
+
    # Spatial-averaged data for fix ID and group name
+# Timestep Number-of-layers
+# Layer Coord Ncount value1 value2 ... 
+
    
+
    In the first line, ID and name are replaced with the fix-ID and group
+name.  In the last line the values are replaced with the appropriate
+fields from the fix ave/spatial command.  Note the first line is
+essentially a title for the file.  The second line describes the
+header line that appears at the first of each section of output.  The
+third line describes the columns of each layer line within a section
+of output.
+
    
 
    
 
 
    Restart, fix_modify, output, run start/stop, minimize info:
@@ -263,21 +289,19 @@ average over less than M values if they are not available.
 files.  None of the fix_modify options
 are relevant to this fix.
 
    
-
    This fix computes a global vector of quantities which can be accessed
-by various output commands.  The values can
+
    This fix computes a global array of values which can be accessed by
+various output commands.  The values can
 only be accessed on timesteps that are multiples of Nfreq since that
-is when averaging is performed.  The global vector is of length N =
-nlayers*nvalues where nlayers is the number of layers and nvalues is
-the number of values per layer that the fix is averaging.  When
-accessed by another output command, a single index M is specified
-which is mapped into a layer I as I = M / nvalues + 1 and into value J
-as J = M % nvalues + 1.  If I exceeds the current number of layers
-than a 0.0 is returned by the fix instead of an error, since the
-number of layers can vary as a simulation runs, depending on the
-simulation box size.  The vector values calculated by this fix are
-"intensive", meaning they are independent of the number of atoms in
-the simulation, since they are already normalized by the count of
-atoms in each layer.
+is when averaging is performed.  The global array has Nlayers rows and
+Nvalues+2 columns.  The first column has the layer coordinate, the 2nd
+column has the count of atoms in that layer, and the remaining columns
+are the Nvalue quantities.  When the array is accessed with an I that
+exceeds the current number of layers, than a 0.0 is returned by the
+fix instead of an error, since the number of layers can vary as a
+simulation runs, depending on the simulation box size.  The array
+values calculated by this fix are "intensive", meaning they are
+independent of the number of atoms in the simulation, since they are
+already normalized by the count of atoms in each layer.
 
    
 
    No parameter of this fix can be used with the start/stop keywords of
 the run command.  This fix is not invoked during energy
@@ -298,6 +322,6 @@ simulation box size doesn't change or if the units keyword is set to
 
    Default:
 
    
 
    The option defaults are units = lattice, norm = all, no file output,
-and ave = one.
+and ave = one, title 1,2,3 = strings as described above.
 
    
 
diff --git a/doc/fix_ave_spatial.txt b/doc/fix_ave_spatial.txt
index 80e0d6de9d..7acd1cefcc 100644
--- a/doc/fix_ave_spatial.txt
+++ b/doc/fix_ave_spatial.txt
@@ -21,17 +21,17 @@ dim = {x} or {y} or {z} :l
 origin = {lower} or {center} or {upper} or coordinate value (distance units) :l
 delta = thickness of spatial layers in dim (distance units) :l
 one or more values can be listed :l
-value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :l
+value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID\[I\], f_ID, f_ID\[I\], v_name :l
   x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
   density/number, density/mass = number or mass density
-  c_ID = per-atom vector value calculated by a compute with ID
-  c_ID\[N\] = Nth column of per-atom array calculated by a compute with ID
-  f_ID = per-atom vector value calculated by a fix with ID
-  f_ID\[N\] = Nth column of per-atom array calculated by a fix with ID
+  c_ID = per-atom vector calculated by a compute with ID
+  c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID
+  f_ID = per-atom vector calculated by a fix with ID
+  f_ID\[I\] = Ith column of per-atom array calculated by a fix with ID
   v_name = per-atom vector calculated by an atom-style variable with name :pre
 
 zero or more keyword/arg pairs may be appended :l
-keyword = {norm} or {units} or {file} or {ave} :l
+keyword = {norm} or {units} or {file} or {ave} or {title1} or {title2} or {title3} :l
   {units} arg = {box} or {lattice} or {reduced}
   {norm} arg = {all} or {sample}
   {file} arg = filename
@@ -39,12 +39,19 @@ keyword = {norm} or {units} or {file} or {ave} :l
   {ave} args = {one} or {running} or {window M}
     one = output new average value every Nfreq steps
     running = output cumulative average of all previous Nfreq steps
-    window M = output average of M most recent Nfreq steps :pre
+    window M = output average of M most recent Nfreq steps
+  {title1} arg = string
+    string = text to print as 1st line of output file = title
+  {title2} arg = string
+    string = text to print as 2nd line of output file = timestep, # of layers
+  {title3} arg = string
+    string = text to print as 3rd line of output file = values :pre
 :ule
 
 [Examples:]
 
-fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced
+fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced &
+                      title1 "My output values"
 fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile
 fix 1 flow ave/spatial 100 5 1000 y 0.0 2.5 density/mass ave running :pre
 
@@ -139,16 +146,16 @@ volume of the layer so that units of number/volume or mass/volume are
 output.
 
 If a value begins with "c_", a compute ID must follow which has been
-previously defined in the input script.  If no bracketed term is
+previously defined in the input script.  If no bracketed integer is
 appended, the per-atom vector calculated by the compute is used.  If a
-bracketed term is appended, the Nth column of the per-atom array
+bracketed interger is appended, the Ith column of the per-atom array
 calculated by the compute is used.  Users can also write code for
 their own compute styles and "add them to LAMMPS"_Section_modify.html.
 
 If a value begins with "f_", a fix ID must follow which has been
-previously defined in the input script.  If no bracketed term is
+previously defined in the input script.  If no bracketed integer is
 appended, the per-atom vector calculated by the fix is used.  If a
-bracketed term is appended, the Nth column of the per-atom array
+bracketed integer is appended, the Ith column of the per-atom array
 calculated by the fix is used.  Note that some fixes only produce
 their values on certain timesteps, which must be compatible with
 {Nevery}, else an error results.  Users can also write code for their
@@ -156,9 +163,10 @@ 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.  Variables of style
-{atom} can reference thermodynamic keywords, or invoke other computes,
-fixes, or variables when they are evaluated, so this is a very general
-means of generating per-atom quantities to spatially average.
+{atom} can reference thermodynamic keywords and various per-atom
+attributes, or invoke other computes, fixes, or variables when they
+are evaluated, so this is a very general means of generating per-atom
+quantities to spatially average.
 
 :line
 
@@ -239,6 +247,24 @@ then the output on step 10000 will be the average of the individual
 layer values on steps 8000,9000,10000.  Outputs on early steps will
 average over less than M values if they are not available.
 
+The {title1} and {title2} and {title3} keywords allow specification of
+the strings that will be printed as the first 3 lines of the output
+file, assuming the {file} keyword was used.  LAMMPS uses default
+values for each of these, so they do not need to be specified.  By
+default, theses lines are as follows:
+
+# Spatial-averaged data for fix ID and group name
+# Timestep Number-of-layers
+# Layer Coord Ncount value1 value2 ... :pre
+
+In the first line, ID and name are replaced with the fix-ID and group
+name.  In the last line the values are replaced with the appropriate
+fields from the fix ave/spatial command.  Note the first line is
+essentially a title for the file.  The second line describes the
+header line that appears at the first of each section of output.  The
+third line describes the columns of each layer line within a section
+of output.
+
 :line
 
 [Restart, fix_modify, output, run start/stop, minimize info:]
@@ -247,21 +273,19 @@ No information about this fix is written to "binary restart
 files"_restart.html.  None of the "fix_modify"_fix_modify.html options
 are relevant to this fix.
 
-This fix computes a global vector of quantities which can be accessed
-by various "output commands"_Section_howto.html#4_15.  The values can
+This fix computes a global array of values which can be accessed by
+various "output commands"_Section_howto.html#4_15.  The values can
 only be accessed on timesteps that are multiples of {Nfreq} since that
-is when averaging is performed.  The global vector is of length N =
-nlayers*nvalues where nlayers is the number of layers and nvalues is
-the number of values per layer that the fix is averaging.  When
-accessed by another output command, a single index M is specified
-which is mapped into a layer I as I = M / nvalues + 1 and into value J
-as J = M % nvalues + 1.  If I exceeds the current number of layers
-than a 0.0 is returned by the fix instead of an error, since the
-number of layers can vary as a simulation runs, depending on the
-simulation box size.  The vector values calculated by this fix are
-"intensive", meaning they are independent of the number of atoms in
-the simulation, since they are already normalized by the count of
-atoms in each layer.
+is when averaging is performed.  The global array has Nlayers rows and
+Nvalues+2 columns.  The first column has the layer coordinate, the 2nd
+column has the count of atoms in that layer, and the remaining columns
+are the Nvalue quantities.  When the array is accessed with an I that
+exceeds the current number of layers, than a 0.0 is returned by the
+fix instead of an error, since the number of layers can vary as a
+simulation runs, depending on the simulation box size.  The array
+values calculated by this fix are "intensive", meaning they are
+independent of the number of atoms in the simulation, since they are
+already normalized by the count of atoms in each layer.
 
 No parameter of this fix can be used with the {start/stop} keywords of
 the "run"_run.html command.  This fix is not invoked during "energy
@@ -282,4 +306,5 @@ simulation box size doesn't change or if the {units} keyword is set to
 [Default:]
 
 The option defaults are units = lattice, norm = all, no file output,
-and ave = one.
+and ave = one, title 1,2,3 = strings as described above.
+
diff --git a/doc/thermo_style.html b/doc/thermo_style.html
index 3848ed32a7..6adfad029e 100644
--- a/doc/thermo_style.html
+++ b/doc/thermo_style.html
@@ -29,7 +29,9 @@
                           vol, lx, ly, lz, xlo, xhi, ylo, yhi, zlo, zhi,
 			  xy, xz, yz,
 			  pxx, pyy, pzz, pxy, pxz, pyz,
-			  c_ID, c_ID[n], f_ID, f_ID[n], v_name
+			  c_ID, c_ID[I], c_ID[I][J],
+                          f_ID, f_ID[I], f_ID[I][J],
+                          v_name
       step = timestep
       atoms = # of atoms
       cpu = elapsed CPU time
@@ -55,10 +57,12 @@
       xy,xz,yz = box tilt for triclinic (non-orthogonal) simulation boxes
       pxx,pyy,pzz,pxy,pxz,pyz = 6 components of pressure tensor
       c_ID = global scalar value calculated by a compute with ID
-      c_ID[N] = Nth component of global vector calculated by a compute with ID
+      c_ID[I] = Ith component of global vector calculated by a compute with ID
+      c_ID[I][J] = I,J component of global array calculated by a compute with ID
       f_ID = global scalar value calculated by a fix with ID
-      f_ID[N] = Nth component of global vector calculated by a fix with ID
-      v_name = global value calculated by an equal-style variable with name 
+      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
    @@ -187,75 +191,65 @@ etc.

    -

    The c_ID and c_ID[N] keywords allow global scalar or vector -quantities calculated by a compute to be output. The ID in the -keyword should be replaced by the actual ID of the compute that has -been defined elsewhere in the input script. See the -compute command for details. Note that only global -scalar or vector quantities calculated by a compute can be output as -thermodynamic data; per-atom quantities calculated by a compute can be -output by the dump custom command. There is a compute -reduce command which can sum per-atom quantities -into a global scalar or vector which can be output by thermo_style -custom. +

    The c_ID and c_ID[I] and c_ID[I][J] keywords allow global +values calculated by a compute to be output. As discussed on the +compute doc page, computes can calculate global, +per-atom, or local values. Only global values can be referenced by +this command. However, per-atom compute values can be referenced in a +variable and the variable referenced by thermo_style +custom, as discussed below. +

    +

    The ID in the keyword should be replaced by the actual ID of a compute +that has been defined elsewhere in the input script. See the +compute command for details. If the compute calculates +a global scalar, vector, or array, then the keyword formats with 0, 1, +or 2 brackets will reference a scalar value from the compute.

    Note that some computes calculate "intensive" global quantities like temperature; others calculate "extensive" global quantities like kinetic energy that are summed over all atoms in the compute group. -Intensive quantities are printed directly as is by thermo_style -custom. Extensive quantities may be normalized when output by the +Intensive quantities are printed directly without normalization by +thermo_style custom. Extensive quantities may be normalized by the total number of atoms in the simulation (NOT the number of atoms in -the compute group) depending on the thermo_modify +the compute group) when output, depending on the thermo_modify norm option being used.

    -

    If c_ID is used as a keyword, then the scalar quantity calculated by -the compute is printed. If c_ID[N] is used, then N must be an -index from 1-M where M is the length of the vector calculated by the -compute. See the doc pages for individual compute styles for info on -what these quantities are. +

    The f_ID and f_ID[I] and f_ID[I][J] keywords allow global +values calculated by a fix to be output. As discussed on the +fix doc page, fixes can calculate global, per-atom, or +local values. Only global values can be referenced by this command. +However, per-atom fix values can be referenced in a +variable and the variable referenced by thermo_style +custom, as discussed below.

    -

    The f_ID and f_ID[N] keywords allow global scalar or vector -quantities calculated by a fix to be output. The ID in the keyword -should be replaced by the actual ID of the fix that has been defined -elsewhere in the input script. See the doc pages for individual fix -commands for details of which fixes generate global values. -One particularly useful fix to use in this context is the fix -ave/time command, which calculates time-averages of -global scalar and vector quantities calculated by other -computes, fixes, or -variables. +

    The ID in the keyword should be replaced by the actual ID of a fix +that has been defined elsewhere in the input script. See the +fix command for details. If the fix calculates a global +scalar, vector, or array, then the keyword formats with 0, 1, or 2 +brackets will reference a scalar value from the fix.

    Note that some fixes calculate "intensive" global quantities like timestep size; others calculate "extensive" global quantities like energy that are summed over all atoms in the fix group. Intensive -quantities are printed directly as is by thermo_style custom. -Extensive quantities may be normalized when output by the total number -of atoms in the simulation (NOT the number of atoms in the fix group) -depending on the thermo_modify norm option being -used. -

    -

    If f_ID is used as a keyword, then the scalar quantity calculated by -the fix is printed. If f_ID[N] is used, then N must be an index -from 1-M where M is the length of the vector calculated by the fix. -See the doc pages for individual fix styles for info on which fixes -calculate these global quantities and what they are. For fixes that -compute a contribution to the potential energy of the system, the -scalar quantity referenced by f_ID is typically that quantity. +quantities are printed directly without normalization by thermo_style +custom. Extensive quantities may be normalized by the total number of +atoms in the simulation (NOT the number of atoms in the fix group) +when output, depending on the thermo_modify norm +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 actual name of the variable that has been defined elsewhere in the input script. Only equal-style variables can be referenced. See the variable command for details. Variables of style -equal can reference individual 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 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.

    See this section for information on how to add -new compute and fix styles to LAMMPS to calculate quantities that -could then be output with these keywords as part of thermodynamic -information. +new compute and fix styles to LAMMPS to calculate quantities that can +then be referenced with these keywords to generate thermodynamic +output.

    diff --git a/doc/thermo_style.txt b/doc/thermo_style.txt index bb77136c43..75883361f2 100644 --- a/doc/thermo_style.txt +++ b/doc/thermo_style.txt @@ -24,7 +24,9 @@ args = list of arguments for a particular style :l vol, lx, ly, lz, xlo, xhi, ylo, yhi, zlo, zhi, xy, xz, yz, pxx, pyy, pzz, pxy, pxz, pyz, - c_ID, c_ID\[n\], f_ID, f_ID\[n\], v_name + c_ID, c_ID\[I\], c_ID\[I\]\[J\], + f_ID, f_ID\[I\], f_ID\[I\]\[J\], + v_name step = timestep atoms = # of atoms cpu = elapsed CPU time @@ -50,10 +52,12 @@ args = list of arguments for a particular style :l xy,xz,yz = box tilt for triclinic (non-orthogonal) simulation boxes pxx,pyy,pzz,pxy,pxz,pyz = 6 components of pressure tensor c_ID = global scalar value calculated by a compute with ID - c_ID\[N\] = Nth component of global vector calculated by a compute with ID + c_ID\[I\] = Ith component of global vector calculated by a compute with ID + c_ID\[I\]\[J\] = I,J component of global array calculated by a compute with ID f_ID = global scalar value calculated by a fix with ID - f_ID\[N\] = Nth component of global vector calculated by a fix with ID - v_name = global value calculated by an equal-style variable with name :pre + 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 :pre :ule [Examples:] @@ -181,75 +185,65 @@ etc. :line -The {c_ID} and {c_ID\[N\]} keywords allow global scalar or vector -quantities calculated by a compute to be output. The ID in the -keyword should be replaced by the actual ID of the compute that has -been defined elsewhere in the input script. See the -"compute"_compute.html command for details. Note that only global -scalar or vector quantities calculated by a compute can be output as -thermodynamic data; per-atom quantities calculated by a compute can be -output by the "dump custom"_dump.html command. There is a "compute -reduce"_compute_reduce.html command which can sum per-atom quantities -into a global scalar or vector which can be output by thermo_style -custom. +The {c_ID} and {c_ID\[I\]} and {c_ID\[I\]\[J\]} keywords allow global +values calculated by a compute to be output. As discussed on the +"compute"_compute.html doc page, computes can calculate global, +per-atom, or local values. Only global values can be referenced by +this command. However, per-atom compute values can be referenced in a +"variable"_variable.html and the variable referenced by thermo_style +custom, as discussed below. + +The ID in the keyword should be replaced by the actual ID of a compute +that has been defined elsewhere in the input script. See the +"compute"_compute.html command for details. If the compute calculates +a global scalar, vector, or array, then the keyword formats with 0, 1, +or 2 brackets will reference a scalar value from the compute. Note that some computes calculate "intensive" global quantities like temperature; others calculate "extensive" global quantities like kinetic energy that are summed over all atoms in the compute group. -Intensive quantities are printed directly as is by thermo_style -custom. Extensive quantities may be normalized when output by the +Intensive quantities are printed directly without normalization by +thermo_style custom. Extensive quantities may be normalized by the total number of atoms in the simulation (NOT the number of atoms in -the compute group) depending on the "thermo_modify +the compute group) when output, depending on the "thermo_modify norm"_thermo_modify.html option being used. -If {c_ID} is used as a keyword, then the scalar quantity calculated by -the compute is printed. If {c_ID\[N\]} is used, then N must be an -index from 1-M where M is the length of the vector calculated by the -compute. See the doc pages for individual compute styles for info on -what these quantities are. +The {f_ID} and {f_ID\[I\]} and {f_ID\[I\]\[J\]} keywords allow global +values calculated by a fix to be output. As discussed on the +"fix"_fix.html doc page, fixes can calculate global, per-atom, or +local values. Only global values can be referenced by this command. +However, per-atom fix values can be referenced in a +"variable"_variable.html and the variable referenced by thermo_style +custom, as discussed below. -The {f_ID} and {f_ID\[N\]} keywords allow global scalar or vector -quantities calculated by a fix to be output. The ID in the keyword -should be replaced by the actual ID of the fix that has been defined -elsewhere in the input script. See the doc pages for individual "fix -commands"_fix.html for details of which fixes generate global values. -One particularly useful fix to use in this context is the "fix -ave/time"_fix_ave_time.html command, which calculates time-averages of -global scalar and vector quantities calculated by other -"computes"_compute.html, "fixes"_fix.html, or -"variables"_variable.html. +The ID in the keyword should be replaced by the actual ID of a fix +that has been defined elsewhere in the input script. See the +"fix"_fix.html command for details. If the fix calculates a global +scalar, vector, or array, then the keyword formats with 0, 1, or 2 +brackets will reference a scalar value from the fix. Note that some fixes calculate "intensive" global quantities like timestep size; others calculate "extensive" global quantities like energy that are summed over all atoms in the fix group. Intensive -quantities are printed directly as is by thermo_style custom. -Extensive quantities may be normalized when output by the total number -of atoms in the simulation (NOT the number of atoms in the fix group) -depending on the "thermo_modify norm"_thermo_modify.html option being -used. - -If {f_ID} is used as a keyword, then the scalar quantity calculated by -the fix is printed. If {f_ID\[N\]} is used, then N must be an index -from 1-M where M is the length of the vector calculated by the fix. -See the doc pages for individual fix styles for info on which fixes -calculate these global quantities and what they are. For fixes that -compute a contribution to the potential energy of the system, the -scalar quantity referenced by f_ID is typically that quantity. +quantities are printed directly without normalization by thermo_style +custom. Extensive quantities may be normalized by the total number of +atoms in the simulation (NOT the number of atoms in the fix group) +when output, depending on the "thermo_modify norm"_thermo_modify.html +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 actual name of the variable that has been defined elsewhere in the input script. Only equal-style variables can be referenced. See the "variable"_variable.html command for details. Variables of style -{equal} can reference individual 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} 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. See "this section"_Section_modify.html for information on how to add -new compute and fix styles to LAMMPS to calculate quantities that -could then be output with these keywords as part of thermodynamic -information. +new compute and fix styles to LAMMPS to calculate quantities that can +then be referenced with these keywords to generate thermodynamic +output. :line diff --git a/doc/variable.html b/doc/variable.html index ce1cfe7031..aad96b4590 100644 --- a/doc/variable.html +++ b/doc/variable.html @@ -38,13 +38,11 @@ region functions = count(group,region), mass(group,region), charge(group,region), xcm(group,dim,region), vcm(group,dim,region), fcm(group,dim,region), bound(group,xmin,region), gyration(group,region), ke(group,reigon) - atom value = mass[N], type[N], x[N], y[N], z[N], - vx[N], vy[N], vz[N], fx[N], fy[N], fz[N] - atom vector = mass[], type[], x[], y[], z[], - vx[], vy[], vz[], fx[], fy[], fz[] - compute references = c_ID, c_ID[2], c_ID[N], c_ID[N][2], c_ID[], c_ID[][2] - fix references = f_ID, f_ID[2], f_ID[N], f_ID[N][2], f_ID[], f_ID[][2] - variable references = v_abc, v_abc[N], v_abc[] + atom value = mass[i], type[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i] + atom vector = mass, type, x, y, z, vx, vy, vz, fx, fy, fz + compute references = c_ID, c_ID[i], c_ID[i][j] + fix references = f_ID, f_ID[i], f_ID[i][j] + variable references = v_name, v_name[i] @@ -57,7 +55,7 @@ variable b1 equal x[234]+0.5*vol variable b1 equal "x[234] + 0.5*vol" variable b equal xcm(mol1,x)/2.0 variable b equal c_myTemp -variable b atom x[]*y[]/vol +variable b atom x*y/vol variable temp world 300.0 310.0 320.0 ${Tfinal} variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 variable x uloop 15 @@ -250,21 +248,23 @@ references, fix references, and references to other variables. Math operations (), -x, x+y, x-y, x*y, x/y, x^y, sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), ceil(x), floor(x), round(x) Group functions count(ID), mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID) Region functions count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR) -Atom values mass[N], type[N], x[N], y[N], z[N], vx[N], vy[N], vz[N], fx[N], fy[N], fz[N] -Atom vectors mass[], type[], x[], y[], z[], vx[], vy[], vz[], fx[], fy[], fz[] -Compute references c_ID, c_ID[2], c_ID[N], c_ID[N][2], c_ID[], c_ID[][2] -Fix references f_ID, f_ID[2], f_ID[N], f_ID[N][2], f_ID[], f_ID[][2] -Other variables v_abc, v_abc[N], v_abc[] +Atom values mass[i], type[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i] +Atom vectors mass, type, x, y, z, vx, vy, vz, fx, fy, fz +Compute references c_ID, c_ID[i], c_ID[i][j] +Fix references f_ID, f_ID[i], f_ID[i][j] +Other variables v_name, v_name[i] -

    Note that formula elements that contain empty brackets, such as an -atom vector, produce per-atom values. All other formula elements -produce a global value. +

    Most of the formula elements generate scalar values. The exceptions +are those that represent 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.

    A formula for equal-style variables cannot use any formula element -that produces per-atom values. A formula for an atom-style variable -can use formula elements that produce either global values or per-atom -values. +that generates a per-atom vector. A formula for an atom-style +variable can use formula elements that produce either scalar values or +per-atom vectors.

    The thermo keywords allowed in a formula are those defined by the thermo_style custom command. Thermo keywords that @@ -276,9 +276,9 @@ the thermo_style command (and the thermo keywords associated with that style) also define and use the needed compute. Note that some thermo keywords use a compute indirectly to calculate their value (e.g. the enthalpy keyword uses temp, pe, and pressure). If a variable is -evaluated in an input script (not during a run), then the values -accessed by the thermo keyword must be current. See the discussion -below about "Variable Accuracy". +evaluated directly in an input script (not during a run), then the +values accessed by the thermo keyword must be current. See the +discussion below about "Variable Accuracy".

    Math operations are written in the usual way, where the "x" and "y" in the examples above can be another section of the formula. Operators @@ -307,79 +307,97 @@ coordinate for all atoms in the group. Gyration() computes the radius-of-gyration of the group of atoms. See the fix gyration command for a definition of the formula.

    -

    Region functions are exactly the same as group functions with an -extra argument which is the region ID. The function is computed -for all atoms that are in both the group and the region. If the -group is "all", then the only criteria for atom inclusion is -that it be in the region. +

    Region functions are exactly the same as group functions except they +take an extra argument which is the region ID. The function is +computed for all atoms that are in both the group and the region. If +the group is "all", then the only criteria for atom inclusion is that +it be in the region.

    -

    Atom values take a single integer argument from 1-N, which is the -desired atom-ID, e.g. x[243]., which means use the x coordinate of -the atom with ID=243. +

    Atom values take a single integer argument I from 1 to N, where I is +the an atom-ID, e.g. x[243], which means use the x coordinate of the +atom with ID = 243.

    -

    Atom vectors use empty brackets, i.e. they take no argument. They -generate one value per atom, so that a reference like x[] means the -x-coord of each atom will be used when evaluating the variable. +

    Atom vectors generate one value per atom, so that a reference like +"vx" means the x-component of each atom's velocity will be used when +evaluating the variable.

    -

    Compute references access one or more quantities calculated by a +

    Compute references access quantities calculated by a compute. The ID in the reference should be replaced by -the actual ID of the compute defined elsewhere in the input script. -See the doc pages for individual computes to see which ones calculate -global versus per-atom quantities. If the compute reference contains -empty brackets, then per-atom values calculated by the compute are -accessed. Otherwise a single value (global or per-atom) calculated by -the compute is accessed. If a variable containing a compute is -evaluated in an input script (not during a run), then the values +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 use +scalar values, which means a scalar itself, or an element of a vector +or array. Atom-style variables can use either scalar or vector +values. A vector value can be a vector itself, or a column of an +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. +

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

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

    -

    The different kinds of compute references are as follows. M is a -positive integer <= the number of vector values calculated by the -compute. N is a global atom ID (positive integer). +

    Fix references access quantities calculated by a fix. +The ID in the reference should be replaced by the ID of a fix defined +elsewhere in the input script. As discussed in the doc page for the +fix command, fixes can produce global, per-atom, or local +values. Only global and per-atom values can be used in a variable. +Fixes can also produce a scalar, vector, or array. An equal-style +variable can use scalar values, which means a scalar itself, or an +element of a vector or array. Atom-style variables can use either +scalar or vector values. A vector value can be a vector itself, or a +column of an 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_".

    - - - - - - + +
    c_ID scalar value of a global compute
    c_ID[2] vector component of a global compute
    c_ID[N] single atom's scalar value of a per-atom compute
    c_ID[N][M] single atom's vector component of a per-atom compute
    c_ID[] per-atom vector from a per-atom compute
    c_ID[][M] column of per-atom array from a per-atom compute +
    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
    -

    Fix references access one or more quantities calculated by a -fix. The ID in the reference should be replaced by the -actual ID of the fix defined elsewhere in the input script. See the -doc pages for individual computes to see which ones calculate global -versus per-atom quantities. If the fix reference contains empty -brackets, then per-atom values calculated by the fix are accessed. -Otherwise a single value (global or per-atom) calculated by the fix is -accessed. +

    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 command may only generate averaged quantities every 100 steps. See -the doc pages for individual fix commands for details. If a variable -containing a fix is evaluated in an input script (not during a run), -then the values accessed by the fix should be current. See the -discussion below about "Variable Accuracy". +the doc pages for individual fix commands for details.

    -

    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_", and the word "compute" is replaced by "fix". +

    Variable references access quantities calulated by other 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, +atom-style variables generate a per-atom vector of values; all other +variable styles generate a single scalar value. An equal-style +variable can use scalar values produce by another variable, but not +per-atom vectors. Atom-style variables can use either scalar or +per-atom vector values.

    -

    The current values of other variables can be accessed by prepending a -"v_" to the variable name. This will cause that variable to be -evaluated. Atom-style variables generate per-atom values; all other -styles of variables generate a single scalar value. -

    -

    The different kinds of variable references are as follows. N is a -global atom ID (positive integer). +

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

    - - - +
    v_ID scalar value of a non atom-style variable
    v_ID[N] single atom's scalar value from an atom-style variable
    v_ID[] per-atom value from an atom-style variable +
    v_name scalar, or per-atom vector
    v_name[I] atom I's value in per-atom vector

    IMPORTANT NOTE: If you define variables in circular manner like this: @@ -388,7 +406,7 @@ global atom ID (positive integer). variable b equal v_a print $a -

    then LAMMPS will run for a while when the print statement is invoked! +

    then LAMMPS may run for a while when the print statement is invoked!

    diff --git a/doc/variable.txt b/doc/variable.txt index 1d3e6d2037..b985ca8598 100644 --- a/doc/variable.txt +++ b/doc/variable.txt @@ -33,13 +33,11 @@ style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {eq region functions = count(group,region), mass(group,region), charge(group,region), xcm(group,dim,region), vcm(group,dim,region), fcm(group,dim,region), bound(group,xmin,region), gyration(group,region), ke(group,reigon) - atom value = mass\[N\], type\[N\], x\[N\], y\[N\], z\[N\], - vx\[N\], vy\[N\], vz\[N\], fx\[N\], fy\[N\], fz\[N\] - atom vector = mass\[\], type\[\], x\[\], y\[\], z\[\], - vx\[\], vy\[\], vz\[\], fx\[\], fy\[\], fz\[\] - compute references = c_ID, c_ID\[2\], c_ID\[N\], c_ID\[N\]\[2\], c_ID\[\], c_ID\[\]\[2\] - fix references = f_ID, f_ID\[2\], f_ID\[N\], f_ID\[N\]\[2\], f_ID\[\], f_ID\[\]\[2\] - variable references = v_abc, v_abc\[N\], v_abc\[\] :pre + atom value = mass\[i\], type\[i\], x\[i\], y\[i\], z\[i\], vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\] + atom vector = mass, type, x, y, z, vx, vy, vz, fx, fy, fz + compute references = c_ID, c_ID\[i\], c_ID\[i\]\[j\] + fix references = f_ID, f_ID\[i\], f_ID\[i\]\[j\] + variable references = v_name, v_name\[i\] :pre :ule [Examples:] @@ -51,7 +49,7 @@ variable b1 equal x\[234\]+0.5*vol variable b1 equal "x\[234\] + 0.5*vol" variable b equal xcm(mol1,x)/2.0 variable b equal c_myTemp -variable b atom x\[\]*y\[\]/vol +variable b atom x*y/vol variable temp world 300.0 310.0 320.0 $\{Tfinal\} variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 variable x uloop 15 @@ -245,22 +243,23 @@ Group functions: count(ID), mass(ID), charge(ID), xcm(ID,dim), \ vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID) Region functions: count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), \ vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR) -Atom values: mass\[N\], type\[N\], x\[N\], y\[N\], z\[N\], \ - vx\[N\], vy\[N\], vz\[N\], fx\[N\], fy\[N\], fz\[N\] -Atom vectors: mass\[\], type\[\], x\[\], y\[\], z\[\], \ - vx\[\], vy\[\], vz\[\], fx\[\], fy\[\], fz\[\] -Compute references: c_ID, c_ID\[2\], c_ID\[N\], c_ID\[N\]\[2\], c_ID\[\], c_ID\[\]\[2\] -Fix references: f_ID, f_ID\[2\], f_ID\[N\], f_ID\[N\]\[2\], f_ID\[\], f_ID\[\]\[2\] -Other variables: v_abc, v_abc\[N\], v_abc\[\] :tb(s=:) +Atom values: mass\[i\], type\[i\], x\[i\], y\[i\], z\[i\], \ + vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\] +Atom vectors: mass, type, x, y, z, vx, vy, vz, fx, fy, fz +Compute references: c_ID, c_ID\[i\], c_ID\[i\]\[j\] +Fix references: f_ID, f_ID\[i\], f_ID\[i\]\[j\] +Other variables: v_name, v_name\[i\] :tb(s=:) -Note that formula elements that contain empty brackets, such as an -atom vector, produce per-atom values. All other formula elements -produce a global value. +Most of the formula elements generate scalar values. The exceptions +are those that represent 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. A formula for equal-style variables cannot use any formula element -that produces per-atom values. A formula for an atom-style variable -can use formula elements that produce either global values or per-atom -values. +that generates a per-atom vector. A formula for an atom-style +variable can use formula elements that produce either scalar values or +per-atom vectors. The thermo keywords allowed in a formula are those defined by the "thermo_style custom"_thermo_style.html command. Thermo keywords that @@ -272,9 +271,9 @@ the thermo_style command (and the thermo keywords associated with that style) also define and use the needed compute. Note that some thermo keywords use a compute indirectly to calculate their value (e.g. the enthalpy keyword uses temp, pe, and pressure). If a variable is -evaluated in an input script (not during a run), then the values -accessed by the thermo keyword must be current. See the discussion -below about "Variable Accuracy". +evaluated directly in an input script (not during a run), then the +values accessed by the thermo keyword must be current. See the +discussion below about "Variable Accuracy". Math operations are written in the usual way, where the "x" and "y" in the examples above can be another section of the formula. Operators @@ -303,76 +302,92 @@ coordinate for all atoms in the group. Gyration() computes the radius-of-gyration of the group of atoms. See the "fix gyration"_fix_gyration.html command for a definition of the formula. -Region functions are exactly the same as group functions with an -extra argument which is the region ID. The function is computed -for all atoms that are in both the group and the region. If the -group is "all", then the only criteria for atom inclusion is -that it be in the region. +Region functions are exactly the same as group functions except they +take an extra argument which is the region ID. The function is +computed for all atoms that are in both the group and the region. If +the group is "all", then the only criteria for atom inclusion is that +it be in the region. -Atom values take a single integer argument from 1-N, which is the -desired atom-ID, e.g. x\[243\]., which means use the x coordinate of -the atom with ID=243. +Atom values take a single integer argument I from 1 to N, where I is +the an atom-ID, e.g. x\[243\], which means use the x coordinate of the +atom with ID = 243. -Atom vectors use empty brackets, i.e. they take no argument. They -generate one value per atom, so that a reference like x\[\] means the -x-coord of each atom will be used when evaluating the variable. +Atom vectors generate one value per atom, so that a reference like +"vx" means the x-component of each atom's velocity will be used when +evaluating the variable. -Compute references access one or more quantities calculated by a +Compute references access quantities calculated by a "compute"_compute.html. The ID in the reference should be replaced by -the actual ID of the compute defined elsewhere in the input script. -See the doc pages for individual computes to see which ones calculate -global versus per-atom quantities. If the compute reference contains -empty brackets, then per-atom values calculated by the compute are -accessed. Otherwise a single value (global or per-atom) calculated by -the compute is accessed. If a variable containing a compute is -evaluated in an input script (not during a run), then the values +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 use +scalar values, which means a scalar itself, or an element of a vector +or array. Atom-style variables can use either scalar or vector +values. A vector value can be a vector itself, or a column of an +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. + +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=:) + +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". -The different kinds of compute references are as follows. M is a -positive integer <= the number of vector values calculated by the -compute. N is a global atom ID (positive integer). +Fix references access quantities calculated by a "fix"_compute.html. +The ID in the reference should be replaced by the ID of a fix defined +elsewhere in the input script. As discussed in the doc page for the +"fix"_fix.html command, fixes can produce global, per-atom, or local +values. Only global and per-atom values can be used in a variable. +Fixes can also produce a scalar, vector, or array. An equal-style +variable can use scalar values, which means a scalar itself, or an +element of a vector or array. Atom-style variables can use either +scalar or vector values. A vector value can be a vector itself, or a +column of an array. See the doc pages for individual fixes to see +what kind of values they produce. -c_ID: scalar value of a global compute -c_ID\[2\]: vector component of a global compute -c_ID\[N\]: single atom's scalar value of a per-atom compute -c_ID\[N\]\[M\]: single atom's vector component of a per-atom compute -c_ID\[\]: per-atom vector from a per-atom compute -c_ID\[\]\[M\]: column of per-atom array from a per-atom compute :tb(s=:) +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_". -Fix references access one or more quantities calculated by a -"fix"_fix.html. The ID in the reference should be replaced by the -actual ID of the fix defined elsewhere in the input script. See the -doc pages for individual computes to see which ones calculate global -versus per-atom quantities. If the fix reference contains empty -brackets, then per-atom values calculated by the fix are accessed. -Otherwise a single value (global or per-atom) calculated by the fix is -accessed. +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=:) + +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"_fix_ave_time.html command may only generate averaged quantities every 100 steps. See -the doc pages for individual fix commands for details. If a variable -containing a fix is evaluated in an input script (not during a run), -then the values accessed by the fix should be current. See the -discussion below about "Variable Accuracy". +the doc pages for individual fix commands for details. -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_", and the word "compute" is replaced by "fix". +Variable references access quantities calulated by other 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, +atom-style variables generate a per-atom vector of values; all other +variable styles generate a single scalar value. An equal-style +variable can use scalar values produce by another variable, but not +per-atom vectors. Atom-style variables can use either scalar or +per-atom vector values. -The current values of other variables can be accessed by prepending a -"v_" to the variable name. This will cause that variable to be -evaluated. Atom-style variables generate per-atom values; all other -styles of variables generate a single scalar value. +Examples of different kinds of variable references are as follows. +There is no ambiguity as to what a reference means, since variables +only produce scalar or per-atom vectors, never both. -The different kinds of variable references are as follows. N is a -global atom ID (positive integer). - -v_ID: scalar value of a non atom-style variable -v_ID\[N\]: single atom's scalar value from an atom-style variable -v_ID\[\]: per-atom value from an atom-style variable :tb(s=:) +v_name: scalar, or per-atom vector +v_name\[I\]: atom I's value in per-atom vector :tb(s=:) IMPORTANT NOTE: If you define variables in circular manner like this: @@ -380,7 +395,7 @@ variable a equal v_b variable b equal v_a print $a :pre -then LAMMPS will run for a while when the print statement is invoked! +then LAMMPS may run for a while when the print statement is invoked! :line