diff --git a/doc/Section_howto.html b/doc/Section_howto.html index b809af9fa0..66ed5932e0 100644 --- a/doc/Section_howto.html +++ b/doc/Section_howto.html @@ -956,200 +956,215 @@ particles are point masses.

4.15 Output from LAMMPS (thermo, dumps, computes, fixes, variables)

-

Aside from restart files, there are two basic kinds of -LAMMPS output. The first is thermodynamic output, -which is a list of quantities printed every few timesteps to the -screen and logfile. The second is dump files, which -contain snapshots of atoms and various per-atom values and are written -at a specified frequency. A simulation prints one set of -thermodynamic output; it may generate any number of dump files. As -discussed below, LAMMPS gives you a variety of ways to determine what -quantities are computed and printed when thermodynamic info or dump -files are output. There are also three fixes which can do their own -output of user-chosen quantities: fix ave/time for -time averaging, fix ave/spatial for spatial -averaging, and fix print. These are also described -below. Throughout this discussion, note that users can add their own -computes and fixes to LAMMPS which can then -generate values that can be output with these commands. +

There are four basic kinds of LAMMPS output:

-
Thermodynamic output + +

A simulation prints one set of thermodynamic output and (optionally) +restart files. It can generate any number of dump files and fix +output files, depending on what dump and fix +commands you specify. +

+

As discussed below, LAMMPS gives you a variety of ways to determine +what quantities are computed and printed when the thermodynamics, +dump, or fix commands listed above perform output. Throughout this +discussion, note that users can also add their own computes and fixes +to LAMMPS which can then generate values that can +then be output with these commands. +

+

The following sub-sections discuss different LAMMPS command related +to output and the kind of data they operate on and produce: +

+ +
Global/per-atom/local data +
+

Various output-related commands work with three different styles of +data: global, per-atom, or local. A global datum is one or more +system-wide values, e.g. the temperature of the system. A per-atom +datum is one or more values per atom, e.g. the kinetic energy of each +atom. Local datums are calculated by each processor based on the +atoms it owns, but there may be zero or more per atom, e.g. a list of +bond distances. +

+
Scalar/vector/array data +
+

Global, per-atom, and local datums can each come in three kinds: a +single scalar value, a vector of values, or a 2d array of values. The +doc page for a "compute" or "fix" or "variable" that generates data +will specify both the style and kind of data it produces, e.g. a +per-atom vector. +

+

When a quantity is accessed, as in many of the output commands +discussed below, it can be referenced via the following bracket +notation, where ID in this case is the ID of a compute. The leading +"c_" would be replaced by "f_" for a fix, or "v_" for a variable: +

+
+ + +
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 data +once (vector -> scalar, array -> vector). Using two brackets reduces +the dimension twice (array -> scalar). Thus a command that uses +scalar values as input can typically also process elements of a vector +or array. +

+
Thermodynamic output

The frequency and format of thermodynamic output is set by the thermo, thermo_style, and thermo_modify commands. The -thermo_style command also specifies what values are -calculated and written out. Pre-defined keywords can be specified -(e.g. press, etotal, etc). Three additional kinds of keywords can also -be specified (c_ID, f_ID, v_name), where a compute or -fix or variable provides the value to be -output. Each of these are described in turn. +thermo_style command also specifies what values +are calculated and written out. Pre-defined keywords can be specified +(e.g. press, etotal, etc). Three additional kinds of keywords can +also be specified (c_ID, f_ID, v_name), where a compute +or fix or variable provides the value to be +output. In each case, the compute, fix, or variable must generate +global values for input to the thermo_style custom +command.

-

In LAMMPS, a compute comes in two flavors: ones that -compute global values (a scalar or a vector, e.g. temperature, -6-element pressure tensor) and ones that compute per-atom values. -Only global quantities from a compute can be used for thermodynamic -output. The user-defined ID of the compute is used along with an -optional subscript as part of the thermo_style -command. E.g. c_myTemp outputs the single scalar value generated by -the compute; c_myTemp[2] outputs the 2nd vector value. Note that -there is a compute reduce command which can sum -per-atom quantities into a global scalar or vector. -

-

Fixes can generate global scalar or vector values which can -be output with thermodynamic output, e.g. the energy of an indenter's -interaction with the simulation atoms. These values are accessed via -the same format as a compute's values, as f_ID or f_ID[N]. See the -doc pages for individual fix commands to see which ones generate -global values that can be output with thermodynamic info. The fix -ave/time command generates time-averaged global -quantities which can be accessed for thermodynamic output, e.g. a -time-averaged pressure. -

-

Variables can be defined in the input script. All -styles except the atom-style variable can be used for thermodynamic -output, since it generates per-atom values. A variable with the name -"abc" is referenced in a thermo_style command as v_abc. -

-

The formula associated with equal-style variables can contain math -operations and functions (x+y,x*y,(),sqrt,exp,etc), atom values -(x[N],fx[N],etc), group functions (mass(),vcm(),etc), references -to thermodynamic quantities (temp,press,vol,etc), references to -computes that generate global values, references to -fixes that generate global values, or references to other -variables. Thus an equal-style variable is the most -general way to define some quantity to calculate and include with -thermodynamic output. -

-
Dump file output +
Dump file output

Dump file output is specified by the dump and dump_modify commands. There are several pre-defined formats (dump atom, dump xtc, etc). There is also a dump custom format where the user specifies what values are -output with each atom. Pre-defined keywords can be specified (tag, x, +output with each atom. Pre-defined keywords can be specified (id, x, fx, etc). Three additional kinds of keywords can also be specified (c_ID, f_ID, v_name), where a compute or fix -or variable provides the value to be output. Each of -these are described in turn. +or variable provides the values to be output. In each +case, the compute, fix, or variable must generate per-atom values for +input to the dump custom command.

-

Computes that generate one or more per-atom values can -be accessed by the dump custom command. These are computes that have -the word "atom" in their style name, e.g. ke/atom, stress/atom, etc. -The values are accessed as c_myKE for a scalar per-atom quantity or as -c_myStress[2] for a component of a vector per-atom quantity. -

-

Fixes can generate per-atom values to output to dump files. -For example, the fix ave/atom command calculates -time-averages of per-atom quantities, such as per-atom -computes and atom-style variables. -These per-atom fix values are accessed by the dump custom -command via the same format as a compute's values, as f_myKE or -f_myStress[2]. -

-

Variables can be defined in the input script. Only -atom-style variables can be used for dump custom output, since only -they produce per-atom values. A variable with the name "abc" is -referenced in a dump custom command as v_abc. -

-

Just like equal-style variables, the formula associated with -atom-style variables can contain math operations and functions -(x+y,x*y,(),sqrt,exp,etc), atom values (x[N],fx[N],etc), group -functions (mass(),vcm(),etc), references to thermodynamic quantities -(temp,press,vol,etc), references to computes that -generate global values, references to fixes that generate -global values, or references to non atom-style variables that generate -global values. In addition, an atom-style variable can reference -vectors of atom values (x[],fx[],etc), computes -that generate per-atom values, fixes that generate per-atom -values, or other atom-style variables. Thus an atom-style variable is -the most general way to define some quantity to calculate and output -to a dump file. -

-
Fix output +
Fixes that write output files
-

Three other fixes are of particular note for output: fix -ave/time, fix ave/spatial, -and fix print. +

Three fixes take various quantities as input and can write output +files: fix ave/time, fix +ave/spatial, and fix print.

-

The fix ave/time command enables time-averaging of -any global quantity, like those output with thermodynamic info. The -user specifies one or more quantities to time average. These can be -global compute values, global fix values, or +

The fix ave/time command enables direct output to +a file and/or time-averaging of any global quantity. The user +specifies one or more quantities as input. These can be global +compute values, global fix values, or variables of any style except the atom style which produces per-atom values. Since a variable can refer to keywords used by the thermo_style custom command (like temp or -press), any thermodynamic quantity can be time averaged in this way. +press) and individual per-atom values, a wide variety of quantities +can be time averaged and/or output in this way. The time-averaged +output of this fix can also be used as input to other output commands.

-

The fix ave/time command offers several options -for how it performs time averaging. The results it produces can be -used in two ways. First, they can be written directly to a file, one -line per timestamp. Note that the averaging parameters can be -specified in such a way that averaging is not done at all, in which -case this is simply a convenient means of outputting desired -quantities directly to a separate file. Like other fixes that produce -global quantities, the results of this fix can also be used as input -to any command that accesses global quantities, e.g. by the -thermo_style custom command, by a variable, etc. -

-

The fix ave/spatial command enables -spatial-averaging of per-atom quantities like those output in dump -files, within 1d layers of the simulation box. The per-atom -quantities can be atom density (mass or number) or atom attributes -such as position, velocity, force. They can also be per-atom -quantities calculated by a compute, by a -fix, or by an atom-style variable. -

-

The fix ave/spatial command offers several -options for how it performs time averaging. The per-layer values it -produces can be used in two ways. First, they can be written directly -to a file. Note that the averaging parameters can be specified in -such a way that time averaging is not done, in which case this is a -convenient means of simply outputting desired quantities (summed over -atoms within a 1d layer) directly to a separate file. Like other -fixes that produce global quantities, the results of this fix can also -be used as input by any command that accesses global quantities, -e.g. by the thermo_style custom command, by a -variable, etc. See the doc page for fix -ave/spatial for a description of how these -values are indexed. +

The fix ave/spatial command enables direct +output to a file of spatial-averaged per-atom quantities like those +output in dump files, within 1d layers of the simulation box. The +per-atom quantities can be atom density (mass or number) or atom +attributes such as position, velocity, force. They can also be +per-atom quantities calculated by a compute, by a +fix, or by an atom-style variable. The +spatial-averaged output of this fix can also be used as input to other +output commands.

The fix print command can generate a line of output written to the screen and log file or to a separate file, periodically during a running simulation. The line can contain one or more -variable values (for any style variable except the -atom style), and as explained above, variables themselves can contain +variable values for any style variable except the atom +style). As explained above, variables themselves can contain references to global values generated by thermodynamic keywords, computes, -fixes, or other variables. Thus the fix -print command is a means to output any desired -calculated quantity separate from normal thermodynamic or dump file -output. +fixes, or other variables, or to per-atom +values for a specific atom. Thus the fix print +command is a means to output a wide variety of quantities separate +from normal thermodynamic or dump file output.

-

This table summarizes the various output options, specifying what -their inputs and outputs are. The frequency with which they are -invoked and produce output is also listed. Basically, any two -commands can be hooked together so long as one produces output that -matches the input needs of the other. A "match" means that the -frequencies and global vs per-atom attributes are the same. +

Computes that process output quantities +
+

The compute reduce and compute +reduce/region commands take one or more vector +quantities as inputs and "reduce" them (sum, min, max, ave) to scalar +quantities. These are produced as output values which can be used as +input to other output commands. +

+
Computes that generate values to output +
+

Every compute in LAMMPS produces either global or +per-atom or local quantities. The quantities can be scalars or +vectors or arrays of data. The doc page for each compute command +describes what it produces. These values can be output using +the other commands described in this section. +

+
Fixes that generate values to output +
+

Some fixes in LAMMPS produces either global or per-atom or +local quantities which can be accessed by other commands. The +quantities can be scalars or vectors or arrays of data. The doc page +for each fix command tells whether it produces any output quantities +and describes them. These values can be output using the other +commands described in this section. +

+
Variables that generate values to output +
+

Every variables defined in an input script generates +either a global scalar value or a per-atom vector (only atom-style +variables) when it is accessed. The formulas used to define equal- +and atom-style variables can contain references to the thermodynamic +keywords and to global and per-atom data generated by computes, fixes, +and other variables. The values generated by variables can be output +using the other commands described in this section. +

+
Summary table of output options and data flow between commands +
+

This table summarizes the various commands that can be used for +generating output from LAMMPS. Each command produces output data of +some kind and/or writes data to a file. Some of the commands take +data from other commands as input. Thus you can link many of these +commands together in pipeline form, where data produced by one command +is used as input to another command and eventually written to the +screen or to a file. Note that to hook two commands together the +output and input data types must match, e.g. global/per-atom/local +data and scalar/vector/array data. +

+

Also note that, as described above, when a command takes a scalar as +input, that could be an element of a vector or array. Likewise a +vector input could be a column of an array.

- - - - - - - - - - - - - - - - + + + + + + + + + + + +
Command Input Input Freq Output Output Freq
thermo_style custom thermo keyword, global scalar/vector compute, global scalar/vector fix, equal variable nthermo screen, log nthermo
dump custom keyword, per-atom compute, per-atom fix, atom variable dump freq file dump freq
global fixes N/A N/A global scalar/vector 1 or nevery
per-atom fixes N/A N/A per-atom vector/array 1 or nevery
fix ave/time global scalar/vector fix, global scalar/vector compute, equal variable nevery global scalar/vector, file nfreq
fix ave/spatial per-atom fix, per-atom compute, atom vector, atom variable, density mass/number nevery global vector nfreq, file
fix ave/atom per-atom compute, per-atom fix, atom variable, atom vector nevery per-atom vector/array nfreq
fix print any variable nevery screen, file nevery
global computes N/A N/A global scalar/vector N/A
per-atom computes N/A N/A per-atom vector/array N/A
compute sum per-atom compute, per-atom fix, atom variable N/A global scalar/vector N/A
variable equal thermo keywords, atom value vx[123], global scalar/vector compute, global scalar/vector fix, non-atom variable N/A global scalar N/A
variable atom thermo keywords, atom value vx[123], atom vector vx[], global scalar/vector compute, per-atom compute, global fix, per-atom fix, any variable N/A per-atom vector N/A
print any variable N/A screen, log between runs
run every any variable nevery screen, log nevery +
Command Input Output
thermo_style custom global scalars screen, log file
dump custom per-atom vectors dump file
fix print global scalar from variable screen, file
print global scalar from variable screen
computes N/A global/per-atom/local scalar/vector/array
fixes N/A global/per-atom/local scalar/vector/array
variables global scalars, per-atom vectors global scalar, per-atom vector
compute reduce global/per-atom/local vectors global scalar/vector
fix ave/time global scalars global scalar/vector, file
fix ave/spatial per-atom vectors/arrays global array, file
fix ave/atom per-atom vectors per-atom vector/array
diff --git a/doc/Section_howto.txt b/doc/Section_howto.txt index 34b513d11f..6cfeb211cc 100644 --- a/doc/Section_howto.txt +++ b/doc/Section_howto.txt @@ -949,199 +949,212 @@ particles are point masses. 4.15 Output from LAMMPS (thermo, dumps, computes, fixes, variables) :link(4_15),h4 -Aside from "restart files"_restart.html, there are two basic kinds of -LAMMPS output. The first is "thermodynamic output"_thermo_style.html, -which is a list of quantities printed every few timesteps to the -screen and logfile. The second is "dump files"_dump.html, which -contain snapshots of atoms and various per-atom values and are written -at a specified frequency. A simulation prints one set of -thermodynamic output; it may generate any number of dump files. As -discussed below, LAMMPS gives you a variety of ways to determine what -quantities are computed and printed when thermodynamic info or dump -files are output. There are also three fixes which can do their own -output of user-chosen quantities: "fix ave/time"_fix_ave_time.html for -time averaging, "fix ave/spatial"_fix_ave_spatial.html for spatial -averaging, and "fix print"_fix_print.html. These are also described -below. Throughout this discussion, note that users can "add their own -computes and fixes to LAMMPS"_Section_modify.html which can then -generate values that can be output with these commands. +There are four basic kinds of LAMMPS output: -Thermodynamic output :h5 +"Thermodynamic output"_thermo_style.html, which is a list +of quantities printed every few timesteps to the screen and logfile. :ulb,l + +"Dump files"_dump.html, which contain snapshots of atoms and various +per-atom values and are written at a specified frequency. :l + +Certain fixes can output user-specified quantities to files: "fix +ave/time"_fix_ave_time.html for time averaging, "fix +ave/spatial"_fix_ave_spatial.html for spatial averaging, and "fix +print"_fix_print.html for single-line output of +"variables"_variable.html. Fix print can also output to the +screen. :l + +"Restart files"_restart.html. :l,ule + +A simulation prints one set of thermodynamic output and (optionally) +restart files. It can generate any number of dump files and fix +output files, depending on what "dump"_dump.html and "fix"_fix.html +commands you specify. + +As discussed below, LAMMPS gives you a variety of ways to determine +what quantities are computed and printed when the thermodynamics, +dump, or fix commands listed above perform output. Throughout this +discussion, note that users can also "add their own computes and fixes +to LAMMPS"_Section_modify.html which can then generate values that can +then be output with these commands. + +The following sub-sections discuss different LAMMPS command related +to output and the kind of data they operate on and produce: + +"Global/per-atom/local data"_#global +"Scalar/vector/array data"_#scalar +"Thermodynamic output"_#thermo +"Dump file output"_#dump +"Fixes that write output files"_#fixoutput +"Computes that process output quantities"_#computeoutput +"Computes that generate values to output"_#compute +"Fixes that generate values to output"_#fix +"Variables that generate values to output"_#variable +"Summary table of output options and data flow between commands"_#table :ul + +Global/per-atom/local data :h5,link(global) + +Various output-related commands work with three different styles of +data: global, per-atom, or local. A global datum is one or more +system-wide values, e.g. the temperature of the system. A per-atom +datum is one or more values per atom, e.g. the kinetic energy of each +atom. Local datums are calculated by each processor based on the +atoms it owns, but there may be zero or more per atom, e.g. a list of +bond distances. + +Scalar/vector/array data :h5,link(scalar) + +Global, per-atom, and local datums can each come in three kinds: a +single scalar value, a vector of values, or a 2d array of values. The +doc page for a "compute" or "fix" or "variable" that generates data +will specify both the style and kind of data it produces, e.g. a +per-atom vector. + +When a quantity is accessed, as in many of the output commands +discussed below, it can be referenced via the following bracket +notation, where ID in this case is the ID of a compute. The leading +"c_" would be replaced by "f_" for a fix, or "v_" for a variable: + +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 data +once (vector -> scalar, array -> vector). Using two brackets reduces +the dimension twice (array -> scalar). Thus a command that uses +scalar values as input can typically also process elements of a vector +or array. + +Thermodynamic output :h5,link(thermo) The frequency and format of thermodynamic output is set by the "thermo"_thermo.html, "thermo_style"_thermo_style.html, and "thermo_modify"_thermo_modify.html commands. The -"thermo_style"_thermo_style.html command also specifies what values are -calculated and written out. Pre-defined keywords can be specified -(e.g. press, etotal, etc). Three additional kinds of keywords can also -be specified (c_ID, f_ID, v_name), where a "compute"_compute.html or -"fix"_fix.html or "variable"_variable.html provides the value to be -output. Each of these are described in turn. +"thermo_style"_thermo_style.html command also specifies what values +are calculated and written out. Pre-defined keywords can be specified +(e.g. press, etotal, etc). Three additional kinds of keywords can +also be specified (c_ID, f_ID, v_name), where a "compute"_compute.html +or "fix"_fix.html or "variable"_variable.html provides the value to be +output. In each case, the compute, fix, or variable must generate +global values for input to the "thermo_style custom"_dump.html +command. -In LAMMPS, a "compute"_compute.html comes in two flavors: ones that -compute global values (a scalar or a vector, e.g. temperature, -6-element pressure tensor) and ones that compute per-atom values. -Only global quantities from a compute can be used for thermodynamic -output. The user-defined ID of the compute is used along with an -optional subscript as part of the "thermo_style"_thermo_style.html -command. E.g. c_myTemp outputs the single scalar value generated by -the compute; c_myTemp\[2\] outputs the 2nd vector value. Note that -there is a "compute reduce"_compute_reduce.html command which can sum -per-atom quantities into a global scalar or vector. - -"Fixes"_fix.html can generate global scalar or vector values which can -be output with thermodynamic output, e.g. the energy of an indenter's -interaction with the simulation atoms. These values are accessed via -the same format as a compute's values, as f_ID or f_ID\[N\]. See the -doc pages for individual fix commands to see which ones generate -global values that can be output with thermodynamic info. The "fix -ave/time"_fix_ave_time.html command generates time-averaged global -quantities which can be accessed for thermodynamic output, e.g. a -time-averaged pressure. - -"Variables"_variable.html can be defined in the input script. All -styles except the atom-style variable can be used for thermodynamic -output, since it generates per-atom values. A variable with the name -"abc" is referenced in a thermo_style command as v_abc. - -The formula associated with equal-style variables can contain math -operations and functions (x+y,x*y,(),sqrt,exp,etc), atom values -(x\[N\],fx\[N\],etc), group functions (mass(),vcm(),etc), references -to thermodynamic quantities (temp,press,vol,etc), references to -"computes"_compute.html that generate global values, references to -"fixes"_fix.html that generate global values, or references to other -"variables"_variable.html. Thus an equal-style variable is the most -general way to define some quantity to calculate and include with -thermodynamic output. - -Dump file output :h5 +Dump file output :h5,link(dump) Dump file output is specified by the "dump"_dump.html and "dump_modify"_dump_modify.html commands. There are several pre-defined formats (dump atom, dump xtc, etc). There is also a "dump custom"_dump.html format where the user specifies what values are -output with each atom. Pre-defined keywords can be specified (tag, x, +output with each atom. Pre-defined keywords can be specified (id, x, fx, etc). Three additional kinds of keywords can also be specified (c_ID, f_ID, v_name), where a "compute"_compute.html or "fix"_fix.html -or "variable"_variable.html provides the value to be output. Each of -these are described in turn. +or "variable"_variable.html provides the values to be output. In each +case, the compute, fix, or variable must generate per-atom values for +input to the "dump custom"_dump.html command. -"Computes"_compute.html that generate one or more per-atom values can -be accessed by the dump custom command. These are computes that have -the word "atom" in their style name, e.g. ke/atom, stress/atom, etc. -The values are accessed as c_myKE for a scalar per-atom quantity or as -c_myStress\[2\] for a component of a vector per-atom quantity. +Fixes that write output files :h5,link(fixoutput) -"Fixes"_fix.html can generate per-atom values to output to dump files. -For example, the "fix ave/atom"_fix_ave_atom.html command calculates -time-averages of per-atom quantities, such as per-atom -"computes"_compute.html and atom-style "variables"_variable.html. -These per-atom fix values are accessed by the "dump custom"_dump.html -command via the same format as a compute's values, as f_myKE or -f_myStress\[2\]. +Three fixes take various quantities as input and can write output +files: "fix ave/time"_fix_ave_time.html, "fix +ave/spatial"_fix_ave_spatial.html, and "fix print"_fix_print.html. -"Variables"_variable.html can be defined in the input script. Only -atom-style variables can be used for dump custom output, since only -they produce per-atom values. A variable with the name "abc" is -referenced in a dump custom command as v_abc. - -Just like equal-style variables, the formula associated with -atom-style variables can contain math operations and functions -(x+y,x*y,(),sqrt,exp,etc), atom values (x\[N\],fx\[N\],etc), group -functions (mass(),vcm(),etc), references to thermodynamic quantities -(temp,press,vol,etc), references to "computes"_compute.html that -generate global values, references to "fixes"_fix.html that generate -global values, or references to non atom-style variables that generate -global values. In addition, an atom-style variable can reference -vectors of atom values (x\[\],fx\[\],etc), "computes"_compute.html -that generate per-atom values, "fixes"_fix.html that generate per-atom -values, or other atom-style variables. Thus an atom-style variable is -the most general way to define some quantity to calculate and output -to a dump file. - -Fix output :h5 - -Three other fixes are of particular note for output: "fix -ave/time"_fix_ave_time.html, "fix ave/spatial"_fix_ave_spatial.html, -and "fix print"_fix_print.html. - -The "fix ave/time"_fix_ave_time.html command enables time-averaging of -any global quantity, like those output with thermodynamic info. The -user specifies one or more quantities to time average. These can be -global "compute"_compute.html values, global "fix"_fix.html values, or +The "fix ave/time"_fix_ave_time.html command enables direct output to +a file and/or time-averaging of any global quantity. The user +specifies one or more quantities as input. These can be global +"compute"_compute.html values, global "fix"_fix.html values, or "variables"_variable.html of any style except the atom style which produces per-atom values. Since a variable can refer to keywords used by the "thermo_style custom"_thermo_style.html command (like temp or -press), any thermodynamic quantity can be time averaged in this way. +press) and individual per-atom values, a wide variety of quantities +can be time averaged and/or output in this way. The time-averaged +output of this fix can also be used as input to other output commands. -The "fix ave/time"_fix_ave_time.html command offers several options -for how it performs time averaging. The results it produces can be -used in two ways. First, they can be written directly to a file, one -line per timestamp. Note that the averaging parameters can be -specified in such a way that averaging is not done at all, in which -case this is simply a convenient means of outputting desired -quantities directly to a separate file. Like other fixes that produce -global quantities, the results of this fix can also be used as input -to any command that accesses global quantities, e.g. by the -"thermo_style custom"_thermo_style.html command, by a variable, etc. - -The "fix ave/spatial"_fix_ave_spatial.html command enables -spatial-averaging of per-atom quantities like those output in dump -files, within 1d layers of the simulation box. The per-atom -quantities can be atom density (mass or number) or atom attributes -such as position, velocity, force. They can also be per-atom -quantities calculated by a "compute"_compute.html, by a -"fix"_fix.html, or by an atom-style "variable"_variable.html. - -The "fix ave/spatial"_fix_ave_spatial.html command offers several -options for how it performs time averaging. The per-layer values it -produces can be used in two ways. First, they can be written directly -to a file. Note that the averaging parameters can be specified in -such a way that time averaging is not done, in which case this is a -convenient means of simply outputting desired quantities (summed over -atoms within a 1d layer) directly to a separate file. Like other -fixes that produce global quantities, the results of this fix can also -be used as input by any command that accesses global quantities, -e.g. by the "thermo_style custom"_thermo_style.html command, by a -variable, etc. See the doc page for "fix -ave/spatial"_fix_ave_spatial.html for a description of how these -values are indexed. +The "fix ave/spatial"_fix_ave_spatial.html command enables direct +output to a file of spatial-averaged per-atom quantities like those +output in dump files, within 1d layers of the simulation box. The +per-atom quantities can be atom density (mass or number) or atom +attributes such as position, velocity, force. They can also be +per-atom quantities calculated by a "compute"_compute.html, by a +"fix"_fix.html, or by an atom-style "variable"_variable.html. The +spatial-averaged output of this fix can also be used as input to other +output commands. The "fix print"_fix_print.html command can generate a line of output written to the screen and log file or to a separate file, periodically during a running simulation. The line can contain one or more -"variable"_variable.html values (for any style variable except the -atom style), and as explained above, variables themselves can contain +"variable"_variable.html values for any style variable except the atom +style). As explained above, variables themselves can contain references to global values generated by "thermodynamic keywords"_thermo_style.html, "computes"_compute.html, -"fixes"_fix.html, or other "variables"_variable.html. Thus the "fix -print"_fix_print.html command is a means to output any desired -calculated quantity separate from normal thermodynamic or dump file -output. +"fixes"_fix.html, or other "variables"_variable.html, or to per-atom +values for a specific atom. Thus the "fix print"_fix_print.html +command is a means to output a wide variety of quantities separate +from normal thermodynamic or dump file output. -This table summarizes the various output options, specifying what -their inputs and outputs are. The frequency with which they are -invoked and produce output is also listed. Basically, any two -commands can be hooked together so long as one produces output that -matches the input needs of the other. A "match" means that the -frequencies and global vs per-atom attributes are the same. +Computes that process output quantities :h5,link(computeoutput) -Command: Input: Input Freq: Output: Output Freq -thermo_style custom: thermo keyword, global scalar/vector compute, global scalar/vector fix, equal variable: nthermo: screen, log: nthermo -dump custom: keyword, per-atom compute, per-atom fix, atom variable: dump freq: file: dump freq -global fixes: N/A: N/A: global scalar/vector: 1 or nevery -per-atom fixes: N/A: N/A: per-atom vector/array: 1 or nevery -fix ave/time: global scalar/vector fix, global scalar/vector compute, equal variable: nevery: global scalar/vector, file: nfreq -fix ave/spatial: per-atom fix, per-atom compute, atom vector, atom variable, density mass/number: nevery: global vector: nfreq, file -fix ave/atom: per-atom compute, per-atom fix, atom variable, atom vector: nevery: per-atom vector/array: nfreq -fix print: any variable: nevery: screen, file: nevery -global computes: N/A: N/A: global scalar/vector: N/A -per-atom computes: N/A: N/A: per-atom vector/array: N/A -compute sum: per-atom compute, per-atom fix, atom variable: N/A: global scalar/vector: N/A -variable equal: thermo keywords, atom value vx\[123\], global scalar/vector compute, global scalar/vector fix, non-atom variable: N/A: global scalar: N/A -variable atom: thermo keywords, atom value vx\[123\], atom vector vx\[\], global scalar/vector compute, per-atom compute, global fix, per-atom fix, any variable: N/A: per-atom vector: N/A -print: any variable: N/A: screen, log: between runs -run every: any variable: nevery: screen, log: nevery :tb(s=:) +The "compute reduce"_compute_reduce.html and "compute +reduce/region"_compute_reduce.html commands take one or more vector +quantities as inputs and "reduce" them (sum, min, max, ave) to scalar +quantities. These are produced as output values which can be used as +input to other output commands. + +Computes that generate values to output :h5,link(compute) + +Every "compute"_compute.html in LAMMPS produces either global or +per-atom or local quantities. The quantities can be scalars or +vectors or arrays of data. The doc page for each compute command +describes what it produces. These values can be output using +the other commands described in this section. + +Fixes that generate values to output :h5,link(fix) + +Some "fixes"_fix.html in LAMMPS produces either global or per-atom or +local quantities which can be accessed by other commands. The +quantities can be scalars or vectors or arrays of data. The doc page +for each fix command tells whether it produces any output quantities +and describes them. These values can be output using the other +commands described in this section. + +Variables that generate values to output :h5,link(variable) + +Every "variables"_variable.html defined in an input script generates +either a global scalar value or a per-atom vector (only atom-style +variables) when it is accessed. The formulas used to define equal- +and atom-style variables can contain references to the thermodynamic +keywords and to global and per-atom data generated by computes, fixes, +and other variables. The values generated by variables can be output +using the other commands described in this section. + +Summary table of output options and data flow between commands :h5,link(table) + +This table summarizes the various commands that can be used for +generating output from LAMMPS. Each command produces output data of +some kind and/or writes data to a file. Some of the commands take +data from other commands as input. Thus you can link many of these +commands together in pipeline form, where data produced by one command +is used as input to another command and eventually written to the +screen or to a file. Note that to hook two commands together the +output and input data types must match, e.g. global/per-atom/local +data and scalar/vector/array data. + +Also note that, as described above, when a command takes a scalar as +input, that could be an element of a vector or array. Likewise a +vector input could be a column of an array. + +Command: Input: Output: +thermo_style custom: global scalars: screen, log file: +dump custom: per-atom vectors: dump file: +fix print: global scalar from variable: screen, file: +print: global scalar from variable: screen: +computes: N/A: global/per-atom/local scalar/vector/array: +fixes: N/A: global/per-atom/local scalar/vector/array: +variables: global scalars, per-atom vectors: global scalar, per-atom vector: +compute reduce: global/per-atom/local vectors: global scalar/vector: +fix ave/time: global scalars: global scalar/vector, file: +fix ave/spatial: per-atom vectors/arrays: global array, file: +fix ave/atom: per-atom vectors: per-atom vector/array: +:tb(s=:) :line diff --git a/doc/compute.html b/doc/compute.html index af262457a9..939b5e9f57 100644 --- a/doc/compute.html +++ b/doc/compute.html @@ -32,7 +32,12 @@ compute 3 all ke/atom Quantities calculated by a compute are instantaneous values, meaning they are calculated from information about atoms on the current timestep or iteration, though a compute may internally store some -information about a previous state of the system. +information about a previous state of the system. Defining a compute +does not perform a computation. Instead computes are invoked by other +LAMMPS commands as needed, e.g. to calculate a temperature needed for +a thermostat fix or to generate thermodynamic or dump file output. +See this howto section for a summary of +various LAMMPS output options, many of which involve computes.

The ID of a compute can only contain alphanumeric characters and underscores. @@ -109,9 +114,6 @@ variable. reduce command, or histogrammed by the fix ave/histo command. -

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, diff --git a/doc/compute.txt b/doc/compute.txt index ebda6a834f..7c3473194f 100644 --- a/doc/compute.txt +++ b/doc/compute.txt @@ -29,7 +29,12 @@ Define a computation that will be performed on a group of atoms. Quantities calculated by a compute are instantaneous values, meaning they are calculated from information about atoms on the current timestep or iteration, though a compute may internally store some -information about a previous state of the system. +information about a previous state of the system. Defining a compute +does not perform a computation. Instead computes are invoked by other +LAMMPS commands as needed, e.g. to calculate a temperature needed for +a thermostat fix or to generate thermodynamic or dump file output. +See this "howto section"_Section_howto.html#4_15 for a summary of +various LAMMPS output options, many of which involve computes. The ID of a compute can only contain alphanumeric characters and underscores. @@ -104,9 +109,6 @@ 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,