forked from lijiext/lammps
424 lines
21 KiB
HTML
424 lines
21 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>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)
|
|
atom value = mass[N], x[N], y[N], z[N],
|
|
vx[N], vy[N], vz[N], fx[N], fy[N], fz[N]
|
|
atom vector = mass[], 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>
|
|
|
|
</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 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> can be evaluated
|
|
to produce 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> can be evaluated to produce 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 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 allows them to be reset, when their formulas contain a
|
|
substitution for another variable, e.g. $x. This can be useful 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> option 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> option 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.
|
|
</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)</TD></TR>
|
|
<TR><TD >Atom values</TD><TD > mass[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[], 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[]
|
|
</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>
|
|
<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.
|
|
</P>
|
|
<P>The thermo keywords allowed in a formula are those defined by the
|
|
"thermo_style custom" command. Since many thermodynamic quantities
|
|
are only computable after the a simulation has begun, these keywords
|
|
cannot be used if a variable is evaluated before the first simulation
|
|
begins.
|
|
</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>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>
|
|
<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>
|
|
<P>Compute references access one or more 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.
|
|
</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>
|
|
<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 scalar from a per-atom compute</TD></TR>
|
|
<TR><TD >c_ID[][M]</TD><TD > per-atom vector component from a per-atom compute
|
|
</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>
|
|
<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>
|
|
<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).
|
|
</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
|
|
</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>
|
|
<HR>
|
|
|
|
<P>It is useful to understand the distinction between referencing a
|
|
variable in a formula using the $x form instead of v_x. There is a
|
|
subtle difference between the two references that has to do with when
|
|
the evaluation of the included variable is done.
|
|
</P>
|
|
<P>Referencing the variable as $x, the value of the include variable is
|
|
substituted for immediately when the line is read from the input
|
|
script, just as it would be in other input script command.
|
|
</P>
|
|
<P>This could be the desired behavior if a static value is desired. Or
|
|
it could be the desired behavior for an equal-style variable if the
|
|
variable command appears in a loop (see the <A HREF = "jump.html">jump</A> and
|
|
<A HREF = "next.html">next</A> commands), since the substitution will be performed
|
|
anew each time thru the loop as the command is re-read. Note that if
|
|
the variable formula is enclosed in double quotes, this prevents
|
|
variable substitution and thus an error will be generated when the
|
|
variable formula is evaluated.
|
|
</P>
|
|
<P>Referencing the variable as v_x, the value of the included variable
|
|
will not be accessed until the variable formula is evaluated. Thus
|
|
the value may change each time the evaluation is performed. This may
|
|
also be desired behavior.
|
|
</P>
|
|
<P>As an example, if the current simulation box volume is 1000.0, then
|
|
these lines:
|
|
</P>
|
|
<PRE>variable x equal vol
|
|
variable y equal 2*$x
|
|
</PRE>
|
|
<P>will associate the equation string "2*1000.0" with variable y.
|
|
</P>
|
|
<P>By contrast, these lines:
|
|
</P>
|
|
<PRE>variable x equal vol
|
|
variable y equal 2*v_x
|
|
</PRE>
|
|
<P>will associate the equation string "2*v_x" with variable y.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<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>
|