diff --git a/doc/compute.html b/doc/compute.html
index beca436ef..af262457a 100644
--- a/doc/compute.html
+++ b/doc/compute.html
@@ -1,158 +1,212 @@
<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>compute command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>compute ID group-ID style args
</PRE>
<UL><LI>ID = user-assigned name for the computation
<LI>group-ID = ID of the group of atoms to perform the computation on
<LI>style = one of a list of possible style names (see below)
<LI>args = arguments used by a particular style
</UL>
<P><B>Examples:</B>
</P>
<PRE>compute 1 all temp
compute newtemp flow temp/partial 1 1 0
compute 3 all ke/atom
</PRE>
<P><B>Description:</B>
</P>
-<P>Create a computation that will be performed on a group of atoms.
+<P>Define a computation that will be performed on a group of atoms.
Quantities calculated by a compute are instantaneous values, meaning
they are calculated from information about atoms on the current
-timestep or iteration. There are two kinds of computes, "global"
-computes that calculate one or more values for the entire group of
-atoms, and "per-atom" computes that calculate one or more values for
-each atom in the group. The latter has the word "atom" in its style
-name.
-</P>
-<P>In LAMMPS, a "compute" can be used in several ways. The results of
-global computes can be output via the <A HREF = "thermo_style.html">thermo_style
+timestep or iteration, though a compute may internally store some
+information about a previous state of the system.
+</P>
+<P>The ID of a compute can only contain alphanumeric characters and
+underscores.
+</P>
+<HR>
+
+<P>Computes calculate one of three styles of quantities: global,
+per-atom, or local. A global quantity is one or more system-wide
+values, e.g. the temperature of the system. A per-atom quantity is
+one or more values per atom, e.g. the kinetic energy of each atom.
+Per-atom values are set to 0.0 for atoms not in the specified compute
+group. Local quantities are calculated by each processor based on the
+atoms it owns, but there may be zero or more per atom, e.g. a list of
+bond distances. Computes that produce per-atom quantities have the
+word "atom" in their style, e.g. <I>ke/atom</I>. Computes that produce
+local quantities have the word "local" in their style,
+e.g. <I>bond/local</I>. Styles with neither "atom" or "local" in their
+style produce global quantities.
+</P>
+<P>Note that a single compute produces either global or per-atom or local
+quantities, but never more than one of these.
+</P>
+<P>Global, per-atom, and local quantities each come in three kinds: a
+single scalar value, a vector of values, or a 2d array of values. The
+doc page for each compute describes the style and kind of values it
+produces, e.g. a per-atom vector. Some computes produce more than one
+kind of a single style, e.g. a global scalar and a global vector.
+</P>
+<P>When a compute quantity is accessed, as in many of the output commands
+discussed below, it can be referenced via the following bracket
+notation, where ID is the ID of the compute:
+</P>
+<DIV ALIGN=center><TABLE BORDER=1 >
+<TR><TD >c_ID </TD><TD > entire scalar, vector, or array</TD></TR>
+<TR><TD >c_ID[I] </TD><TD > one element of vector, one column of array</TD></TR>
+<TR><TD >c_ID[I][J] </TD><TD > one element of array
+</TD></TR></TABLE></DIV>
+
+<P>In other words, using one bracket reduces the dimension of the
+quantity once (vector -> scalar, array -> vector). Using two brackets
+reduces the dimension twice (array -> scalar). Thus a command that
+uses scalar compute values as input can also process elements of a
+vector or array.
+</P>
+<P>Note that commands and <A HREF = "variable.html">variables</A> which use compute
+quantities typically do not allow for all kinds, e.g. a command may
+require a vector of values, not a scalar. This means there is no
+ambiguity about referring to a compute quantity as c_ID even if it
+produces, for example, both a scalar and vector. The doc pages for
+various commands explain the details.
+</P>
+<HR>
+
+<P>In LAMMPS, the values generated by a compute can be used in several
+ways:
+</P>
+<UL><LI>The results of computes that calculate a global temperature or
+pressure can be used by fixes that do thermostatting or barostatting
+or when atom velocities are created.
+
+<LI>Global values can be output via the <A HREF = "thermo_style.html">thermo_style
custom</A> or <A HREF = "fix_ave_time.html">fix ave/time</A> command.
Or the values can be referenced in a <A HREF = "variable.html">variable equal</A> or
-<A HREF = "variable.html">variable atom</A> command. The results of computes that
-calculate a global temperature or pressure can be used by fixes that
-do thermostatting or barostatting and when atom velocities are
-created.
-</P>
-<P>The results of per-atom computes that calculate a per-atom vector or
-array can be output via the <A HREF = "dump.html">dump custom</A> command or the
-<A HREF = "fix_ave_spatial.html">fix ave/spatial</A> command. Or the per-atom
-values can be time-averaged via the <A HREF = "fix_ave_atom.html">fix ave/atom</A>
-command and then output via the <A HREF = "dump.html">dump custom</A> or <A HREF = "fix_ave_spatial.html">fix
-ave/spatial</A> commands. Or the per-atom values
-can be referenced in a <A HREF = "variable.html">variable atom</A> command. Note
-that the value of per-atom computes will be 0.0 for atoms not in the
-specified compute group.
-</P>
+<A HREF = "variable.html">variable atom</A> command.
+
+<LI>Per-atom values can be output via the <A HREF = "dump.html">dump custom</A> command
+or the <A HREF = "fix_ave_spatial.html">fix ave/spatial</A> command. Or they can be
+time-averaged via the <A HREF = "fix_ave_atom.html">fix ave/atom</A> command or
+reduced by the <A HREF = "compute_reduce.html">compute reduce</A> command. Or the
+per-atom values can be referenced in an <A HREF = "variable.html">atom-style
+variable</A>.
+
+<LI>Local values can be reduced by the <A HREF = "compute_reduce.html">compute
+reduce</A> command, or histogrammed by the <A HREF = "fix_ave_histo.html">fix
+ave/histo</A> command.
+</UL>
<P>See this <A HREF = "Section_howto.html#4_15">howto section</A> for a summary of
various LAMMPS output options, many of which involve computes.
</P>
-<P>The ID of a compute can only contain alphanumeric characters and
-underscores.
-</P>
<P>The results of computes that calculate global quantities can be either
"intensive" or "extensive" values. Intensive means the value is
independent of the number of atoms in the simulation,
e.g. temperature. Extensive means the value scales with the number of
atoms in the simulation, e.g. total rotational kinetic energy.
<A HREF = "thermo_style.html">Thermodynamic output</A> will normalize extensive
values depending on the "thermo_modify norm" setting. But if a
compute value is accessed in another way, e.g. by a
<A HREF = "variable.html">variable</A>, you may need to know whether it is an
intensive or extensive value. See the doc page for individual
computes for further info.
</P>
-<P>LAMMPS creates its own global computes for thermodynamic output.
+<HR>
+
+<P>LAMMPS creates its own computes internally for thermodynamic output.
Three computes are always created, named "thermo_temp",
"thermo_press", and "thermo_pe", as if these commands had been invoked
in the input script:
</P>
<PRE>compute thermo_temp all temp
compute thermo_press all pressure thermo_temp
compute thermo_pe all pe
</PRE>
<P>Additional computes for other quantities are created if the thermo
style requires it. See the documentation for the
<A HREF = "thermo_style.html">thermo_style</A> command.
</P>
<P>Fixes that calculate temperature or pressure, i.e. for thermostatting
or barostatting, may also create computes. These are discussed in the
documentation for specific <A HREF = "fix.html">fix</A> commands.
</P>
-<P>In all these cases, the default computes can be replaced by computes
-defined by the user in the input script, as described by the
-<A HREF = "thermo_modify.html">thermo_modify</A> and <A HREF = "fix_modify.html">fix modify</A>
-commands.
+<P>In all these cases, the default computes LAMMPS creates can be
+replaced by computes defined by the user in the input script, as
+described by the <A HREF = "thermo_modify.html">thermo_modify</A> and <A HREF = "fix_modify.html">fix
+modify</A> commands.
</P>
<P>Properties of either a default or user-defined compute can be modified
via the <A HREF = "compute_modify.html">compute_modify</A> command.
</P>
<P>Computes can be deleted with the <A HREF = "uncompute.html">uncompute</A> command.
</P>
<P>Code for new computes can be added to LAMMPS (see <A HREF = "Section_modify.html">this
section</A> of the manual) and the results of their
calculations accessed in the various ways described above.
</P>
+<HR>
+
<P>Each compute style has its own doc page which describes its arguments
and what it does. Here is an alphabetic list of compute styles
available in LAMMPS:
</P>
<UL><LI><A HREF = "compute_centro_atom.html">centro/atom</A> - centro-symmetry parameter for each atom
<LI><A HREF = "compute_cna_atom.html">cna/atom</A> - common neighbor analysis (CNA) for each atom
<LI><A HREF = "compute_com.html">com</A> - center-of-mass of group of atoms
<LI><A HREF = "compute_coord_atom.html">coord/atom</A> - coordination number for each atom
<LI><A HREF = "compute_damage_atom.html">damage/atom</A> - Peridynamic damage for each atom
<LI><A HREF = "compute_displace_atom.html">displace/atom</A> - displacement of each atom
<LI><A HREF = "compute_erotate_asphere.html">erotate/asphere</A> - rotational energy of aspherical particles
<LI><A HREF = "compute_erotate_sphere.html">erotate/sphere</A> - rotational energy of spherical particles
<LI><A HREF = "compute_event_displace.html">event/displace</A> - detect event on atom displacement
<LI><A HREF = "compute_group_group.html">group/group</A> - energy/force between two groups of atoms
<LI><A HREF = "compute_gyration.html">gyration</A> - radius of gyration of group of atoms
<LI><A HREF = "compute_heat_flux.html">heat/flux</A> - heat flux through a group of atoms
<LI><A HREF = "compute_ke.html">ke</A> - translational kinetic energy
<LI><A HREF = "compute_ke_atom.html">ke/atom</A> - kinetic energy for each atom
<LI><A HREF = "compute_msd.html">msd</A> - mean-squared displacement of group of atoms
<LI><A HREF = "compute_pe.html">pe</A> - potential energy
<LI><A HREF = "compute_pe_atom.html">pe/atom</A> - potential energy for each atom
<LI><A HREF = "compute_pressure.html">pressure</A> - total pressure and pressure tensor
<LI><A HREF = "compute_reduce.html">reduce</A> - combine per-atom quantities into a single global value
<LI><A HREF = "compute_reduce.html">reduce/region</A> - same as compute reduce, within a region
<LI><A HREF = "compute_stress_atom.html">stress/atom</A> - stress tensor for each atom
<LI><A HREF = "compute_temp.html">temp</A> - temperature of group of atoms
<LI><A HREF = "compute_temp_asphere.html">temp/asphere</A> - temperature of aspherical particles
<LI><A HREF = "compute_temp_com.html">temp/com</A> - temperature after subtracting center-of-mass velocity
<LI><A HREF = "compute_temp_deform.html">temp/deform</A> - temperature excluding box deformation velocity
<LI><A HREF = "compute_temp_partial.html">temp/partial</A> - temperature excluding one or more dimensions of velocity
<LI><A HREF = "compute_temp_profile.html">temp/profile</A> - temperature excluding a binned velocity profile
<LI><A HREF = "compute_temp_ramp.html">temp/ramp</A> - temperature excluding ramped velocity component
<LI><A HREF = "compute_temp_region.html">temp/region</A> - temperature of a region of atoms
<LI><A HREF = "compute_temp_sphere.html">temp/sphere</A> - temperature of spherical particles
</UL>
<P>There are also additional compute styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to
the individual styles are given in the compute section of <A HREF = "Section_commands.html#3_5">this
page</A>.
</P>
<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "uncompute.html">uncompute</A>, <A HREF = "compute_modify.html">compute_modify</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>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/compute.txt b/doc/compute.txt
index b834ccfba..ebda6a834 100644
--- a/doc/compute.txt
+++ b/doc/compute.txt
@@ -1,153 +1,205 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
compute command :h3
[Syntax:]
compute ID group-ID style args :pre
ID = user-assigned name for the computation
group-ID = ID of the group of atoms to perform the computation on
style = one of a list of possible style names (see below)
args = arguments used by a particular style :ul
[Examples:]
compute 1 all temp
compute newtemp flow temp/partial 1 1 0
compute 3 all ke/atom :pre
[Description:]
-Create a computation that will be performed on a group of atoms.
+Define a computation that will be performed on a group of atoms.
Quantities calculated by a compute are instantaneous values, meaning
they are calculated from information about atoms on the current
-timestep or iteration. There are two kinds of computes, "global"
-computes that calculate one or more values for the entire group of
-atoms, and "per-atom" computes that calculate one or more values for
-each atom in the group. The latter has the word "atom" in its style
-name.
-
-In LAMMPS, a "compute" can be used in several ways. The results of
-global computes can be output via the "thermo_style
+timestep or iteration, though a compute may internally store some
+information about a previous state of the system.
+
+The ID of a compute can only contain alphanumeric characters and
+underscores.
+
+:line
+
+Computes calculate one of three styles of quantities: global,
+per-atom, or local. A global quantity is one or more system-wide
+values, e.g. the temperature of the system. A per-atom quantity is
+one or more values per atom, e.g. the kinetic energy of each atom.
+Per-atom values are set to 0.0 for atoms not in the specified compute
+group. Local quantities are calculated by each processor based on the
+atoms it owns, but there may be zero or more per atom, e.g. a list of
+bond distances. Computes that produce per-atom quantities have the
+word "atom" in their style, e.g. {ke/atom}. Computes that produce
+local quantities have the word "local" in their style,
+e.g. {bond/local}. Styles with neither "atom" or "local" in their
+style produce global quantities.
+
+Note that a single compute produces either global or per-atom or local
+quantities, but never more than one of these.
+
+Global, per-atom, and local quantities each come in three kinds: a
+single scalar value, a vector of values, or a 2d array of values. The
+doc page for each compute describes the style and kind of values it
+produces, e.g. a per-atom vector. Some computes produce more than one
+kind of a single style, e.g. a global scalar and a global vector.
+
+When a compute quantity is accessed, as in many of the output commands
+discussed below, it can be referenced via the following bracket
+notation, where ID is the ID of the compute:
+
+c_ID | entire scalar, vector, or array
+c_ID\[I\] | one element of vector, one column of array
+c_ID\[I\]\[J\] | one element of array :tb(s=|)
+
+In other words, using one bracket reduces the dimension of the
+quantity once (vector -> scalar, array -> vector). Using two brackets
+reduces the dimension twice (array -> scalar). Thus a command that
+uses scalar compute values as input can also process elements of a
+vector or array.
+
+Note that commands and "variables"_variable.html which use compute
+quantities typically do not allow for all kinds, e.g. a command may
+require a vector of values, not a scalar. This means there is no
+ambiguity about referring to a compute quantity as c_ID even if it
+produces, for example, both a scalar and vector. The doc pages for
+various commands explain the details.
+
+:line
+
+In LAMMPS, the values generated by a compute can be used in several
+ways:
+
+The results of computes that calculate a global temperature or
+pressure can be used by fixes that do thermostatting or barostatting
+or when atom velocities are created. :ulb,l
+
+Global values can be output via the "thermo_style
custom"_thermo_style.html or "fix ave/time"_fix_ave_time.html command.
Or the values can be referenced in a "variable equal"_variable.html or
-"variable atom"_variable.html command. The results of computes that
-calculate a global temperature or pressure can be used by fixes that
-do thermostatting or barostatting and when atom velocities are
-created.
-
-The results of per-atom computes that calculate a per-atom vector or
-array can be output via the "dump custom"_dump.html command or the
-"fix ave/spatial"_fix_ave_spatial.html command. Or the per-atom
-values can be time-averaged via the "fix ave/atom"_fix_ave_atom.html
-command and then output via the "dump custom"_dump.html or "fix
-ave/spatial"_fix_ave_spatial.html commands. Or the per-atom values
-can be referenced in a "variable atom"_variable.html command. Note
-that the value of per-atom computes will be 0.0 for atoms not in the
-specified compute group.
+"variable atom"_variable.html command. :l
+
+Per-atom values can be output via the "dump custom"_dump.html command
+or the "fix ave/spatial"_fix_ave_spatial.html command. Or they can be
+time-averaged via the "fix ave/atom"_fix_ave_atom.html command or
+reduced by the "compute reduce"_compute_reduce.html command. Or the
+per-atom values can be referenced in an "atom-style
+variable"_variable.html. :l
+
+Local values can be reduced by the "compute
+reduce"_compute_reduce.html command, or histogrammed by the "fix
+ave/histo"_fix_ave_histo.html command. :l,ule
See this "howto section"_Section_howto.html#4_15 for a summary of
various LAMMPS output options, many of which involve computes.
-The ID of a compute can only contain alphanumeric characters and
-underscores.
-
The results of computes that calculate global quantities can be either
"intensive" or "extensive" values. Intensive means the value is
independent of the number of atoms in the simulation,
e.g. temperature. Extensive means the value scales with the number of
atoms in the simulation, e.g. total rotational kinetic energy.
"Thermodynamic output"_thermo_style.html will normalize extensive
values depending on the "thermo_modify norm" setting. But if a
compute value is accessed in another way, e.g. by a
"variable"_variable.html, you may need to know whether it is an
intensive or extensive value. See the doc page for individual
computes for further info.
-LAMMPS creates its own global computes for thermodynamic output.
+:line
+
+LAMMPS creates its own computes internally for thermodynamic output.
Three computes are always created, named "thermo_temp",
"thermo_press", and "thermo_pe", as if these commands had been invoked
in the input script:
compute thermo_temp all temp
compute thermo_press all pressure thermo_temp
compute thermo_pe all pe :pre
Additional computes for other quantities are created if the thermo
style requires it. See the documentation for the
"thermo_style"_thermo_style.html command.
Fixes that calculate temperature or pressure, i.e. for thermostatting
or barostatting, may also create computes. These are discussed in the
documentation for specific "fix"_fix.html commands.
-In all these cases, the default computes can be replaced by computes
-defined by the user in the input script, as described by the
-"thermo_modify"_thermo_modify.html and "fix modify"_fix_modify.html
-commands.
+In all these cases, the default computes LAMMPS creates can be
+replaced by computes defined by the user in the input script, as
+described by the "thermo_modify"_thermo_modify.html and "fix
+modify"_fix_modify.html commands.
Properties of either a default or user-defined compute can be modified
via the "compute_modify"_compute_modify.html command.
Computes can be deleted with the "uncompute"_uncompute.html command.
Code for new computes can be added to LAMMPS (see "this
section"_Section_modify.html of the manual) and the results of their
calculations accessed in the various ways described above.
+:line
+
Each compute style has its own doc page which describes its arguments
and what it does. Here is an alphabetic list of compute styles
available in LAMMPS:
"centro/atom"_compute_centro_atom.html - centro-symmetry parameter for each atom
"cna/atom"_compute_cna_atom.html - common neighbor analysis (CNA) for each atom
"com"_compute_com.html - center-of-mass of group of atoms
"coord/atom"_compute_coord_atom.html - coordination number for each atom
"damage/atom"_compute_damage_atom.html - Peridynamic damage for each atom
"displace/atom"_compute_displace_atom.html - displacement of each atom
"erotate/asphere"_compute_erotate_asphere.html - rotational energy of aspherical particles
"erotate/sphere"_compute_erotate_sphere.html - rotational energy of spherical particles
"event/displace"_compute_event_displace.html - detect event on atom displacement
"group/group"_compute_group_group.html - energy/force between two groups of atoms
"gyration"_compute_gyration.html - radius of gyration of group of atoms
"heat/flux"_compute_heat_flux.html - heat flux through a group of atoms
"ke"_compute_ke.html - translational kinetic energy
"ke/atom"_compute_ke_atom.html - kinetic energy for each atom
"msd"_compute_msd.html - mean-squared displacement of group of atoms
"pe"_compute_pe.html - potential energy
"pe/atom"_compute_pe_atom.html - potential energy for each atom
"pressure"_compute_pressure.html - total pressure and pressure tensor
"reduce"_compute_reduce.html - combine per-atom quantities into a single global value
"reduce/region"_compute_reduce.html - same as compute reduce, within a region
"stress/atom"_compute_stress_atom.html - stress tensor for each atom
"temp"_compute_temp.html - temperature of group of atoms
"temp/asphere"_compute_temp_asphere.html - temperature of aspherical particles
"temp/com"_compute_temp_com.html - temperature after subtracting center-of-mass velocity
"temp/deform"_compute_temp_deform.html - temperature excluding box deformation velocity
"temp/partial"_compute_temp_partial.html - temperature excluding one or more dimensions of velocity
"temp/profile"_compute_temp_profile.html - temperature excluding a binned velocity profile
"temp/ramp"_compute_temp_ramp.html - temperature excluding ramped velocity component
"temp/region"_compute_temp_region.html - temperature of a region of atoms
"temp/sphere"_compute_temp_sphere.html - temperature of spherical particles :ul
There are also additional compute styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to
the individual styles are given in the compute section of "this
page"_Section_commands.html#3_5.
[Restrictions:] none
[Related commands:]
"uncompute"_uncompute.html, "compute_modify"_compute_modify.html, "fix
ave/atom"_fix_ave_atom.html, "fix ave/spatial"_fix_ave_spatial.html,
"fix ave/time"_fix_ave_time.html
[Default:] none
diff --git a/doc/compute_reduce.html b/doc/compute_reduce.html
index 6970993bc..b9036bab4 100644
--- a/doc/compute_reduce.html
+++ b/doc/compute_reduce.html
@@ -1,118 +1,144 @@
<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>compute reduce command
</H3>
<H3>compute reduce/region command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>compute ID group-ID style arg mode input1 input2 ...
</PRE>
<UL><LI>ID, group-ID are documented in <A HREF = "compute.html">compute</A> command
<LI>style = <I>reduce</I> or <I>reduce/region</I>
<PRE> <I>reduce</I> arg = none
<I>reduce/region</I> arg = region-ID
region-ID = ID of region to use for choosing atoms
</PRE>
-<LI>mode = <I>sum</I> or <I>min</I> or <I>max</I>
+<LI>mode = <I>sum</I> or <I>min</I> or <I>max</I> or <I>ave</I>
<LI>one or more inputs can be listed
<LI>input = 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 = per-atom vector value calculated by a compute with ID
- c_ID[N] = Nth column of per-atom array calculated by a compute with ID
- f_ID = per-atom vector value calculated by a fix with ID
- f_ID[N] = Nth column of per-atom array calculated by a fix with ID
+ c_ID = vector calculated by a compute with ID
+ c_ID[I] = Ith column of array calculated by a compute with ID
+ f_ID = vector calculated by a fix with ID
+ f_ID[I] = Ith column of array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>compute 1 all reduce sum c_force
compute 1 all reduce/region subbox sum c_force
compute 2 all reduce min c_press<B>2</B> f_ave v_myKE
</PRE>
<P><B>Description:</B>
</P>
-<P>Define a calculation that "reduces" one or more per-atom inputs across
-all atoms in the group to yield a single global scalar for each listed
-input. If the compute reduce/region command is used, the selection of
-atoms is limited to atoms in the region as well as in the group.
+<P>Define a calculation that "reduces" one or more vector inputs into
+scalar values, one per listed input. The inputs can be global,
+per-atom, or local quantities. Atom attributes are per-atom
+quantities, <A HREF = "compute.html">computes</A> and <A HREF = "fix.html">fixes</A> may generate
+any of the three kinds of quantities, and <A HREF = "variable.html">atom-style
+variables</A> generate per-atom quantities.
</P>
<P>The reduction operation is specified by the <I>mode</I> setting. The <I>sum</I>
-option adds the per-atom quantities into a global total. The <I>min</I> or
-<I>max</I> options find the minimum or maximum value across all per-atom
-quantities.
-</P>
-<P>Each listed input is operated on independently. The group specified
-with the command means only atoms within the group contribute to the
-result. If the compute reduce/region command is used, the atoms must
-also be within the region. Note that the input that produces the
-per-atom quantities may define its own group which affects the
-quantities it returns. For example, if a per-atom compute is used as
-an input, it will generate values of 0.0 for atoms that are not in the
+option adds the values in the vector into a global total. The <I>min</I>
+or <I>max</I> options find the minimum or maximum value across all vector
+values. The <I>ave</I> setting adds the vector values into a global total,
+then divides by the number of values in the vector.
+</P>
+<P>Each listed input is operated on independently. For per-atom inputs,
+the group specified with this command means only atoms within the
+group contribute to the result. For per-atom inputs, if the compute
+reduce/region command is used, the atoms must also currently be within
+the region. Note that an input that produces per-atom quantities may
+define its own group which affects the quantities it returns. For
+example, if a compute is used as an input which generates a per-atom
+vector, it will generate values of 0.0 for atoms that are not in the
group specified for that compute.
</P>
<P>Each listed input 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 atom-style
-<A HREF = "variable.html">variable</A>. In the latter cases, the compute, fix, or
-variable must produce per-atom quantities, not a global quantity.
-</P>
-<P><A HREF = "compute.html">Computes</A> that produce per-atom quantities are those
-which have the word <I>atom</I> in their style name. See the doc pages for
-individual <A HREF = "fix.html">fixes</A> to determine which ones produce per-atom
-quantities. <A HREF = "variable.html">Variables</A> of style <I>atom</I> are the only
-ones that can be used with this compute since all other variable
-styles produce global quantities.
+<A HREF = "variable.html">variable</A>.
+</P>
+<P>Atom attributes are per-atom inputs.
+</P>
+<P>If a value begins with "c_", a compute ID must follow which has been
+previously defined in the input script. Computes can generate global,
+per-atom, or local quantities. See the individual
+<A HREF = "compute.html">compute</A> doc page for details. If no bracketed integer
+is appended, the vector calculated by the compute is used. If a
+bracketed interger is appended, the Ith column of the array calculated
+by the compute is used. 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. Fixes can generate global,
+per-atom, or local quantities. See the individual <A HREF = "fix.html">fix</A> doc
+page for details. Note that some fixes only produce their values on
+certain timesteps, which must be compatible with when compute reduce
+references the values, else an error results. If no bracketed integer
+is appended, the vector calculated by the fix is used. If a bracketed
+integer is appended, the Ith column of the array calculated by the fix
+is used. Users can also write code for their own fix style 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. It must be an
+<A HREF = "variable.html">atom-style variable</A>. Atom-style variables can
+reference thermodynamic keywords and various per-atom attributes, or
+invoke other computes, fixes, or variables when they are evaluated, so
+this is a very general means of generating per-atom quantities to
+reduce.
</P>
<P>If a single input is specified this compute produces a global scalar
value. If multiple inputs are specified, this compute produces a
vector of global values, the length of which is equal to the number of
inputs specified.
</P>
<P>As discussed below, for <I>sum</I> mode, the value(s) produced by this
compute are all "extensive", meaning their value scales linearly with
the number of atoms involved. If normalized values are desired, this
compute can be accessed by the <A HREF = "thermo_style.html">thermo_style custom</A>
command with <A HREF = "thermo_modify.html">thermo_modify norm yes</A> set as an
option. Or it can be accessed by a <A HREF = "variable.html">variable</A> that
divides by the appropriate atom count.
</P>
<P><B>Output info:</B>
</P>
<P>This compute calculates a global scalar or global vector of length N
where N is the number of inputs, and which can be accessed by indices
-1-6. These values can be used by any command that uses global scalar
+1-N. These values can be used by any command that uses global scalar
or vector values from a compute as input. See <A HREF = "Section_howto.html#4_15">this
section</A> for an overview of LAMMPS output
options.
</P>
<P>For <I>sum</I> mode, the scalar and vector values calculated by this
compute are "extensive", meaning they scale with the number of atoms
-in the simulation. For <I>min</I> and <I>max</I> modes, the value(s) are
-intensive.
+in the simulation. For <I>min</I> or <I>max</I> or <I>ave</I> modes, the value(s)
+are intensive.
</P>
<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "compute.html">compute</A>, <A HREF = "fix.html">fix</A>, <A HREF = "variable.html">variable</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/compute_reduce.txt b/doc/compute_reduce.txt
index e7e208653..90069cc28 100644
--- a/doc/compute_reduce.txt
+++ b/doc/compute_reduce.txt
@@ -1,105 +1,131 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
compute reduce command :h3
compute reduce/region command :h3
[Syntax:]
compute ID group-ID style arg mode input1 input2 ... :pre
ID, group-ID are documented in "compute"_compute.html command :ulb,l
style = {reduce} or {reduce/region} :l
{reduce} arg = none
{reduce/region} arg = region-ID
region-ID = ID of region to use for choosing atoms :pre
-mode = {sum} or {min} or {max} :l
+mode = {sum} or {min} or {max} or {ave} :l
one or more inputs can be listed :l
input = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :l
x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force component)
- c_ID = per-atom vector value calculated by a compute with ID
- c_ID\[N\] = Nth column of per-atom array calculated by a compute with ID
- f_ID = per-atom vector value calculated by a fix with ID
- f_ID\[N\] = Nth column of per-atom array calculated by a fix with ID
+ c_ID = vector calculated by a compute with ID
+ c_ID\[I\] = Ith column of array calculated by a compute with ID
+ f_ID = vector calculated by a fix with ID
+ f_ID\[I\] = Ith column of array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name :pre
:ule
[Examples:]
compute 1 all reduce sum c_force
compute 1 all reduce/region subbox sum c_force
compute 2 all reduce min c_press[2] f_ave v_myKE :pre
[Description:]
-Define a calculation that "reduces" one or more per-atom inputs across
-all atoms in the group to yield a single global scalar for each listed
-input. If the compute reduce/region command is used, the selection of
-atoms is limited to atoms in the region as well as in the group.
+Define a calculation that "reduces" one or more vector inputs into
+scalar values, one per listed input. The inputs can be global,
+per-atom, or local quantities. Atom attributes are per-atom
+quantities, "computes"_compute.html and "fixes"_fix.html may generate
+any of the three kinds of quantities, and "atom-style
+variables"_variable.html generate per-atom quantities.
The reduction operation is specified by the {mode} setting. The {sum}
-option adds the per-atom quantities into a global total. The {min} or
-{max} options find the minimum or maximum value across all per-atom
-quantities.
-
-Each listed input is operated on independently. The group specified
-with the command means only atoms within the group contribute to the
-result. If the compute reduce/region command is used, the atoms must
-also be within the region. Note that the input that produces the
-per-atom quantities may define its own group which affects the
-quantities it returns. For example, if a per-atom compute is used as
-an input, it will generate values of 0.0 for atoms that are not in the
+option adds the values in the vector into a global total. The {min}
+or {max} options find the minimum or maximum value across all vector
+values. The {ave} setting adds the vector values into a global total,
+then divides by the number of values in the vector.
+
+Each listed input is operated on independently. For per-atom inputs,
+the group specified with this command means only atoms within the
+group contribute to the result. For per-atom inputs, if the compute
+reduce/region command is used, the atoms must also currently be within
+the region. Note that an input that produces per-atom quantities may
+define its own group which affects the quantities it returns. For
+example, if a compute is used as an input which generates a per-atom
+vector, it will generate values of 0.0 for atoms that are not in the
group specified for that compute.
Each listed input can be an atom attribute (position, velocity, force
component) or can be the result of a "compute"_compute.html or
"fix"_fix.html or the evaluation of an atom-style
-"variable"_variable.html. In the latter cases, the compute, fix, or
-variable must produce per-atom quantities, not a global quantity.
-
-"Computes"_compute.html that produce per-atom quantities are those
-which have the word {atom} in their style name. See the doc pages for
-individual "fixes"_fix.html to determine which ones produce per-atom
-quantities. "Variables"_variable.html of style {atom} are the only
-ones that can be used with this compute since all other variable
-styles produce global quantities.
+"variable"_variable.html.
+
+Atom attributes are per-atom inputs.
+
+If a value begins with "c_", a compute ID must follow which has been
+previously defined in the input script. Computes can generate global,
+per-atom, or local quantities. See the individual
+"compute"_compute.html doc page for details. If no bracketed integer
+is appended, the vector calculated by the compute is used. If a
+bracketed interger is appended, the Ith column of the array calculated
+by the compute is used. Users can also write code for their own
+compute styles and "add them to LAMMPS"_Section_modify.html.
+
+If a value begins with "f_", a fix ID must follow which has been
+previously defined in the input script. Fixes can generate global,
+per-atom, or local quantities. See the individual "fix"_fix.html doc
+page for details. Note that some fixes only produce their values on
+certain timesteps, which must be compatible with when compute reduce
+references the values, else an error results. If no bracketed integer
+is appended, the vector calculated by the fix is used. If a bracketed
+integer is appended, the Ith column of the array calculated by the fix
+is used. Users can also write code for their own fix style and "add
+them to LAMMPS"_Section_modify.html.
+
+If a value begins with "v_", a variable name must follow which has
+been previously defined in the input script. It must be an
+"atom-style variable"_variable.html. Atom-style variables can
+reference thermodynamic keywords and various per-atom attributes, or
+invoke other computes, fixes, or variables when they are evaluated, so
+this is a very general means of generating per-atom quantities to
+reduce.
If a single input is specified this compute produces a global scalar
value. If multiple inputs are specified, this compute produces a
vector of global values, the length of which is equal to the number of
inputs specified.
As discussed below, for {sum} mode, the value(s) produced by this
compute are all "extensive", meaning their value scales linearly with
the number of atoms involved. If normalized values are desired, this
compute can be accessed by the "thermo_style custom"_thermo_style.html
command with "thermo_modify norm yes"_thermo_modify.html set as an
option. Or it can be accessed by a "variable"_variable.html that
divides by the appropriate atom count.
[Output info:]
This compute calculates a global scalar or global vector of length N
where N is the number of inputs, and which can be accessed by indices
-1-6. These values can be used by any command that uses global scalar
+1-N. These values can be used by any command that uses global scalar
or vector values from a compute as input. See "this
section"_Section_howto.html#4_15 for an overview of LAMMPS output
options.
For {sum} mode, the scalar and vector values calculated by this
compute are "extensive", meaning they scale with the number of atoms
-in the simulation. For {min} and {max} modes, the value(s) are
-intensive.
+in the simulation. For {min} or {max} or {ave} modes, the value(s)
+are intensive.
[Restrictions:] none
[Related commands:]
"compute"_compute.html, "fix"_fix.html, "variable"_variable.html
[Default:] none
diff --git a/doc/fix.html b/doc/fix.html
index 57f5b0753..4f6403839 100644
--- a/doc/fix.html
+++ b/doc/fix.html
@@ -1,192 +1,247 @@
<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 command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>fix ID group-ID style args
</PRE>
<UL><LI>ID = user-assigned name for the fix
<LI>group-ID = ID of the group of atoms to apply the fix to
<LI>style = one of a long list of possible style names (see below)
<LI>args = arguments used by a particular style
</UL>
<P><B>Examples:</B>
</P>
<PRE>fix 1 all nve
fix 3 all nvt 300.0 300.0 0.01
fix mine top setforce 0.0 NULL 0.0
</PRE>
<P><B>Description:</B>
</P>
<P>Set a fix that will be applied to a group of atoms. In LAMMPS, a
"fix" is any operation that is applied to the system during
timestepping or minimization. Examples include updating of atom
positions and velocities due to time integration, controlling
temperature, applying constraint forces to atoms, enforcing boundary
conditions, computing diagnostics, etc. There are dozens of fixes
defined in LAMMPS and new ones can be added; see <A HREF = "Section_modify.html">this
section</A> for a discussion.
</P>
<P>Fixes perform their operations at different stages of the timestep.
If 2 or more fixes operate at the same stage of the timestep, they are
invoked in the order they were specified in the input script.
</P>
<P>The ID of a fix can only contain alphanumeric characters and
underscores.
</P>
<P>Fixes can be deleted with the <A HREF = "unfix.html">unfix</A> command.
</P>
<P>IMPORTANT NOTE: The <A HREF = "unfix.html">unfix</A> command is the only way to turn
off a fix; simply specifying a new fix with a similar style will not
turn off the first one. This is especially important to realize for
integration fixes. For example, using a <A HREF = "fix_nve.html">fix nve</A>
command for a second run after using a <A HREF = "fix_nvt.html">fix nvt</A> command
for the first run, will not cancel out the NVT time integration
invoked by the "fix nvt" command. Thus two time integrators would be
in place!
</P>
<P>If you specify a new fix with the same ID and style as an existing
fix, the old fix is deleted and the new one is created (presumably
with new settings). This is the same as if an "unfix" command were
first performed on the old fix, except that the new fix is kept in the
same order relative to the existing fixes as the old one originally
was. Note that this operation also wipes out any additional changes
made to the old fix via the <A HREF = "fix_modify.html">fix_modify</A> command.
</P>
<P>The <A HREF = "fix_modify.html">fix modify</A> command allows settings for some
fixes to be reset. See the doc page for individual fixes for details.
</P>
-<P>Some fixes calculate a global scalar or vector quantity which can be
-accessed by various commands for output, including <A HREF = "variable.html">equal- and
-atom-style variables</A>, <A HREF = "thermo_style.html">thermo_style
-custom</A>, and <A HREF = "fix_ave_time.html">fix ave/time</A>.
-</P>
-<P>Some fixes calculate a per-atom vector or array quantity which can be
-accessed by various commands for output, including <A HREF = "variable.html">atom-style
-variables</A>, <A HREF = "dump.html">dump_style custom</A>, and <A HREF = "fix_ave_spatial.html">fix
-ave/spatial</A>.
-</P>
-<P>The results of fixes that calculate global quantities can be either
-"intensive" or "extensive" values. Intensive means the value is
-independent of the number of atoms in the simulation, e.g. timestep
-size. Extensive means the value scales with the number of atoms in
-the simulation, e.g. total force applied by the fix. <A HREF = "thermo_style.html">Thermodynamic
-output</A> will normalize extensive values depending on
-the "thermo_modify norm" setting. But if a fix value is accessed in
-another way, e.g. by a <A HREF = "variable.html">variable</A>, you may need to know
-whether it is an intensive or extensive value. See the doc page for
-individual fixes for further info.
-</P>
-<P>See this <A HREF = "Section_howto.html#4_15">howto section</A> for a summary of
-various LAMMPS output options. See the doc pages for individual fixes
-for info on which ones calculate these quantities.
-</P>
<P>Some fixes store an internal "state" which is written to binary
restart files via the <A HREF = "restart.html">restart</A> or
<A HREF = "write_restart.html">write_restart</A> commands. This allows the fix to
continue on with its calculations in a restarted simulation. See the
<A HREF = "read_restart.html">read_restart</A> command for info on how to re-specify
a fix in an input script that reads a restart file. See the doc pages
for individual fixes for info on which ones can be restarted.
</P>
+<HR>
+
+<P>Some fixes calculate one of three styles of quantities: global,
+per-atom, or local, which can be used by other commands or output as
+described below. A global quantity is one or more system-wide values,
+e.g. the energy of a wall interacting with particles. A per-atom
+quantity is one or more values per atom, e.g. the displacement vector
+for each atom since time 0. Per-atom values are set to 0.0 for atoms
+not in the specified fix group. Local quantities are calculated by
+each processor based on the atoms it owns, but there may be zero or
+more per atoms.
+</P>
+<P>Note that a single fix may produces either global or per-atom or local
+quantities (or none at all), but never more than one of these.
+</P>
+<P>Global, per-atom, and local quantities each come in three kinds: a
+single scalar value, a vector of values, or a 2d array of values. The
+doc page for each fix describes the style and kind of values it
+produces, e.g. a per-atom vector. Some fixes produce more than one
+kind of a single style, e.g. a global scalar and a global vector.
+</P>
+<P>When a fix quantity is accessed, as in many of the output commands
+discussed below, it can be referenced via the following bracket
+notation, where ID is the ID of the fix:
+</P>
+<DIV ALIGN=center><TABLE BORDER=1 >
+<TR><TD >f_ID </TD><TD > entire scalar, vector, or array</TD></TR>
+<TR><TD >f_ID[I] </TD><TD > one element of vector, one column of array</TD></TR>
+<TR><TD >f_ID[I][J] </TD><TD > one element of array
+</TD></TR></TABLE></DIV>
+
+<P>In other words, using one bracket reduces the dimension of the
+quantity once (vector -> scalar, array -> vector). Using two brackets
+reduces the dimension twice (array -> scalar). Thus a command that
+uses scalar fix values as input can also process elements of a vector
+or array.
+</P>
+<P>Note that commands and <A HREF = "variable.html">variables</A> which use fix
+quantities typically do not allow for all kinds, e.g. a command may
+require a vector of values, not a scalar. This means there is no
+ambiguity about referring to a fix quantity as f_ID even if it
+produces, for example, both a scalar and vector. The doc pages for
+various commands explain the details.
+</P>
+<HR>
+
+<P>In LAMMPS, the values generated by a fix can be used in several ways:
+</P>
+<UL><LI>Global values can be output via the <A HREF = "thermo_style.html">thermo_style
+custom</A> or <A HREF = "fix_ave_time.html">fix ave/time</A> command.
+Or the values can be referenced in a <A HREF = "variable.html">variable equal</A> or
+<A HREF = "variable.html">variable atom</A> command.
+
+<LI>Per-atom values can be output via the <A HREF = "dump.html">dump custom</A> command
+or the <A HREF = "fix_ave_spatial.html">fix ave/spatial</A> command. Or they can be
+time-averaged via the <A HREF = "fix_ave_atom.html">fix ave/atom</A> command or
+reduced by the <A HREF = "compute_reduce.html">compute reduce</A> command. Or the
+per-atom values can be referenced in an <A HREF = "variable.html">atom-style
+variable</A>.
+
+<LI>Local values can be reduced by the <A HREF = "compute_reduce.html">compute
+reduce</A> command, or histogrammed by the <A HREF = "fix_ave_histo.html">fix
+ave/histo</A> command.
+</UL>
+<P>See this <A HREF = "Section_howto.html#4_15">howto section</A> for a summary of
+various LAMMPS output options, many of which involve fixes.
+</P>
+<P>The results of fixes that calculate global quantities can be either
+"intensive" or "extensive" values. Intensive means the value is
+independent of the number of atoms in the simulation,
+e.g. temperature. Extensive means the value scales with the number of
+atoms in the simulation, e.g. total rotational kinetic energy.
+<A HREF = "thermo_style.html">Thermodynamic output</A> will normalize extensive
+values depending on the "thermo_modify norm" setting. But if a fix
+value is accessed in another way, e.g. by a <A HREF = "variable.html">variable</A>,
+you may need to know whether it is an intensive or extensive value.
+See the doc page for individual fixes for further info.
+</P>
+<HR>
+
<P>Each fix style has its own documentation page which describes its
arguments and what it does, as listed below. Here is an alphabetic
list of fix styles available in LAMMPS:
</P>
<UL><LI><A HREF = "fix_addforce.html">addforce</A> - add a force to each atom
<LI><A HREF = "fix_aveforce.html">aveforce</A> - add an averaged force to each atom
<LI><A HREF = "fix_ave_atom.html">ave/atom</A> - compute per-atom time-averaged quantities
<LI><A HREF = "fix_ave_spatial.html">ave/spatial</A> - output per-atom quantities by layer
<LI><A HREF = "fix_ave_time.html">ave/time</A> - output time-averaged compute quantities
<LI><A HREF = "fix_bond_break.html">bond/break</A> - break bonds on the fly
<LI><A HREF = "fix_bond_create.html">bond/create</A> - create bonds on the fly
<LI><A HREF = "fix_bond_swap.html">bond/swap</A> - Monte Carlo bond swapping
<LI><A HREF = "fix_box_relax.html">box/relax</A> - relax box size during energy minimization
<LI><A HREF = "fix_com.html">com</A> - compute a center-of-mass
<LI><A HREF = "fix_coord_original.html">coord/original</A> - store original coords of each atom
<LI><A HREF = "fix_deform.html">deform</A> - change the simulation box size/shape
<LI><A HREF = "fix_deposit.html">deposit</A> - add new atoms above a surface
<LI><A HREF = "fix_drag.html">drag</A> - drag atoms towards a defined coordinate
<LI><A HREF = "fix_dt_reset.html">dt/reset</A> - reset the timestep based on velocity, forces
<LI><A HREF = "fix_efield.html">efield</A> - impose electric field on system
<LI><A HREF = "fix_enforce2d.html">enforce2d</A> - zero out z-dimension velocity and force
<LI><A HREF = "fix_evaporate.html">evaporate</A> - remove atoms from simulation periodically
<LI><A HREF = "fix_freeze.html">freeze</A> - freeze atoms in a granular simulation
<LI><A HREF = "fix_gravity.html">gravity</A> - add gravity to atoms in a granular simulation
<LI><A HREF = "fix_gyration.html">gyration</A> - compute radius of gyration
<LI><A HREF = "fix_heat.html">heat</A> - add/subtract momentum-conserving heat
<LI><A HREF = "fix_indent.html">indent</A> - impose force due to an indenter
<LI><A HREF = "fix_langevin.html">langevin</A> - Langevin temperature control
<LI><A HREF = "fix_lineforce.html">lineforce</A> - constrain atoms to move in a line
<LI><A HREF = "fix_msd.html">msd</A> - compute mean-squared displacement (i.e. diffusion coefficient)
<LI><A HREF = "fix_momentum.html">momentum</A> - zero the linear and/or angular momentum of a group of atoms
<LI><A HREF = "fix_move.html">move</A> - move atoms in a prescribed fashion
<LI><A HREF = "fix_nph.html">nph</A> - constant NPH time integration via Nose/Hoover
<LI><A HREF = "fix_npt.html">npt</A> - constant NPT time integration via Nose/Hoover
<LI><A HREF = "fix_npt_asphere.html">npt/asphere</A> - NPT for aspherical particles
<LI><A HREF = "fix_npt_sphere.html">npt/sphere</A> - NPT for spherical particles
<LI><A HREF = "fix_nve.html">nve</A> - constant NVE time integration
<LI><A HREF = "fix_nve_asphere.html">nve/asphere</A> - NVT for aspherical particles
<LI><A HREF = "fix_nve_limit.html">nve/limit</A> - NVE with limited step length
<LI><A HREF = "fix_nve_noforce.html">nve/noforce</A> - NVE without forces (v only)
<LI><A HREF = "fix_nve_asphere.html">nve/sphere</A> - NVT for spherical particles
<LI><A HREF = "fix_nvt.html">nvt</A> - constant NVT time integration via Nose/Hoover
<LI><A HREF = "fix_nvt_asphere.html">nvt/asphere</A> - NVT for aspherical particles
<LI><A HREF = "fix_nvt_sllod.html">nvt/sllod</A> - NVT for NEMD with SLLOD equations
<LI><A HREF = "fix_nvt_sphere.html">nvt/sphere</A> - NVT for spherical particles
<LI><A HREF = "fix_orient_fcc.html">orient/fcc</A> - add grain boundary migration force
<LI><A HREF = "fix_planeforce.html">planeforce</A> - constrain atoms to move in a plane
<LI><A HREF = "fix_poems.html">poems</A> - constrain clusters of atoms to move as coupled rigid bodies
<LI><A HREF = "fix_pour.html">pour</A> - pour new atoms into a granular simulation domain
<LI><A HREF = "fix_press_berendsen.html">press/berendsen</A> - pressure control by Berendsen barostat
<LI><A HREF = "fix_print.html">print</A> - print text and variables during a simulation
<LI><A HREF = "fix_rdf.html">rdf</A> - compute radial distribution functions
<LI><A HREF = "fix_reax_bonds.html">reax/bonds</A> - write out ReaxFF bond information <A HREF = "fix_recenter.html">recenter</A> - constrain the center-of-mass position of a group of atoms
<LI><A HREF = "fix_rigid.html">rigid</A> - constrain one or more clusters of atoms to move as a rigid body
<LI><A HREF = "fix_setforce.html">setforce</A> - set the force on each atom
<LI><A HREF = "fix_shake.html">shake</A> - SHAKE constraints on bonds and/or angles
<LI><A HREF = "fix_spring.html">spring</A> - apply harmonic spring force to group of atoms
<LI><A HREF = "fix_spring_rg.html">spring/rg</A> - spring on radius of gyration of group of atoms
<LI><A HREF = "fix_spring_self.html">spring/self</A> - spring from each atom to its origin
<LI><A HREF = "fix_temp_berendsen.html">temp/berendsen</A> - temperature control by Berendsen thermostat
<LI><A HREF = "fix_temp_rescale.html">temp/rescale</A> - temperature control by velocity rescaling
<LI><A HREF = "fix_thermal_conductivity.html">thermal/conductivity</A> - Muller-Plathe kinetic energy exchange for thermal conductivity calculation
<LI><A HREF = "fix_tmd.html">tmd</A> - guide a group of atoms to a new configuration
<LI><A HREF = "fix_ttm.html">ttm</A> - two-temperature model for electronic/atomic coupling
<LI><A HREF = "fix_viscosity.html">viscosity</A> - Muller-Plathe momentum exchange for viscosity calculation
<LI><A HREF = "fix_viscous.html">viscous</A> - viscous damping for granular simulations
<LI><A HREF = "fix_wall_colloid.html">wall/colloid</A> - Lennard-Jones wall interacting with finite-size particles
<LI><A HREF = "fix_wall_gran.html">wall/gran</A> - frictional wall(s) for granular simulations
<LI><A HREF = "fix_wall_lj126.html">wall/lj126</A> - Lennard-Jones 12-6 wall
<LI><A HREF = "fix_wall_lj93.html">wall/lj93</A> - Lennard-Jones 9-3 wall
<LI><A HREF = "fix_wall_reflect.html">wall/reflect</A> - reflecting wall(s)
</UL>
<P>There are also additional fix styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to
the individual styles are given in the fix section of <A HREF = "Section_commands.html#3_5">this
page</A>.
</P>
<P><B>Restrictions:</B>
</P>
<P>Some fix styles are part of specific packages. They are only enabled
if LAMMPS was built with that package. See the <A HREF = "Section_start.html#2_3">Making
LAMMPS</A> section for more info on packages. The
doc pages for individual fixes tell if it is part of a package.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "unfix.html">unfix</A>, <A HREF = "fix_modify.html">fix_modify</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/fix.txt b/doc/fix.txt
index fb9cf4722..1423ef2f5 100644
--- a/doc/fix.txt
+++ b/doc/fix.txt
@@ -1,199 +1,252 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
fix command :h3
[Syntax:]
fix ID group-ID style args :pre
ID = user-assigned name for the fix
group-ID = ID of the group of atoms to apply the fix to
style = one of a long list of possible style names (see below)
args = arguments used by a particular style :ul
[Examples:]
fix 1 all nve
fix 3 all nvt 300.0 300.0 0.01
fix mine top setforce 0.0 NULL 0.0 :pre
[Description:]
Set a fix that will be applied to a group of atoms. In LAMMPS, a
"fix" is any operation that is applied to the system during
timestepping or minimization. Examples include updating of atom
positions and velocities due to time integration, controlling
temperature, applying constraint forces to atoms, enforcing boundary
conditions, computing diagnostics, etc. There are dozens of fixes
defined in LAMMPS and new ones can be added; see "this
section"_Section_modify.html for a discussion.
Fixes perform their operations at different stages of the timestep.
If 2 or more fixes operate at the same stage of the timestep, they are
invoked in the order they were specified in the input script.
The ID of a fix can only contain alphanumeric characters and
underscores.
Fixes can be deleted with the "unfix"_unfix.html command.
IMPORTANT NOTE: The "unfix"_unfix.html command is the only way to turn
off a fix; simply specifying a new fix with a similar style will not
turn off the first one. This is especially important to realize for
integration fixes. For example, using a "fix nve"_fix_nve.html
command for a second run after using a "fix nvt"_fix_nvt.html command
for the first run, will not cancel out the NVT time integration
invoked by the "fix nvt" command. Thus two time integrators would be
in place!
If you specify a new fix with the same ID and style as an existing
fix, the old fix is deleted and the new one is created (presumably
with new settings). This is the same as if an "unfix" command were
first performed on the old fix, except that the new fix is kept in the
same order relative to the existing fixes as the old one originally
was. Note that this operation also wipes out any additional changes
made to the old fix via the "fix_modify"_fix_modify.html command.
The "fix modify"_fix_modify.html command allows settings for some
fixes to be reset. See the doc page for individual fixes for details.
-Some fixes calculate a global scalar or vector quantity which can be
-accessed by various commands for output, including "equal- and
-atom-style variables"_variable.html, "thermo_style
-custom"_thermo_style.html, and "fix ave/time"_fix_ave_time.html.
-
-Some fixes calculate a per-atom vector or array quantity which can be
-accessed by various commands for output, including "atom-style
-variables"_variable.html, "dump_style custom"_dump.html, and "fix
-ave/spatial"_fix_ave_spatial.html.
-
-The results of fixes that calculate global quantities can be either
-"intensive" or "extensive" values. Intensive means the value is
-independent of the number of atoms in the simulation, e.g. timestep
-size. Extensive means the value scales with the number of atoms in
-the simulation, e.g. total force applied by the fix. "Thermodynamic
-output"_thermo_style.html will normalize extensive values depending on
-the "thermo_modify norm" setting. But if a fix value is accessed in
-another way, e.g. by a "variable"_variable.html, you may need to know
-whether it is an intensive or extensive value. See the doc page for
-individual fixes for further info.
-
-See this "howto section"_Section_howto.html#4_15 for a summary of
-various LAMMPS output options. See the doc pages for individual fixes
-for info on which ones calculate these quantities.
-
Some fixes store an internal "state" which is written to binary
restart files via the "restart"_restart.html or
"write_restart"_write_restart.html commands. This allows the fix to
continue on with its calculations in a restarted simulation. See the
"read_restart"_read_restart.html command for info on how to re-specify
a fix in an input script that reads a restart file. See the doc pages
for individual fixes for info on which ones can be restarted.
+:line
+
+Some fixes calculate one of three styles of quantities: global,
+per-atom, or local, which can be used by other commands or output as
+described below. A global quantity is one or more system-wide values,
+e.g. the energy of a wall interacting with particles. A per-atom
+quantity is one or more values per atom, e.g. the displacement vector
+for each atom since time 0. Per-atom values are set to 0.0 for atoms
+not in the specified fix group. Local quantities are calculated by
+each processor based on the atoms it owns, but there may be zero or
+more per atoms.
+
+Note that a single fix may produces either global or per-atom or local
+quantities (or none at all), but never more than one of these.
+
+Global, per-atom, and local quantities each come in three kinds: a
+single scalar value, a vector of values, or a 2d array of values. The
+doc page for each fix describes the style and kind of values it
+produces, e.g. a per-atom vector. Some fixes produce more than one
+kind of a single style, e.g. a global scalar and a global vector.
+
+When a fix quantity is accessed, as in many of the output commands
+discussed below, it can be referenced via the following bracket
+notation, where ID is the ID of the fix:
+
+f_ID | entire scalar, vector, or array
+f_ID\[I\] | one element of vector, one column of array
+f_ID\[I\]\[J\] | one element of array :tb(s=|)
+
+In other words, using one bracket reduces the dimension of the
+quantity once (vector -> scalar, array -> vector). Using two brackets
+reduces the dimension twice (array -> scalar). Thus a command that
+uses scalar fix values as input can also process elements of a vector
+or array.
+
+Note that commands and "variables"_variable.html which use fix
+quantities typically do not allow for all kinds, e.g. a command may
+require a vector of values, not a scalar. This means there is no
+ambiguity about referring to a fix quantity as f_ID even if it
+produces, for example, both a scalar and vector. The doc pages for
+various commands explain the details.
+
+:line
+
+In LAMMPS, the values generated by a fix can be used in several ways:
+
+Global values can be output via the "thermo_style
+custom"_thermo_style.html or "fix ave/time"_fix_ave_time.html command.
+Or the values can be referenced in a "variable equal"_variable.html or
+"variable atom"_variable.html command. :ulb,l
+
+Per-atom values can be output via the "dump custom"_dump.html command
+or the "fix ave/spatial"_fix_ave_spatial.html command. Or they can be
+time-averaged via the "fix ave/atom"_fix_ave_atom.html command or
+reduced by the "compute reduce"_compute_reduce.html command. Or the
+per-atom values can be referenced in an "atom-style
+variable"_variable.html. :l
+
+Local values can be reduced by the "compute
+reduce"_compute_reduce.html command, or histogrammed by the "fix
+ave/histo"_fix_ave_histo.html command. :l,ule
+
+See this "howto section"_Section_howto.html#4_15 for a summary of
+various LAMMPS output options, many of which involve fixes.
+
+The results of fixes that calculate global quantities can be either
+"intensive" or "extensive" values. Intensive means the value is
+independent of the number of atoms in the simulation,
+e.g. temperature. Extensive means the value scales with the number of
+atoms in the simulation, e.g. total rotational kinetic energy.
+"Thermodynamic output"_thermo_style.html will normalize extensive
+values depending on the "thermo_modify norm" setting. But if a fix
+value is accessed in another way, e.g. by a "variable"_variable.html,
+you may need to know whether it is an intensive or extensive value.
+See the doc page for individual fixes for further info.
+
+:line
+
Each fix style has its own documentation page which describes its
arguments and what it does, as listed below. Here is an alphabetic
list of fix styles available in LAMMPS:
"addforce"_fix_addforce.html - add a force to each atom
"aveforce"_fix_aveforce.html - add an averaged force to each atom
"ave/atom"_fix_ave_atom.html - compute per-atom time-averaged quantities
"ave/spatial"_fix_ave_spatial.html - output per-atom quantities by layer
"ave/time"_fix_ave_time.html - output time-averaged compute quantities
"bond/break"_fix_bond_break.html - break bonds on the fly
"bond/create"_fix_bond_create.html - create bonds on the fly
"bond/swap"_fix_bond_swap.html - Monte Carlo bond swapping
"box/relax"_fix_box_relax.html - relax box size during energy minimization
"com"_fix_com.html - compute a center-of-mass
"coord/original"_fix_coord_original.html - store original coords of each atom
"deform"_fix_deform.html - change the simulation box size/shape
"deposit"_fix_deposit.html - add new atoms above a surface
"drag"_fix_drag.html - drag atoms towards a defined coordinate
"dt/reset"_fix_dt_reset.html - reset the timestep based on velocity, forces
"efield"_fix_efield.html - impose electric field on system
"enforce2d"_fix_enforce2d.html - zero out z-dimension velocity and force
"evaporate"_fix_evaporate.html - remove atoms from simulation periodically
"freeze"_fix_freeze.html - freeze atoms in a granular simulation
"gravity"_fix_gravity.html - add gravity to atoms in a granular simulation
"gyration"_fix_gyration.html - compute radius of gyration
"heat"_fix_heat.html - add/subtract momentum-conserving heat
"indent"_fix_indent.html - impose force due to an indenter
"langevin"_fix_langevin.html - Langevin temperature control
"lineforce"_fix_lineforce.html - constrain atoms to move in a line
"msd"_fix_msd.html - compute mean-squared displacement \
(i.e. diffusion coefficient)
"momentum"_fix_momentum.html - zero the linear and/or angular momentum \
of a group of atoms
"move"_fix_move.html - move atoms in a prescribed fashion
"nph"_fix_nph.html - constant NPH time integration via Nose/Hoover
"npt"_fix_npt.html - constant NPT time integration via Nose/Hoover
"npt/asphere"_fix_npt_asphere.html - NPT for aspherical particles
"npt/sphere"_fix_npt_sphere.html - NPT for spherical particles
"nve"_fix_nve.html - constant NVE time integration
"nve/asphere"_fix_nve_asphere.html - NVT for aspherical particles
"nve/limit"_fix_nve_limit.html - NVE with limited step length
"nve/noforce"_fix_nve_noforce.html - NVE without forces (v only)
"nve/sphere"_fix_nve_asphere.html - NVT for spherical particles
"nvt"_fix_nvt.html - constant NVT time integration via Nose/Hoover
"nvt/asphere"_fix_nvt_asphere.html - NVT for aspherical particles
"nvt/sllod"_fix_nvt_sllod.html - NVT for NEMD with SLLOD equations
"nvt/sphere"_fix_nvt_sphere.html - NVT for spherical particles
"orient/fcc"_fix_orient_fcc.html - add grain boundary migration force
"planeforce"_fix_planeforce.html - constrain atoms to move in a plane
"poems"_fix_poems.html - constrain clusters of atoms to move \
as coupled rigid bodies
"pour"_fix_pour.html - pour new atoms into a granular simulation domain
"press/berendsen"_fix_press_berendsen.html - pressure control by \
Berendsen barostat
"print"_fix_print.html - print text and variables during a simulation
"rdf"_fix_rdf.html - compute radial distribution functions
"reax/bonds"_fix_reax_bonds.html - write out ReaxFF bond information \
"recenter"_fix_recenter.html - constrain the center-of-mass position \
of a group of atoms
"rigid"_fix_rigid.html - constrain one or more clusters of atoms to \
move as a rigid body
"setforce"_fix_setforce.html - set the force on each atom
"shake"_fix_shake.html - SHAKE constraints on bonds and/or angles
"spring"_fix_spring.html - apply harmonic spring force to group of atoms
"spring/rg"_fix_spring_rg.html - spring on radius of gyration of \
group of atoms
"spring/self"_fix_spring_self.html - spring from each atom to its origin
"temp/berendsen"_fix_temp_berendsen.html - temperature control by \
Berendsen thermostat
"temp/rescale"_fix_temp_rescale.html - temperature control by \
velocity rescaling
"thermal/conductivity"_fix_thermal_conductivity.html - Muller-Plathe kinetic energy exchange for \
thermal conductivity calculation
"tmd"_fix_tmd.html - guide a group of atoms to a new configuration
"ttm"_fix_ttm.html - two-temperature model for electronic/atomic coupling
"viscosity"_fix_viscosity.html - Muller-Plathe momentum exchange for \
viscosity calculation
"viscous"_fix_viscous.html - viscous damping for granular simulations
"wall/colloid"_fix_wall_colloid.html - Lennard-Jones wall interacting with finite-size particles
"wall/gran"_fix_wall_gran.html - frictional wall(s) for granular simulations
"wall/lj126"_fix_wall_lj126.html - Lennard-Jones 12-6 wall
"wall/lj93"_fix_wall_lj93.html - Lennard-Jones 9-3 wall
"wall/reflect"_fix_wall_reflect.html - reflecting wall(s) :ul
There are also additional fix styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to
the individual styles are given in the fix section of "this
page"_Section_commands.html#3_5.
[Restrictions:]
Some fix styles are part of specific packages. They are only enabled
if LAMMPS was built with that package. See the "Making
LAMMPS"_Section_start.html#2_3 section for more info on packages. The
doc pages for individual fixes tell if it is part of a package.
[Related commands:]
"unfix"_unfix.html, "fix_modify"_fix_modify.html
[Default:] none
diff --git a/doc/fix_ave_atom.html b/doc/fix_ave_atom.html
index a0c232f1b..3436e8b52 100644
--- a/doc/fix_ave_atom.html
+++ b/doc/fix_ave_atom.html
@@ -1,154 +1,157 @@
<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/atom command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>fix ID group-ID ave/atom Nevery Nrepeat Nfreq value1 value2 ...
</PRE>
<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command
<LI>ave/atom = style name of this fix command
<LI>Nevery = calculate property every this many timesteps
<LI>Nrepeat = # of times to repeat the Nevery calculation before averaging
<LI>Nfreq = timestep frequency at which the average value is calculated
<LI>one or more values can be listed
-<LI>value = x, y, z, xu, yu, zu, vx, vy, vz, fx, fy, fz, c_ID, c_ID[N], f_ID, f_ID[N], v_name
+<LI>value = x, y, z, xu, yu, zu, vx, vy, vz, fx, fy, fz, c_ID, c_ID[i], f_ID, f_ID[i], v_name
<PRE> x,y,z,xu,yu,zu,vx,vy,vz,fx,fy,fz = atom attribute (position, unwrapped position, velocity, force component)
- c_ID = per-atom vector value calculated by a compute with ID
- c_ID[N] = Nth column of per-atom array calculated by a compute with ID
- f_ID = per-atom vector value calculated by a fix with ID
- f_ID[N] = Nth column of per-atom array calculated by a fix with ID
+ c_ID = per-atom vector calculated by a compute with ID
+ c_ID[I] = Ith column of per-atom array calculated by a compute with ID
+ f_ID = per-atom vector calculated by a fix with ID
+ f_ID[I] = Ith column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>fix 1 all ave/atom 1 100 100 vx vy vz
fix 1 all ave/atom 10 20 1000 c_my_stress<B>1</B>
</PRE>
<P><B>Description:</B>
</P>
<P>Calculate one or more instantaneous per-atom quantities every few
timesteps, and average them over longer timescales. The resulting
per-atom averages can be used by other <A HREF = "Section_howto.html#4_15">output
commands</A> such as the <A HREF = "fix_ave_spatial.html">fix
ave/spatial</A> or <A HREF = "dump.html">dump custom</A> commands.
</P>
<P>Each listed value is averaged independently. The group specified with
the command means only atoms within the group have their averages
computed. Atoms not in the group have their result(s) set to 0.0.
</P>
<P>Each listed value can be an atom attribute (position, unwrapped
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
atom-style <A HREF = "variable.html">variable</A>. In the latter cases, the
-compute, fix, or variable must produce a per-atom quantity, not a
-global quantity. If you wish to time-average global quantities from a
-compute, fix, or variable, then see the <A HREF = "fix_ave_time.html">fix
+compute, fix, or variable must produce a per-atom vector, not a global
+scalar or vector or array. If you wish to time-average global
+quantities from a compute, fix, or variable, then see the <A HREF = "fix_ave_time.html">fix
ave/time</A> command.
</P>
-<P><A HREF = "compute.html">Computes</A> that produce per-atom quantities are those
-which have the word <I>atom</I> in their style name. See the doc pages for
-individual <A HREF = "fix.html">fixes</A> to determine which ones produce per-atom
-quantities. <A HREF = "variable.html">Variables</A> of style <I>atom</I> are the only
-ones that can be used with this fix since all other styles of variable
-produce global quantities.
+<P><A HREF = "compute.html">Computes</A> that produce per-atom vectors or arrays are
+those which have the word <I>atom</I> in their style name. See the doc
+pages for individual <A HREF = "fix.html">fixes</A> to determine which ones produce
+per-atom vectors or arrays. <A HREF = "variable.html">Variables</A> of style <I>atom</I>
+are the only ones that can be used with this fix since they are the
+only ones that produce per-atom vectors.
</P>
<HR>
<P>The <I>Nevery</I>, <I>Nrepeat</I>, and <I>Nfreq</I> arguments specify on what
timesteps the values will be generated in order to contribute to the
average. The final averaged quantities are generated every <I>Nfreq</I>
timesteps. The average is over <I>Nrepeat</I> quantities, 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 average value
cannot overlap, i.e. Nfreq > (Nrepeat-1)*Nevery is required.
</P>
<P>For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on
timesteps 90,92,94,96,98,100 will be used to compute the final average
on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on
timestep 200, etc.
</P>
<HR>
<P>The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are
self-explanatory. The unwrapped values (xu,yu,zu) mean that the
coordinates are "unwrapped" by the images flags for each atom. This
means that if the atom has passed thru a periodic boundary one or more
times, its unwrapped value is what the coordinate would be if it had
not been wrapped back into the periodic box. Note that this means the
coordinate value may be far outside the box. The
<A HREF = "dump_modify.html">dump_modify</A> command describes in more detail what
is meant by image flags.
</P>
<P>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 per-atom vector calculated by the compute is used. If a
-bracketed term is appended, the Nth columnd of the per-atom array
-calculated by the compute is used. Users can also write code for
-their own compute styles and <A HREF = "Section_modify.html">add them to LAMMPS</A>.
+bracketed term containing an index I is appended, the Ith column of
+the per-atom array calculated by the compute is used. 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 no bracketed term is
appended, the per-atom vector calculated by the fix is used. If a
-bracketed term is appended, the Nth column of the per-atom array
-calculated by the fix is used. Note that some fixes only produce
-their values on certain timesteps, which must be compatible with
-<I>Nevery</I>, else an error will results. Users can also write code for
-their own fix styles and <A HREF = "Section_modify.html">add them to LAMMPS</A>.
+bracketed term containing an index I is appended, the Ith column of
+the per-atom array calculated by the fix is used. 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. Variables of style
-<I>atom</I> can reference thermodynamic keywords, or invoke other computes,
-fixes, or variables when they are evaluated, so this is a very general
-means of generating per-atom quantities to time average.
+been previously defined in the input script as an <A HREF = "variable.html">atom-style
+variable</A> Variables of style <I>atom</I> can reference
+thermodynamic keywords, or invoke other computes, fixes, or variables
+when they are evaluated, so this is a very general means of generating
+per-atom quantities to time average.
</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. No global scalar or vector quantities are
stored by this fix for access by various <A HREF = "Section_howto.html#4_15">output
commands</A>.
</P>
<P>This fix produces a per-atom vector or array which can be accessed by
various <A HREF = "Section_howto.html#4_15">output commands</A>. A vector is
produced if only a single quantity is averaged by this fix. If two or
more quantities are averaged, then an array of values is produced.
The per-atom values can only be accessed on timesteps that are
multiples of <I>Nfreq</I> since that is when averaging is performed.
</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_spatial.html">fix ave/spatial</A>, <A HREF = "dump.html">dump
custom</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/fix_ave_atom.txt b/doc/fix_ave_atom.txt
index 309efb6d2..323eee450 100644
--- a/doc/fix_ave_atom.txt
+++ b/doc/fix_ave_atom.txt
@@ -1,141 +1,144 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
fix ave/atom command :h3
[Syntax:]
fix ID group-ID ave/atom Nevery Nrepeat Nfreq value1 value2 ... :pre
ID, group-ID are documented in "fix"_fix.html command :ulb,l
ave/atom = style name of this fix command :l
Nevery = calculate property every this many timesteps :l
Nrepeat = # of times to repeat the Nevery calculation before averaging :l
Nfreq = timestep frequency at which the average value is calculated :l
one or more values can be listed :l
-value = x, y, z, xu, yu, zu, vx, vy, vz, fx, fy, fz, c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :l
+value = x, y, z, xu, yu, zu, vx, vy, vz, fx, fy, fz, c_ID, c_ID\[i\], f_ID, f_ID\[i\], v_name :l
x,y,z,xu,yu,zu,vx,vy,vz,fx,fy,fz = atom attribute (position, unwrapped position, velocity, force component)
- c_ID = per-atom vector value calculated by a compute with ID
- c_ID\[N\] = Nth column of per-atom array calculated by a compute with ID
- f_ID = per-atom vector value calculated by a fix with ID
- f_ID\[N\] = Nth column of per-atom array calculated by a fix with ID
+ c_ID = per-atom vector calculated by a compute with ID
+ c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID
+ f_ID = per-atom vector calculated by a fix with ID
+ f_ID\[I\] = Ith column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name :pre
:ule
[Examples:]
fix 1 all ave/atom 1 100 100 vx vy vz
fix 1 all ave/atom 10 20 1000 c_my_stress[1] :pre
[Description:]
Calculate one or more instantaneous per-atom quantities every few
timesteps, and average them over longer timescales. The resulting
per-atom averages can be used by other "output
commands"_Section_howto.html#4_15 such as the "fix
ave/spatial"_fix_ave_spatial.html or "dump custom"_dump.html commands.
Each listed value is averaged independently. The group specified with
the command means only atoms within the group have their averages
computed. Atoms not in the group have their result(s) set to 0.0.
Each listed value can be an atom attribute (position, unwrapped
position, velocity, force component) or can be the result of a
"compute"_compute.html or "fix"_fix.html or the evaluation of an
atom-style "variable"_variable.html. In the latter cases, the
-compute, fix, or variable must produce a per-atom quantity, not a
-global quantity. If you wish to time-average global quantities from a
-compute, fix, or variable, then see the "fix
+compute, fix, or variable must produce a per-atom vector, not a global
+scalar or vector or array. If you wish to time-average global
+quantities from a compute, fix, or variable, then see the "fix
ave/time"_fix_ave_time.html command.
-"Computes"_compute.html that produce per-atom quantities are those
-which have the word {atom} in their style name. See the doc pages for
-individual "fixes"_fix.html to determine which ones produce per-atom
-quantities. "Variables"_variable.html of style {atom} are the only
-ones that can be used with this fix since all other styles of variable
-produce global quantities.
+"Computes"_compute.html that produce per-atom vectors or arrays are
+those which have the word {atom} in their style name. See the doc
+pages for individual "fixes"_fix.html to determine which ones produce
+per-atom vectors or arrays. "Variables"_variable.html of style {atom}
+are the only ones that can be used with this fix since they are the
+only ones that produce per-atom vectors.
:line
The {Nevery}, {Nrepeat}, and {Nfreq} arguments specify on what
timesteps the values will be generated in order to contribute to the
average. The final averaged quantities are generated every {Nfreq}
timesteps. The average is over {Nrepeat} quantities, 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 average value
cannot overlap, i.e. Nfreq > (Nrepeat-1)*Nevery is required.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on
timesteps 90,92,94,96,98,100 will be used to compute the final average
on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on
timestep 200, etc.
:line
The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are
self-explanatory. The unwrapped values (xu,yu,zu) mean that the
coordinates are "unwrapped" by the images flags for each atom. This
means that if the atom has passed thru a periodic boundary one or more
times, its unwrapped value is what the coordinate would be if it had
not been wrapped back into the periodic box. Note that this means the
coordinate value may be far outside the box. The
"dump_modify"_dump_modify.html command describes in more detail what
is meant by image flags.
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 per-atom vector calculated by the compute is used. If a
-bracketed term is appended, the Nth columnd of the per-atom array
-calculated by the compute is used. Users can also write code for
-their own compute styles and "add them to LAMMPS"_Section_modify.html.
+bracketed term containing an index I is appended, the Ith column of
+the per-atom array calculated by the compute is used. Users can also
+write code for their own compute styles and "add them to
+LAMMPS"_Section_modify.html.
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 per-atom vector calculated by the fix is used. If a
-bracketed term is appended, the Nth column of the per-atom 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 results. Users can also write code for
-their own fix styles and "add them to LAMMPS"_Section_modify.html.
+bracketed term containing an index I is appended, the Ith column of
+the per-atom 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"_Section_modify.html.
If a value begins with "v_", a variable name must follow which has
-been previously defined in the input script. Variables of style
-{atom} can reference thermodynamic keywords, or invoke other computes,
-fixes, or variables when they are evaluated, so this is a very general
-means of generating per-atom quantities to time average.
+been previously defined in the input script as an "atom-style
+variable"_variable.html Variables of style {atom} can reference
+thermodynamic keywords, or invoke other computes, fixes, or variables
+when they are evaluated, so this is a very general means of generating
+per-atom quantities to time average.
:line
[Restart, fix_modify, output, run start/stop, minimize info:]
No information about this fix is written to "binary restart
files"_restart.html. None of the "fix_modify"_fix_modify.html options
are relevant to this fix. No global scalar or vector quantities are
stored by this fix for access by various "output
commands"_Section_howto.html#4_15.
This fix produces a per-atom vector or array which can be accessed by
various "output commands"_Section_howto.html#4_15. A vector is
produced if only a single quantity is averaged by this fix. If two or
more quantities are averaged, then an array of values is produced.
The per-atom values can only be accessed on timesteps that are
multiples of {Nfreq} since that is when averaging is performed.
No parameter of this fix can be used with the {start/stop} keywords of
the "run"_run.html command. This fix is not invoked during "energy
minimization"_minimize.html.
[Restrictions:] none
[Related commands:]
"compute"_compute.html, "fix ave/spatial"_fix_ave_spatial.html, "dump
custom"_dump.html
[Default:] none
diff --git a/doc/fix_ave_spatial.html b/doc/fix_ave_spatial.html
index 406ad0b3f..e37b0e16e 100644
--- a/doc/fix_ave_spatial.html
+++ b/doc/fix_ave_spatial.html
@@ -1,303 +1,327 @@
<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/spatial command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>fix ID group-ID ave/spatial Nevery Nrepeat Nfreq dim origin delta value1 value2 ... keyword args ...
</PRE>
<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command
<LI>ave/spatial = style name of this fix command
<LI>Nevery = calculate property every this many timesteps
<LI>Nrepeat = # of times to repeat the Nevery calculation before averaging
<LI>Nfreq = timestep frequency at which the average value is computed
<LI>dim = <I>x</I> or <I>y</I> or <I>z</I>
<LI>origin = <I>lower</I> or <I>center</I> or <I>upper</I> or coordinate value (distance units)
<LI>delta = thickness of spatial layers in dim (distance units)
<LI>one or more values can be listed
-<LI>value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[N], f_ID, f_ID[N], v_name
+<LI>value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[I], f_ID, f_ID[I], v_name
<PRE> x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
density/number, density/mass = number or mass density
- c_ID = per-atom vector value calculated by a compute with ID
- c_ID[N] = Nth column of per-atom array calculated by a compute with ID
- f_ID = per-atom vector value calculated by a fix with ID
- f_ID[N] = Nth column of per-atom array calculated by a fix with ID
+ c_ID = per-atom vector calculated by a compute with ID
+ c_ID[I] = Ith column of per-atom array calculated by a compute with ID
+ f_ID = per-atom vector calculated by a fix with ID
+ f_ID[I] = Ith column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
</PRE>
<LI>zero or more keyword/arg pairs may be appended
-<LI>keyword = <I>norm</I> or <I>units</I> or <I>file</I> or <I>ave</I>
+<LI>keyword = <I>norm</I> or <I>units</I> or <I>file</I> or <I>ave</I> or <I>title1</I> or <I>title2</I> or <I>title3</I>
<PRE> <I>units</I> arg = <I>box</I> or <I>lattice</I> or <I>reduced</I>
<I>norm</I> arg = <I>all</I> or <I>sample</I>
<I>file</I> arg = filename
filename = file to write results to
<I>ave</I> args = <I>one</I> or <I>running</I> or <I>window M</I>
one = output 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
+ window M = output average of M most recent Nfreq steps
+ <I>title1</I> arg = string
+ string = text to print as 1st line of output file = title
+ <I>title2</I> arg = string
+ string = text to print as 2nd line of output file = timestep, # of layers
+ <I>title3</I> arg = string
+ string = text to print as 3rd line of output file = values
</PRE>
</UL>
<P><B>Examples:</B>
</P>
-<PRE>fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced
+<PRE>fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced &
+ title1 "My output values"
fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile
fix 1 flow ave/spatial 100 5 1000 y 0.0 2.5 density/mass ave running
</PRE>
<P><B>Description:</B>
</P>
<P>Calculate one or more instantaneous per-atom quantities every few
timesteps, average them by layer in a chosen dimension, and average
the layer values over a longer timescale. The resulting averages can
be used by other <A HREF = "Section_howto.html#4_15">output commands</A> such as
<A HREF = "thermo_style.html">thermo_style custom</A>, and can also be written to a
file.
</P>
<P>Each listed value is averaged independently. The group specified with
the command means only atoms within the group contribute to the layer
averages.
</P>
<P>Each listed value can be an atom attribute (position, velocity, force
component), a mass or number density, or the result of a
<A HREF = "compute.html">compute</A> or <A HREF = "fix.html">fix</A> or the evaluation of an
atom-style <A HREF = "variable.html">variable</A>. In the latter cases, the
compute, fix, or variable must produce a per-atom quantity, not a
global quantity. If you wish to time-average global quantities from a
compute, fix, or variable, then see the <A HREF = "fix_ave_time.html">fix
ave/time</A> command.
</P>
<P><A HREF = "compute.html">Computes</A> that produce per-atom quantities are those
which have the word <I>atom</I> in their style name. See the doc pages for
individual <A HREF = "fix.html">fixes</A> to determine which ones produce per-atom
quantities. <A HREF = "variable.html">Variables</A> of style <I>atom</I> are the only
ones that can be used with this fix since all other styles of variable
produce global quantities.
</P>
<HR>
<P>The <I>Nevery</I>, <I>Nrepeat</I>, and <I>Nfreq</I> arguments specify on what
timesteps the layer values will be generated in order to contribute to
the average. The final averaged quantities are generated every
<I>Nfreq</I> timesteps. The average is over <I>Nrepeat</I> quantities, 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
average value cannot overlap, i.e. Nfreq > (Nrepeat-1)*Nevery is
required.
</P>
<P>For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on
timesteps 90,92,94,96,98,100 will be used to compute the final average
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 is done; values are simply generated on timesteps
100,200,etc.
</P>
<HR>
<P>Each per-atom property is also averaged over atoms in each layer,
where the layers are in a particular <I>dim</I> and have a thickness given
by <I>delta</I>. Every Nfreq steps, when an averaging is being performed
and the per-atom property is calculated for the first time, the number
of layers and the layer boundaries are computed. Thus if the
simulation box changes size during a simulation, the number of layers
and their boundaries may also change. Layers are defined relative to
a specified <I>origin</I>, which may be the lower/upper edge of the box (in
<I>dim</I>) or its center point, or a specified coordinate value. Starting
at the origin, sufficient layers are created in both directions to
completely cover the box. On subsequent timesteps every atom is
mapped to one of the layers. Atoms beyond the lowermost/uppermost
layer are counted in the first/last layer.
</P>
<P>For orthogonal simulation boxes, the layers are "slices" aligned with
the xyz coordinate axes. For non-orthogonal (triclinic) simulation
boxes, the layers are "tilted slices" that are parallel to the tilted
faces of the box. See the <A HREF = "region.html">region prism</A> command for a
discussion of the geometry of tilted boxes in LAMMPS. As described
there, a tilted simulation box has edge vectors a,b,c. In that
nomenclature, layers in the x dimension have faces with normals in the
"b" cross "c" direction. Layers in y have faces normal to the "a"
cross "c" direction. And layers in z have faces normal to the "a"
cross "b" direction. Note that in order to define the thickness and
position of these tilted layers in an unambiguous fashion, the <I>units</I>
option must be set to <I>reduced</I> when using a non-orthogonal simulation
box, as discussed below.
</P>
<HR>
<P>The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are
self-explanatory.
</P>
<P>The <I>density/number</I> value means the number density is computed in
each layer, i.e. a weighting of 1 for each atom. The <I>density/mass</I>
value means the mass density is computed in each layer, i.e. each atom
is weighted by its mass. The resulting density is normalized by the
volume of the layer so that units of number/volume or mass/volume are
output.
</P>
<P>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
+previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
-bracketed term is appended, the Nth column of the per-atom array
+bracketed interger is appended, the Ith column of the per-atom array
calculated by the compute is used. 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 no bracketed term is
+previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
-bracketed term is appended, the Nth column of the per-atom array
+bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with
<I>Nevery</I>, else an error results. 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. Variables of style
-<I>atom</I> can reference thermodynamic keywords, or invoke other computes,
-fixes, or variables when they are evaluated, so this is a very general
-means of generating per-atom quantities to spatially average.
+<I>atom</I> can reference thermodynamic keywords and various per-atom
+attributes, or invoke other computes, fixes, or variables when they
+are evaluated, so this is a very general means of generating per-atom
+quantities to spatially average.
</P>
<HR>
<P>Additional optional keywords also affect the operation of this fix.
</P>
<P>The <I>units</I> keyword determines the meaning of the distance units used
for the layer thickness <I>delta</I> and for <I>origin</I> if it is a coordinate
value. For orthogonal simulation boxes, any of the 3 options may be
used. For non-orthogonal (triclinic) simulation boxes, only the
<I>reduced</I> option may be used.
</P>
<P>A <I>box</I> value selects standard distance units as defined by the
<A HREF = "units.html">units</A> command, e.g. Angstroms for units = real or metal.
A <I>lattice</I> value means the distance units are in lattice spacings.
The <A HREF = "lattice.html">lattice</A> command must have been previously used to
define the lattice spacing. A <I>reduced</I> value means normalized
unitless values between 0 and 1, which represent the lower and upper
faces of the simulation box respectively. Thus an <I>origin</I> value of
0.5 means the center of the box in any dimension. A <I>delta</I> value of
0.1 means 10 layers span the box in any dimension.
</P>
<P>Consider a non-orthogonal box, with layers in the x dimension. No
matter how the box is tilted, an <I>origin</I> of 0.0 means start layers at
the lower "b" cross "c" plane of the simulation box and an <I>origin</I> of
1.0 means to start layers at the upper "b" cross "c" face of the box.
A <I>delta</I> value of 0.1 means there will be 10 layers from 0.0 to 1.0,
regardless of the current size or shape of the simulation box.
</P>
<P>The <I>norm</I> keyword affects how averaging is done for the output
produced every <I>Nfreq</I> timesteps. For an <I>all</I> setting, a layer
quantity is summed over all atoms in all <I>Nrepeat</I> samples, as is the
count of atoms in the layer. The printed value for the layer is
Total-quantity / Total-count. In other words it is an average over
the entire <I>Nfreq</I> timescale.
</P>
<P>For a <I>sample</I> setting, the layer quantity is summed over atoms for
only a single sample, as is the count, and a "average sample value" is
computed, i.e. Sample-quantity / Sample-count. The printed value for
the layer is the average of the <I>Nrepeat</I> "average sample values", In
other words it is an average of an average.
</P>
<P>The <I>file</I> keyword allows a filename to be specified. Every <I>Nfreq</I>
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 <I>units</I> keyword is <I>box</I> or
<I>lattice</I>, the "coord" is printed in box units. If the value of the
<I>units</I> keyword is <I>reduced</I>, the "coord" is printed in reduced units
(0-1).
</P>
<P>The <I>ave</I> keyword determines how the layer values produced every
<I>Nfreq</I> steps are averaged with layer values 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 layer values 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 layer values produced on
timesteps that are multiples of <I>Nfreq</I> are summed and averaged in a
cumulative sense before being output. Each output layer value is
thus the average of the layer value produced on that timestep with all
preceding values for the same layer. 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 re-defining the fix by
re-specifying it.
</P>
<P>If the <I>ave</I> setting is <I>window</I>, then the layer values produced on
timesteps that are multiples of <I>Nfreq</I> are summed and averaged within
a moving "window" of time, so that the last M values for the same
layer are used to produce the output. E.g. if M = 3 and Nfreq = 1000,
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.
</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. By
+default, theses lines are as follows:
+</P>
+<PRE># Spatial-averaged data for fix ID and group name
+# Timestep Number-of-layers
+# Layer Coord Ncount value1 value2 ...
+</PRE>
+<P>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.
+</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 computes a global vector of quantities which can be accessed
-by various <A HREF = "Section_howto.html#4_15">output commands</A>. The values can
+<P>This fix computes a global array of values 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 averaging is performed. The global vector is of length N =
-nlayers*nvalues where nlayers is the number of layers and nvalues is
-the number of values per layer that the fix is averaging. When
-accessed by another output command, a single index M is specified
-which is mapped into a layer I as I = M / nvalues + 1 and into value J
-as J = M % nvalues + 1. If I 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 vector values calculated by this fix are
-"intensive", meaning they are independent of the number of atoms in
-the simulation, since they are already normalized by the count of
-atoms in each layer.
+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
+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
+already normalized by the count of atoms in each layer.
</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>
</P>
<P>When the <I>ave</I> keyword is set to <I>running</I> or <I>window</I> then the number
of layers must remain the same during the simulation, so that the
appropriate averaging can be done. This will be the case if the
simulation box size doesn't change or if the <I>units</I> keyword is set to
<I>reduced</I>.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "compute.html">compute</A>, <A HREF = "fix_ave_time.html">fix ave/time</A>
</P>
<P><B>Default:</B>
</P>
<P>The option defaults are units = lattice, norm = all, no file output,
-and ave = one.
+and ave = one, title 1,2,3 = strings as described above.
</P>
</HTML>
diff --git a/doc/fix_ave_spatial.txt b/doc/fix_ave_spatial.txt
index 80e0d6de9..7acd1cefc 100644
--- a/doc/fix_ave_spatial.txt
+++ b/doc/fix_ave_spatial.txt
@@ -1,285 +1,310 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
fix ave/spatial command :h3
[Syntax:]
fix ID group-ID ave/spatial Nevery Nrepeat Nfreq dim origin delta value1 value2 ... keyword args ... :pre
ID, group-ID are documented in "fix"_fix.html command :ulb,l
ave/spatial = style name of this fix command :l
Nevery = calculate property every this many timesteps :l
Nrepeat = # of times to repeat the Nevery calculation before averaging :l
Nfreq = timestep frequency at which the average value is computed :l
dim = {x} or {y} or {z} :l
origin = {lower} or {center} or {upper} or coordinate value (distance units) :l
delta = thickness of spatial layers in dim (distance units) :l
one or more values can be listed :l
-value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :l
+value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID\[I\], f_ID, f_ID\[I\], v_name :l
x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
density/number, density/mass = number or mass density
- c_ID = per-atom vector value calculated by a compute with ID
- c_ID\[N\] = Nth column of per-atom array calculated by a compute with ID
- f_ID = per-atom vector value calculated by a fix with ID
- f_ID\[N\] = Nth column of per-atom array calculated by a fix with ID
+ c_ID = per-atom vector calculated by a compute with ID
+ c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID
+ f_ID = per-atom vector calculated by a fix with ID
+ f_ID\[I\] = Ith column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name :pre
zero or more keyword/arg pairs may be appended :l
-keyword = {norm} or {units} or {file} or {ave} :l
+keyword = {norm} or {units} or {file} or {ave} or {title1} or {title2} or {title3} :l
{units} arg = {box} or {lattice} or {reduced}
{norm} arg = {all} or {sample}
{file} arg = filename
filename = file to write results to
{ave} args = {one} or {running} or {window M}
one = output 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 :pre
+ window M = output average of M most recent Nfreq steps
+ {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 = timestep, # of layers
+ {title3} arg = string
+ string = text to print as 3rd line of output file = values :pre
:ule
[Examples:]
-fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced
+fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced &
+ title1 "My output values"
fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile
fix 1 flow ave/spatial 100 5 1000 y 0.0 2.5 density/mass ave running :pre
[Description:]
Calculate one or more instantaneous per-atom quantities every few
timesteps, average them by layer in a chosen dimension, and average
the layer values over a longer timescale. The resulting averages can
be used by other "output commands"_Section_howto.html#4_15 such as
"thermo_style custom"_thermo_style.html, and can also be written to a
file.
Each listed value is averaged independently. The group specified with
the command means only atoms within the group contribute to the layer
averages.
Each listed value can be an atom attribute (position, velocity, force
component), a mass or number density, or the result of a
"compute"_compute.html or "fix"_fix.html or the evaluation of an
atom-style "variable"_variable.html. In the latter cases, the
compute, fix, or variable must produce a per-atom quantity, not a
global quantity. If you wish to time-average global quantities from a
compute, fix, or variable, then see the "fix
ave/time"_fix_ave_time.html command.
"Computes"_compute.html that produce per-atom quantities are those
which have the word {atom} in their style name. See the doc pages for
individual "fixes"_fix.html to determine which ones produce per-atom
quantities. "Variables"_variable.html of style {atom} are the only
ones that can be used with this fix since all other styles of variable
produce global quantities.
:line
The {Nevery}, {Nrepeat}, and {Nfreq} arguments specify on what
timesteps the layer values will be generated in order to contribute to
the average. The final averaged quantities are generated every
{Nfreq} timesteps. The average is over {Nrepeat} quantities, 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
average value cannot overlap, i.e. Nfreq > (Nrepeat-1)*Nevery is
required.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on
timesteps 90,92,94,96,98,100 will be used to compute the final average
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 is done; values are simply generated on timesteps
100,200,etc.
:line
Each per-atom property is also averaged over atoms in each layer,
where the layers are in a particular {dim} and have a thickness given
by {delta}. Every Nfreq steps, when an averaging is being performed
and the per-atom property is calculated for the first time, the number
of layers and the layer boundaries are computed. Thus if the
simulation box changes size during a simulation, the number of layers
and their boundaries may also change. Layers are defined relative to
a specified {origin}, which may be the lower/upper edge of the box (in
{dim}) or its center point, or a specified coordinate value. Starting
at the origin, sufficient layers are created in both directions to
completely cover the box. On subsequent timesteps every atom is
mapped to one of the layers. Atoms beyond the lowermost/uppermost
layer are counted in the first/last layer.
For orthogonal simulation boxes, the layers are "slices" aligned with
the xyz coordinate axes. For non-orthogonal (triclinic) simulation
boxes, the layers are "tilted slices" that are parallel to the tilted
faces of the box. See the "region prism"_region.html command for a
discussion of the geometry of tilted boxes in LAMMPS. As described
there, a tilted simulation box has edge vectors a,b,c. In that
nomenclature, layers in the x dimension have faces with normals in the
"b" cross "c" direction. Layers in y have faces normal to the "a"
cross "c" direction. And layers in z have faces normal to the "a"
cross "b" direction. Note that in order to define the thickness and
position of these tilted layers in an unambiguous fashion, the {units}
option must be set to {reduced} when using a non-orthogonal simulation
box, as discussed below.
:line
The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are
self-explanatory.
The {density/number} value means the number density is computed in
each layer, i.e. a weighting of 1 for each atom. The {density/mass}
value means the mass density is computed in each layer, i.e. each atom
is weighted by its mass. The resulting density is normalized by the
volume of the layer so that units of number/volume or mass/volume are
output.
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
+previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
-bracketed term is appended, the Nth column of the per-atom array
+bracketed interger is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and "add them to LAMMPS"_Section_modify.html.
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
+previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
-bracketed term is appended, the Nth column of the per-atom array
+bracketed integer is appended, the Ith column of the per-atom 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 results. Users can also write code for their
own fix styles and "add them to LAMMPS"_Section_modify.html.
If a value begins with "v_", a variable name must follow which has
been previously defined in the input script. Variables of style
-{atom} can reference thermodynamic keywords, or invoke other computes,
-fixes, or variables when they are evaluated, so this is a very general
-means of generating per-atom quantities to spatially average.
+{atom} can reference thermodynamic keywords and various per-atom
+attributes, or invoke other computes, fixes, or variables when they
+are evaluated, so this is a very general means of generating per-atom
+quantities to spatially average.
:line
Additional optional keywords also affect the operation of this fix.
The {units} keyword determines the meaning of the distance units used
for the layer thickness {delta} and for {origin} if it is a coordinate
value. For orthogonal simulation boxes, any of the 3 options may be
used. For non-orthogonal (triclinic) simulation boxes, only the
{reduced} option may be used.
A {box} value selects standard distance units as defined by the
"units"_units.html command, e.g. Angstroms for units = real or metal.
A {lattice} value means the distance units are in lattice spacings.
The "lattice"_lattice.html command must have been previously used to
define the lattice spacing. A {reduced} value means normalized
unitless values between 0 and 1, which represent the lower and upper
faces of the simulation box respectively. Thus an {origin} value of
0.5 means the center of the box in any dimension. A {delta} value of
0.1 means 10 layers span the box in any dimension.
Consider a non-orthogonal box, with layers in the x dimension. No
matter how the box is tilted, an {origin} of 0.0 means start layers at
the lower "b" cross "c" plane of the simulation box and an {origin} of
1.0 means to start layers at the upper "b" cross "c" face of the box.
A {delta} value of 0.1 means there will be 10 layers from 0.0 to 1.0,
regardless of the current size or shape of the simulation box.
The {norm} keyword affects how averaging is done for the output
produced every {Nfreq} timesteps. For an {all} setting, a layer
quantity is summed over all atoms in all {Nrepeat} samples, as is the
count of atoms in the layer. The printed value for the layer is
Total-quantity / Total-count. In other words it is an average over
the entire {Nfreq} timescale.
For a {sample} setting, the layer quantity is summed over atoms for
only a single sample, as is the count, and a "average sample value" is
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
another output command or written to a file.
If the {ave} setting is {one}, then the layer values 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 layer values produced on
timesteps that are multiples of {Nfreq} are summed and averaged in a
cumulative sense before being output. Each output layer value is
thus the average of the layer value produced on that timestep with all
preceding values for the same layer. This running average begins
when the fix is defined; it can only be restarted by deleting the fix
via the "unfix"_unfix.html command, or re-defining the fix by
re-specifying it.
If the {ave} setting is {window}, then the layer values produced on
timesteps that are multiples of {Nfreq} are summed and averaged within
a moving "window" of time, so that the last M values for the same
layer are used to produce the output. E.g. if M = 3 and Nfreq = 1000,
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 {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:
+
+# 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.
+
:line
[Restart, fix_modify, output, run start/stop, minimize info:]
No information about this fix is written to "binary restart
files"_restart.html. None of the "fix_modify"_fix_modify.html options
are relevant to this fix.
-This fix computes a global vector of quantities which can be accessed
-by various "output commands"_Section_howto.html#4_15. The values can
+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 vector is of length N =
-nlayers*nvalues where nlayers is the number of layers and nvalues is
-the number of values per layer that the fix is averaging. When
-accessed by another output command, a single index M is specified
-which is mapped into a layer I as I = M / nvalues + 1 and into value J
-as J = M % nvalues + 1. If I 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 vector values calculated by this fix are
-"intensive", meaning they are independent of the number of atoms in
-the simulation, since they are already normalized by the count of
-atoms in each layer.
+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
+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
+already normalized by the count of atoms in each layer.
No parameter of this fix can be used with the {start/stop} keywords of
the "run"_run.html command. This fix is not invoked during "energy
minimization"_minimize.html.
[Restrictions:]
When the {ave} keyword is set to {running} or {window} then the number
of layers must remain the same during the simulation, so that the
appropriate averaging can be done. This will be the case if the
simulation box size doesn't change or if the {units} keyword is set to
{reduced}.
[Related commands:]
"compute"_compute.html, "fix ave/time"_fix_ave_time.html
[Default:]
The option defaults are units = lattice, norm = all, no file output,
-and ave = one.
+and ave = one, title 1,2,3 = strings as described above.
+
diff --git a/doc/thermo_style.html b/doc/thermo_style.html
index 3848ed32a..6adfad029 100644
--- a/doc/thermo_style.html
+++ b/doc/thermo_style.html
@@ -1,278 +1,272 @@
<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>thermo_style command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>thermo_style style args
</PRE>
<UL><LI>style = <I>one</I> or <I>multi</I> or <I>custom</I>
<LI>args = list of arguments for a particular style
<PRE> <I>one</I> args = none
<I>multi</I> args = none
<I>custom</I> args = list of attributes
possible attributes = step, atoms, cpu, temp, press,
pe, ke, etotal, enthalpy,
evdwl, ecoul, epair, ebond, eangle, edihed, eimp,
emol, elong, etail,
vol, lx, ly, lz, xlo, xhi, ylo, yhi, zlo, zhi,
xy, xz, yz,
pxx, pyy, pzz, pxy, pxz, pyz,
- c_ID, c_ID[n], f_ID, f_ID[n], v_name
+ c_ID, c_ID[I], c_ID[I][J],
+ f_ID, f_ID[I], f_ID[I][J],
+ v_name
step = timestep
atoms = # of atoms
cpu = elapsed CPU time
temp = temperature
press = pressure
pe = total potential energy
ke = kinetic energy
etotal = total energy (pe + ke)
enthalpy = enthalpy (etotal + press*vol)
evdwl = VanderWaal pairwise energy
ecoul = Coulombic pairwise energy
epair = pairwise energy (evdwl + ecoul + elong + etail)
ebond = bond energy
eangle = angle energy
edihed = dihedral energy
eimp = improper energy
emol = molecular energy (ebond + eangle + edihed + eimp)
elong = long-range kspace energy
etail = VanderWaal energy long-range tail correction
vol = volume
lx,ly,lz = box lengths in x,y,z
xlo,xhi,ylo,yhi,zlo,zhi = box boundaries
xy,xz,yz = box tilt for triclinic (non-orthogonal) simulation boxes
pxx,pyy,pzz,pxy,pxz,pyz = 6 components of pressure tensor
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
+ c_ID[I] = Ith component of global vector calculated by a compute with ID
+ c_ID[I][J] = I,J component of global array 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
- v_name = global value calculated by an equal-style variable with name
+ f_ID[I] = Ith component of global vector calculated by a fix with ID
+ f_ID[I][J] = I,J component of global array calculated by a fix with ID
+ v_name = scalar value calculated by an equal-style variable with name
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>thermo_style multi
thermo_style custom step temp pe etotal press vol
thermo_style custom step temp etotal c_myTemp v_abc
</PRE>
<P><B>Description:</B>
</P>
<P>Set the style and content for printing thermodynamic data to the
screen and log file.
</P>
<P>Style <I>one</I> prints a one-line summary of thermodynamic info that is
the equivalent of "thermo_style custom step temp epair emol etotal
press". The line contains only numeric values.
</P>
<P>Style <I>multi</I> prints a multiple-line listing of thermodynamic info
that is the equivalent of "thermo_style custom etotal ke temp pe ebond
eangle edihed eimp evdwl ecoul elong press". The listing contains
numeric values and a string ID for each quantity.
</P>
<P>Style <I>custom</I> is the most general setting and allows you to specify
which of the keywords listed above you want printed on each
thermodynamic timestep. Note that the keywords c_ID, f_ID, v_name are
references to <A HREF = "compute.html">computes</A>, <A HREF = "fix.html">fixes</A>, and
equal-style <A HREF = "variable.html"">variables</A> that have been defined
elsewhere in the input script or can even be new styles which users
have added to LAMMPS (see the <A HREF = "Section_modify.html">Section_modify</A>
section of the documentation). Thus the <I>custom</I> style provides a
flexible means of outputting essentially any desired quantity as a
simulation proceeds.
</P>
<P>All styles except <I>custom</I> have <I>vol</I> appended to their list of
outputs if the simulation box volume changes during the simulation.
</P>
<P>The values printed by the various keywords are instantaneous values,
calculated on the current timestep. Time-averaged quantities, which
include values from previous timesteps, can be output by using the
f_ID keyword and accessing a fix that does time-averaging such as the
<A HREF = "fix_ave_time.html">fix ave/time</A> command.
</P>
<P>Options invoked by the <A HREF = "thermo_modify.html">thermo_modify</A> command can
be used to set the one- or multi-line format of the print-out, the
normalization of thermodynamic output (total values versus per-atom
values for extensive quantities (ones which scale with the number of
atoms in the system), and the numeric precision of each printed value.
</P>
<P>IMPORTANT NOTE: When you use a "thermo_style" command, all
thermodynamic settings are restored to their default values, including
those previously set by a <A HREF = "thermo_modify.html">thermo_modify</A> command.
Thus if your input script specifies a thermo_style command, you should
use the thermo_modify command after it.
</P>
<HR>
<P>Several of the thermodynamic quantities require a temperature to be
computed: "temp", "press", "ke", "etotal", "enthalpy", "pxx etc". By
default this is done by using a <I>temperature</I> compute which is created
when LAMMPS starts up, as if this command had been issued:
</P>
<PRE>compute thermo_temp all temp
</PRE>
<P>See the <A HREF = "compute_temp.html">compute temp</A> command for details. Note
that the ID of this compute is <I>thermo_temp</I> and the group is <I>all</I>.
You can change the attributes of this temperature (e.g. its
degrees-of-freedom) via the <A HREF = "compute_modify.html">compute_modify</A>
command. Alternatively, you can directly assign a new compute (that
calculates temperature) which you have defined, to be used for
calculating any thermodynamic quantity that requires a temperature.
This is done via the <A HREF = "thermo_modify.html">thermo_modify</A> command.
</P>
<P>Several of the thermodynamic quantities require a pressure to be
computed: "press", "enthalpy", "pxx", etc. By default this is done by
using a <I>pressure</I> compute which is created when LAMMPS starts up, as
if this command had been issued:
</P>
<PRE>compute thermo_press all pressure thermo_temp
</PRE>
<P>See the <A HREF = "compute_pressure.html">compute pressure</A> command for details.
Note that the ID of this compute is <I>thermo_press</I> and the group is
<I>all</I>. You can change the attributes of this pressure via the
<A HREF = "compute_modify.html">compute_modify</A> command. Alternatively, you can
directly assign a new compute (that calculates pressure) which you
have defined, to be used for calculating any thermodynamic quantity
that requires a pressure. This is done via the
<A HREF = "thermo_modify.html">thermo_modify</A> command.
</P>
<P>Several of the thermodynamic quantities require a potential energy to
be computed: "pe", "etotal", "ebond", etc. This is done by using a
<I>pe</I> compute which is created when LAMMPS starts up, as if this
command had been issued:
</P>
<PRE>compute thermo_pe all pe
</PRE>
<P>See the <A HREF = "compute_pe.html">compute pe</A> command for details. Note that
the ID of this compute is <I>thermo_pe</I> and the group is <I>all</I>. You can
change the attributes of this potential energy via the
<A HREF = "compute_modify.html">compute_modify</A> command.
</P>
<HR>
<P>The kinetic energy of the system <I>ke</I> is inferred from the temperature
of the system with 1/2 Kb T of energy for each degree of freedom.
Thus, using different <A HREF = "compute.html">compute commands</A> for calculating
temperature, via the <A HREF = "thermo_modify.html">thermo_modify temp</A> command,
may yield different kinetic energies, since different computes that
calculate temperature can subtract out different non-thermal
components of velocity and/or include different degrees of freedom
(translational, rotational, etc).
</P>
<P>The potential energy of the system <I>pe</I> will include contributions
from fixes if the <A HREF = "fix_modify.html">fix_modify thermo</A> option is set
for a fix that calculates such a contribution. For example, the <A HREF = "fix_wall_lj93">fix
wall/lj93</A> fix calculates the energy of atoms
interacting with the wall. See the doc pages for "individual fixes"
to see which ones contribute.
</P>
<P>A long-range tail correction <I>etail</I> for the VanderWaal pairwise
energy will be non-zero only if the <A HREF = "pair_modify.html">pair_modify
tail</A> option is turned on. The <I>etail</I> contribution
is included in <I>evdwl</I>, <I>pe</I>, and <I>etotal</I>, and the corresponding tail
correction to the pressure is included in <I>press</I> and <I>pxx</I>, <I>pyy</I>,
etc.
</P>
<HR>
-<P>The <I>c_ID</I> and <I>c_ID[N]</I> keywords allow global scalar or vector
-quantities calculated by a compute to be output. The ID in the
-keyword should be replaced by the actual ID of the compute that has
-been defined elsewhere in the input script. See the
-<A HREF = "compute.html">compute</A> command for details. Note that only global
-scalar or vector quantities calculated by a compute can be output as
-thermodynamic data; per-atom quantities calculated by a compute can be
-output by the <A HREF = "dump.html">dump custom</A> command. 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 be output by thermo_style
-custom.
+<P>The <I>c_ID</I> and <I>c_ID[I]</I> and <I>c_ID[I][J]</I> keywords allow global
+values calculated by a compute to be output. As discussed on the
+<A HREF = "compute.html">compute</A> doc page, computes can calculate global,
+per-atom, or local values. Only global values can be referenced by
+this command. However, per-atom compute values can be referenced in a
+<A HREF = "variable.html">variable</A> and the variable referenced by thermo_style
+custom, as discussed below.
+</P>
+<P>The ID in the keyword should be replaced by the actual ID of a compute
+that has been defined elsewhere in the input script. See the
+<A HREF = "compute.html">compute</A> command for details. If the compute calculates
+a global scalar, vector, or array, then the keyword formats with 0, 1,
+or 2 brackets will reference a scalar value from the compute.
</P>
<P>Note that some computes calculate "intensive" global quantities like
temperature; others calculate "extensive" global quantities like
kinetic energy that are summed over all atoms in the compute group.
-Intensive quantities are printed directly as is by thermo_style
-custom. Extensive quantities may be normalized when output by the
+Intensive quantities are printed directly without normalization by
+thermo_style custom. Extensive quantities may be normalized by the
total number of atoms in the simulation (NOT the number of atoms in
-the compute group) depending on the <A HREF = "thermo_modify.html">thermo_modify
+the compute group) when output, depending on the <A HREF = "thermo_modify.html">thermo_modify
norm</A> option being used.
</P>
-<P>If <I>c_ID</I> is used as a keyword, then the scalar quantity calculated by
-the compute is printed. If <I>c_ID[N]</I> is used, then N must be an
-index from 1-M where M is the length of the vector calculated by the
-compute. See the doc pages for individual compute styles for info on
-what these quantities are.
-</P>
-<P>The <I>f_ID</I> and <I>f_ID[N]</I> keywords allow global scalar or vector
-quantities calculated by a fix to be output. The ID in the keyword
-should be replaced by the actual ID of the fix that has been defined
-elsewhere in the input script. See the doc pages for individual <A HREF = "fix.html">fix
-commands</A> for details of which fixes generate global values.
-One particularly useful fix to use in this context is the <A HREF = "fix_ave_time.html">fix
-ave/time</A> command, which calculates time-averages of
-global scalar and vector quantities calculated by other
-<A HREF = "compute.html">computes</A>, <A HREF = "fix.html">fixes</A>, or
-<A HREF = "variable.html">variables</A>.
+<P>The <I>f_ID</I> and <I>f_ID[I]</I> and <I>f_ID[I][J]</I> keywords allow global
+values calculated by a fix to be output. As discussed on the
+<A HREF = "fix.html">fix</A> doc page, fixes can calculate global, per-atom, or
+local values. Only global values can be referenced by this command.
+However, per-atom fix values can be referenced in a
+<A HREF = "variable.html">variable</A> and the variable referenced by thermo_style
+custom, as discussed below.
+</P>
+<P>The ID in the keyword should be replaced by the actual ID of a fix
+that has been defined elsewhere in the input script. See the
+<A HREF = "fix.html">fix</A> command for details. If the fix calculates a global
+scalar, vector, or array, then the keyword formats with 0, 1, or 2
+brackets will reference a scalar value from the fix.
</P>
<P>Note that some fixes calculate "intensive" global quantities like
timestep size; others calculate "extensive" global quantities like
energy that are summed over all atoms in the fix group. Intensive
-quantities are printed directly as is by thermo_style custom.
-Extensive quantities may be normalized when output by the total number
-of atoms in the simulation (NOT the number of atoms in the fix group)
-depending on the <A HREF = "thermo_modify.html">thermo_modify norm</A> option being
-used.
-</P>
-<P>If <I>f_ID</I> is used as a keyword, then the scalar quantity calculated by
-the fix is printed. If <I>f_ID[N]</I> is used, then N must be an index
-from 1-M where M is the length of the vector calculated by the fix.
-See the doc pages for individual fix styles for info on which fixes
-calculate these global quantities and what they are. For fixes that
-compute a contribution to the potential energy of the system, the
-scalar quantity referenced by f_ID is typically that quantity.
+quantities are printed directly without normalization by thermo_style
+custom. Extensive quantities may be normalized by the total number of
+atoms in the simulation (NOT the number of atoms in the fix group)
+when output, depending on the <A HREF = "thermo_modify.html">thermo_modify norm</A>
+option being used.
</P>
<P>The <I>v_name</I> keyword allow the current value of a variable to be
output. The name in the keyword should be replaced by the actual name
of the variable that has been defined elsewhere in the input script.
Only equal-style variables can be referenced. See the
<A HREF = "variable.html">variable</A> command for details. Variables of style
-<I>equal</I> can reference individual atom properties or thermodynamic
-keywords, or they can invoke other computes, fixes, or variables when
-evaluated, so this is a very general means of creating thermodynamic
-output.
+<I>equal</I> can reference per-atom properties or thermodynamic keywords,
+or they can invoke other computes, fixes, or variables when evaluated,
+so this is a very general means of creating thermodynamic output.
</P>
<P>See <A HREF = "Section_modify.html">this section</A> for information on how to add
-new compute and fix styles to LAMMPS to calculate quantities that
-could then be output with these keywords as part of thermodynamic
-information.
+new compute and fix styles to LAMMPS to calculate quantities that can
+then be referenced with these keywords to generate thermodynamic
+output.
</P>
<HR>
<P><B>Restrictions:</B>
</P>
<P>This command must come after the simulation box is defined by a
<A HREF = "read_data.html">read_data</A>, <A HREF = "read_restart.html">read_restart</A>, or
<A HREF = "create_box.html">create_box</A> command.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "thermo.html">thermo</A>, <A HREF = "thermo_modify.html">thermo_modify</A>,
<A HREF = "fix_modify.html">fix_modify</A>, <A HREF = "compute_temp.html">compute temp</A>,
<A HREF = "compute_pressure.html">compute pressure</A>
</P>
<P><B>Default:</B>
</P>
<PRE>thermo_style one
</PRE>
</HTML>
diff --git a/doc/thermo_style.txt b/doc/thermo_style.txt
index bb77136c4..75883361f 100644
--- a/doc/thermo_style.txt
+++ b/doc/thermo_style.txt
@@ -1,270 +1,264 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
thermo_style command :h3
[Syntax:]
thermo_style style args :pre
style = {one} or {multi} or {custom} :ulb,l
args = list of arguments for a particular style :l
{one} args = none
{multi} args = none
{custom} args = list of attributes
possible attributes = step, atoms, cpu, temp, press,
pe, ke, etotal, enthalpy,
evdwl, ecoul, epair, ebond, eangle, edihed, eimp,
emol, elong, etail,
vol, lx, ly, lz, xlo, xhi, ylo, yhi, zlo, zhi,
xy, xz, yz,
pxx, pyy, pzz, pxy, pxz, pyz,
- c_ID, c_ID\[n\], f_ID, f_ID\[n\], v_name
+ c_ID, c_ID\[I\], c_ID\[I\]\[J\],
+ f_ID, f_ID\[I\], f_ID\[I\]\[J\],
+ v_name
step = timestep
atoms = # of atoms
cpu = elapsed CPU time
temp = temperature
press = pressure
pe = total potential energy
ke = kinetic energy
etotal = total energy (pe + ke)
enthalpy = enthalpy (etotal + press*vol)
evdwl = VanderWaal pairwise energy
ecoul = Coulombic pairwise energy
epair = pairwise energy (evdwl + ecoul + elong + etail)
ebond = bond energy
eangle = angle energy
edihed = dihedral energy
eimp = improper energy
emol = molecular energy (ebond + eangle + edihed + eimp)
elong = long-range kspace energy
etail = VanderWaal energy long-range tail correction
vol = volume
lx,ly,lz = box lengths in x,y,z
xlo,xhi,ylo,yhi,zlo,zhi = box boundaries
xy,xz,yz = box tilt for triclinic (non-orthogonal) simulation boxes
pxx,pyy,pzz,pxy,pxz,pyz = 6 components of pressure tensor
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
+ c_ID\[I\] = Ith component of global vector calculated by a compute with ID
+ c_ID\[I\]\[J\] = I,J component of global array 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
- v_name = global value calculated by an equal-style variable with name :pre
+ f_ID\[I\] = Ith component of global vector calculated by a fix with ID
+ f_ID\[I\]\[J\] = I,J component of global array calculated by a fix with ID
+ v_name = scalar value calculated by an equal-style variable with name :pre
:ule
[Examples:]
thermo_style multi
thermo_style custom step temp pe etotal press vol
thermo_style custom step temp etotal c_myTemp v_abc :pre
[Description:]
Set the style and content for printing thermodynamic data to the
screen and log file.
Style {one} prints a one-line summary of thermodynamic info that is
the equivalent of "thermo_style custom step temp epair emol etotal
press". The line contains only numeric values.
Style {multi} prints a multiple-line listing of thermodynamic info
that is the equivalent of "thermo_style custom etotal ke temp pe ebond
eangle edihed eimp evdwl ecoul elong press". The listing contains
numeric values and a string ID for each quantity.
Style {custom} is the most general setting and allows you to specify
which of the keywords listed above you want printed on each
thermodynamic timestep. Note that the keywords c_ID, f_ID, v_name are
references to "computes"_compute.html, "fixes"_fix.html, and
equal-style "variables"_variable.html" that have been defined
elsewhere in the input script or can even be new styles which users
have added to LAMMPS (see the "Section_modify"_Section_modify.html
section of the documentation). Thus the {custom} style provides a
flexible means of outputting essentially any desired quantity as a
simulation proceeds.
All styles except {custom} have {vol} appended to their list of
outputs if the simulation box volume changes during the simulation.
The values printed by the various keywords are instantaneous values,
calculated on the current timestep. Time-averaged quantities, which
include values from previous timesteps, can be output by using the
f_ID keyword and accessing a fix that does time-averaging such as the
"fix ave/time"_fix_ave_time.html command.
Options invoked by the "thermo_modify"_thermo_modify.html command can
be used to set the one- or multi-line format of the print-out, the
normalization of thermodynamic output (total values versus per-atom
values for extensive quantities (ones which scale with the number of
atoms in the system), and the numeric precision of each printed value.
IMPORTANT NOTE: When you use a "thermo_style" command, all
thermodynamic settings are restored to their default values, including
those previously set by a "thermo_modify"_thermo_modify.html command.
Thus if your input script specifies a thermo_style command, you should
use the thermo_modify command after it.
:line
Several of the thermodynamic quantities require a temperature to be
computed: "temp", "press", "ke", "etotal", "enthalpy", "pxx etc". By
default this is done by using a {temperature} compute which is created
when LAMMPS starts up, as if this command had been issued:
compute thermo_temp all temp :pre
See the "compute temp"_compute_temp.html command for details. Note
that the ID of this compute is {thermo_temp} and the group is {all}.
You can change the attributes of this temperature (e.g. its
degrees-of-freedom) via the "compute_modify"_compute_modify.html
command. Alternatively, you can directly assign a new compute (that
calculates temperature) which you have defined, to be used for
calculating any thermodynamic quantity that requires a temperature.
This is done via the "thermo_modify"_thermo_modify.html command.
Several of the thermodynamic quantities require a pressure to be
computed: "press", "enthalpy", "pxx", etc. By default this is done by
using a {pressure} compute which is created when LAMMPS starts up, as
if this command had been issued:
compute thermo_press all pressure thermo_temp :pre
See the "compute pressure"_compute_pressure.html command for details.
Note that the ID of this compute is {thermo_press} and the group is
{all}. You can change the attributes of this pressure via the
"compute_modify"_compute_modify.html command. Alternatively, you can
directly assign a new compute (that calculates pressure) which you
have defined, to be used for calculating any thermodynamic quantity
that requires a pressure. This is done via the
"thermo_modify"_thermo_modify.html command.
Several of the thermodynamic quantities require a potential energy to
be computed: "pe", "etotal", "ebond", etc. This is done by using a
{pe} compute which is created when LAMMPS starts up, as if this
command had been issued:
compute thermo_pe all pe :pre
See the "compute pe"_compute_pe.html command for details. Note that
the ID of this compute is {thermo_pe} and the group is {all}. You can
change the attributes of this potential energy via the
"compute_modify"_compute_modify.html command.
:line
The kinetic energy of the system {ke} is inferred from the temperature
of the system with 1/2 Kb T of energy for each degree of freedom.
Thus, using different "compute commands"_compute.html for calculating
temperature, via the "thermo_modify temp"_thermo_modify.html command,
may yield different kinetic energies, since different computes that
calculate temperature can subtract out different non-thermal
components of velocity and/or include different degrees of freedom
(translational, rotational, etc).
The potential energy of the system {pe} will include contributions
from fixes if the "fix_modify thermo"_fix_modify.html option is set
for a fix that calculates such a contribution. For example, the "fix
wall/lj93"_fix_wall_lj93 fix calculates the energy of atoms
interacting with the wall. See the doc pages for "individual fixes"
to see which ones contribute.
A long-range tail correction {etail} for the VanderWaal pairwise
energy will be non-zero only if the "pair_modify
tail"_pair_modify.html option is turned on. The {etail} contribution
is included in {evdwl}, {pe}, and {etotal}, and the corresponding tail
correction to the pressure is included in {press} and {pxx}, {pyy},
etc.
:line
-The {c_ID} and {c_ID\[N\]} keywords allow global scalar or vector
-quantities calculated by a compute to be output. The ID in the
-keyword should be replaced by the actual ID of the compute that has
-been defined elsewhere in the input script. See the
-"compute"_compute.html command for details. Note that only global
-scalar or vector quantities calculated by a compute can be output as
-thermodynamic data; per-atom quantities calculated by a compute can be
-output by the "dump custom"_dump.html command. There is a "compute
-reduce"_compute_reduce.html command which can sum per-atom quantities
-into a global scalar or vector which can be output by thermo_style
-custom.
+The {c_ID} and {c_ID\[I\]} and {c_ID\[I\]\[J\]} keywords allow global
+values calculated by a compute to be output. As discussed on the
+"compute"_compute.html doc page, computes can calculate global,
+per-atom, or local values. Only global values can be referenced by
+this command. However, per-atom compute values can be referenced in a
+"variable"_variable.html and the variable referenced by thermo_style
+custom, as discussed below.
+
+The ID in the keyword should be replaced by the actual ID of a compute
+that has been defined elsewhere in the input script. See the
+"compute"_compute.html command for details. If the compute calculates
+a global scalar, vector, or array, then the keyword formats with 0, 1,
+or 2 brackets will reference a scalar value from the compute.
Note that some computes calculate "intensive" global quantities like
temperature; others calculate "extensive" global quantities like
kinetic energy that are summed over all atoms in the compute group.
-Intensive quantities are printed directly as is by thermo_style
-custom. Extensive quantities may be normalized when output by the
+Intensive quantities are printed directly without normalization by
+thermo_style custom. Extensive quantities may be normalized by the
total number of atoms in the simulation (NOT the number of atoms in
-the compute group) depending on the "thermo_modify
+the compute group) when output, depending on the "thermo_modify
norm"_thermo_modify.html option being used.
-If {c_ID} is used as a keyword, then the scalar quantity calculated by
-the compute is printed. If {c_ID\[N\]} is used, then N must be an
-index from 1-M where M is the length of the vector calculated by the
-compute. See the doc pages for individual compute styles for info on
-what these quantities are.
-
-The {f_ID} and {f_ID\[N\]} keywords allow global scalar or vector
-quantities calculated by a fix to be output. The ID in the keyword
-should be replaced by the actual ID of the fix that has been defined
-elsewhere in the input script. See the doc pages for individual "fix
-commands"_fix.html for details of which fixes generate global values.
-One particularly useful fix to use in this context is the "fix
-ave/time"_fix_ave_time.html command, which calculates time-averages of
-global scalar and vector quantities calculated by other
-"computes"_compute.html, "fixes"_fix.html, or
-"variables"_variable.html.
+The {f_ID} and {f_ID\[I\]} and {f_ID\[I\]\[J\]} keywords allow global
+values calculated by a fix to be output. As discussed on the
+"fix"_fix.html doc page, fixes can calculate global, per-atom, or
+local values. Only global values can be referenced by this command.
+However, per-atom fix values can be referenced in a
+"variable"_variable.html and the variable referenced by thermo_style
+custom, as discussed below.
+
+The ID in the keyword should be replaced by the actual ID of a fix
+that has been defined elsewhere in the input script. See the
+"fix"_fix.html command for details. If the fix calculates a global
+scalar, vector, or array, then the keyword formats with 0, 1, or 2
+brackets will reference a scalar value from the fix.
Note that some fixes calculate "intensive" global quantities like
timestep size; others calculate "extensive" global quantities like
energy that are summed over all atoms in the fix group. Intensive
-quantities are printed directly as is by thermo_style custom.
-Extensive quantities may be normalized when output by the total number
-of atoms in the simulation (NOT the number of atoms in the fix group)
-depending on the "thermo_modify norm"_thermo_modify.html option being
-used.
-
-If {f_ID} is used as a keyword, then the scalar quantity calculated by
-the fix is printed. If {f_ID\[N\]} is used, then N must be an index
-from 1-M where M is the length of the vector calculated by the fix.
-See the doc pages for individual fix styles for info on which fixes
-calculate these global quantities and what they are. For fixes that
-compute a contribution to the potential energy of the system, the
-scalar quantity referenced by f_ID is typically that quantity.
+quantities are printed directly without normalization by thermo_style
+custom. Extensive quantities may be normalized by the total number of
+atoms in the simulation (NOT the number of atoms in the fix group)
+when output, depending on the "thermo_modify norm"_thermo_modify.html
+option being used.
The {v_name} keyword allow the current value of a variable to be
output. The name in the keyword should be replaced by the actual name
of the variable that has been defined elsewhere in the input script.
Only equal-style variables can be referenced. See the
"variable"_variable.html command for details. Variables of style
-{equal} can reference individual atom properties or thermodynamic
-keywords, or they can invoke other computes, fixes, or variables when
-evaluated, so this is a very general means of creating thermodynamic
-output.
+{equal} can reference per-atom properties or thermodynamic keywords,
+or they can invoke other computes, fixes, or variables when evaluated,
+so this is a very general means of creating thermodynamic output.
See "this section"_Section_modify.html for information on how to add
-new compute and fix styles to LAMMPS to calculate quantities that
-could then be output with these keywords as part of thermodynamic
-information.
+new compute and fix styles to LAMMPS to calculate quantities that can
+then be referenced with these keywords to generate thermodynamic
+output.
:line
[Restrictions:]
This command must come after the simulation box is defined by a
"read_data"_read_data.html, "read_restart"_read_restart.html, or
"create_box"_create_box.html command.
[Related commands:]
"thermo"_thermo.html, "thermo_modify"_thermo_modify.html,
"fix_modify"_fix_modify.html, "compute temp"_compute_temp.html,
"compute pressure"_compute_pressure.html
[Default:]
thermo_style one :pre
diff --git a/doc/variable.html b/doc/variable.html
index ce1cfe703..aad96b459 100644
--- a/doc/variable.html
+++ b/doc/variable.html
@@ -1,586 +1,604 @@
<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>variable command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>variable name style args ...
</PRE>
<UL><LI>name = name of variable to define
<LI>style = <I>delete</I> or <I>index</I> or <I>loop</I> or <I>world</I> or <I>universe</I> or <I>uloop</I> or <I>equal</I> or <I>atom</I>
<PRE> <I>delete</I> = no args
<I>index</I> args = one or more strings
<I>loop</I> args = N = integer size of loop
<I>world</I> args = one string for each partition of processors
<I>universe</I> args = one or more strings
<I>uloop</I> args = N = integer size of loop
<I>equal</I> or <I>atom</I> args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references
numbers = 0.0, 100, -5.4, 2.8e-4, etc
thermo keywords = vol, ke, press, etc from <A HREF = "thermo_style.html">thermo_style</A>
math operations = (), -x, x+y, x-y, x*y, x/y, x^y,
sqrt(x), exp(x), ln(x), log(x),
sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
ceil(x), floor(x), round(x)
group functions = count(group), mass(group), charge(group),
xcm(group,dim), vcm(group,dim), fcm(group,dim),
bound(group,xmin), gyration(group), ke(group)
region functions = count(group,region), mass(group,region), charge(group,region),
xcm(group,dim,region), vcm(group,dim,region), fcm(group,dim,region),
bound(group,xmin,region), gyration(group,region), ke(group,reigon)
- atom value = mass[N], type[N], x[N], y[N], z[N],
- vx[N], vy[N], vz[N], fx[N], fy[N], fz[N]
- atom vector = mass[], type[], x[], y[], z[],
- vx[], vy[], vz[], fx[], fy[], fz[]
- compute references = c_ID, c_ID[2], c_ID[N], c_ID[N][2], c_ID[], c_ID[][2]
- fix references = f_ID, f_ID[2], f_ID[N], f_ID[N][2], f_ID[], f_ID[][2]
- variable references = v_abc, v_abc[N], v_abc[]
+ atom value = mass[i], type[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i]
+ atom vector = mass, type, x, y, z, vx, vy, vz, fx, fy, fz
+ compute references = c_ID, c_ID[i], c_ID[i][j]
+ fix references = f_ID, f_ID[i], f_ID[i][j]
+ variable references = v_name, v_name[i]
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>variable x index run1 run2 run3 run4 run5 run6 run7 run8
variable LoopVar loop $n
variable beta equal temp/3.0
variable b1 equal x[234]+0.5*vol
variable b1 equal "x[234] + 0.5*vol"
variable b equal xcm(mol1,x)/2.0
variable b equal c_myTemp
-variable b atom x[]*y[]/vol
+variable b atom x*y/vol
variable temp world 300.0 310.0 320.0 ${Tfinal}
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
variable x uloop 15
variable x delete
</PRE>
<P><B>Description:</B>
</P>
<P>This command assigns one or more strings to a variable name for
evaluation later in the input script or during a simulation.
</P>
<P>Variables can be used in several ways in LAMMPS. A variable can be
referenced elsewhere in an input script to become part of a new input
command. For variable styles that store multiple strings, the
<A HREF = "next.html">next</A> command can be used to increment which string is
assigned to the variable. Variables of style <I>equal</I> store a formula
which when evaluated produces a single numeric value which can be
output either directly (see the <A HREF = "print.html">print</A>, <A HREF = "fix_print.html">fix
print</A>, and <A HREF = "run.html">run every</A> commands) or as part
of thermodynamic output (see the <A HREF = "thermo_style.html">thermo_style</A>
command), or used as input to an averaging fix (see the <A HREF = "fix_ave/time">fix
ave/time</A> command). Variables of style <I>atom</I> store a
formula which when evaluated produces one numeric value per atom which
can be output to a dump file (see the <A HREF = "dump.html">dump custom</A> command)
or used as input to an averaging fix (see the <A HREF = "fix_ave_spatial.html">fix
ave/spatial</A> and <A HREF = "fix_ave_atom.html">fix ave/atom</A>
commands).
</P>
<P>In the discussion that follows, the "name" of the variable is the
arbitrary string that is the 1st argument in the variable command.
This name can only contain alphanumeric characters and underscores.
The "string" is one or more of the subsequent arguments. The "string"
can be simple text as in the 1st example above, it can contain other
variables as in the 2nd example, or it can be a formula as in the 3rd
example. The "value" is the numeric quantity resulting from
evaluation of the string. Note that the same string can generate
different values when it is evaluated at different times during a
simulation.
</P>
<P>IMPORTANT NOTE: When the input script line that defines a variable of
style <I>equal</I> or <I>atom</I> that contain a formula is encountered, the
formula is NOT immediately evaluated and the result stored. See the
discussion below about "Immediate Evaluation of Variables" if you want
to do this.
</P>
<P>IMPORTANT NOTE: When a variable command is encountered in the input
script and the variable name has already been specified, the command
is ignored. This means variables can NOT be re-defined in an input
script (with 2 exceptions, read further). This is to allow an input
script to be processed multiple times without resetting the variables;
see the <A HREF = "jump.html">jump</A> or <A HREF = "include.html">include</A> commands. It also
means that using the <A HREF = "Section_start.html#2_6">command-line switch</A> -var
will override a corresponding index variable setting in the input
script.
</P>
<P>There are two exceptions to this rule. First, variables of style
<I>equal</I> and <I>atom</I> ARE redefined each time the command is encountered.
This only changes their associated formula if the formula contains a
substitution for another variable, e.g. $x. But that can be useful,
for example, in a loop.
</P>
<P>Second, as described below, if a variable is iterated on to the end of
its list of strings via the <A HREF = "next.html">next</A> command, it is removed
from the list of active variables, and is thus available to be
re-defined in a subsequent variable command. The <I>delete</I> style does
the same thing.
</P>
<HR>
<P><A HREF = "Section_commands.html#3_2">This section</A> of the manual explains how
occurrences of a variable name in an input script line are replaced by
the variable's string. The variable name can be referenced as $x if
the name "x" is a single character, or as ${LoopVar} if the name
"LoopVar" is one or more characters.
</P>
<P>As described below, for variable styles <I>index</I>, <I>loop</I>, <I>universe</I>,
and <I>uloop</I>, which string is assigned to a variable can be incremented
via the <A HREF = "next.html">next</A> command. When there are no more strings to
assign, the variable is exhausted and a flag is set that causes the
next <A HREF = "jump.html">jump</A> command encountered in the input script to be
skipped. This enables the construction of simple loops in the input
script that are iterated over and then exited from.
</P>
<P>As explained above, an exhausted variable can be re-used in an input
script. The <I>delete</I> style also removes the variable, the same as if
it were exhausted, allowing it to be redefined later in the input
script or when the input script is looped over. This can be useful
when breaking out of a loop via the <A HREF = "if.html">if</A> and <A HREF = "jump.html">jump</A>
commands before the variable would become exhausted. For example,
</P>
<PRE>label loop
variable a loop 5
print "A = $a"
if $a > 2 then "jump in.script break"
next a
jump in.script loop
label break
variable a delete
</PRE>
<HR>
<P>For the <I>index</I> style, one or more strings are specified. Initially,
the 1st string is assigned to the variable. Each time a
<A HREF = "next.html">next</A> command is used with the variable name, the next
string is assigned. All processors assign the same string to the
variable.
</P>
<P><I>Index</I> style variables with a single string value can also be set by
using the command-line switch -var; see <A HREF = "Section_start.html#2_6">this
section</A> for details.
</P>
<P>The <I>loop</I> style is identical to the <I>index</I> style except that the
strings are the integers from 1 to N. This allows generation of a
long list of runs (e.g. 1000) without having to list N strings in the
input script. Initially, the string "1" is assigned to the variable.
Each time a <A HREF = "next.html">next</A> command is used with the variable name,
the next string ("2", "3", etc) is assigned. All processors assign
the same string to the variable.
</P>
<P>For the <I>world</I> style, one or more strings are specified. There must
be one string for each processor partition or "world". See <A HREF = "Section_start.html#2_6">this
section</A> of the manual for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command assigns one string to each
world. All processors in the world are assigned the same string. The
next command cannot be used with <I>equal</I> style variables, since there
is only one value per world. This style of variable is useful when
you wish to run different simulations on different partitions, or when
performing a parallel tempering simulation (see the
<A HREF = "temper.html">temper</A> command), to assign different temperatures to
different partitions.
</P>
<P>For the <I>universe</I> style, one or more strings are specified. There
must be at least as many strings as there are processor partitions or
"worlds". See <A HREF = "Section_start.html#2_6">this page</A> for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command initially assigns one
string to each world. When a <A HREF = "next.html">next</A> command is encountered
using this variable, the first processor partition to encounter it, is
assigned the next available string. This continues until all the
variable strings are consumed. Thus, this command can be used to run
50 simulations on 8 processor partitions. The simulations will be run
one after the other on whatever partition becomes available, until
they are all finished. <I>Universe</I> style variables are incremented
using the files "tmp.lammps.variable" and "tmp.lammps.variable.lock"
which you will see in your directory during such a LAMMPS run.
</P>
<P>The <I>uloop</I> style is identical to the <I>universe</I> style except that the
strings are the integers from 1 to N. This allows generation of long
list of runs (e.g. 1000) without having to list N strings in the input
script.
</P>
<HR>
<P>For the <I>equal</I> and <I>atom</I> styles, a single string is specified which
represents a formula that will be evaluated afresh each time the
variable is used. If you want spaces in the string, enclose it in
double quotes so the parser will treat it as a single argument. For
<I>equal</I> style variables the formula computes a scalar quantity, which
becomes the value of the variable whenever it is evaluated. For
<I>atom</I> style variables the formula computes one quantity for each
atom whenever it is evaluated.
</P>
<P>Note that <I>equal</I> and <I>atom</I> variables can produce different values at
different stages of the input script or at different times during a
run. For example, if an <I>equal</I> variable is used in a <A HREF = "fix_print.html">fix
print</A> command, different values could be printed each
timestep it was invoked. If you want a variable to be evaluated
immediately, so that the result is stored by the variable instead of
the string, see the section below on "Immediate Evaluation of
Variables".
</P>
<P>The next command cannot be used with <I>equal</I> or <I>atom</I> style
variables, since there is only one string.
</P>
<P>The formula for an <I>equal</I> or <I>atom</I> variable can contain a variety
of quantities. The syntax for each kind of quantity is simple, but
multiple quantities can be nested and combined in various ways to
build up formulas of arbitrary complexity. For example, this is a
valid (though strange) variable formula:
</P>
<PRE>variable x equal "pe + c_MyTemp / vol^(1/3)"
</PRE>
<P>Specifically, an formula can contain numbers, thermo keywords, math
operations, group functions, atom values, atom vectors, compute
references, fix references, and references to other variables.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >Number</TD><TD > 0.2, 100, 1.0e20, -15.4, etc</TD></TR>
<TR><TD >Thermo keywords</TD><TD > vol, pe, ebond, etc</TD></TR>
<TR><TD >Math operations</TD><TD > (), -x, x+y, x-y, x*y, x/y, x^y, sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), ceil(x), floor(x), round(x)</TD></TR>
<TR><TD >Group functions</TD><TD > count(ID), mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID)</TD></TR>
<TR><TD >Region functions</TD><TD > count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR)</TD></TR>
-<TR><TD >Atom values</TD><TD > mass[N], type[N], x[N], y[N], z[N], vx[N], vy[N], vz[N], fx[N], fy[N], fz[N]</TD></TR>
-<TR><TD >Atom vectors</TD><TD > mass[], type[], x[], y[], z[], vx[], vy[], vz[], fx[], fy[], fz[]</TD></TR>
-<TR><TD >Compute references</TD><TD > c_ID, c_ID[2], c_ID[N], c_ID[N][2], c_ID[], c_ID[][2]</TD></TR>
-<TR><TD >Fix references</TD><TD > f_ID, f_ID[2], f_ID[N], f_ID[N][2], f_ID[], f_ID[][2]</TD></TR>
-<TR><TD >Other variables</TD><TD > v_abc, v_abc[N], v_abc[]
+<TR><TD >Atom values</TD><TD > mass[i], type[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i]</TD></TR>
+<TR><TD >Atom vectors</TD><TD > mass, type, x, y, z, vx, vy, vz, fx, fy, fz</TD></TR>
+<TR><TD >Compute references</TD><TD > c_ID, c_ID[i], c_ID[i][j]</TD></TR>
+<TR><TD >Fix references</TD><TD > f_ID, f_ID[i], f_ID[i][j]</TD></TR>
+<TR><TD >Other variables</TD><TD > v_name, v_name[i]
</TD></TR></TABLE></DIV>
-<P>Note that formula elements that contain empty brackets, such as an
-atom vector, produce per-atom values. All other formula elements
-produce a global value.
+<P>Most of the formula elements generate scalar values. The exceptions
+are those that represent a per-atom vector of values. These are the
+atom vectors, compute references that represent a per-atom vector, fix
+references that represent a per-atom vector, and variables that are
+atom-style variables.
</P>
<P>A formula for equal-style variables cannot use any formula element
-that produces per-atom values. A formula for an atom-style variable
-can use formula elements that produce either global values or per-atom
-values.
+that generates a per-atom vector. A formula for an atom-style
+variable can use formula elements that produce either scalar values or
+per-atom vectors.
</P>
<P>The thermo keywords allowed in a formula are those defined by the
<A HREF = "thermo_style.html">thermo_style custom</A> command. Thermo keywords that
require a <A HREF = "compute.html">compute</A> to calculate their values such as
"temp" or "press", use computes stored and invoked by the
<A HREF = "thermo_style.html">thermo_style</A> command. This means that you can
only use those keywords in a variable if the style you are using with
the thermo_style command (and the thermo keywords associated with that
style) also define and use the needed compute. Note that some thermo
keywords use a compute indirectly to calculate their value (e.g. the
enthalpy keyword uses temp, pe, and pressure). If a variable is
-evaluated in an input script (not during a run), then the values
-accessed by the thermo keyword must be current. See the discussion
-below about "Variable Accuracy".
+evaluated directly in an input script (not during a run), then the
+values accessed by the thermo keyword must be current. See the
+discussion below about "Variable Accuracy".
</P>
<P>Math operations are written in the usual way, where the "x" and "y" in
the examples above can be another section of the formula. Operators
are evaluated left to right and have the usual precedence: unary minus
before exponentiation ("^"), exponentiation before multiplication and
division, and multiplication and division before addition and
subtraction. Parenthesis can be used to group one or more portions of
a formula and enforce a desired order of operations. Additional math
operations can be specified as keywords followed by a parenthesized
argument, e.g. sqrt(v_ke). Note that ln() is the natural log; log()
is the base 10 log. The ceil(), floor(), and round() operations are
those in the C math library. Ceil() is the smallest integer not less
than its argument. Floor() if the largest integer not greater than
its argument. Round() is the nearest integer to its argument.
</P>
<P>Group functions take one or two arguments in a specific format. The
first argument is the group-ID. The <I>dim</I> argument, if it exists, is
<I>x</I> or <I>y</I> or <I>z</I>. The <I>dir</I> argument, if it exists, is <I>xmin</I>,
<I>xmax</I>, <I>ymin</I>, <I>ymax</I>, <I>zmin</I>, or <I>zmax</I>. The group function count()
is the number of atoms in the group. The group functions mass() and
charge() are the total mass and charge of the group. Xcm() and vcm()
return components of the position and velocity of the center of mass
of the group. Fcm() returns a component of the total force on the
group of atoms. Bound() returns the min/max of a particular
coordinate for all atoms in the group. Gyration() computes the
radius-of-gyration of the group of atoms. See the <A HREF = "fix_gyration.html">fix
gyration</A> command for a definition of the formula.
</P>
-<P>Region functions are exactly the same as group functions with an
-extra argument which is the region ID. The function is computed
-for all atoms that are in both the group and the region. If the
-group is "all", then the only criteria for atom inclusion is
-that it be in the region.
+<P>Region functions are exactly the same as group functions except they
+take an extra argument which is the region ID. The function is
+computed for all atoms that are in both the group and the region. If
+the group is "all", then the only criteria for atom inclusion is that
+it be in the region.
</P>
-<P>Atom values take a single integer argument from 1-N, which is the
-desired atom-ID, e.g. x[243]., which means use the x coordinate of
-the atom with ID=243.
+<P>Atom values take a single integer argument I from 1 to N, where I is
+the an atom-ID, e.g. x[243], which means use the x coordinate of the
+atom with ID = 243.
</P>
-<P>Atom vectors use empty brackets, i.e. they take no argument. They
-generate one value per atom, so that a reference like x[] means the
-x-coord of each atom will be used when evaluating the variable.
+<P>Atom vectors generate one value per atom, so that a reference like
+"vx" means the x-component of each atom's velocity will be used when
+evaluating the variable.
</P>
-<P>Compute references access one or more quantities calculated by a
+<P>Compute references access quantities calculated by a
<A HREF = "compute.html">compute</A>. The ID in the reference should be replaced by
-the actual ID of the compute defined elsewhere in the input script.
-See the doc pages for individual computes to see which ones calculate
-global versus per-atom quantities. If the compute reference contains
-empty brackets, then per-atom values calculated by the compute are
-accessed. Otherwise a single value (global or per-atom) calculated by
-the compute is accessed. If a variable containing a compute is
-evaluated in an input script (not during a run), then the values
+the ID of a compute defined elsewhere in the input script. As
+discussed in the doc page for the <A HREF = "compute.html">compute</A> command,
+computes can produce global, per-atom, or local values. Only global
+and per-atom values can be used in a variable. Computes can also
+produce a scalar, vector, or array. An equal-style variable can use
+scalar values, which means a scalar itself, or an element of a vector
+or array. Atom-style variables can use either scalar or vector
+values. A vector value can be a vector itself, or a column of an
+array. See the doc pages for individual computes to see what kind of
+values they produce.
+</P>
+<P>Examples of different kinds of compute references are as follows.
+There is no ambiguity as to what a reference means, since computes
+only produce global or per-atom quantities, never both.
+</P>
+<DIV ALIGN=center><TABLE BORDER=1 >
+<TR><TD >c_ID</TD><TD > global scalar, or per-atom vector</TD></TR>
+<TR><TD >c_ID[I]</TD><TD > Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array</TD></TR>
+<TR><TD >c_ID[I][J]</TD><TD > I,J element of global array, or atom I's Jth value in per-atom array
+</TD></TR></TABLE></DIV>
+
+<P>If a variable containing a compute is evaluated
+directly in an input script (not during a run), then the values
accessed by the compute must be current. See the discussion below
about "Variable Accuracy".
</P>
-<P>The different kinds of compute references are as follows. M is a
-positive integer <= the number of vector values calculated by the
-compute. N is a global atom ID (positive integer).
+<P>Fix references access quantities calculated by a <A HREF = "compute.html">fix</A>.
+The ID in the reference should be replaced by the ID of a fix defined
+elsewhere in the input script. As discussed in the doc page for the
+<A HREF = "fix.html">fix</A> command, fixes can produce global, per-atom, or local
+values. Only global and per-atom values can be used in a variable.
+Fixes can also produce a scalar, vector, or array. An equal-style
+variable can use scalar values, which means a scalar itself, or an
+element of a vector or array. Atom-style variables can use either
+scalar or vector values. A vector value can be a vector itself, or a
+column of an array. See the doc pages for individual fixes to see
+what kind of values they produce.
+</P>
+<P>The different kinds of fix references are exactly the same as the
+compute references listed in the above table, where "c_" is replaced
+by "f_".
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
-<TR><TD >c_ID</TD><TD > scalar value of a global compute</TD></TR>
-<TR><TD >c_ID[2]</TD><TD > vector component of a global compute</TD></TR>
-<TR><TD >c_ID[N]</TD><TD > single atom's scalar value of a per-atom compute</TD></TR>
-<TR><TD >c_ID[N][M]</TD><TD > single atom's vector component of a per-atom compute</TD></TR>
-<TR><TD >c_ID[]</TD><TD > per-atom vector from a per-atom compute</TD></TR>
-<TR><TD >c_ID[][M]</TD><TD > column of per-atom array from a per-atom compute
+<TR><TD >f_ID</TD><TD > global scalar, or per-atom vector</TD></TR>
+<TR><TD >f_ID[I]</TD><TD > Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array</TD></TR>
+<TR><TD >f_ID[I][J]</TD><TD > I,J element of global array, or atom I's Jth value in per-atom array
</TD></TR></TABLE></DIV>
-<P>Fix references access one or more quantities calculated by a
-<A HREF = "fix.html">fix</A>. The ID in the reference should be replaced by the
-actual ID of the fix defined elsewhere in the input script. See the
-doc pages for individual computes to see which ones calculate global
-versus per-atom quantities. If the fix reference contains empty
-brackets, then per-atom values calculated by the fix are accessed.
-Otherwise a single value (global or per-atom) calculated by the fix is
-accessed.
+<P>If a variable containing a fix is evaluated directly in an input
+script (not during a run), then the values accessed by the fix should
+be current. See the discussion below about "Variable Accuracy".
</P>
<P>Note that some fixes only generate quantities on certain timesteps.
If a variable attempts to access the fix on non-allowed timesteps, an
error is generated. For example, the <A HREF = "fix_ave_time.html">fix ave/time</A>
command may only generate averaged quantities every 100 steps. See
-the doc pages for individual fix commands for details. If a variable
-containing a fix is evaluated in an input script (not during a run),
-then the values accessed by the fix should be current. See the
-discussion below about "Variable Accuracy".
-</P>
-<P>The different kinds of fix references are exactly the same as the
-compute references listed in the above table, where "c_" is replaced
-by "f_", and the word "compute" is replaced by "fix".
-</P>
-<P>The current values of other variables can be accessed by prepending a
-"v_" to the variable name. This will cause that variable to be
-evaluated. Atom-style variables generate per-atom values; all other
-styles of variables generate a single scalar value.
-</P>
-<P>The different kinds of variable references are as follows. N is a
-global atom ID (positive integer).
+the doc pages for individual fix commands for details.
+</P>
+<P>Variable references access quantities calulated by other variables,
+which will cause those variables to be evaluated. The name in the
+reference should be replaced by the name of a variable defined
+elsewhere in the input script. As discussed on this doc page,
+atom-style variables generate a per-atom vector of values; all other
+variable styles generate a single scalar value. An equal-style
+variable can use scalar values produce by another variable, but not
+per-atom vectors. Atom-style variables can use either scalar or
+per-atom vector values.
+</P>
+<P>Examples of different kinds of variable references are as follows.
+There is no ambiguity as to what a reference means, since variables
+only produce scalar or per-atom vectors, never both.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
-<TR><TD >v_ID</TD><TD > scalar value of a non atom-style variable</TD></TR>
-<TR><TD >v_ID[N]</TD><TD > single atom's scalar value from an atom-style variable</TD></TR>
-<TR><TD >v_ID[]</TD><TD > per-atom value from an atom-style variable
+<TR><TD >v_name</TD><TD > scalar, or per-atom vector</TD></TR>
+<TR><TD >v_name[I]</TD><TD > atom I's value in per-atom vector
</TD></TR></TABLE></DIV>
<P>IMPORTANT NOTE: If you define variables in circular manner like this:
</P>
<PRE>variable a equal v_b
variable b equal v_a
print $a
</PRE>
-<P>then LAMMPS will run for a while when the print statement is invoked!
+<P>then LAMMPS may run for a while when the print statement is invoked!
</P>
<HR>
<P><B>Immediate Evaluation of Variables:</B>
</P>
<P>There is a difference between referencing a variable with a leading $
sign (e.g. $x or ${abc}) versus with a leading "v_" (e.g. v_x or
v_abc). The former can be used in any command, including a variable
command, to force the immediate evaluation of the referenced variable
and the substitution of its value into the command. The latter is a
required kind of argument to some commands (e.g. the <A HREF = "fix_ave_spatial.html">fix
ave/spatial</A> or <A HREF = "dump.html">dump custom</A> or
<A HREF = "thermo_style.html">thermo_style</A> commands) if you wish it to evaluate
a variable periodically during a run. It can also be used in a
variable formula if you wish to reference a second variable. The
second variable will be evaluated whenever the first variable is
evaluated.
</P>
<P>As an example, suppose you use this command in your input script to
define the variable "v" as
</P>
<PRE>variable v equal vol
</PRE>
<P>before a run where the simulation box size changes. You might think
this will assign the initial volume to the variable "v". That is not
the case. Rather it assigns a formula which evaluates the volume
(using the thermo_style keyword "vol") to the variable "v". If you
use the variable "v" in some other command like "fix ave/time" then
the current volume of the box will be evaluated continuously during
the run.
</P>
<P>If you want to store the initial volume of the system, you can do it
this way:
</P>
<PRE>variable v equal vol
variable v0 equal $v
</PRE>
<P>The second command will force "v" to be evaluated (yielding the
initial volume) and assign that value to the variable "v0". Thus the
command
</P>
<PRE>thermo_style custom step v_v v_v0
</PRE>
<P>would print out both the current and initial volume periodically
during the run.
</P>
<P>Note that it is a mistake to enclose a variable formula in double
quotes if it contains variables preceeded by $ signs. For example,
</P>
<PRE>variable vratio equal "${vfinal}/${v0}"
</PRE>
<P>This is because the quotes prevent variable substitution (see <A HREF = "Section_commands.html#3_2">this
section</A> on parsing input script commands),
and thus an error will occur when the formula for "vratio" is
evaluated later.
</P>
<HR>
<P><B>Variable Accuracy:</B>
</P>
<P>Obviously, LAMMPS attempts to evaluate variables containing formulas
(<I>equal</I> and <I>atom</I> style variables) accurately whenever the
evaluation is performed. Depending on what is included in the
formula, this may require invoking a <A HREF = "compute.html">compute</A>, either
directly or indirectly via a thermo keyword, or accessing a value
previously calculated by a compute, or accessing a value calculated
and stored by a <A HREF = "fix.html">fix</A>. If the compute is one that calculates
the pressure or energy of the system, then these quantities need to be
tallied during the evaluation of the interatomic potentials (pair,
bond, etc) on timesteps that the variable will need the values.
</P>
<P>LAMMPS keeps track of all of this during a <A HREF = "run.html">run</A> or <A HREF = "minimize.html">energy
minimization</A>. An error will be generated if you
attempt to evaluate a variable on timesteps when it cannot produce
accurate values. For example, if a <A HREF = "thermo_style.html">thermo_style
custom</A> command prints a variable which accesses
values stored by a <A HREF = "fix_ave_time.html">fix ave/time</A> command and the
timesteps on which thermo output is generated are not multiples of the
averaging frequency used in the fix command, then an error will occur.
</P>
<P>An input script can also request variables be evaluated before or
after or in between runs, e.g. by including them in a
<A HREF = "print.html">print</A> command. In this case, if a compute is needed to
evaluate a variable (either directly or indirectly), LAMMPS will not
invoke the compute, but it will use a value previously calculated by
the compute if it is current. Fixes will always provide a quantity
needed by a variable, but the quantity may or may not be current.
This leads to one of three kinds of behavior:
</P>
<P>(1) The variable may be evaluated accurately. If it contains
references to a compute or fix, and these values were calculated on
the last timestep of a preceeding run, then they will be accessed and
used by the variable and the result will be accurate.
</P>
<P>(2) LAMMPS may not be able to evaluate the variable and generate an
error. For example, if the variable requires a quantity from a
<A HREF = "compute.html">compute</A> that is not current, LAMMPS will not do it.
This means, for example, that such a variable then the variable cannot
be evaluated before the first run has occurred.
</P>
<P>One way to get around this problem is to perform a 0-timestep run
before using the variable. For example, these commands
</P>
<PRE>variable t equal temp
print "Initial temperature = $t"
run 1000
</PRE>
<P>will generate an error if the run is the first run specified in the
input script, because generating a value for the "t" variable requires
a compute for calculating the temperature to be invoked.
</P>
<P>However, this sequence of commands would be fine:
</P>
<PRE>run 0
variable t equal temp
print "Initial temperature = $t"
run 1000
</PRE>
<P>The 0-timestep run initializes and invokes various computes, including
the one for temperature, so that the value it stores is current and
can be accessed by the variable "t" after the run has completed. Note
that a 0-timestep run does not alter the state of the system, so it
does not change the input state for the 1000-timestep run that
follows. Also note that the 0-timestep run must actually use and
invoke the compute in question (e.g. via <A HREF = "thermo_style.html">thermo</A> or
<A HREF = "dump.html">dump</A> output) in order for it to enable the compute to be
used in a variable after the run.
</P>
<P>Unlike computes, <A HREF = "fix.html">fixes</A> will never generate an error if
their values are accessed by a variable in between runs. They always
return some value to the variable. However, the value may not be what
you expect if the fix has not yet calculated the quantity of interest
or it is not current. For example, the <A HREF = "fix_indent.html">fix indent</A>
command stores the force on the indenter. But this is not computed
until a run is performed. Thus if a variable attempts to print this
value before the first run, zeroes will be output. Again, performing
a 0-timestep run before printing the variable has the desired effect.
</P>
<P>(3) The variable may be evaluated incorrectly. And LAMMPS may have
no way to detect this has occurred. Consider the following sequence
of commands:
</P>
<PRE>pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
variable e equal pe
print "Final potential energy = $e"
</PRE>
<P>The first run is performed using one setting for the pairwise
potential defined by the <A HREF = "pair_style.html">pair_style</A> and
<A HREF = "pair_coeff.html">pair_coeff</A> commands. The potential energy is
evaluated on the final timestep and stored by the <A HREF = "compute_pe.html">compute
pe</A> compute (this is done by the
<A HREF = "thermo_style.html">thermo_style</A> command). Then a pair coefficient is
changed, altering the potential energy of the system. When the
potential energy is printed via the "e" variable, LAMMPS will use the
potential energy value stored by the <A HREF = "compute_pe.html">compute pe</A>
compute, thinking it is current. There are many other commands which
could alter the state of the system between runs, causing a variable
to evaluate incorrectly.
</P>
<P>The solution to this issue is the same as for case (2) above, namely
perform a 0-timestep run before the variable is evaluated to insure
the system is up-to-date. For example, this sequence of commands
would print a potential energy that reflected the changed pairwise
coefficient:
</P>
<PRE>pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
run 0
variable e equal pe
print "Final potential energy = $e"
</PRE>
<HR>
<P><B>Restrictions:</B>
</P>
<P>Indexing any formula element by global atom ID, such as an atom value,
requires the atom style to use a global mapping in order to look up
the vector indices. By default, only atom styles with molecular
information create global maps. The <A HREF = "atom_modify.html">atom_modify
map</A> command can override the default.
</P>
<P>All <I>universe</I>- and <I>uloop</I>-style variables defined in an input script
must have the same number of values.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "next.html">next</A>, <A HREF = "jump.html">jump</A>, <A HREF = "include.html">include</A>,
<A HREF = "temper.html">temper</A>, <A HREF = "fix_print.html">fix print</A>, <A HREF = "print.html">print</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/variable.txt b/doc/variable.txt
index 1d3e6d203..b985ca859 100644
--- a/doc/variable.txt
+++ b/doc/variable.txt
@@ -1,576 +1,591 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
variable command :h3
[Syntax:]
variable name style args ... :pre
name = name of variable to define :ulb,l
style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {equal} or {atom} :l
{delete} = no args
{index} args = one or more strings
{loop} args = N = integer size of loop
{world} args = one string for each partition of processors
{universe} args = one or more strings
{uloop} args = N = integer size of loop
{equal} or {atom} args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references
numbers = 0.0, 100, -5.4, 2.8e-4, etc
thermo keywords = vol, ke, press, etc from "thermo_style"_thermo_style.html
math operations = (), -x, x+y, x-y, x*y, x/y, x^y,
sqrt(x), exp(x), ln(x), log(x),
sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
ceil(x), floor(x), round(x)
group functions = count(group), mass(group), charge(group),
xcm(group,dim), vcm(group,dim), fcm(group,dim),
bound(group,xmin), gyration(group), ke(group)
region functions = count(group,region), mass(group,region), charge(group,region),
xcm(group,dim,region), vcm(group,dim,region), fcm(group,dim,region),
bound(group,xmin,region), gyration(group,region), ke(group,reigon)
- atom value = mass\[N\], type\[N\], x\[N\], y\[N\], z\[N\],
- vx\[N\], vy\[N\], vz\[N\], fx\[N\], fy\[N\], fz\[N\]
- atom vector = mass\[\], type\[\], x\[\], y\[\], z\[\],
- vx\[\], vy\[\], vz\[\], fx\[\], fy\[\], fz\[\]
- compute references = c_ID, c_ID\[2\], c_ID\[N\], c_ID\[N\]\[2\], c_ID\[\], c_ID\[\]\[2\]
- fix references = f_ID, f_ID\[2\], f_ID\[N\], f_ID\[N\]\[2\], f_ID\[\], f_ID\[\]\[2\]
- variable references = v_abc, v_abc\[N\], v_abc\[\] :pre
+ atom value = mass\[i\], type\[i\], x\[i\], y\[i\], z\[i\], vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\]
+ atom vector = mass, type, x, y, z, vx, vy, vz, fx, fy, fz
+ compute references = c_ID, c_ID\[i\], c_ID\[i\]\[j\]
+ fix references = f_ID, f_ID\[i\], f_ID\[i\]\[j\]
+ variable references = v_name, v_name\[i\] :pre
:ule
[Examples:]
variable x index run1 run2 run3 run4 run5 run6 run7 run8
variable LoopVar loop $n
variable beta equal temp/3.0
variable b1 equal x\[234\]+0.5*vol
variable b1 equal "x\[234\] + 0.5*vol"
variable b equal xcm(mol1,x)/2.0
variable b equal c_myTemp
-variable b atom x\[\]*y\[\]/vol
+variable b atom x*y/vol
variable temp world 300.0 310.0 320.0 $\{Tfinal\}
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
variable x uloop 15
variable x delete :pre
[Description:]
This command assigns one or more strings to a variable name for
evaluation later in the input script or during a simulation.
Variables can be used in several ways in LAMMPS. A variable can be
referenced elsewhere in an input script to become part of a new input
command. For variable styles that store multiple strings, the
"next"_next.html command can be used to increment which string is
assigned to the variable. Variables of style {equal} store a formula
which when evaluated produces a single numeric value which can be
output either directly (see the "print"_print.html, "fix
print"_fix_print.html, and "run every"_run.html commands) or as part
of thermodynamic output (see the "thermo_style"_thermo_style.html
command), or used as input to an averaging fix (see the "fix
ave/time"_fix_ave/time command). Variables of style {atom} store a
formula which when evaluated produces one numeric value per atom which
can be output to a dump file (see the "dump custom"_dump.html command)
or used as input to an averaging fix (see the "fix
ave/spatial"_fix_ave_spatial.html and "fix ave/atom"_fix_ave_atom.html
commands).
In the discussion that follows, the "name" of the variable is the
arbitrary string that is the 1st argument in the variable command.
This name can only contain alphanumeric characters and underscores.
The "string" is one or more of the subsequent arguments. The "string"
can be simple text as in the 1st example above, it can contain other
variables as in the 2nd example, or it can be a formula as in the 3rd
example. The "value" is the numeric quantity resulting from
evaluation of the string. Note that the same string can generate
different values when it is evaluated at different times during a
simulation.
IMPORTANT NOTE: When the input script line that defines a variable of
style {equal} or {atom} that contain a formula is encountered, the
formula is NOT immediately evaluated and the result stored. See the
discussion below about "Immediate Evaluation of Variables" if you want
to do this.
IMPORTANT NOTE: When a variable command is encountered in the input
script and the variable name has already been specified, the command
is ignored. This means variables can NOT be re-defined in an input
script (with 2 exceptions, read further). This is to allow an input
script to be processed multiple times without resetting the variables;
see the "jump"_jump.html or "include"_include.html commands. It also
means that using the "command-line switch"_Section_start.html#2_6 -var
will override a corresponding index variable setting in the input
script.
There are two exceptions to this rule. First, variables of style
{equal} and {atom} ARE redefined each time the command is encountered.
This only changes their associated formula if the formula contains a
substitution for another variable, e.g. $x. But that can be useful,
for example, in a loop.
Second, as described below, if a variable is iterated on to the end of
its list of strings via the "next"_next.html command, it is removed
from the list of active variables, and is thus available to be
re-defined in a subsequent variable command. The {delete} style does
the same thing.
:line
"This section"_Section_commands.html#3_2 of the manual explains how
occurrences of a variable name in an input script line are replaced by
the variable's string. The variable name can be referenced as $x if
the name "x" is a single character, or as $\{LoopVar\} if the name
"LoopVar" is one or more characters.
As described below, for variable styles {index}, {loop}, {universe},
and {uloop}, which string is assigned to a variable can be incremented
via the "next"_next.html command. When there are no more strings to
assign, the variable is exhausted and a flag is set that causes the
next "jump"_jump.html command encountered in the input script to be
skipped. This enables the construction of simple loops in the input
script that are iterated over and then exited from.
As explained above, an exhausted variable can be re-used in an input
script. The {delete} style also removes the variable, the same as if
it were exhausted, allowing it to be redefined later in the input
script or when the input script is looped over. This can be useful
when breaking out of a loop via the "if"_if.html and "jump"_jump.html
commands before the variable would become exhausted. For example,
label loop
variable a loop 5
print "A = $a"
if $a > 2 then "jump in.script break"
next a
jump in.script loop
label break
variable a delete :pre
:line
For the {index} style, one or more strings are specified. Initially,
the 1st string is assigned to the variable. Each time a
"next"_next.html command is used with the variable name, the next
string is assigned. All processors assign the same string to the
variable.
{Index} style variables with a single string value can also be set by
using the command-line switch -var; see "this
section"_Section_start.html#2_6 for details.
The {loop} style is identical to the {index} style except that the
strings are the integers from 1 to N. This allows generation of a
long list of runs (e.g. 1000) without having to list N strings in the
input script. Initially, the string "1" is assigned to the variable.
Each time a "next"_next.html command is used with the variable name,
the next string ("2", "3", etc) is assigned. All processors assign
the same string to the variable.
For the {world} style, one or more strings are specified. There must
be one string for each processor partition or "world". See "this
section"_Section_start.html#2_6 of the manual for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command assigns one string to each
world. All processors in the world are assigned the same string. The
next command cannot be used with {equal} style variables, since there
is only one value per world. This style of variable is useful when
you wish to run different simulations on different partitions, or when
performing a parallel tempering simulation (see the
"temper"_temper.html command), to assign different temperatures to
different partitions.
For the {universe} style, one or more strings are specified. There
must be at least as many strings as there are processor partitions or
"worlds". See "this page"_Section_start.html#2_6 for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command initially assigns one
string to each world. When a "next"_next.html command is encountered
using this variable, the first processor partition to encounter it, is
assigned the next available string. This continues until all the
variable strings are consumed. Thus, this command can be used to run
50 simulations on 8 processor partitions. The simulations will be run
one after the other on whatever partition becomes available, until
they are all finished. {Universe} style variables are incremented
using the files "tmp.lammps.variable" and "tmp.lammps.variable.lock"
which you will see in your directory during such a LAMMPS run.
The {uloop} style is identical to the {universe} style except that the
strings are the integers from 1 to N. This allows generation of long
list of runs (e.g. 1000) without having to list N strings in the input
script.
:line
For the {equal} and {atom} styles, a single string is specified which
represents a formula that will be evaluated afresh each time the
variable is used. If you want spaces in the string, enclose it in
double quotes so the parser will treat it as a single argument. For
{equal} style variables the formula computes a scalar quantity, which
becomes the value of the variable whenever it is evaluated. For
{atom} style variables the formula computes one quantity for each
atom whenever it is evaluated.
Note that {equal} and {atom} variables can produce different values at
different stages of the input script or at different times during a
run. For example, if an {equal} variable is used in a "fix
print"_fix_print.html command, different values could be printed each
timestep it was invoked. If you want a variable to be evaluated
immediately, so that the result is stored by the variable instead of
the string, see the section below on "Immediate Evaluation of
Variables".
The next command cannot be used with {equal} or {atom} style
variables, since there is only one string.
The formula for an {equal} or {atom} variable can contain a variety
of quantities. The syntax for each kind of quantity is simple, but
multiple quantities can be nested and combined in various ways to
build up formulas of arbitrary complexity. For example, this is a
valid (though strange) variable formula:
variable x equal "pe + c_MyTemp / vol^(1/3)" :pre
Specifically, an formula can contain numbers, thermo keywords, math
operations, group functions, atom values, atom vectors, compute
references, fix references, and references to other variables.
Number: 0.2, 100, 1.0e20, -15.4, etc
Thermo keywords: vol, pe, ebond, etc
Math operations: (), -x, x+y, x-y, x*y, x/y, x^y, sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), ceil(x), floor(x), round(x)
Group functions: count(ID), mass(ID), charge(ID), xcm(ID,dim), \
vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID)
Region functions: count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), \
vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR)
-Atom values: mass\[N\], type\[N\], x\[N\], y\[N\], z\[N\], \
- vx\[N\], vy\[N\], vz\[N\], fx\[N\], fy\[N\], fz\[N\]
-Atom vectors: mass\[\], type\[\], x\[\], y\[\], z\[\], \
- vx\[\], vy\[\], vz\[\], fx\[\], fy\[\], fz\[\]
-Compute references: c_ID, c_ID\[2\], c_ID\[N\], c_ID\[N\]\[2\], c_ID\[\], c_ID\[\]\[2\]
-Fix references: f_ID, f_ID\[2\], f_ID\[N\], f_ID\[N\]\[2\], f_ID\[\], f_ID\[\]\[2\]
-Other variables: v_abc, v_abc\[N\], v_abc\[\] :tb(s=:)
-
-Note that formula elements that contain empty brackets, such as an
-atom vector, produce per-atom values. All other formula elements
-produce a global value.
+Atom values: mass\[i\], type\[i\], x\[i\], y\[i\], z\[i\], \
+ vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\]
+Atom vectors: mass, type, x, y, z, vx, vy, vz, fx, fy, fz
+Compute references: c_ID, c_ID\[i\], c_ID\[i\]\[j\]
+Fix references: f_ID, f_ID\[i\], f_ID\[i\]\[j\]
+Other variables: v_name, v_name\[i\] :tb(s=:)
+
+Most of the formula elements generate scalar values. The exceptions
+are those that represent a per-atom vector of values. These are the
+atom vectors, compute references that represent a per-atom vector, fix
+references that represent a per-atom vector, and variables that are
+atom-style variables.
A formula for equal-style variables cannot use any formula element
-that produces per-atom values. A formula for an atom-style variable
-can use formula elements that produce either global values or per-atom
-values.
+that generates a per-atom vector. A formula for an atom-style
+variable can use formula elements that produce either scalar values or
+per-atom vectors.
The thermo keywords allowed in a formula are those defined by the
"thermo_style custom"_thermo_style.html command. Thermo keywords that
require a "compute"_compute.html to calculate their values such as
"temp" or "press", use computes stored and invoked by the
"thermo_style"_thermo_style.html command. This means that you can
only use those keywords in a variable if the style you are using with
the thermo_style command (and the thermo keywords associated with that
style) also define and use the needed compute. Note that some thermo
keywords use a compute indirectly to calculate their value (e.g. the
enthalpy keyword uses temp, pe, and pressure). If a variable is
-evaluated in an input script (not during a run), then the values
-accessed by the thermo keyword must be current. See the discussion
-below about "Variable Accuracy".
+evaluated directly in an input script (not during a run), then the
+values accessed by the thermo keyword must be current. See the
+discussion below about "Variable Accuracy".
Math operations are written in the usual way, where the "x" and "y" in
the examples above can be another section of the formula. Operators
are evaluated left to right and have the usual precedence: unary minus
before exponentiation ("^"), exponentiation before multiplication and
division, and multiplication and division before addition and
subtraction. Parenthesis can be used to group one or more portions of
a formula and enforce a desired order of operations. Additional math
operations can be specified as keywords followed by a parenthesized
argument, e.g. sqrt(v_ke). Note that ln() is the natural log; log()
is the base 10 log. The ceil(), floor(), and round() operations are
those in the C math library. Ceil() is the smallest integer not less
than its argument. Floor() if the largest integer not greater than
its argument. Round() is the nearest integer to its argument.
Group functions take one or two arguments in a specific format. The
first argument is the group-ID. The {dim} argument, if it exists, is
{x} or {y} or {z}. The {dir} argument, if it exists, is {xmin},
{xmax}, {ymin}, {ymax}, {zmin}, or {zmax}. The group function count()
is the number of atoms in the group. The group functions mass() and
charge() are the total mass and charge of the group. Xcm() and vcm()
return components of the position and velocity of the center of mass
of the group. Fcm() returns a component of the total force on the
group of atoms. Bound() returns the min/max of a particular
coordinate for all atoms in the group. Gyration() computes the
radius-of-gyration of the group of atoms. See the "fix
gyration"_fix_gyration.html command for a definition of the formula.
-Region functions are exactly the same as group functions with an
-extra argument which is the region ID. The function is computed
-for all atoms that are in both the group and the region. If the
-group is "all", then the only criteria for atom inclusion is
-that it be in the region.
+Region functions are exactly the same as group functions except they
+take an extra argument which is the region ID. The function is
+computed for all atoms that are in both the group and the region. If
+the group is "all", then the only criteria for atom inclusion is that
+it be in the region.
-Atom values take a single integer argument from 1-N, which is the
-desired atom-ID, e.g. x\[243\]., which means use the x coordinate of
-the atom with ID=243.
+Atom values take a single integer argument I from 1 to N, where I is
+the an atom-ID, e.g. x\[243\], which means use the x coordinate of the
+atom with ID = 243.
-Atom vectors use empty brackets, i.e. they take no argument. They
-generate one value per atom, so that a reference like x\[\] means the
-x-coord of each atom will be used when evaluating the variable.
+Atom vectors generate one value per atom, so that a reference like
+"vx" means the x-component of each atom's velocity will be used when
+evaluating the variable.
-Compute references access one or more quantities calculated by a
+Compute references access quantities calculated by a
"compute"_compute.html. The ID in the reference should be replaced by
-the actual ID of the compute defined elsewhere in the input script.
-See the doc pages for individual computes to see which ones calculate
-global versus per-atom quantities. If the compute reference contains
-empty brackets, then per-atom values calculated by the compute are
-accessed. Otherwise a single value (global or per-atom) calculated by
-the compute is accessed. If a variable containing a compute is
-evaluated in an input script (not during a run), then the values
+the ID of a compute defined elsewhere in the input script. As
+discussed in the doc page for the "compute"_compute.html command,
+computes can produce global, per-atom, or local values. Only global
+and per-atom values can be used in a variable. Computes can also
+produce a scalar, vector, or array. An equal-style variable can use
+scalar values, which means a scalar itself, or an element of a vector
+or array. Atom-style variables can use either scalar or vector
+values. A vector value can be a vector itself, or a column of an
+array. See the doc pages for individual computes to see what kind of
+values they produce.
+
+Examples of different kinds of compute references are as follows.
+There is no ambiguity as to what a reference means, since computes
+only produce global or per-atom quantities, never both.
+
+c_ID: global scalar, or per-atom vector
+c_ID\[I\]: Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array
+c_ID\[I\]\[J\]: I,J element of global array, or atom I's Jth value in per-atom array :tb(s=:)
+
+If a variable containing a compute is evaluated
+directly in an input script (not during a run), then the values
accessed by the compute must be current. See the discussion below
about "Variable Accuracy".
-The different kinds of compute references are as follows. M is a
-positive integer <= the number of vector values calculated by the
-compute. N is a global atom ID (positive integer).
-
-c_ID: scalar value of a global compute
-c_ID\[2\]: vector component of a global compute
-c_ID\[N\]: single atom's scalar value of a per-atom compute
-c_ID\[N\]\[M\]: single atom's vector component of a per-atom compute
-c_ID\[\]: per-atom vector from a per-atom compute
-c_ID\[\]\[M\]: column of per-atom array from a per-atom compute :tb(s=:)
-
-Fix references access one or more quantities calculated by a
-"fix"_fix.html. The ID in the reference should be replaced by the
-actual ID of the fix defined elsewhere in the input script. See the
-doc pages for individual computes to see which ones calculate global
-versus per-atom quantities. If the fix reference contains empty
-brackets, then per-atom values calculated by the fix are accessed.
-Otherwise a single value (global or per-atom) calculated by the fix is
-accessed.
+Fix references access quantities calculated by a "fix"_compute.html.
+The ID in the reference should be replaced by the ID of a fix defined
+elsewhere in the input script. As discussed in the doc page for the
+"fix"_fix.html command, fixes can produce global, per-atom, or local
+values. Only global and per-atom values can be used in a variable.
+Fixes can also produce a scalar, vector, or array. An equal-style
+variable can use scalar values, which means a scalar itself, or an
+element of a vector or array. Atom-style variables can use either
+scalar or vector values. A vector value can be a vector itself, or a
+column of an array. See the doc pages for individual fixes to see
+what kind of values they produce.
+
+The different kinds of fix references are exactly the same as the
+compute references listed in the above table, where "c_" is replaced
+by "f_".
+
+f_ID: global scalar, or per-atom vector
+f_ID\[I\]: Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array
+f_ID\[I\]\[J\]: I,J element of global array, or atom I's Jth value in per-atom array :tb(s=:)
+
+If a variable containing a fix is evaluated directly in an input
+script (not during a run), then the values accessed by the fix should
+be current. See the discussion below about "Variable Accuracy".
Note that some fixes only generate quantities on certain timesteps.
If a variable attempts to access the fix on non-allowed timesteps, an
error is generated. For example, the "fix ave/time"_fix_ave_time.html
command may only generate averaged quantities every 100 steps. See
-the doc pages for individual fix commands for details. If a variable
-containing a fix is evaluated in an input script (not during a run),
-then the values accessed by the fix should be current. See the
-discussion below about "Variable Accuracy".
-
-The different kinds of fix references are exactly the same as the
-compute references listed in the above table, where "c_" is replaced
-by "f_", and the word "compute" is replaced by "fix".
+the doc pages for individual fix commands for details.
-The current values of other variables can be accessed by prepending a
-"v_" to the variable name. This will cause that variable to be
-evaluated. Atom-style variables generate per-atom values; all other
-styles of variables generate a single scalar value.
+Variable references access quantities calulated by other variables,
+which will cause those variables to be evaluated. The name in the
+reference should be replaced by the name of a variable defined
+elsewhere in the input script. As discussed on this doc page,
+atom-style variables generate a per-atom vector of values; all other
+variable styles generate a single scalar value. An equal-style
+variable can use scalar values produce by another variable, but not
+per-atom vectors. Atom-style variables can use either scalar or
+per-atom vector values.
-The different kinds of variable references are as follows. N is a
-global atom ID (positive integer).
+Examples of different kinds of variable references are as follows.
+There is no ambiguity as to what a reference means, since variables
+only produce scalar or per-atom vectors, never both.
-v_ID: scalar value of a non atom-style variable
-v_ID\[N\]: single atom's scalar value from an atom-style variable
-v_ID\[\]: per-atom value from an atom-style variable :tb(s=:)
+v_name: scalar, or per-atom vector
+v_name\[I\]: atom I's value in per-atom vector :tb(s=:)
IMPORTANT NOTE: If you define variables in circular manner like this:
variable a equal v_b
variable b equal v_a
print $a :pre
-then LAMMPS will run for a while when the print statement is invoked!
+then LAMMPS may run for a while when the print statement is invoked!
:line
[Immediate Evaluation of Variables:]
There is a difference between referencing a variable with a leading $
sign (e.g. $x or $\{abc\}) versus with a leading "v_" (e.g. v_x or
v_abc). The former can be used in any command, including a variable
command, to force the immediate evaluation of the referenced variable
and the substitution of its value into the command. The latter is a
required kind of argument to some commands (e.g. the "fix
ave/spatial"_fix_ave_spatial.html or "dump custom"_dump.html or
"thermo_style"_thermo_style.html commands) if you wish it to evaluate
a variable periodically during a run. It can also be used in a
variable formula if you wish to reference a second variable. The
second variable will be evaluated whenever the first variable is
evaluated.
As an example, suppose you use this command in your input script to
define the variable "v" as
variable v equal vol :pre
before a run where the simulation box size changes. You might think
this will assign the initial volume to the variable "v". That is not
the case. Rather it assigns a formula which evaluates the volume
(using the thermo_style keyword "vol") to the variable "v". If you
use the variable "v" in some other command like "fix ave/time" then
the current volume of the box will be evaluated continuously during
the run.
If you want to store the initial volume of the system, you can do it
this way:
variable v equal vol
variable v0 equal $v :pre
The second command will force "v" to be evaluated (yielding the
initial volume) and assign that value to the variable "v0". Thus the
command
thermo_style custom step v_v v_v0 :pre
would print out both the current and initial volume periodically
during the run.
Note that it is a mistake to enclose a variable formula in double
quotes if it contains variables preceeded by $ signs. For example,
variable vratio equal "$\{vfinal\}/$\{v0\}" :pre
This is because the quotes prevent variable substitution (see "this
section"_Section_commands.html#3_2 on parsing input script commands),
and thus an error will occur when the formula for "vratio" is
evaluated later.
:line
[Variable Accuracy:]
Obviously, LAMMPS attempts to evaluate variables containing formulas
({equal} and {atom} style variables) accurately whenever the
evaluation is performed. Depending on what is included in the
formula, this may require invoking a "compute"_compute.html, either
directly or indirectly via a thermo keyword, or accessing a value
previously calculated by a compute, or accessing a value calculated
and stored by a "fix"_fix.html. If the compute is one that calculates
the pressure or energy of the system, then these quantities need to be
tallied during the evaluation of the interatomic potentials (pair,
bond, etc) on timesteps that the variable will need the values.
LAMMPS keeps track of all of this during a "run"_run.html or "energy
minimization"_minimize.html. An error will be generated if you
attempt to evaluate a variable on timesteps when it cannot produce
accurate values. For example, if a "thermo_style
custom"_thermo_style.html command prints a variable which accesses
values stored by a "fix ave/time"_fix_ave_time.html command and the
timesteps on which thermo output is generated are not multiples of the
averaging frequency used in the fix command, then an error will occur.
An input script can also request variables be evaluated before or
after or in between runs, e.g. by including them in a
"print"_print.html command. In this case, if a compute is needed to
evaluate a variable (either directly or indirectly), LAMMPS will not
invoke the compute, but it will use a value previously calculated by
the compute if it is current. Fixes will always provide a quantity
needed by a variable, but the quantity may or may not be current.
This leads to one of three kinds of behavior:
(1) The variable may be evaluated accurately. If it contains
references to a compute or fix, and these values were calculated on
the last timestep of a preceeding run, then they will be accessed and
used by the variable and the result will be accurate.
(2) LAMMPS may not be able to evaluate the variable and generate an
error. For example, if the variable requires a quantity from a
"compute"_compute.html that is not current, LAMMPS will not do it.
This means, for example, that such a variable then the variable cannot
be evaluated before the first run has occurred.
One way to get around this problem is to perform a 0-timestep run
before using the variable. For example, these commands
variable t equal temp
print "Initial temperature = $t"
run 1000 :pre
will generate an error if the run is the first run specified in the
input script, because generating a value for the "t" variable requires
a compute for calculating the temperature to be invoked.
However, this sequence of commands would be fine:
run 0
variable t equal temp
print "Initial temperature = $t"
run 1000 :pre
The 0-timestep run initializes and invokes various computes, including
the one for temperature, so that the value it stores is current and
can be accessed by the variable "t" after the run has completed. Note
that a 0-timestep run does not alter the state of the system, so it
does not change the input state for the 1000-timestep run that
follows. Also note that the 0-timestep run must actually use and
invoke the compute in question (e.g. via "thermo"_thermo_style.html or
"dump"_dump.html output) in order for it to enable the compute to be
used in a variable after the run.
Unlike computes, "fixes"_fix.html will never generate an error if
their values are accessed by a variable in between runs. They always
return some value to the variable. However, the value may not be what
you expect if the fix has not yet calculated the quantity of interest
or it is not current. For example, the "fix indent"_fix_indent.html
command stores the force on the indenter. But this is not computed
until a run is performed. Thus if a variable attempts to print this
value before the first run, zeroes will be output. Again, performing
a 0-timestep run before printing the variable has the desired effect.
(3) The variable may be evaluated incorrectly. And LAMMPS may have
no way to detect this has occurred. Consider the following sequence
of commands:
pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
variable e equal pe
print "Final potential energy = $e" :pre
The first run is performed using one setting for the pairwise
potential defined by the "pair_style"_pair_style.html and
"pair_coeff"_pair_coeff.html commands. The potential energy is
evaluated on the final timestep and stored by the "compute
pe"_compute_pe.html compute (this is done by the
"thermo_style"_thermo_style.html command). Then a pair coefficient is
changed, altering the potential energy of the system. When the
potential energy is printed via the "e" variable, LAMMPS will use the
potential energy value stored by the "compute pe"_compute_pe.html
compute, thinking it is current. There are many other commands which
could alter the state of the system between runs, causing a variable
to evaluate incorrectly.
The solution to this issue is the same as for case (2) above, namely
perform a 0-timestep run before the variable is evaluated to insure
the system is up-to-date. For example, this sequence of commands
would print a potential energy that reflected the changed pairwise
coefficient:
pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
run 0
variable e equal pe
print "Final potential energy = $e" :pre
:line
[Restrictions:]
Indexing any formula element by global atom ID, such as an atom value,
requires the atom style to use a global mapping in order to look up
the vector indices. By default, only atom styles with molecular
information create global maps. The "atom_modify
map"_atom_modify.html command can override the default.
All {universe}- and {uloop}-style variables defined in an input script
must have the same number of values.
[Related commands:]
"next"_next.html, "jump"_jump.html, "include"_include.html,
"temper"_temper.html, "fix print"_fix_print.html, "print"_print.html
[Default:] none