LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

variable command

Syntax:

variable name style args ... 

Examples:

variable x index run1 run2 run3 run4 run5 run6 run7 run8
variable LoopVar loop 20
variable beta equal div(temp,3.0)
variable b1 equal add(x[234],mult(0.5,col))
variable b equal div(xcm(mol1,x),2.0)
variable b equal c_myTemp[0]
variable temp world 300.0 310.0 320.0 330.0
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 values to a variable name so that the variable can be used in subsequent input script commands or its value output during a simulation. The "name" of the variable is an arbitrary string. Each "value" is a string which could be text or numbers, as in the examples above.

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

Variable values can also be accessed for output once or periodically during a simulation by the print command, fix print command, run every command, and the thermo_style command.


As described below, for variable styles index, loop, universe, and uloop, the value assigned to a variable can be incremented via the next command. When there are no more values 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.

When a variable command is encountered for a variable that has already been specified, the command is ignored. This allows an input script with a variable command to be processed multiple times; see the jump or include commands. It also means that the use of the command-line switch -var will override a corresponding variable setting in the input script.

There are two exceptions to this rule. The first is for equal style variables. They are re-defined each time a variable command using an equal-style variable is encountered. Also, if a variable is iterated on to the end of its list via the next command, it is available to be re-defined in a subsequent variable command.


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 can also be set (with a single value) 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 you to generate a long list of runs (e.g. 1000) without having to list N values in your 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 value. This continues until all the variable values 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 you to generate a long list of runs (e.g. 1000) without having to list N values in your input script.


For the equal style, a single string is specified which represents an equation that will be evaluated afresh each time the variable is used. Thus the variable can take on different values at different stages of the input script. For example, if the 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-style variables, since there is only one value.

The equation for an equal-style 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:

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), bound(ID,dir), gyration(ID)
Atom vectors x[N], y[N], z[N], vx[N], vy[N], vz[N], fx[N], fy[N], fz[N]
Compute references c_ID[0], c_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. 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.

The atom vectors take a single integer argument from 1-N, which is the desired atom-ID, e.g. x[243].

Compute references access allow access to scalar or vector quantities calculated by a compute. The ID in the reference should be replaced by the actual ID of the compute that has been defined elsewhere in the input script. See the compute command for details. Note that per-atom quantities calcalated by a compute cannot be accessed this way, but only global scalar or vector quantities.

If c_ID[0] is used as a keyword, then the scalar quantity calculated by the compute is printed. If c_ID[N] is used, then N in the range from 1-M will print a specific component of the vector calculated by the compute.

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-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 500.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.

Related commands:

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

Default: none