forked from lijiext/lammps
758 lines
38 KiB
HTML
758 lines
38 KiB
HTML
<HTML>
|
|
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
|
|
</CENTER>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<HR>
|
|
|
|
<H3>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>string</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, loop from 1 to N inclusive
|
|
<I>loop</I> args = N1 N2 = loop from N1 to N2 inclusive
|
|
<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>string</I> arg = one string
|
|
<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 operators = (), -x, x+y, x-y, x*y, x/y, x^y,
|
|
x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y
|
|
math functions = sqrt(x), exp(x), ln(x), log(x),
|
|
sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,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),
|
|
angmom(group,dim),inertia(group,dimdim),omega(group,dim)
|
|
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),
|
|
angmom(group,dim,region), inertia(group,dimdim,region),omega(group,dim,region)
|
|
special functions = ramp(x,y), stagger(x,y), logfreq(x,y,z), sum(x), min(x), max(x), ave(x), trap(x)
|
|
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 foo myfile
|
|
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.html">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>string</I> and <I>equal</I> and <I>atom</I> ARE redefined each time the command is
|
|
encountered. This allows these style of variables to be redefined
|
|
multiple times in an input script. In a loop, this means the formula
|
|
associated with an <I>equal</I> or <I>atom</I> style variable can change if it
|
|
contains a substitution for another variable, e.g. $x.
|
|
</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 inclusive, if only one argument N
|
|
is specified. 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. The <I>loop</I> style can also be specified with
|
|
two arguments N1 and N2. In this case the loop runs from N1 to N2
|
|
inclusive, and the string N1 is initially assigned 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
|
|
operators, math functions, group functions, region 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 operators</TD><TD > (), -x, x+y, x-y, x*y, x/y, x^y, x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y</TD></TR>
|
|
<TR><TD >Math functions</TD><TD > sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,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), angmom(ID,dim), inertia(ID,dimdim), omega(ID,dim)</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), angmom(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR)</TD></TR>
|
|
<TR><TD >Special functions</TD><TD > ramp(x,y), stagger(x,y), logfreq(x,y,z), sum(x), min(x), max(x), ave(x), trap(x)</TD></TR>
|
|
<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>
|
|
|
|
<HR>
|
|
|
|
<P>Most of the formula elements produce a scalar value. A few produce 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. Math functions that operate on scalar values produce a
|
|
scalar value; math function that operate on per-atom vectors do so
|
|
element-by-element and produce a per-atom vector.
|
|
</P>
|
|
<P>A formula for equal-style variables cannot use any formula element
|
|
that produces a per-atom vector. A formula for an atom-style variable
|
|
can use formula elements that produce either a scalar value or a
|
|
per-atom vector.
|
|
</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 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>
|
|
<HR>
|
|
|
|
<P>Math operators are written in the usual way, where the "x" and "y" in
|
|
the examples can themselves be arbitrarily complex formulas, as in the
|
|
examples above. In this syntax, "x" and "y" can be scalar values or
|
|
per-atom vectors. For example, "ke/natoms" is the division of two
|
|
scalars, where "y+z" is the element-by-element sum of two per-atom
|
|
vectors of y- and z-coordinates.
|
|
</P>
|
|
<P>Operators are evaluated left to right and have the usual C-style
|
|
precedence: unary minus before exponentiation ("^"); exponentiation
|
|
before multiplication and division; multiplication and division before
|
|
addition and subtraction; addition and subtraction before the 4
|
|
relational operators "<", "<=", ">", and ">="; those 4 relational
|
|
operators before the remaining two relational operators "==" and "!=";
|
|
those two relational operators before the logical AND operator "&&";
|
|
and the AND operator "&&" before the logical OR operator "||".
|
|
Parenthesis can be used to group one or more portions of a formula and
|
|
enforce a different order of evaluation than what would occur with the
|
|
default precedence.
|
|
</P>
|
|
<P>The 6 relational operators return either a 1.0 or 0.0 depending on
|
|
whether the relationship between x and y is true or false. For
|
|
example the expression x<10.0 in an atom-style variable formula will
|
|
return 1.0 for all atoms whose x-coordinate is less than 10.0, and 0.0
|
|
for the others. The logical AND operator will return 1.0 of both its
|
|
arguments are non-zero, else return a 0.0. The logical OR operator
|
|
will return 1.0 of either of its arguments is non-zero, else return a
|
|
0.0. These relational and logical operators can be used as a masking
|
|
or selection operation in a formula. For example, the number of atoms
|
|
whose properties satifsy one or more criteria could be calculated by
|
|
taking the returned per-atom vector of ones and zeroes and passing it
|
|
to the <A HREF = "compute_reduce.html">compute reduce</A> command.
|
|
</P>
|
|
<P>Math functions are specified as keywords followed by one or more
|
|
parenthesized arguments "x", "y", etc, each of which can themselves be
|
|
arbitrarily complex formulas. In this syntax, the arguments can
|
|
represent scalar values or per-atom vectors. In the latter case, the
|
|
math operation is performed on each element of the vector. For
|
|
example, "sqrt(natoms)" is the sqrt() of a scalar, where "sqrt(y*z)"
|
|
yields a per-atom vector with each element being the sqrt() of the
|
|
product of one atom's y and z coordinates.
|
|
</P>
|
|
<P>Most of the math functions perform obvious operations. The 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>
|
|
<HR>
|
|
|
|
<P>Group functions are specified as keywords followed by one or two
|
|
parenthesized arguments. 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 <I>dimdim</I> argument, if it exists, is <I>xx</I> or <I>yy</I> or <I>zz</I>
|
|
or <I>xy</I> or <I>yz</I> or <I>xz</I>.
|
|
</P>
|
|
<P>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 = "compute_gyration.html">compute gyration</A> command for a definition
|
|
of the formula. Angmom() returns components of the angular momentum
|
|
of the group of atoms around its center of mass. Inertia() returns
|
|
one of 6 components of the inertia tensor of the group of atoms around
|
|
its center of mass. Omega() returns components of the angular
|
|
velocity of the group of atoms around its center of mass.
|
|
</P>
|
|
<P>Region functions are specified exactly the same way 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>
|
|
<HR>
|
|
|
|
<P>Special functions take specific kinds of arguments, meaning their
|
|
arguments cannot be formulas themselves. For example ramp(10.0,100.0)
|
|
is valid, but ramp(2*5,sqrt(10000)) is not.
|
|
</P>
|
|
<P>Ramp(x,y) takes two integer or floating point values and uses the
|
|
current timestep to generate a scalar value:
|
|
</P>
|
|
<PRE>value = x + (y-x) * (timestep-startstep) / (stopstep-startstep)
|
|
</PRE>
|
|
<P>which is a value that ramps linearly between x and y over the course of
|
|
a run. The run begins on startstep and ends on stopstep. Startstep
|
|
and stopstep can span multiple runs, using the <I>start</I> and <I>stop</I>
|
|
keywords of the <A HREF = "run.html">run</A> command. See the <A HREF = "run.html">run</A>
|
|
command for details of how to do this.
|
|
</P>
|
|
<P>Stagger(x,y) takes two integer values and uses the current timestep to
|
|
generate a new timestep. X,y > 0 and x > y is required. The
|
|
generated timesteps increase in a staggered fashion, as the sequence
|
|
x,x+y,2x,2x+y,3x,3x+y,etc. For any current timestep, the next
|
|
timestep in the sequence is returned. Thus if stagger(1000,100) is
|
|
used in a variable by the <A HREF = "dump_modify.html">dump_modify every</A>
|
|
command, it will generate the sequence of output timesteps:
|
|
</P>
|
|
<PRE>100,1000,1100,2000,2100,3000,etc
|
|
</PRE>
|
|
<P>Logfreq(x,y,z) takes 3 integer values and uses the current timestep to
|
|
generate a new timestep. X,y,z > 0 and y < z is required. The
|
|
generated timesteps increase in a logarithmic fashion, as the sequence
|
|
x,2x,3x,...y*x,z*x,2*z*x,3*z*x,...y*z*x,z*z*x,2*z*x*x,etc. For any
|
|
current timestep, the next timestep in the sequence is returned. Thus
|
|
if logfreq(100,4,10) is used in a variable by the <A HREF = "dump_modify.html">dump_modify
|
|
every</A> command, it will generate the sequence of
|
|
output timesteps:
|
|
</P>
|
|
<PRE>100,200,300,400,1000,2000,3000,4000,10000,20000,etc
|
|
</PRE>
|
|
<P>The sum(x), min(x), max(x), ave(x), and trap(x) functions each take 1
|
|
argument which is of the form "c_ID" or "c_ID[N]" or "f_ID" or
|
|
"f_ID[N]". The first two are computes and the second two are fixes;
|
|
the ID in the reference should be replaced by the ID of a compute or
|
|
fix defined elsewhere in the input script. The compute or fix must
|
|
produce either a global vector or array. If it produces a global
|
|
vector, then the notation without "[N]" should be used. If it
|
|
produces a global array, then the notation with "[N]" should be
|
|
used, when N is an integer, to specify which column of the global
|
|
array is being referenced.
|
|
</P>
|
|
<P>All of these functions operate on the global vector of inputs and
|
|
reduce it to a single scalar value. This is analagous to the
|
|
operation of the <A HREF = "compute_reduce.html">compute reduce</A> command, which
|
|
invokes the same functions on per-atom and local vectors.
|
|
</P>
|
|
<P>The sum() function calculates the sum of all the vector elements. The
|
|
min() and max() functions find the minimum and maximum element
|
|
respectively. The ave() function is the same as sum() except that it
|
|
divides the result by the length of the vector. The trap() function
|
|
is the same as sum() except the first and last elements are multiplied
|
|
by a weighting factor of 1/2 when performing the sum. This
|
|
effectively implements an integratiion via the trapezoidal rule on the
|
|
global vector of data. I.e. consider a set of points, equally spaced
|
|
by 1 in their x coordinate: (1,V1), (2,V2), ..., (N,VN), where the Vi
|
|
are the values in the global vector of length N. The integral from 1
|
|
to N of these points is trap(). When appropriately normalized by the
|
|
timestep size, this function is useful for calculating integrals of
|
|
time-series data, like that generated by the <A HREF = "fix_ave_correlate.html">fix
|
|
ave/correlate</A> command.
|
|
</P>
|
|
<HR>
|
|
|
|
<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 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. Note that other atom attributes can be used
|
|
as inputs to a variable by using the <A HREF = "compute_property_atom.html">compute
|
|
property/atom</A> command and then specifying
|
|
a quantity from that compute.
|
|
</P>
|
|
<HR>
|
|
|
|
<P>Compute references access quantities calculated by a
|
|
<A HREF = "compute.html">compute</A>. The ID in the reference should be replaced by
|
|
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 only
|
|
use scalar values, which means a global scalar, or an element of a
|
|
global or per-atom vector or array. Atom-style variables can use the
|
|
same scalar values. They can also use per-atom vector values. A
|
|
vector value can be a per-atom vector itself, or a column of an
|
|
per-atom 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>
|
|
<HR>
|
|
|
|
<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 only use scalar values, which means a global scalar, or
|
|
an element of a global or per-atom vector or array. Atom-style
|
|
variables can use the same scalar values. They can also use per-atom
|
|
vector values. A vector value can be a per-atom vector itself, or a
|
|
column of an per-atom 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_". Again, there is no ambiguity as to what a reference means,
|
|
since fixes only produce global or per-atom quantities, never both.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<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>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.
|
|
</P>
|
|
<HR>
|
|
|
|
<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 global scalar value. An equal-style
|
|
variable can reference a global scalar value produced by another
|
|
variable, but not a per-atom vector produced by an atom-style
|
|
variable. Atom-style variables can reference either global scalar or
|
|
per-atom vector values produced by kind of variable.
|
|
</P>
|
|
<P>Examples of different kinds of variable references are as follows.
|
|
There is no ambiguity as to what a reference means, since variables
|
|
produce only a global scalar or a per-atom vectors, never both.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<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 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 <A HREF = "fix_ave_time.html">fix
|
|
ave/time</A> 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, and can do this only 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 generate an
|
|
error. This means, for example, that such a variable cannot be
|
|
evaluated before the first run has occurred. Likewise, in between
|
|
runs, such a variable cannot be accessed unless it was evaluated on
|
|
the last timestep of the preceding run, e.g. by thermodynamic output.
|
|
</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. Thus if you are trying to print a
|
|
variable that uses a compute you have defined, you could insure it was
|
|
invoked on the last timestep of the preceding run by including it in
|
|
thermodynamic output.
|
|
</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>
|