The fix ave/time command enables direct output to -a file and/or time-averaging of any global quantity. The user +a file and/or time-averaging of global scalars or vectors. 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) and individual per-atom values, a wide variety of quantities -can be time averaged and/or output in this way. The time-averaged +can be time averaged and/or output in this way. If the inputs are one +or more scalar values, then the fix generate a global scalar or vector +of output. If the inputs are one or more vector values, then the fix +generates a global vector or array of output. The time-averaged output of this fix can also be used as input to other output commands.
The fix ave/spatial command enables direct @@ -1161,7 +1164,7 @@ vector input could be a column of an array.
The file keyword allows a filename to be specified. Every Nfreq -timesteps, layer info will be written to a text file in the following -format. A line with the timestep and number of layers is written. -Then one line per layer is written, containing the layer ID (1-N), the -coordinate of the center of the layer, the number of atoms in the -layer, and one or more calculated values. The number of values in -each line corresponds to the number of values specified in the fix -ave/spatial command. The number of atoms and the value(s) are average -quantities. If the value of the units keyword is box or -lattice, the "coord" is printed in box units. If the value of the -units keyword is reduced, the "coord" is printed in reduced units -(0-1). -
The ave keyword determines how the layer values produced every Nfreq steps are averaged with layer values produced on previous steps that were multiples of Nfreq, before they are accessed by @@ -263,23 +250,34 @@ 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 file keyword allows a filename to be specified. Every Nfreq +timesteps, a section of layer info will be written to a text file in +the following format. A line with the timestep and number of layers +is written. Then one line per layer is written, containing the layer +ID (1-N), the coordinate of the center of the layer, the number of +atoms in the layer, and one or more calculated values. The number of +values in each line corresponds to the number of values specified in +the fix ave/spatial command. The number of atoms and the value(s) are +average quantities. If the value of the units keyword is box or +lattice, the "coord" is printed in box units. If the value of the +units keyword is reduced, the "coord" is printed in reduced units +(0-1). +
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: +values for each of these, so they do not need to be specified. +
+By default, these header 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. +name. The second line describes the two values that are printed at +the first of each section of output. In the third line the values are +replaced with the appropriate fields from the fix ave/spatial command.
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 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 +is when averaging is performed. The global array has rows = Nlayers +and columns = Nvalues+2. 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 diff --git a/doc/fix_ave_spatial.txt b/doc/fix_ave_spatial.txt index 7acd1cefcc..41111c3ab1 100644 --- a/doc/fix_ave_spatial.txt +++ b/doc/fix_ave_spatial.txt @@ -45,7 +45,7 @@ keyword = {norm} or {units} or {file} or {ave} or {title1} or {title2} or {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 + string = text to print as 3rd line of output file = column headings for values :pre :ule [Examples:] @@ -208,19 +208,6 @@ computed, i.e. Sample-quantity / Sample-count. The printed value for the layer is the average of the {Nrepeat} "average sample values", In other words it is an average of an average. -The {file} keyword allows a filename to be specified. Every {Nfreq} -timesteps, layer info will be written to a text file in the following -format. A line with the timestep and number of layers is written. -Then one line per layer is written, containing the layer ID (1-N), the -coordinate of the center of the layer, the number of atoms in the -layer, and one or more calculated values. The number of values in -each line corresponds to the number of values specified in the fix -ave/spatial command. The number of atoms and the value(s) are average -quantities. If the value of the {units} keyword is {box} or -{lattice}, the "coord" is printed in box units. If the value of the -{units} keyword is {reduced}, the "coord" is printed in reduced units -(0-1). - The {ave} keyword determines how the layer values produced every {Nfreq} steps are averaged with layer values produced on previous steps that were multiples of {Nfreq}, before they are accessed by @@ -247,23 +234,34 @@ 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 {file} keyword allows a filename to be specified. Every {Nfreq} +timesteps, a section of layer info will be written to a text file in +the following format. A line with the timestep and number of layers +is written. Then one line per layer is written, containing the layer +ID (1-N), the coordinate of the center of the layer, the number of +atoms in the layer, and one or more calculated values. The number of +values in each line corresponds to the number of values specified in +the fix ave/spatial command. The number of atoms and the value(s) are +average quantities. If the value of the {units} keyword is {box} or +{lattice}, the "coord" is printed in box units. If the value of the +{units} keyword is {reduced}, the "coord" is printed in reduced units +(0-1). + 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: +values for each of these, so they do not need to be specified. + +By default, these header 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. +name. The second line describes the two values that are printed at +the first of each section of output. In the third line the values are +replaced with the appropriate fields from the fix ave/spatial command. :line @@ -276,12 +274,12 @@ are relevant to this fix. 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 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 +is when averaging is performed. The global array has rows = Nlayers +and columns = Nvalues+2. 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 @@ -307,4 +305,3 @@ simulation box size doesn't change or if the {units} keyword is set to The option defaults are units = lattice, norm = all, no file output, and ave = one, title 1,2,3 = strings as described above. - diff --git a/doc/fix_ave_time.html b/doc/fix_ave_time.html index ba70478ce9..1ca34f67aa 100644 --- a/doc/fix_ave_time.html +++ b/doc/fix_ave_time.html @@ -29,32 +29,44 @@
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 - 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 +c_ID = global scalar or vector calculated by a compute with ID + c_ID[I] = Ith component of global vector or Ith column of global array calculated by a compute with ID + f_ID = global scalar or vector calculated by a fix with ID + f_ID[I] = Ith component of global vector or Ith column of global array calculated by a fix with ID v_name = global value calculated by an equal-style variable with name
file arg = filename +mode arg = scalar or vector + scalar = all input values are global scalars + vector = all input values are global vectors + file arg = filename filename = name of file to output time averages to ave args = one or running or window M one = output a 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 start args = Nstart - Nstart = start averaging on this timestep + Nstart = start averaging on this timestep + off arg = M = do not average this value + M = value # from 1 to Nvalues + 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 + title3 arg = string + string = text to print as 3rd line of output file, only for vector modeExamples:
fix 1 all ave/time 100 5 1000 c_myTemp c_thermo_temp file temp.profile -fix 1 all ave/time 100 5 1000 c_thermo_press[2] ave window 20 -fix 1 all ave/time 1 100 1000 f_indent f_indent[1] file temp.indent +fix 1 all ave/time 100 5 1000 c_thermo_press[2] ave window 20 & + title1 "My output values" +fix 1 all ave/time 1 100 1000 f_indent f_indent[1] file temp.indent off 1Description:
@@ -62,14 +74,13 @@ fix 1 all ave/time 1 100 1000 f_indent f_indent[1] file temp.indent timesteps, and average them over longer timescales. The resulting averages can be used by other output commands such as thermo_style -custom, and can also be written to a file. If no -averaging is done, this command is a convenient way to simply write -one or more desired quantities to a separate file. +custom, and can also be written to a file. Note +that if no time averaging is done, this command can simply be used as +a convenient way to output one or more desired quantities to a +separate file. -Each listed value is averaged independently. If written to a file, -then over time, one column of numbers is produced for each value. The -group specified with the command is ignored, since calculations are -performed by computes and fixes which store their own "group" +
The group specified with this command is ignored, since calculations +are performed by computes and fixes which store their own "group" definition,
Each listed value can be the result of a compute or @@ -90,6 +101,15 @@ individual fixes for info on which ones produce such values. be used with this fix. Variables of style atom cannot be used, since they produce per-atom values.
+The listed values must either be all global scalars or all global +vectors, depending on the setting of the mode option. In both +cases, the averaging is performed independently on every input +quantity. I.e. each input value and the elements of each input value +(if it is a vector) are averaged independently. +
+If mode = vector, then all the input values must be vectors of the +same length. +
The Nevery, Nrepeat, and Nfreq arguments specify on what @@ -111,49 +131,56 @@ averaging is done; values are simply generated on timesteps
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 global scalar calculated by the compute is used. If a -bracketed term is appended, the Nth vector value calculated by the -compute is used. Note that there is a compute -reduce command which can sum per-atom quantities -into a global scalar or vector which can thus be accessed by fix -ave/time. Or it can be a compute defined not in your input script, -but by thermodynamic output or other fixes such as -fix nvt or fix temp/rescale. -See the doc pages for these commands which give the IDs of these -computes. Users can also write code for their own compute styles and -add them to LAMMPS. +previously defined in the input script. If mode = scalar, then if +no bracketed term is appended, the global scalar calculated by the +compute is used. If a bracketed term is appended, the Ith element of +the global vector calculated by the compute is used. If mode = +vector, then if no bracketed term is appended, the global vector +calculated by the compute is used. If a bracketed term is appended, +the Ith column of the global array calculated by the compute is used. +
+Note that there is a compute reduce command +which can sum per-atom quantities into a global scalar or vector which +can thus be accessed by fix ave/time. Or it can be a compute defined +not in your input script, but by thermodynamic +output or other fixes such as fix +nvt or fix temp/rescale. See +the doc pages for these commands which give the IDs of these computes. +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 global scalar calculated by the fix is used. If a -bracketed term is appended, the Nth vector value 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. +previously defined in the input script. If mode = scalar, then if +no bracketed term is appended, the global scalar calculated by the fix +is used. If a bracketed term is appended, the Ith element of the +global vector calculated by the fix is used. If mode = vector, then +if no bracketed term is appended, the global vector calculated by the +fix is used. If a bracketed term is appended, the Ith column of the +global 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. Only equal-style -variables can be referenced. See the variable command -for details. Variables of style equal define a formula which can +been previously defined in the input script. Variables can only be +used as input for mode = scalar. Only equal-style variables can be +referenced. See the variable command for details. +Note that variables of style equal define a formula which can reference individual atom properties or thermodynamic keywords, or they can invoke other computes, fixes, or variables when they are -evaluated, so this is a very general means of generating quantities to +evaluated, so this is a very general means of specifying quantities to time average.
Additional optional keywords also affect the operation of this fix.
-The file keyword allows a filename to be specified. Each timestamp, -one quantity is written to the file for each value specified in the -fix ave/time command. The file is in a self-explanatory text format. -
-The ave keyword determines how the scalar and/or vector values -produced every Nfreq steps are averaged with values produced on -previous steps that were multiples of Nfreq, before they are -accessed by another output command or written to a file. +
The ave keyword determines how the values produced every Nfreq +steps are averaged with values produced on previous steps that were +multiples of Nfreq, before they are accessed by another output +command or written to a file.
If the ave setting is one, then the values produced on timesteps that are multiples of Nfreq are independent of each other; they are @@ -176,9 +203,54 @@ on step 10000 will be the average of the individual values on steps values if they are not available.
The start keyword specifies what timestep averaging will begin on. -The default is step 0. Often this value is 0.0, so setting start to -a larger value can avoid including a 0.0 in a running or windowed -average. +The default is step 0. Often input values can be 0.0 at time 0, so +setting start to a larger value can avoid including a 0.0 in a +running or windowed average. +
+The off keyword can be used to flag any of the input values. If a +value is flagged, it will not be time averaged. Instead the most +recent input value will always be stored and output. This is useful +if one of more of the inputs produced by a compute or fix or variable +are effectively constant or are simply current values. E.g. they are +being written to a file with other time-averaged values for purposes +of creating well-formatted output. +
+The file keyword allows a filename to be specified. Every Nfreq +steps, one quantity or vector of quantities is written to the file for +each input value specified in the fix ave/time command. For mode = +scalar, this means a single line is written each time output is +performed. Thus the file ends up to be a series of lines, i.e. one +column of numbers for each input value. For mode = vector, an array +of numbers is written each time output is performed. The number of +rows is the length of the input vectors, and the number of columns is +the number of values. Thus the file ends up to be a series of these +array sections. +
+The title1 and title2 and title3 keywords allow specification of +the strings that will be printed as the first 2 or 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, these header lines are as follows for mode = scalar: +
+# Time-averaged data for fix ID +# TimeStep value1 value2 ... ++In the first line, ID is replaced with the fix-ID. In the second line +the values are replaced with the appropriate fields from the fix +ave/time command. There is no third line in the header of the file, +so the title3 setting is ignored when mode = scalar. +
+By default, these header lines are as follows for mode = vector: +
+# Time-averaged data for fix ID +# TimeStep Number-of-rows +# Row value1 value2 ... ++In the first line, ID is replaced with the fix-ID. The second line +describes the two values that are printed at the first of each section +of output. In the third line the values are replaced with the +appropriate fields from the fix ave/time command.
@@ -188,20 +260,30 @@ average. files. None of the fix_modify options are relevant to this fix. -This fix produces a global scalar or vector which can be accessed by -various output commands. A scalar is -produced if only a single quantity is averaged by this fix. If two or -more quantities are averaged, then a vector of values is produced. -The global values can only be accessed on timesteps that are multiples -of Nfreq since that is when averaging is performed. Each value -(scalar or vector component) calculated by this fix may be either -"intensive" or "extensive". Intensive means the value is independent -of the number of atoms in the simulation. Extensive means the value -scales with the number of atoms in the simulation. If a compute or -fix provides the value being time averaged, then the compute or fix -determines whether the value is intensive or extensive; see the doc -page for that compute or fix for further info. Values produced by a -variable are whatever the variable calculates. +
This fix produces a global scalar or vector or array 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. +
+A scalar is produced if only a single input value is averaged and +mode = scalar. A vector is produced if multiple input values are +averaged for mode = scalar, or a single input value for mode = +vector. In the first case, the length of the vector is the number of +inputs. In the second case, the length of the vector is the same as +the length of the input vector. An array is produced if multiple +input values are averaged and mode = vector. The global array has +rows = length of the input vectors and columns = number of inputs. +
+If the fix prouduces a scalar or vector, then the scalar and each +element of the vector may be either "intensive" or "extensive". If +the fix produces an array, then all elements in the array will be +either "intensive" or "extensive". Intensive means the value is +independent of the number of atoms in the simulation. Extensive means +the value scales with the number of atoms in the simulation. If a +compute or fix provides the value being time averaged, then the +compute or fix determines whether the value is intensive or extensive; +see the doc page for that compute or fix for further info. Values +produced by a variable are whatever the variable calculates.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy @@ -217,6 +299,8 @@ ave/atom
Default: none
-The option defaults no file output, ave = one, and start = 0. +
The option defaults are mode = scalar, ave = one, start = 0, no file +output, title 1,2,3 = strings as described above, and no off settings +for any input values.