forked from lijiext/lammps
314 lines
15 KiB
HTML
314 lines
15 KiB
HTML
<HTML>
|
|
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
|
|
</CENTER>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<HR>
|
|
|
|
<H3>fix ave/histo command
|
|
</H3>
|
|
<P><B>Syntax:</B>
|
|
</P>
|
|
<PRE>fix ID group-ID ave/time Nevery Nrepeat Nfreq lo hi Nbin value1 value2 ... keyword args ...
|
|
</PRE>
|
|
<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command
|
|
|
|
<LI>ave/histo = style name of this fix command
|
|
|
|
<LI>Nevery = use input values every this many timesteps
|
|
|
|
<LI>Nrepeat = # of times to use input values for calculating histogram
|
|
|
|
<LI>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
|
|
|
|
<LI>value = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID[N], f_ID, f_ID[N], v_name
|
|
|
|
<PRE> 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
|
|
</PRE>
|
|
<LI>zero or more keyword/arg pairs may be appended
|
|
|
|
<LI>keyword = <I>mode</I> or <I>file</I> or <I>ave</I> or <I>start</I> or <I>beyond</I> or <I>title1</I> or <I>title2</I> or <I>title3</I>
|
|
|
|
<PRE> <I>mode</I> arg = <I>scalar</I> or <I>vector</I>
|
|
scalar = all input values are scalars
|
|
vector = all input values are vectors
|
|
<I>file</I> arg = filename
|
|
filename = name of file to output histogram(s) to
|
|
<I>ave</I> args = <I>one</I> or <I>running</I> or <I>window</I>
|
|
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
|
|
<I>start</I> args = Nstart
|
|
Nstart = start averaging on this timestep
|
|
<I>beyond</I> arg = <I>ignore</I> or <I>end</I> or <I>extra</I>
|
|
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
|
|
<I>title1</I> arg = string
|
|
string = text to print as 1st line of output file
|
|
<I>title2</I> arg = string
|
|
string = text to print as 2nd line of output file
|
|
<I>title3</I> arg = string
|
|
string = text to print as 3rd line of output file, only for vector mode
|
|
</PRE>
|
|
|
|
</UL>
|
|
<P><B>Examples:</B>
|
|
</P>
|
|
<PRE>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_thermo_press[2] c_thermo_press[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
|
|
</PRE>
|
|
<P><B>Description:</B>
|
|
</P>
|
|
<P>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 <A HREF = "Section_howto.html#4_15">output
|
|
commands</A>, and can also be written to a file.
|
|
</P>
|
|
<P>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, calculations may be performed by computes and fixes which store
|
|
their own "group" definition.
|
|
</P>
|
|
<P>A histogram is simply a count of the number of values that fall within
|
|
a histogram bin. <I>Nbins</I> are defined, with even spacing between <I>lo</I>
|
|
and <I>hi</I>. Values that fall outside the lo/hi bounds can be treated in
|
|
different ways; see the discussion of the <I>beyond</I> keyword below.
|
|
</P>
|
|
<P>Each input value can be an atom attribute (position, velocity, force
|
|
component) or can be the result of a <A HREF = "compute.html">compute</A> or
|
|
<A HREF = "fix.html">fix</A> or the evaluation of an equal-style or atom-style
|
|
<A HREF = "variable.html">variable</A>. 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. The input values
|
|
must also be either all scalar or all vector values, depending on the
|
|
setting of the <I>mode</I> keyword.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<HR>
|
|
|
|
<P>The <I>Nevery</I>, <I>Nrepeat</I>, and <I>Nfreq</I> arguments specify on what
|
|
timesteps the input values will be used in order to contribute to the
|
|
histogram. The final histogram is generated every <I>Nfreq</I> timesteps.
|
|
It is averaged over <I>Nrepeat</I> histograms, computed in the preceding
|
|
portion of the simulation every <I>Nevery</I> timesteps. <I>Nfreq</I> must be a
|
|
multiple of <I>Nevery</I> and <I>Nevery</I> must be non-zero even if <I>Nrepeat</I>
|
|
is 1. Also, the timesteps contributing to the histogram cannot
|
|
overlap, i.e. Nfreq > (Nrepeat-1)*Nevery is required.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<HR>
|
|
|
|
<P>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 <A HREF = "compute_property_atom.html">compute
|
|
property/atom</A> command and then specifying
|
|
an input value from that compute.
|
|
</P>
|
|
<P>If a value begins with "c_", a compute ID must follow which has been
|
|
previously defined in the input script. If <I>mode</I> = 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 <I>mode</I> =
|
|
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-atom or local
|
|
array calculated by the compute is used.
|
|
</P>
|
|
<P>Note that there is a <A HREF = "compute_reduce.html">compute reduce</A> 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 <A HREF = "thermo_style.html">thermodynamic
|
|
output</A> or other fixes such as <A HREF = "fix_nvt.html">fix
|
|
nvt</A> or <A HREF = "fix_temp_rescale.html">fix temp/rescale</A>. 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 <A HREF = "Section_modify.html">add them
|
|
to LAMMPS</A>.
|
|
</P>
|
|
<P>If a value begins with "f_", a fix ID must follow which has been
|
|
previously defined in the input script. If <I>mode</I> = 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 <I>mode</I> = 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-atom or local array
|
|
calculated by the fix is used.
|
|
</P>
|
|
<P>Note that some fixes only produce their values on certain timesteps,
|
|
which must be compatible with <I>Nevery</I>, else an error will result.
|
|
Users can also write code for their own fix styles and <A HREF = "Section_modify.html">add them to
|
|
LAMMPS</A>.
|
|
</P>
|
|
<P>If a value begins with "v_", a variable name must follow which has
|
|
been previously defined in the input script. If <I>mode</I> = scalar, then
|
|
only equal-style variables can be used, which produce a global value.
|
|
If <I>mode</I> = vector, then only atom-style variables can be used, which
|
|
produce a per-atom vector. See the <A HREF = "variable.html">variable</A> command
|
|
for details. Note that variables of style <I>equal</I> and <I>atom</I> 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.
|
|
</P>
|
|
<HR>
|
|
|
|
<P>Additional optional keywords also affect the operation of this fix.
|
|
</P>
|
|
<P>If the <I>mode</I> keyword is set to <I>scalar</I>, then all input values must
|
|
be global scalars, or elements of global vectors. If the <I>mode</I>
|
|
keyword is set to <I>vector</I>, then all input values must be global or
|
|
per-atom or local vectors, or columns of global or per-atom or local
|
|
arrays.
|
|
</P>
|
|
<P>The <I>beyond</I> keyword determines how input values that fall outside the
|
|
<I>lo</I> to <I>hi</I> bounds are treated. Values such that <I>lo</I> <= value <=
|
|
<I>hi</I> are assigned to one bin. Values on a bin boundary are assigned
|
|
to the lower of the 2 bins. If <I>beyond</I> is set to <I>ignore</I> then
|
|
values < <I>lo</I> and values > <I>hi</I> are ignored, i.e. they are not binned.
|
|
If <I>beyond</I> is set to <I>end</I> then values < <I>lo</I> are counted in the
|
|
first bin and values > <I>hi</I> are counted in the last bin. If <I>beyond</I>
|
|
is set to <I>extend</I> then two extra bins are created, so that there are
|
|
Nbins+2 total bins. Values < <I>lo</I> are counted in the first bin and
|
|
values > <I>hi</I> are counted in the last bin (Nbins+1). Values between
|
|
<I>lo</I> and <I>hi</I> (inclusive) are counted in bins 2 thru Nbins+1. The
|
|
"coordinate" stored and printed for these two extra bins is <I>lo</I> and
|
|
<I>hi</I>.
|
|
</P>
|
|
<P>The <I>ave</I> keyword determines how the histogram produced every <I>Nfreq</I>
|
|
steps are averaged with histograms produced on previous steps that
|
|
were multiples of <I>Nfreq</I>, before they are accessed by another output
|
|
command or written to a file.
|
|
</P>
|
|
<P>If the <I>ave</I> setting is <I>one</I>, then the histograms produced on
|
|
timesteps that are multiples of <I>Nfreq</I> are independent of each other;
|
|
they are output as-is without further averaging.
|
|
</P>
|
|
<P>If the <I>ave</I> setting is <I>running</I>, then the histograms produced on
|
|
timesteps that are multiples of <I>Nfreq</I> 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 <A HREF = "unfix.html">unfix</A> command, or by re-defining the fix by
|
|
re-specifying it.
|
|
</P>
|
|
<P>If the <I>ave</I> setting is <I>window</I>, then the histograms produced on
|
|
timesteps that are multiples of <I>Nfreq</I> 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.
|
|
</P>
|
|
<P>The <I>start</I> 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 <I>start</I> to a larger value can avoid including a 0.0 in
|
|
a running or windowed histogram.
|
|
</P>
|
|
<P>The <I>file</I> keyword allows a filename to be specified. Every <I>Nfreq</I>
|
|
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 <I>beyond</I> 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 <I>lo</I> and
|
|
<I>hi</I>), 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.
|
|
</P>
|
|
<P>The <I>title1</I> and <I>title2</I> and <I>title3</I> keywords allow specification of
|
|
the strings that will be printed as the first 3 lines of the output
|
|
file, assuming the <I>file</I> keyword was used. LAMMPS uses default
|
|
values for each of these, so they do not need to be specified.
|
|
</P>
|
|
<P>By default, these header lines are as follows:
|
|
</P>
|
|
<PRE># Histogram for fix ID
|
|
# TimeStep Number-of-bins Total-counts Missing-counts Min-value Max-value
|
|
# Bin Coord Count Count/Total
|
|
</PRE>
|
|
<P>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.
|
|
</P>
|
|
<HR>
|
|
|
|
<P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
|
|
</P>
|
|
<P>No information about this fix is written to <A HREF = "restart.html">binary restart
|
|
files</A>. None of the <A HREF = "fix_modify.html">fix_modify</A> options
|
|
are relevant to this fix.
|
|
</P>
|
|
<P>This fix produces a global vector and global array which can be
|
|
accessed by various <A HREF = "Section_howto.html#4_15">output commands</A>. The
|
|
values can only be accessed on timesteps that are multiples of <I>Nfreq</I>
|
|
since that is when a histogram is generated.
|
|
The global vector has 4 values:
|
|
</P>
|
|
<P>1 = total counts in the histogram
|
|
2 = values that were not histogrammed (see <I>beyond</I> keyword)
|
|
3 = min value of all input values, including ones not histogrammed
|
|
4 = max value of all input values, including ones not histogrammed
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<P>The vector and array values calculated by this fix are all treated as
|
|
"intensive", meaning they are independent of the number of atoms in
|
|
the simulation. 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.
|
|
</P>
|
|
<P>No parameter of this fix can be used with the <I>start/stop</I> keywords of
|
|
the <A HREF = "run.html">run</A> command. This fix is not invoked during <A HREF = "minimize.html">energy
|
|
minimization</A>.
|
|
</P>
|
|
<P><B>Restrictions:</B> none
|
|
</P>
|
|
<P><B>Related commands:</B>
|
|
</P>
|
|
<P><A HREF = "compute.html">compute</A>, <A HREF = "fix_ave_atom.html">fix ave/atom</A>, <A HREF = "fix_ave_spatial.html">fix
|
|
ave/spatial</A>, <A HREF = "fix_ave_time.html">fix ave/time</A>,
|
|
<A HREF = "variable.html">variable</A>,
|
|
</P>
|
|
<P><B>Default:</B> none
|
|
</P>
|
|
<P>The option defaults are mode = scalar, ave = one, start = 0, no file
|
|
output, beyond = ignore, and title 1,2,3 = strings as described above.
|
|
</P>
|
|
</HTML>
|