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