<HTML>
<CENTER><A HREF = "https://sparta.github.io">SPARTA WWW Site</A> - <A HREF = "Manual.html">SPARTA Documentation</A> - <A HREF = "Section_commands.html#comm">SPARTA 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>format</I> or <I>getenv</I> or <I>file</I> or <I>internal</I> or <I>equal</I> or <I>particle</I> or <I>grid</I> or <I>surf</I> 

<PRE>  <I>delete</I> = no args
  <I>index</I> args = one or more strings
  <I>loop</I> args = N
    N = integer size of loop, loop from 1 to N inclusive
  <I>loop</I> args = N pad
    N = integer size of loop, loop from 1 to N inclusive
    pad = all values will be same length, e.g. 001, 002, ..., 100
  <I>loop</I> args = N1 N2
    N1,N2 = loop from N1 to N2 inclusive
  <I>loop</I> args = N1 N2 pad
    N1,N2 = loop from N1 to N2 inclusive
    pad = all values will be same length, e.g. 050, 051, ..., 100
  <I>world</I> args = one string for each partition of processors
  <I>universe</I> args = one or more strings
  <I>uloop</I> args = N
    N = integer size of loop
  <I>uloop</I> args = N pad
    N = integer size of loop
    pad = all values will be same length, e.g. 001, 002, ..., 100
  <I>string</I> arg = one string
  <I>format</I> args = vname fstr
    vname = name of equal-style variable to evaluate
    fstr = C-style format string
  <I>getenv</I> arg = one string
  <I>file</I> arg = filename
  <I>internal</I> arg = numeric value
  <I>equal</I> or <I>particle</I> or <I>grid</I> or <I>surf</I> args = one formula
  containing numbers, stats keywords, math operations, particle vectors, compute/fix and custom attribute and surface collision/reaction and variable references
    numbers = 0.0, 100, -5.4, 2.8e-4, etc
    constants = PI
    stats keywords = step, np, vol, etc from <A HREF = "stats_style.html">stats_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, x||y, !x
    math functions = sqrt(x), exp(x), ln(x), log(x), abs(x),
                     sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), erf(x),
                     random(x,y), normal(x,y), ceil(x), floor(x), round(x)
                     ramp(x,y), stagger(x,y), logfreq(x,y,z), stride(x,y,z), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z)
    special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), next(x), grid2part(x)
    particle vectors = id, type, mass, q, mu, x, y, z, vx, vy, vz
    grid vectors = cxlo, cxhi, cylo, cyhi, czlo, czhi
    compute references = c_ID, c_ID[I], c_ID[I][J]
    fix references = f_ID, f_ID[I], f_ID[I][J]
    custom attribute references = p_name, p_name[I], g_name, g_name[I], s_name, s_name[I]
    surface collision model references = sc_ID[I]
    surface reaction model references = sr_ID[I]
    variable references = v_name 
</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 vol/ngrid
variable beta equal "vol / ngrid"
variable b equal c_myTemp
variable b particle x*y/vol
variable foo string myfile
variable foo internal 3.5
variable f file values.txt
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 pad
variable str format x %.6g
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 thus be useful in several contexts.  A variable can be
defined and then 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 statistical output (see the <A HREF = "stats_style.html">stats_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>particle</I>
or <I>grid</I> or <I>surf</I> store a formula which when evaluated produces one
numeric value per particle or grid cell or surface element which can
be output to the appropriate styles of dump file (see the
<A HREF = "dump.html">dump</A> command).  Variables of style <I>internal</I> are used by
a few commands which set their value directly.
</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 an input script line is encountered that defines
a variable of style <I>equal</I> or <I>particle</I> or <I>grid</I> of <I>surf</I> that
contains a formula, 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.  This is also true of the
<I>format</I> style variable since it evaluates another variable when it is
invoked.
</P>
<P>Variables of style <I>equal</I> and <I>particle</I> and <I>grid</I> and <I>surf</I> can be
used as inputs to various other commands which evaluate their formulas
as needed, e.g. at different timesteps during a <A HREF = "run.html">run</A>.
</P>
<P>Variables of style <I>internal</I> can be used in place of an equal-style
variable, except by commands that set the value stored by the
internal-style variable.  Thus any command that states it can use an
equal-style variable as an argument, can also use an internal-style
variable.  This means that when the command evaluates the variable, it
will use the value set (internally) by another command.
</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#start_7">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>, <I>getenv</I>, <I>internal</I>, <I>equal</I>, <I>particle</I>, <I>grid</I>, and
<I>surf</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>particle</I> or <I>grid</I> or <I>surf</I> style variable can change if
it contains a substitution for another variable, e.g. $x or v_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#cmd_2">Section 3.2</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>This section describes how various variable styles are defined and
what they store.  Many of the styles store one or more strings.  Note
that a single string can contain spaces (multiple words), if it is
enclosed in quotes in the variable command.  When the variable is
substituted for in another input script command, its returned string
will then be interpreted as multiple arguments in the expanded
command.
</P>
<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#start_7">Section
2.6</A> of the manual 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.
N1 <= N2 and N2 >= 0 is required.
</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#start_7">Section
2.6</A> of the manual for information on
running SPARTA 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.
</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#start_7">this page</A> for information
on running SPARTA 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.sparta.variable" and "tmp.sparta.variable.lock"
which you will see in your directory during such a SPARTA 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>
<P>For the <I>string</I> style, a single string is assigned to the variable.
The only difference between this and using the <I>index</I> style with a
single string is that a variable with <I>string</I> style can be redefined.
E.g. by another command later in the input script, or if the script is
read again in a loop.
</P>
<P>For the <I>format</I> style, an equal-style variable is specified along
with a C-style format string, e.g. "%f" or "%.10g", which must be
appropriate for formatting a double-precision floating-point value.
This allows an equal-style variable to be formatted specifically for
output as a string, e.g. by the <A HREF = "print.html">print</A> command, if the
default format "%.15g" has too much precision.
</P>
<P>For the <I>getenv</I> style, a single string is assigned to the variable
which should be the name of an environment variable.  When the
variable is evaluated, it returns the value of the environment
variable, or an empty string if it not defined.  This style of
variable can be used to adapt the behavior of SPARTA input scripts via
environment variable settings, or to retrieve information that has
been previously stored with the <A HREF = "shell.html">shell putenv</A> command.
Note that because environment variable settings are stored by the
operating systems, they persist beyond a <A HREF = "clear.html">clear</A> command.
</P>
<P>For the <I>file</I> style, a filename is provided which contains a list of
strings to assign to the variable, one per line.  The strings can be
numeric values if desired.  See the discussion of the next() function
below for equal-style variables, which will convert the string of a
file-style variable into a numeric value in a formula.
</P>
<P>When a file-style variable is defined, the file is opened and the
string on the first line is read and stored with the variable.  This
means the variable can then be evaluated as many times as desired and
will return that string.  There are two ways to cause the next string
from the file to be read: use the <A HREF = "next.html">next</A> command or the
next() function in an equal- or particle- or grid-style variable, as
discussed below.
</P>
<P>The rules for formatting the file are as follows.  A comment character
"#" can be used anywhere on a line; text starting with the comment
character is stripped.  Blank lines are skipped.  The first "word" of
a non-blank line, delimited by white space, is the "string" assigned
to the variable.
</P>
<P>For the <I>internal</I> style a numeric value is provided.  This value will
be assigned to the variable until a SPARTA command sets it to a new
value.  There is currently only one command that requirew <I>internal</I>
variables as inputs, because it resets them:
<A HREF = "create_particles.html">create_particles</A>.  As mentioned above, an
internal-style variable can be used in place of an equal-style
variable anywhere else in an input script, e.g. as an argument to
another command that allows for equal-style variables.
</P>
<HR>

<P>For the <I>equal</I>, <I>particle</I>, <I>grid</I>, and <I>surf</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.
</P>
<P>For <I>particle</I> style variables the formula computes one quantity for
each particle whenever it is evaluated.  For <I>grid</I> style variables
the formula computes one quantity for each grid cell whenever it is
evaluated.  A <I>grid</I> style variable computes quantites for all flavors
of child grid cells in the simulation, which includes unsplit, cut,
split, and sub cells.  See <A HREF = "Section_howto.html#howto_8">Section 4.8</A> of
the manual gives details of how SPARTA defines child, unsplit, split,
and sub cells.  For <I>surf</I> style variables the formula computes one
quantity for each surface element (line or triangle) whenever it is
evaluated.  They can only be defined for explicit surfaces, not
implicit surfaces.  See <A HREF = "Section_howto.html#howto_9">Section 4.9</A> of
the manual for a description of both kinds of surface elements.
</P>
<P>Note that <I>equal</I>, <I>particle</I>, <I>grid</I>, and <I>surf</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>, <I>particle</I>, <I>grid</I>, or
<I>surf</I> style variables, since there is only one string.
</P>
<P>The formula for an <I>equal</I>, <I>particle</I>, <I>grid</I>, or <I>surf</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 "np + c_MyTemp / vol^(1/3)" 
</PRE>
<P>Specifically, a formula can contain numbers, stats keywords, math
operators, math functions, particle vectors, grid vectors, compute
references, fix references, custom attribute references, and 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 >Constant</TD><TD > PI</TD></TR>
<TR><TD >Stats keywords</TD><TD > step, np, vol, 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, x||y, !x</TD></TR>
<TR><TD >Math functions</TD><TD > sqrt(x), exp(x), ln(x), log(x), abs(x), sin(x), cos(x), tan(x),      asin(x), acos(x), atan(x), atan2(y,x), erf(x), random(x,y,z), normal(x,y,z),      ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z),      stride(x,y,z), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z)</TD></TR>
<TR><TD >Special functions</TD><TD > sum(x), min(x), max(x), ave(x), trap(x), slope(x), next(x), grid2part(x)</TD></TR>
<TR><TD >Particle vectors</TD><TD > id, type, mass, q, mu, x, y, z, vx, vy, vz</TD></TR>
<TR><TD >Grid vectors = cxlo, cxhi, cylo, cyhi, czlo, czhi</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 >Custom attribute references = name_ID, name_ID[I], name_ID, name_ID[I], name_ID, name_ID[I]</TD></TR>
<TR><TD >Surface collision model references</TD><TD > sc_ID[I]</TD></TR>
<TR><TD >Surface reaction model references</TD><TD > sr_ID[I]</TD></TR>
<TR><TD >Other variables</TD><TD > v_name 
</TD></TR></TABLE></DIV>

<HR>

<P>Most of the formula elements produce a scalar value.  A few produce a
per-particle vector or per-grid vector or per-surf vector of values.
These are the particle vectors, grid vectors, compute and fix
references that represent a per-particle or per-grid vector or
per-surf vector, and variables that are particle-style or grid-style
or surf-style variables.  Math functions that operate on scalar values
produce a scalar value; math functions that operate on per-particle or
per-grid or per-surf vectors do so element-by-element and produce a
per-particle or per-grid or per-surf vectors.
</P>
<P>A formula for equal-style variables cannot use any formula element
that produces a per-particle or per-grid or per-surf vector.  A
formula for a particle-style variable can use formula elements that
produce either a scalar value or a per-particle vector, but not a
per-grid or per-surf vector.  Likewise a grid-style variable can use
formula elements that produce either a scalar value or a per-grid
vector, but not a per-particle or per-surf vector.  And a surf-style
variable can use formula elements that produce either a scalar value
or a per-surf vector, but not a per-particle or per-grid vector.
</P>
<P>The stats keywords allowed in a formula are those defined by the
<A HREF = "stats_style.html">stats_style custom</A> command.
</P>
<HR>

<H4>Math Operators 
</H4>
<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-particle or per-grid vectors.  For example, "vol/np" is the
division of two scalars, where "vy+vz" is the element-by-element sum
of two per-particle vectors of y and z velocities.
</P>
<P>Operators are evaluated left to right and have the usual C-style
precedence: unary minus and unary logical NOT operator "!" have the
highest precedence, exponentiation "^" is next; multiplication and
division and the modulo operator "%" are next; addition and
subtraction are next; the 4 relational operators "<", "<=", ">", and
">=" are next; the two remaining relational operators "==" and "!="
are next; then the logical AND operator "&&"; and finally the logical
OR operator "||" has the lowest precedence.  Parenthesis can be used
to group one or more portions of a formula and/or enforce a different
order of evaluation than what would occur with the default precedence.
</P>
<P>IMPORTANT NOTE: Because a unary minus is higher precedence than
exponentiation, the formula "-2^2" will evaluate to 4, not -4.  This
convention is compatible with some programming languages, but not
others.  As mentioned, this behavior can be easily overridden with
parenthesis; the formula "-(2^2)" will evaluate to -4.
</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 a particle-style variable formula
will return 1.0 for all particles whose x-coordinate is less than
10.0, and 0.0 for the others.  The logical AND operator will return
1.0 if both its arguments are non-zero, else it returns 0.0.  The
logical OR operator will return 1.0 if either of its arguments is
non-zero, else it returns 0.0.  The logical NOT operator returns 1.0
if its argument is 0.0, else it returns 0.0.
</P>
<P>These relational and logical operators can be used as a masking or
selection operation in a formula.  For example, the number of
particles whose properties satifsy one or more criteria could be
calculated by taking the returned per-particle vector of ones and
zeroes and passing it to the <A HREF = "compute_reduce.html">compute reduce</A>
command.
</P>
<HR>

<H4>Math Functions 
</H4>
<P>Math functions are specified as keywords followed by one or more
parenthesized arguments "x", "y", "z", each of which can themselves be
arbitrarily complex formulas.  In this syntax, the arguments can
represent scalar values or per-particle or per-grid vectors.  In the
latter cases, the math operation is performed on each element of the
vector.  For example, "sqrt(np)" is the sqrt() of a scalar, where
"sqrt(y*z)" yields a per-particle vector with each element being the
sqrt() of the product of one particle'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.
</P>
<P>The random(x,y) function takes 2 arguments: x = lo and y = hi.  It
generates a uniform random number between lo and hi.  The normal(x,y)
function also takes 2 arguments: x = mu and y = sigma.  It generates a
Gaussian variate centered on mu with variance sigma^2.  For
equal-style variables, every processor uses the same random number
seed so that they each generate the same sequence of random numbers.
For particle-style or grid-style variables, a unique seed is created
for each processor.  This effectively generates a different random
number for each particle or grid cell being looped over in the
particle-style or grid-style variable.
</P>
<P>IMPORTANT NOTE: Internally, there is just one random number generator
for all equal-style variables and one for all particle-style and
grid-style variables.  If you define multiple variables (of each
style) which use the random() or normal() math functions, then the
internal random number generators will only be initialized once.
</P>
<P>The ceil(), floor(), and round() functions 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>The ramp(x,y) function uses the current timestep to generate a value
linearly intepolated between the specified x,y values over the course
of a run, according to this formula:
</P>
<PRE>value = x + (y-x) * (timestep-startstep) / (stopstep-startstep) 
</PRE>
<P>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>IMPORTANT NOTE: Currently, the run command does not currently support
the start/stop keywords.  In the formula above startstep = 0 and
stopstep = the number of timesteps being performed by the run.
</P>
<P>The stagger(x,y) function uses the current timestep to generate a new
timestep.  X,y > 0 and x > y are 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>The logfreq(x,y,z) function uses the current timestep to generate a
new timestep.  X,y,z > 0 and y < z are 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 stride(x,y,z) function uses the current timestep to generate a new
timestep.  X,y >= 0 and z > 0 and x <= y are required.  The generated
timesteps increase in increments of z, from x to y, I.e. it generates
the sequece x,x+z,x+2z,...,y.  If y-x is not a multiple of z, then
similar to the way a for loop operates, the last value will be one
that does not exceed y.  For any current timestep, the next timestep
in the sequence is returned.  Thus if stagger(1000,2000,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>1000,1100,1200, ... ,1900,2000 
</PRE>
<P>The vdisplace(x,y) function takes 2 arguments: x = value0 and y =
velocity, and uses the elapsed time to change the value by a linear
displacement due to the applied velocity over the course of a run,
according to this formula:
</P>
<PRE>value = value0 + velocity*(timestep-startstep)*dt 
</PRE>
<P>where dt = the timestep size.
</P>
<P>The run begins on startstep.  Startstep can span multiple runs, using
the <I>start</I> keyword 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.  Note that the
<A HREF = "stats_style.html">stats_style</A> keyword <I>elaplong</I> =
timestep-startstep.
</P>
<P>The swiggle(x,y,z) and cwiggle(x,y,z) functions each take 3 arguments:
x = value0, y = amplitude, z = period.  They use the elapsed time to
oscillate the value by a sin() or cos() function over the course of a
run, according to one of these formulas, where omega = 2 PI / period:
</P>
<PRE>value = value0 + Amplitude * sin(omega*(timestep-startstep)*dt)
value = value0 + Amplitude * (1 - cos(omega*(timestep-startstep)*dt)) 
</PRE>
<P>where dt = the timestep size.
</P>
<P>The run begins on startstep.  Startstep can span multiple runs, using
the <I>start</I> keyword 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.  Note that the
<A HREF = "stats_style.html">stats_style</A> keyword <I>elaplong</I> =
timestep-startstep.
</P>
<HR>

<H4>Special Functions 
</H4>
<P>Special functions take specific kinds of arguments, meaning their
arguments cannot be formulas themselves.
</P>
<P>The sum(x), min(x), max(x), ave(x), trap(x), and slope(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>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-particle or per-grid 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.  
</P>
<P>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().
</P>
<P>The slope() function uses linear regression to fit a line to the 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 returned value is the slope of the line.  If the line
has a single point or is vertical, it returns 1.0e20.
</P>
<P>The next(x) function takes 1 argument which is a variable ID (not
"v_foo", just "foo").  It must be for a file-style
variable.  Each time the next() function is invoked (i.e. each time
the equal-style or particle-style or grid-style variable is evaluated),
the following steps occur.
</P>
<P>For file-style variables, the current string value stored by the
file-style variable is converted to a numeric value and returned by
the function.  And the next string value in the file is read and
stored.  Note that if the line previously read from the file was not a
numeric string, then it will typically evaluate to 0.0, which is
likely not what you want.
</P>
<P>Since file-style variables read and store the first line of the file
when they are defined in the input script, this is the value that will
be returned the first time the next() function is invoked.  If next()
is invoked more times than there are lines in the file, the variable
is deleted, similar to how the <A HREF = "next.html">next</A> command operates.
</P>
<P>The grid2part(x) function can only be used in a particle-style
variable formula.  Its purpose is to enable each particle to access a
per-grid quantity for the grid cell it is currently in.  The per-grid
quantity must be produced by a compute or fix.  When the
particle-style variable formula is evaluated for each particle, the
per-grid vector or array from the compute or fix is accessed, using
the grid cell index for each particle.
</P>
<P>An example of its usage is as follows:
</P>
<PRE>variable     csq particle "vx*vx + vy*vy + vz*vz"
compute      therm thermal/grid all all temp press
variable     csq_norm particle v_csq/grid2part(c_therm<B>1</B>) 
</PRE>
<P>The per-particle variable csq_norm will calculate the kinetic energy
for each particle, normalized by the thermal temperature of the full
set of particles for the grid cell it is in.  The latter is computed
by the <A HREF = "compute_thermal_grid.html">compute thermal/grid</A> command.
</P>
<P>The grid2part(x) function takes 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 per-grid vector or
array.  If it produces a per-grid vector, then the notation without
"[N]" should be used.  If it produces a per-grid array, then the
notation with "[N]" should be used, when N is an integer, to specify
which column of the per-grid array is being referenced.
</P>
<HR>

<H4>Particle Vectors 
</H4>
<P>Particle vectors generate one value per particle, so that a reference
like "vx" means the x-component of each particles's velocity will be
used when evaluating the variable.  The reference "type" is an integer
index representing the particle species.  It is a value from 1 to
Nspecies. The value corresponds to the order in which species were
defined via the <A HREF = "species.html">species</A> command.
</P>
<P>Particle vectors for mass and q and mu are per-species values.  "Mass"
is the mass for the particle's species, "q" is the particle's charge,
"mu" is its magnetic moment.
</P>
<P>The meaning of the other particle vectors should be self-explanatory.
</P>
<P>Particle vectors can only be used in <I>particle</I> style variables, not
in <I>equal</I> or <I>grid</I> or <I>surf</I> style varaibles.
</P>
<HR>

<H4>Grid Vectors 
</H4>
<P>Grid vectors generate one value per grid cell, so that a reference
like "cxhi" means the x-component of each grid cell's upper right
corner will be used when evaluating the variable.
</P>
<P>The meaning of the other grid vectors should be self-explanatory.
</P>
<P>Grid vectors can only be used in <I>grid</I> style variables, not in
<I>equal</I> or <I>particle</I> or <I>surf</I> style varaibles.
</P>
<HR>

<H4>Compute References 
</H4>
<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-particle, per-grid, or per-surf
values.  Computes can also produce a scalar, vector, or array.  See
the doc pages for individual computes to see what kind of values they
produce.
</P>
<P>An equal-style variable can only use scalar values, which means a
global scalar, or an element of a global vector or array.
Particle-style variables can use the same scalar values.  They can
also use per-particle vector values.  A vector value can be a
per-particle vector itself, or a column of an per-particle array.
Grid-style variables can use the same scalar values.  They can also
use per-grid vector values.  A vector value can be a per-grid vector
itself, or a column of an per-grid array.  Surf-style variables can
use the same scalar values.  They can also use per-surf vector values.
A vector value can be a per-surf vector itself, or a column of an
per-surf array.
</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, per-particle, per-grid, or per-surf quantities,
never more than one kind of quantity.
</P>
<DIV ALIGN=center><TABLE  BORDER=1 >
<TR><TD >c_ID</TD><TD > global scalar, or per-particle or per-grid or per-surf vector</TD></TR>
<TR><TD >c_ID[I]</TD><TD > Ith element of global vector, or Ith column from per-particle or per-grid or per-surf array</TD></TR>
<TR><TD >c_ID[I][J]</TD><TD > I,J element of global array 
</TD></TR></TABLE></DIV>

<P>For I and J, integers can be specified or a variable name, specified
as v_name, where name is the name of the variable, like
x[v_myIndex].  The variable can be of any style expect
particle-style.  The variable is evaluated and the result is expected
to be numeric and is cast to an integer (i.e. 3.4 becomes 3), to use
an an index, which must be a value from 1 to N.  Note that a "formula"
cannot be used as the argument between the brackets, e.g. x[243+10]
or x[v_myIndex+1] are not allowed.  To do this a single variable can
be defined that contains the needed formula.
</P>
<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>

<H4>Fix References 
</H4>
<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-particle,
per-grid, or per-surf values.  Fixes can also produce a scalar,
vector, or array.  See the doc pages for individual fixes to see what
kind of values they produce.
</P>
<P>An equal-style variable can only use scalar values, which means a
global scalar, or an element of a global vector or array.
Particle-style variables can use the same scalar values.  They can
also use per-particle vector values.  A vector value can be a
per-particle vector itself, or a column of an per-particle array.
Grid-style variables can use the same scalar values.  They can also
use per-grid vector values.  A vector value can be a per-grid vector
itself, or a column of an per-grid array.  Surf-style variables can
use the same scalar values.  They can also use per-surf vector values.
A vector value can be a per-surf vector itself, or a column of an
per-surf array.
</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-particle or per-grid
quantities, never more than one kind of quantity.
</P>
<DIV ALIGN=center><TABLE  BORDER=1 >
<TR><TD >f_ID</TD><TD > global scalar, or per-particle or per-grid or per-surf vector</TD></TR>
<TR><TD >f_ID[I]</TD><TD > Ith element of global vector, or Ith column from per-particle or per-grid or per-surf array</TD></TR>
<TR><TD >f_ID[I][J]</TD><TD > I,J element of global array 
</TD></TR></TABLE></DIV>

<P>For I and J, integers can be specified or a variable name, specified
as v_name, where name is the name of the variable.  The rules for this
syntax are the same as for the "Compute References" discussion above.
</P>
<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>

<H4>Custom Attribute References 
</H4>
<P>Particles, grid cells, and surface elements can have custom attributes
which store either single or multiple values per particle, per grid
cell, or per surface element.  They can be defined and initialized in
data files, e.g. via the <A HREF = "read_surf.html">read_surf</A> command.  Or they
can be defined and used by specific commands, e.g. <A HREF = "fix_ambipolar.html">fix
ambipolar</A> or <A HREF = "fix_surf_temp.html">fix surf/temp</A> or
<A HREF = "surf_react_adsorb.html">surf_react adsorb</A>.  The name of each
attribute sis set by the user or defined by the command.  See <A HREF = "Section_howto.html#howto_17">Section
6.17</A> for more discussion of custom
attributes.
</P>
<P>Single-value attributes are referred to as per-particle, per-grid, or
per-surf vectors.  Multiple-value attributes are referred to as
per-particle, per-grid, or per-surf arrays.  In variable formulas they
can be referenced using the following syntax:
</P>
<DIV ALIGN=center><TABLE  BORDER=1 >
<TR><TD >p_name</TD><TD > per-particle vector</TD></TR>
<TR><TD >p_name[I]</TD><TD > Ith column from a per-particle array</TD></TR>
<TR><TD >g_name</TD><TD > per-grid vector</TD></TR>
<TR><TD >g_name[I]</TD><TD > Ith column from a per-grid array</TD></TR>
<TR><TD >s_name</TD><TD > per-surf vector</TD></TR>
<TR><TD >s_name[I]</TD><TD > Ith column from a per-surf array 
</TD></TR></TABLE></DIV>

<P>Particle attributes can only be used in particle-style variables.
Grid cell attributes can only be used in grid-style variables.
Surface element attributes can only be used in surf-style variables.
</P>
<HR>

<H4>Surface Collision and Surface Reaction Model References 
</H4>
<P>These references access quantities calculated by a
<A HREF = "surf_collide.html">surf_collide</A> or <A HREF = "surf_react.html">surf_react</A>
command.  The ID in the reference should be replaced by the ID of a
surface collision or surface reaction model defined elsewhere in the
input script.  As discussed in the doc pages for the
<A HREF = "surf_collide.html">surf_collide</A> and <A HREF = "surf_react.html">surf_react</A>
commands, these commmands produce global vectors, the elements of
which can be accessed by equal-style, particle-style, grid-style, or
surf-style variables, e.g.
</P>
<DIV ALIGN=center><TABLE  BORDER=1 >
<TR><TD >sc_ID[I]</TD><TD > Ith element of global vector for a surface collision model</TD></TR>
<TR><TD >sr_ID[I]</TD><TD > Ith element of global vector for a surface reaction model 
</TD></TR></TABLE></DIV>

<HR>

<H4>Variable References 
</H4>
<P>Variable references access quantities stored or calculated 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.
</P>
<P>As discussed on this doc page, equal-style variables generate a global
scalar numeric value; particle-style variables generate a per-particle
vector of numeric values; grid-style variables generate a per-grid
vector of numeric values; surf-style variables generate a per-surf
vector of numeric values; all other variables store a string.
</P>
<P>The formula for an equal-style variable can use any style of variable
except a particle- or grid- or surf-style.  The formula for a
particle-style variable can use any style of variable except a grid-
or surf-style.  The formula for a grid-style variable can use any
style of variable except a particle- or surf-style.  The formula for a
surf-style variable can use any style of variable except a particle-
or grid-style.
</P>
<P>If a string-storing variable is used, the string is converted to a
numeric value.  Note that this will typically produce a 0.0 if the
string is not a numeric string, which is likely not what you want.
</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-particle or per-grid or per-surf
vector, never more than one of these quantities.
</P>
<DIV ALIGN=center><TABLE  BORDER=1 >
<TR><TD >v_name</TD><TD > equal- or particle- or grid- or surf-style variable 
</TD></TR></TABLE></DIV>

<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 input script command, including
a variable command.  The input script parser evaluates the reference
variable immediately and substitutes its value into the command.  As
explained in <A HREF = "Section_commands.html#3_2">Section commands 3.2</A> for
"Parsing rules", you can also use un-named "immediate" variables for
this purpose.  For example, a string like this
$((xlo+xhi)/2+sqrt(v_area)) in an input script command evaluates the
string between the parenthesis as an equal-style variable formula.
</P>
<P>Referencing a variable with a leading "v_" is an optional or required
kind of argument for 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 = "stats_style.html">stats_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 "n" as
</P>
<PRE>variable n equal np 
</PRE>
<P>before a run where the particle count changes.  You might think this
will assign the initial count to the variable "n".  That is not the
case.  Rather it assigns a formula which evaluates the count (using
the stats_style keyword "np") to the variable "n".  If you use the
variable "n" in some other command like <A HREF = "fix_ave_time.html">fix
ave/time</A> then the current particle count will be
evaluated continuously during the run.
</P>
<P>If you want to store the initial particle count of the system, it
can be done in this manner:
</P>
<PRE>variable n equal np
variable n0 equal $n 
</PRE>
<P>The second command will force "n" to be evaluated (yielding the
initial count) and assign that value to the variable "n0".  Thus the
command
</P>
<PRE>stats_style custom step v_n v_n0 
</PRE>
<P>would print out both the current and initial particle count
periodically during the run.
</P>
<P>Also note that it is a mistake to enclose a variable formula in quotes
if it contains variables preceeded by $ signs.  For example,
</P>
<PRE>variable nratio equal "${nfinal}/${n0}" 
</PRE>
<P>This is because the quotes prevent variable substitution (see <A HREF = "Section_commands.html#cmd_2">Section
2.2</A> of the manual on parsing input script
commands), and thus an error will occur when the formula for "nratio"
is evaluated later.
</P>
<HR>

<P><B>Variable Accuracy:</B>
</P>
<P>Obviously, SPARTA attempts to evaluate variables containing formulas
(<I>equal</I>, <I>particle</I>, <I>grid</I>, <I>surf</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>, 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 certain properties of the system such as the
pressure induced on a global boundary due to collisions, then these
quantities need to be tallied during the timesteps on which the
variable will need the values.
</P>
<P>SPARTA keeps track of all of this as it performs a <A HREF = "run.html">run</A> as
well as in between simulations.  An error will be generated if you
attempt to evaluate a variable when SPARTA knows it cannot produce
accurate values.  For example, if a <A HREF = "stats.html">stats</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 stats
output is generated are not multiples of the averaging frequency used
in the fix command, then an error will occur.
</P>
<P>However, there are two special cases to be aware of when a variable
requires invocation of a compute (directly or indirectly).  The first
is if the variable is evaluated before a <A HREF = "run.html">run</A> command which
follows the <A HREF = "compute.html">compute</A> command which created that compute.
In this case, SPARTA will generate an error.  This is because some
computes require initializations which does not take place unit a run
is initialized.  One example is the <A HREF = "compute_property_surf.html">compute
property/surf</A> command which creates a list
of surface elements in the specified group.  This does not occur until
a run begins.
</P>
<P>The second special case is when a variable that depends on a compute
is evaluated in between <A HREF = "run.html">run</A> commands.  It is possible for
other input script commands issued following the previous run, but
before the variable is evaluated, to change the system.  For example,
the <A HREF = "remove_surf.html">remove_surf</A> command could be used to remove
surface elements.  If the variable depends on a <A HREF = "compute_property_surf.html">property/surf
compute</A>, that compute will not
re-initialize itself until the next simulation.  Thus it may generate
an incorrect answer when evaluated.  Note that SPARTA will not
generate an error in this case; the evaluated variable may simply be
incorrect.
</P>
<P>The way to get around both of these special cases is to perform a
0-timestep run before evaluating the variable.
</P>
<HR>

<P><B>Restrictions:</B>
</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 = "fix_print.html">fix
print</A>, <A HREF = "print.html">print</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
