Syntax:
fix ID style Nevery Nrepeat Nfreq lo hi Nbin value1 value2 ... keyword args ...
x,y,z,vx,vy,vz = particle attribute (position, velocity component) c_ID = scalar or vector calculated by a compute with ID c_ID[I] = Ith component of vector or Ith column of array calculated by a compute with ID, I can include wildcard (see below) f_ID = scalar or vector calculated by a fix with ID f_ID[I] = Ith component of vector or Ith column of array calculated by a fix with ID, I can include wildcard (see below) v_name = value(s) calculated by an equal-style or particle-style or grid-style variable with name
mode arg = scalar or vector
scalar = all input values are scalars
vector = all input values are vectors
file arg = filename
filename = name of file to output histogram(s) to
region arg = region-ID for particle inclusion
mix arg = mixture-ID for particle inclusion
group arg = group-ID for grid cell inclusion
ave args = one or running or window
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
beyond arg = ignore or end or extra
ignore = ignore values outside histogram lo/hi bounds
end = count values outside histogram lo/hi bounds in end bins
extra = create 2 extra bins for value outside histogram lo/hi bounds
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, only for vector mode
Examples:
fix 1 ave/histo 100 5 1000 0.5 1.5 50 c_myGrid[*] file temp.histo ave running fix 1 ave/histo 100 5 1000 0 5 100 c_kePart "My output values" fix 1 ave/histo/weight 1 100 1000 -2.0 2.0 18 vx vy ave running beyond extra
Description:
Use one or more values as inputs every few timesteps to create a single histogram. The histogram can then be averaged over longer timescales. The resulting histogram can be used by other output commands, and can also be written to a file. The fix ave/histo/weight command has identical syntax to fix ave/histo, except that exactly two values must be specified. See details below.
A histogram is simply a count of the number of values that fall within a histogram bin. Nbins are defined, with even spacing between lo and hi. Values that fall outside the lo/hi bounds can be treated in different ways; see the discussion of the beyond keyword below.
Each input value can be a particle attribute (position, velocity), or can be the result of a compute or fix that produces global or per-particle or per-grid quantities, or the evaluation of an equal-style or particle-style or grid-style variable. The set of input values can be either all global, all per-particle, or all per-grid quantities. Inputs of different kinds (e.g. global and per-particle) cannot be mixed. Particle attributes are per-particle vector values. See the doc page for individual "compute" and "fix" commands to see what kinds of quantities they generate.
The input values must either be all scalars or all vectors (or arrays), depending on the setting of the mode keyword.
Note that the output of this command is a single histogram for all input values combined together, not one histogram per input value. See below for details on the format of the output of this fix.
If mode = scalar, then the input values must be scalars, or vectors with a bracketed term appended, indicating the Ith value of the vector is used.
If mode = vector, then the input values must be vectors, or arrays with a bracketed term appended, indicating the Ith column of the array is used.
Note that for values from a compute or fix, 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 "n*" or "m*n". If N = the size of the vector (for mode = scalar) or the number of columns in the array (for mode = vector), then an asterisk with no numeric values means all indices from 1 to N. A leading asterisk means all indices from 1 to n (inclusive). A trailing asterisk means all indices from n to N (inclusive). A middle asterisk means all indices from m to n (inclusive).
Using a wildcard is the same as if the individual elements of the vector or columns of the array had been listed one by one. E.g. these 2 fix ave/histo commands are equivalent, since the compute grid command creates a per-grid array with 3 columns:
compute myGrid grid all all u v w fix 1 ave/histo 100 1 100 c_myGrid file tmp1.grid mode vector fix 2 ave/histo 100 1 100 c_myGrid[1] c_myGrid[2] c_myGrid[3] file tmp2.grid mode vector
If the fix ave/histo/weight command is used, exactly two values must be specified. If the values are vectors, they must be the same length. The first value (a scalar or vector) is what is histogrammed into bins, in the same manner the fix ave/histo command operates. The second value (a scalar or vector) is used as a "weight". This means that instead of each value tallying a "1" to its bin, the corresponding weight is tallied. E.g. the Nth entry in the first vector tallies the Nth entry (weight) in the second vector.
The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the input values will be used in order to contribute to the histogram. The final histogram is generated on timesteps that are multiple of Nfreq. It is averaged over Nrepeat histograms, computed in the preceding portion of the simulation every Nevery timesteps. Nfreq must be a multiple of Nevery and Nevery must be non-zero even if Nrepeat is 1. Also, the timesteps contributing to the histogram value cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then input values on timesteps 90,92,94,96,98,100 will be used to compute the final histogram on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on timestep 200, etc. If Nrepeat=1 and Nfreq = 100, then no time averaging of the histogram is done; a histogram is simply generated on timesteps 100,200,etc.
The particle attribute values (x,y,z,vx,vy,vz) are self-explanatory.
If a value begins with "c_", a compute ID must follow which has been 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 or per-atom or local vector calculated by the compute is used. If a bracketed term is appended, the Ith column of the global or per-particle or per-grid array calculated by the compute is used. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values.
Note that there is a compute reduce command which can sum per-particle or per-grid or per-surf quantities into a global scalar or vector which can thus be accessed by fix ave/histo. Users can also write code for their own compute styles and add them to SPARTA.
If a value begins with "f_", a fix ID must follow which has been 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 or per-atom or local vector calculated by the fix is used. If a bracketed term is appended, the Ith column of the global or per-particle or per-grid array calculated by the fix is used. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values.
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 SPARTA.
If a value begins with "v_", a variable name must follow which has been previously defined in the input script. If mode = scalar, then only equal-style variables can be used. If mode = vector, then only particle-style or grid-style variables can be used, which produce per-particle per-grid vectors respectively. See the variable command for details.
Note that variables of style equal, particle, and grid define a formula which can reference individual particle properties or stats output keywords, or they can invoke other computes, fixes, or variables when they are evaluated, so this is a very general means of specifying quantities to histogram.
Additional optional keywords also affect the operation of this fix.
If the mode keyword is set to scalar, then all input values must be global scalars, or elements of global vectors. If the mode keyword is set to vector, then all input values must be global or per-particle or per-grid vectors, or columns of global or per-particle or per-grid arrays.
The file keyword allows a filename to be specified. Every Nfreq steps, one histogram is written to the file. This includes a leading line that contains the timestep, number of bins, the total count of values contributing to the histogram, the count of values that were not histogrammed (see the beyond keyword), the minimum value encountered, and the maximum value encountered. The min/max values include values that were not histogrammed. Following the leading line, one line per bin is written into the file. Each line contains the bin #, the coordinate for the center of the bin (between lo and hi), the count of values in the bin, and the normalized count. The normalized count is the bin count divided by the total count (not including values not histogrammed), so that the normalized values sum to 1.0 across all bins.
The region, mix, and group keywords limit which particles or grid cells are included in the histogramming.
The region keyword only applies to per-particle histogramming. Only particles in the specified region-ID are included in the histogram. See the region command for details of how geometric regions are defined.
The mix keyword only applies to per-particle histogramming. Only particles whose species are in the specified mixture-ID are included in the histogram, which allows for only a subset of species to be included. See the mixture command for details of how mixtures are defined.
The group keyword only applies to per-grid cell histogramming. Only grid cells in the grid group specified by group-ID are included in the histogram. See the grid group command for details of how grid groups are defined.
The ave keyword determines how the histogram produced every Nfreq steps are averaged with histograms 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 histograms produced on timesteps that are multiples of Nfreq are independent of each other; they are output as-is without further averaging.
If the ave setting is running, then the histograms produced on timesteps that are multiples of Nfreq are summed and averaged in a cumulative sense before being output. Each bin value in the histogram is thus the average of the bin value produced on that timestep with all preceding values for the same bin. This running average begins when the fix is defined; it can only be restarted by deleting the fix via the unfix command, or by re-defining the fix by re-specifying it.
If the ave setting is window, then the histograms produced on timesteps that are multiples of Nfreq are summed within a moving "window" of time, so that the last M histograms are used to produce the output. E.g. if M = 3 and Nfreq = 1000, then the output on step 10000 will be the combined histogram of the individual histograms on steps 8000,9000,10000. Outputs on early steps will be sums over less than M histograms if they are not available.
The start keyword specifies what timestep histogramming will begin on. 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 histogram.
The beyond keyword determines how input values that fall outside the lo to hi bounds are treated. Values such that lo <= value <= hi are assigned to one bin. Values on a bin boundary are assigned to the lower of the 2 bins. If beyond is set to ignore then values < lo and values > hi are ignored, i.e. they are not binned. If beyond is set to end then values < lo are counted in the first bin and values > hi are counted in the last bin. If beyond is set to extend then two extra bins are created, so that there are Nbins+2 total bins. Values < lo are counted in the first bin and values > hi are counted in the last bin (Nbins+1). Values between lo and hi (inclusive) are counted in bins 2 thru Nbins+1. The "coordinate" stored and printed for these two extra bins is lo and hi.
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 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. SPARTA uses default values for each of these, so they do not need to be specified.
By default, these header lines are as follows:
# Histogram for fix ID # TimeStep Number-of-bins Total-counts Missing-counts Min-value Max-value # Bin Coord Count Count/Total
In the first line, ID is replaced with the fix-ID. The second line describes the six values that are printed at the first of each section of output. The third describes the 4 values printed for each bin in the histogram.
Restart, output info:
No information about this fix is written to binary restart files.
This fix produces a global vector and global 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 a histogram is generated. The global vector has 4 values:
The global array has # of rows = Nbins and # of columns = 3. The first column has the bin coordinate, the 2nd column has the count of values in that histogram bin, and the 3rd column has the bin count divided by the total count (not including missing counts), so that the values in the 3rd column sum to 1.0.
Styles with a kk suffix are functionally the same as the corresponding style without the suffix. They have been optimized to run faster, depending on your available hardware, as discussed in the Accelerating SPARTA section of the manual. The accelerated styles take the same arguments and should produce the same results, except for different random number, round-off and precision issues.
These accelerated styles are part of the KOKKOS package. They are only enabled if SPARTA was built with that package. See the Making SPARTA section for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix command-line switch when you invoke SPARTA, or you can use the suffix command in your input script.
See the Accelerating SPARTA section of the manual for more instructions on how to use the accelerated styles effectively.
Restrictions: none
Related commands:
compute, fix ave/time, variable
Default:
The option defaults are mode = scalar, ave = one, start = 0, no file output, no region/mixture/group restriction on inclusion of particles or grid cells, beyond = ignore, and title 1,2,3 = strings as described above.