fix ave/correlate command
Syntax
fix ID group-ID ave/correlate Nevery Nrepeat Nfreq value1 value2 ... keyword args ...
ID, group-ID are documented in fix command
ave/correlate = style name of this fix command
Nevery = use input values every this many timesteps
Nrepeat = # of correlation time windows to accumulate
Nfreq = calculate time window averages every this many timesteps
one or more input values can be listed
value = c_ID, c_ID[N], f_ID, f_ID[N], v_name
c_ID = global scalar calculated by a compute with ID c_ID[I] = Ith component of global vector calculated by a compute with ID, I can include wildcard (see below) f_ID = global scalar calculated by a fix with ID f_ID[I] = Ith component of global vector calculated by a fix with ID, I can include wildcard (see below) v_name = global value calculated by an equal-style variable with name v_name[I] = Ith component of a vector-style variable with name, I can include wildcard (see below)
zero or more keyword/arg pairs may be appended
keyword = type or ave or start or prefactor or file or overwrite or title1 or title2 or title3
type arg = auto or upper or lower or auto/upper or auto/lower or full auto = correlate each value with itself upper = correlate each value with each succeeding value lower = correlate each value with each preceding value auto/upper = auto + upper auto/lower = auto + lower full = correlate each value with every other value, including itself = auto + upper + lower ave args = one or running one = zero the correlation accumulation every Nfreq steps running = accumulate correlations continuously start args = Nstart Nstart = start accumulating correlations on this timestep prefactor args = value value = prefactor to scale all the correlation data by file arg = filename filename = name of file to output correlation data to overwrite arg = none = overwrite output file with only latest output title1 arg = string string = text to print as 1st line of output file 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
Examples
fix 1 all ave/correlate 5 100 1000 c_myTemp file temp.correlate
fix 1 all ave/correlate 1 50 10000 &
c_thermo_press[1] c_thermo_press[2] c_thermo_press[3] &
type upper ave running title1 "My correlation data"
fix 1 all ave/correlate 1 50 10000 c_thermo_press[*]
Description
Use one or more global scalar values as inputs every few timesteps, calculate time correlations between them at varying time intervals, and average the correlation data over longer timescales. The resulting correlation values can be time integrated by variables or used by other output commands such as thermo_style custom, and can also be written to a file. See the fix ave/correlate/long command for an alternate method for computing correlation functions efficiently over very long time windows.
The group specified with this command is ignored. However, note that specified values may represent calculations performed by computes and fixes which store their own “group” definitions.
Each listed value can be the result of a compute or fix or the evaluation of an equal-style or vector-style variable. In each case, the compute, fix, or variable must produce a global quantity, not a per-atom or local quantity. If you wish to spatial- or time-average or histogram per-atom quantities from a compute, fix, or variable, then see the fix ave/chunk, fix ave/atom, or fix ave/histo commands. If you wish to convert a per-atom quantity into a single global value, see the compute reduce command.
The input values must be all scalars. What kinds of correlations between input values are calculated is determined by the type keyword as discussed below.
Computes that produce global quantities are those which do not have the word atom in their style name. Only a few fixes produce global quantities. See the doc pages for individual fixes for info on which ones produce such values. Variables of style equal and vector are the only ones that can be used with this fix. Variables of style atom cannot be used, since they produce per-atom values.
For input values from a compute or fix or variable , the bracketed
index I can be specified using a wildcard asterisk with the index to
effectively specify multiple values. This takes the form “*” or
“*n” or “m*” or “m*n”. If
Using a wildcard is the same as if the individual elements of the vector had been listed one by one. For example, the following two fix ave/correlate commands are equivalent, since the compute pressure command creates a global vector with six values:
compute myPress all pressure NULL
fix 1 all ave/correlate 1 50 10000 c_myPress[*]
fix 1 all ave/correlate 1 50 10000 &
c_myPress[1] c_myPress[2] c_myPress[3] &
c_myPress[4] c_myPress[5] c_myPress[6]
Note
For a vector-style variable, only the wildcard forms “*n” or “m*n” are allowed. You must specify the upper bound, because vector-style variable lengths are not determined until the variable is evaluated. If n is specified larger than the vector length turns out to be, zeroes are output for missing vector values.
The
which is the correlation value between input values
For example, if
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
Note that there is a compute reduce command that can sum per-atom quantities into a global scalar or vector which can then be accessed by fix ave/correlate. It can also 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
Note that some fixes only produce their values on certain timesteps,
which must be compatible with
If a value begins with “v_”, a variable name must follow which has been
previously defined in the input script. Only equal-style or vector-style
variables can be referenced; the latter requires a bracketed term to specify
the
Additional optional keywords also affect the operation of this fix.
The type keyword determines which pairs of input values are
correlated with each other. For
If type is set to auto then each input value is correlated with itself (i.e.,
for , so ).If type is set to upper then each input value is correlated with every succeeding value (i.e.,
for , so ).If type is set to lower then each input value is correlated with every preceding value (i.e.,
for , so ).If type is set to auto/upper then each input value is correlated with itself and every succeeding value (i.e.,
for , so ).If type is set to auto/lower then each input value is correlated with itself and every preceding value (i.e.,
for , so ).If type is set to full then each input value is correlated with itself and every other value (i.e.,
for , so ).
The ave keyword determines what happens to the accumulation of correlation
samples every
If the ave setting is running, then the accumulation is never zeroed.
Thus the output of correlation data at any timestep is the average over samples
accumulated every
The start keyword specifies what time step the accumulation of correlation samples will begin on. The default is step 0. Setting it to a larger value can avoid adding non-equilibrated data to the correlation averages.
The prefactor keyword specifies a constant which will be used as a multiplier
on the correlation data after it is averaged. It is effectively a scale factor
on
The file keyword allows a filename to be specified. Every
The overwrite keyword will continuously overwrite the output file with the latest output, so that it only contains one timestep worth of output. This option can only be used with the ave running setting.
The title1, title2, and title3 keywords allow specification of the strings that will be printed as the first three 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:
# Time-correlated data for fix ID # TimeStep Number-of-time-windows # Index TimeDelta Ncount valueI*valueJ valueI*valueJ ...
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 value pairs are replaced with the appropriate fields from the fix ave/correlate command.
Let
As explained below, these data are output as one column of a global array, which is effectively the correlation matrix.
The trap function defined for equal-style variables can be used to perform a time integration of this vector of data, using a trapezoidal rule. This is useful for calculating various quantities which can be derived from time correlation data. If a normalization factor is needed for the time integration, it can be included in the variable formula or via the prefactor keyword.
Restart, fix_modify, output, run start/stop, minimize info
No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
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
For type = auto, the
columns are ordered:For type = upper, the
columns are ordered:For type = lower, the
columns are ordered:For type = auto/upper, the
columns are ordered:For type = auto/lower, the
columns are ordered:For type = full, the
columns are ordered:
The array values calculated by this fix are treated as extensive. If you need to divide them by the number of atoms, you must do this in a later processing step (e.g., when using them in a variable).
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.
Restrictions
none
Default
none
The option defaults are ave = one, type = auto, start = 0, no file output, title 1,2,3 = strings as described above, and prefactor = 1.0.