LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

### variable command

Syntax:

    variable name style args ...

- name = name of variable to define
- style = index or loop or world or universe or uloop or equal or atom

        index args = one or more strings
        loop args = N = integer size of loop
        world args = one string for each partition of processors
        universe args = one or more strings
        uloop args = N = integer size of loop
        equal or atom args = one equation containing numbers, thermo keywords, math functions, group functions, atom vectors, compute references, other variables
          numbers = 0.0, -5.4, 2.8e-4, etc
          thermo keywords = vol, ke, press, etc from thermo_style
          math functions = add(x,y), sub(x,y), mult(x,y), div(x,y),
                           neg(x), pow(x,y), exp(x), ln(x), sqrt(x)
          group functions = mass(group), charge(group),
      		      xcm(group,dim), vcm(group,dim), fcm(group,dim),
      		      bound(group,xmin), gyration(group)
          atom vectors for equal = mass[N], x[N], y[N], z[N],
                                     vx[N], vy[N], vz[N],
      			       fx[N], fy[N], fz[N]
          atom vectors for atom =  mass[], x[], y[], z[],
                                     vx[], vy[], vz[],
      			       fx[], fy[], fz[]
          compute references = c_ID[0], c_ID[N]
          fix references = f_ID[0], f_ID[N]
          other variables = v_abc, v_x, etc

Examples:

    variable x index run1 run2 run3 run4 run5 run6 run7 run8
    variable LoopVar loop $n
    variable beta equal div(temp,3.0)
    variable b1 equal add(x[234],mult(0.5,vol))
    variable b equal div(xcm(mol1,x),2.0)
    variable b equal c_myTemp[0]
    variable b atom div(mult(x,y),vol)
    variable temp world 300.0 310.0 320.0 $Tfinal
    variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
    variable x uloop 15

Description:

This command assigns one or more strings to a variable name. Variables can be used in several ways in LAMMPS. A variable can be referenced elsewhere in an input script. For variable styles that store multiple strings, the next command can be used to increment which string is assigned to the variable. Variables can be evaluated to produce a numeric value which can be output either directly (see the print, fix print, and run every commands) or as part of thermodynamic output (see the thermo_style command), fix output (see the fix ave/spatial and compute variable/atom commands), or dump output (see the dump custom and compute variable/atom commands).

In the discussion that follows, the "name" of the variable is the arbitrary string that is the 1st argument in the variable command. The "string" is one or more of the subsequent arguments. The "string" can be simple text as in the 1st example above, it can contain other variables as in the 2nd example, or it can be an equation as in the 3rd example. The "value" is the numeric quantity resulting from evaluation of the string. Note that the same string can generate different values when it is evaluated at different times during a simulation.

IMPORTANT NOTE: When a variable command is encountered in the input script and the variable name has already been specified, the command is ignored. This means variables can NOT be re-defined in an input script (with 2 exceptions, read further). This is to allow an input script to be processed multiple times without resetting the variables; see the jump or include commands. It also means that using a command-line switch -var will override a corresponding variable setting in the input script.

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

Second, as described below, if a variable is iterated on to the end of its list of strings via the next command, it is removed from the list of active varaibles, and is thus available to be re-defined in a subsequent variable command.

This section of the manual explains how occurrences of a variable name in an input script line are replaced by the variable's string. The variable name can be referenced as $x if the name "x" is a single character, or as ${LoopVar} if the name "LoopVar" is one or more characters.

As described below, for variable styles index, loop, universe, and uloop, which string is assigned to a variable can be incremented via the next command. When there are no more strings to assign, the variable is "exhausted" and a flag is set that causes the next jump command encountered in the input script to be skipped. This enables the construction of simple loops in the input script that are iterated over and exited from.

For the index style, one or more strings are specified. Initially, the 1st string is assigned to the variable. Each time a next command is used with the variable name, the next string is assigned. All processors assign the same string to the variable.

Index style variables with a single string value can also be set by using the command-line switch -var; see this section for details.

The loop style is identical to the index style except that the strings are the integers from 1 to N. This allows generation of a long list of runs (e.g. 1000) without having to list N strings in the input script. Initially, the string "1" is assigned to the variable. Each time a next command is used with the variable name, the next string ("2", "3", etc) is assigned. All processors assign the same string to the variable.

For the world style, one or more strings are specified. There must be one string for each processor partition or "world". See this section of the manual for information on running LAMMPS with multiple partitions via the "-partition" command-line switch. This variable command assigns one string to each world. All processors in the world are assigned the same string. The next command cannot be used with equal style variables, since there is only one value per world. This style of variable is useful when you wish to run different simulations on different partitions, or when performing a parallel tempering simulation (see the temper command), to assign different temperatures to different partitions.

For the universe style, one or more strings are specified. There must be at least as many strings as there are processor partitions or "worlds". See this page for information on running LAMMPS with multiple partitions via the "-partition" command-line switch. This variable command initially assigns one string to each world. When a next command is encountered using this variable, the first processor partition to encounter it, is assigned the next available string. This continues until all the variable strings are consumed. Thus, this command can be used to run 50 simulations on 8 processor partitions. The simulations will be run one after the other on whatever partition becomes available, until they are all finished. Universe style variables are incremented using the files "tmp.lammps.variable" and "tmp.lammps.variable.lock" which you will see in your directory during such a LAMMPS run.

The uloop style is identical to the universe style except that the strings are the integers from 1 to N. This allows generation of long list of runs (e.g. 1000) without having to list N strings in the input script.

For the equal and atom styles, a single string is specified which represents an equation that will be evaluated afresh each time the variable is used. For equal style variables this equation computes a scalar quantity, which becomes the value of the variable whenever it is evaluated. For atom style variables it computes a quantity for each atom, which is used by the "compute variable/atom" command and its associated output.

Note that equal and atom variables can produce different values at different stages of the input script or at different times during a run. For example, if an equal variable is used in a fix print command, different values could be printed each timestep it was invoked.

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

The equation for an equal or atom variable can contain a variety of quantities. The syntax for each kind of quantity is simple, but multiple quantities can be nested and combined in various ways to build up formulas of arbitrary complexity. For example, this is a valid (though strange) variable equation:

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

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

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

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

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

Group functions take one or two arguments. The first argument is the group-ID. The dim argument is x or y or z. The dir argument is xmin, xmax, ymin, ymax, zmin, or zmax. The group functions mass() and charge() are the total mass and charge of the group of atoms. Xcm() and vcm() return components of the position and velocity of the center of mass of the group. Fcm() returns a component of the total force on the group of atoms. Bound() returns the min/max of a particular coordinate for all atoms in the group. Gyration() computes the radius-of-gyration of the group of atoms. See the fix gyration command for the formula.

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

Compute references access scalar or vector quantities calculated by a compute. The ID in the reference should be replaced by the actual ID of the compute defined elsewhere in the input script. See the compute command for details. Note that per-atom quantities calculated by a compute cannot be accessed this way, but only global scalar or vector quantities. However, there is a compute sum command which sums per-atom quantities into a global scalar or vector which can be accessed by a variable.

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

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

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

The current values of other variables can be accessed by prepending a "v_" to the variable name. This will cause the other variable to be evaulated. Note that if you do something circular like this:

    variable a equal v_b
    variable b equal v_a
    print $a

then LAMMPS will run for a while when the print statement is invoked.

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

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

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

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

By contrast, these lines:

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

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

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

Restrictions:

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

All universe- and uloop-style variables must have the same number of values.

Related commands:

next, jump, include, temper, fix print, print

Default: none