lammps/doc/variable.txt

"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 = {index} or {loop} or {world} or {universe} or {uloop} or {equal} or {atom} :l
  {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 equation containing numbers, thermo keywords, math functions, group functions, atom vectors, compute references, other variables
    numbers = 0.0, -5.4, 2.8e-4, etc
    thermo keywords = vol, ke, press, etc from "thermo_style"_thermo_style.html
    math functions = add(x,y), sub(x,y), mult(x,y), div(x,y),
                     neg(x), pow(x,y), exp(x), ln(x), sqrt(x)
    group functions = mass(group), charge(group),
		      xcm(group,dim), vcm(group,dim), fcm(group,dim),
		      bound(group,xmin), gyration(group)
    atom vectors for {equal} = mass\[N\], x\[N\], y\[N\], z\[N\],
                               vx\[N\], vy\[N\], vz\[N\],
			       fx\[N\], fy\[N\], fz\[N\]
    atom vectors for {atom} =  mass\[\], x\[\], y\[\], z\[\],
                               vx\[\], vy\[\], vz\[\],
			       fx\[\], fy\[\], fz\[\]
    compute references = c_ID\[0\], c_ID\[N\]
    fix references = f_ID\[0\], f_ID\[N\]
    other variables = v_abc, v_x, etc :pre
:ule

[Examples:]

variable x index run1 run2 run3 run4 run5 run6 run7 run8
variable LoopVar loop $n
variable beta equal div(temp,3.0)
variable b1 equal add(x\[234\],mult(0.5,vol))
variable b equal div(xcm(mol1,x),2.0)
variable b equal c_myTemp\[0\]
variable b atom div(mult(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 :pre

[Description:]

This command assigns one or more strings to a variable name.
Variables can be used in several ways in LAMMPS.  A variable can be
referenced elsewhere in an input script.  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 can be
evaluated to produce a 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), fix output (see the
"fix ave/spatial"_fix_ave_spatial.html and "compute
variable/atom"_compute_variable_atom.html commands), or dump output
(see the "dump custom"_dump.html and "compute
variable/atom"_compute_variable_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.
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 an equation 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 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 a command-line switch -var will override a
corresponding variable setting in the input script.

There are two exceptions to this rule.  First, variables of style
{equal} ARE redefined each time the command is encountered.  This
allow them to be reset, e.g. in a loop.  This means an {equal}-style
variable will re-define a command-line swich -var setting, so use an
{index}-style variable for these settings instead, as in bench/in.lj.

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 varaibles, and is thus available to be
re-defined in a subsequent variable command.

: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 exited from.

: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 an equation that will be evaluated afresh each time the
variable is used.  For {equal} style variables this equation computes
a scalar quantity, which becomes the value of the variable whenever it
is evaluated.  For {atom} style variables it computes a quantity for
each atom, which is used by the "compute variable/atom" command and
its associated output.

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.

The next command cannot be used with {equal} or {atom} style
variables, since there is only one string.

The equation 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 equation:

variable x equal div(add(pe,c_MyTemp\[0\]),pow(vol,div(1,3))) :pre

Specifically, an equation can contain numbers, thermo keywords, math
functions, group functions, atom vectors, compute references, and
other variables.  There is one difference between {equal} and {atom}
variables; the syntax of Atom vector references is different.

Number: 0.2, 1.0e20, -15.4, etc
Thermo keywords: vol, pe, ebond, etc
Math functions: add(x,y), sub(x,y), mult(x,y), div(x,y), \
  neg(x), pow(x,y), exp(x), ln(x), sqrt(x)
Group functions: mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim) \
  bound(ID,dir), gyration(ID)
Atom vectors for {equal}: mass\[N\], x\[N\], y\[N\], z\[N\], \
                          vx\[N\], vy\[N\], vz\[N\], \
                          fx\[N\], fy\[N\], fz\[N\]
Atom vectors for {atom}:  mass\[\], x\[\], y\[\], z\[\], \
                          vx\[\], vy\[\], vz\[\], \
                          fx\[\], fy\[\], fz\[\]
Compute references: c_ID\[0\], c_ID\[N\]
Fix references: f_ID\[0\], f_ID\[N\]
Other variables: v_abc, v_x, etc :tb(s=:)

The thermo keywords allowed in the equation are those defined by the
"thermo_style custom" command.  Note that many thermodyanmic
quantities are only computable after the first simulation has begun.
Likewise, many thermodynamic quantities (such as energies) are only
computed on timesteps when thermodyanmic output is being performed.
If the variable equation these quantities at other times, out-of-date
or invalid values may be used.

Math functions take one or two arguments, each of which may be an
equation containing any of the quantities defined above.  This allows
equations to be nested, as in the examples above.

Group functions take one or two arguments.  The first argument is the
group-ID.  The {dim} argument is {x} or {y} or {z}.  The {dir}
argument is {xmin}, {xmax}, {ymin}, {ymax}, {zmin}, or {zmax}.  The
group functions mass() and charge() are the total mass and charge of
the group of atoms.  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 the formula.

For {equal} style variables, atom vectors take a single integer
argument from 1-N, which is the desired atom-ID, e.g. x\[243\].  For
{atom} style variables, atom vectors take no argument.  Since {atom}
style variables compute one value per atom, a reference like x\[\]
means the x-coord of each atom will be used when evaluating the
variable.

Compute references access scalar or vector 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 "compute"_compute.html command for details.  Note that
per-atom quantities calculated by a compute cannot be accessed this
way, but only global scalar or vector quantities.  However, there is a
"compute sum"_compute_sum.html command which sums per-atom quantities
into a global scalar or vector which can be accessed by a variable.

If {c_ID\[0\]} is used as a keyword, then the scalar quantity
calculated by the compute is used.  If {c_ID\[N\]} is used, then one
component of the vector quantity calculated by the compute is used.  N
should be an integer from 1-M, where M is the length of the vector
calculated by the compute.

Fix references access scalar or vector quantities calculated by a
"fix"_fix.html.  See the doc pages for individual fixes to see which
ones compute a scalar or vector quantity.  Since the fix may not be
invoked every timestep and compute its quantities, you should insure
the variable is only evaluated on appropriate timesteps.  The ID in
the reference should be replaced by the actual ID of the fix defined
elsewhere in the input script.  See the "fix"_fix.html command for
details.  Note that per-atom quantities calculated by a fix cannot be
accessed this way, but only global scalar or vector quantities.

If {f_ID\[0\]} is used as a keyword, then the scalar quantity
calculated by the fix is used.  If {f_ID\[N\]} is used, then one
component of the vector quantity calculated by the fix is used.  N
should be an integer from 1-M, where M is the length of the vector
calculated by the fix.

The current values of other variables can be accessed by prepending a
"v_" to the variable name.  This will cause the other variable to be
evaulated.  Note that if you do something circular 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.

Note that there is a subtle difference between using a variable in a
{equal} or {atom} style equation in the form $x versus v_x.

In the former case, as with any other input script command, the
variable's value is substituted for immediately when the line is read
from the input script.  Thus if the current simulation box volume was
1000.0, then these lines:

variable x equal vol
variable y equal mult($x,2) :pre

would associate the equation string "mult(1000.0,2)" with variable y.

By contrast, these lines:

variable x equal vol
variable y equal mult(v_x,2) :pre

would associate the equation string "mult(v_x,2)" with variable y.

Thus if the variable y were evaluated periodically during a run where
the box volume changed, the resulting value would always be 2000.0 for
the first case, but would change dynamically for the second case.

:line

[Restrictions:]

The use of atom vectors in {equal} style variables requires the atom
style to use a global mapping in order to look up the vector indices.
Only atom styles with molecular information create global maps unless
the "atom_modify map"_atom_modify.html command is used.

All {universe}- and {uloop}-style variables 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