.. index:: fix ave/histo fix ave/histo command ===================== Syntax """""" .. parsed-literal:: fix ID group-ID ave/histo Nevery Nrepeat Nfreq lo hi Nbin value1 value2 ... keyword args ... * ID, group-ID are documented in :doc:`fix ` command * ave/histo = style name of this fix command * Nevery = use input values every this many timesteps * Nrepeat = # of times to use input values for calculating histogram * Nfreq = calculate histogram every this many timesteps * lo,hi = lo/hi bounds within which to histogram * Nbin = # of histogram bins * one or more input values can be listed * value = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID[N], f_ID, f_ID[N], v_name .. parsed-literal:: x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force 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 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 v_name = value(s) calculated by an equal-style or atom-style variable with name * zero or more keyword/arg pairs may be appended * keyword = *mode* or *file* or *ave* or *start* or *beyond* or *overwrite* or *title1* or *title2* or *title3* .. parsed-literal:: *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 *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 """""""" .. parsed-literal:: fix 1 all ave/histo 100 5 1000 0.5 1.5 50 c_myTemp file temp.histo ave running fix 1 all ave/histo 100 5 1000 -5 5 100 c_myArray[2] c_myArray[3] title1 "My output values" fix 1 all ave/histo 1 100 1000 -2.0 2.0 18 vx vy vz mode vector ave running beyond extra Description """"""""""" Use one or more values as inputs every few timesteps, histogram them, and average the histogram over longer timescales. The resulting histogram can be used by other :ref:`output commands `, and can also be written to a file. The group specified with this command is ignored for global and local input values. For per-atom input values, only atoms in the group contribute to the histogram. Note that regardless of the specified group, specified values may represent calculations performed by computes and fixes which store their own "group" definition. 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 an atom attribute (position, velocity, force component) or can be the result of a :doc:`compute ` or :doc:`fix ` or the evaluation of an equal-style or atom-style :doc:`variable `. The set of input values can be either all global, all per-atom, or all local quantities. Inputs of different kinds (e.g. global and per-atom) cannot be mixed. Atom attributes are per-atom 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. If *mode* = vector, then the input values may either be vectors or arrays. If a global array is listed, then it is the same as if the individual columns of the array had been listed one by one. E.g. these 2 fix ave/histo commands are equivalent, since the :doc:`compute com/molecule ` command creates a global array with 3 columns: .. parsed-literal:: compute myCOM all com/molecule fix 1 all ave/histo 100 1 100 c_myCOM file tmp1.com mode vector fix 2 all ave/histo 100 1 100 c_myCOM[1] c_myCOM[2] c_myCOM[3] file tmp2.com mode vector 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. ---------- 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 cannot overlap, i.e. Nfreq > (Nrepeat-1)*Nevery is required. 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 atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are self-explanatory. Note that other atom attributes can be used as inputs to this fix by using the :doc:`compute property/atom ` command and then specifying an input value from that compute. 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. Or if the compute calculates an array, all of the columns of the array are used as if they had been specified as individual vectors (see description above). If a bracketed term is appended, the Ith column of the global or per-atom or local array calculated by the compute is used. Note that there is a :doc:`compute reduce ` command which can sum per-atom quantities into a global scalar or vector which can thus be accessed by fix ave/histo. Or it can be a compute defined not in your input script, but by :doc:`thermodynamic output ` or other fixes such as :doc:`fix nvt ` or :doc:`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 :doc:`add them to LIGGGHTS(R)-PUBLIC `. 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. Or if the fix calculates an array, all of the columns of the array are used as if they had been specified as individual vectors (see description above). If a bracketed term is appended, the Ith column of the global or per-atom or local 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 :doc:`add them to LIGGGHTS(R)-PUBLIC `. 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, which produce a global value. If *mode* = vector, then only atom-style variables can be used, which produce a per-atom vector. See the :doc:`variable ` command for details. Note that variables of style *equal* and *atom* 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 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-atom or local vectors, or columns of global or per-atom or local arrays. 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 *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 :doc:`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 *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 *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. LIGGGHTS(R)-PUBLIC uses default values for each of these, so they do not need to be specified. By default, these header lines are as follows: .. parsed-literal:: # 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, fix_modify, output, run start/stop, minimize info """""""""""""""""""""""""""""""""""""""""""""""""""""""""" No information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix_modify ` options are relevant to this fix. This fix produces a global vector and global array which can be accessed by various :ref:`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: * 1 = total counts in the histogram * 2 = values that were not histogrammed (see *beyond* keyword) * 3 = min value of all input values, including ones not histogrammed * 4 = max value of all input values, including ones not histogrammed 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. The vector and array values calculated by this fix are all treated as "intensive". If this is not the case, e.g. due to histogramming per-atom input values, then you will need to account for that when interpreting the values produced by this fix. No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. Restrictions """""""""""" none Related commands """""""""""""""" :doc:`compute `, :doc:`fix ave/atom `, :doc:`fix ave/spatial `, :doc:`fix ave/time `, :doc:`variable `, :doc:`fix ave/correlate `, **Default:** none The option defaults are mode = scalar, ave = one, start = 0, no file output, beyond = ignore, and title 1,2,3 = strings as described above. .. _liws: http://www.cfdem.com .. _ld: Manual.html .. _lc: Section_commands.html#comm