diff --git a/doc/fix_wall.html b/doc/fix_wall.html index 620fb89204..fbebcb0b4a 100644 --- a/doc/fix_wall.html +++ b/doc/fix_wall.html @@ -19,39 +19,40 @@

Syntax:

-
fix ID group-ID style keyword values ... 
+
fix ID group-ID style face args ... keyword value ... 
 

Examples:

-
fix wallhi all wall/lj93 xhi 10.0 1.0 1.0 2.5
-fix wallhi all wall/lj126 xhi 23.2 1.0 1.0 2.5 vel 1.0 units box
+
fix wallhi all wall/lj93 xlo -1.0 1.0 1.0 2.5 units box
+fix wallhi all wall/lj93 xhi EDGE 1.0 1.0 2.5
+fix wallhi all wall/lj126 v_wiggle 23.2 1.0 1.0 2.5
 fix zwalls all wall/colloid zlo 0.0 1.0 1.0 0.858 zhi 40.0 1.0 1.0 0.858 
 

Description: @@ -85,6 +86,27 @@ particle and wall no longer interact. The energy of the wall potential is shifted so that the wall-particle interaction energy is 0.0 at the cutoff distance.

+

Up to 6 walls or faces can be specified in a single command: xlo, +xhi, ylo, yhi, zlo, zhi. A lo face interacts with +particles near the lower side of the simulation box in that dimension. +A hi face interacts with particles near the upper side of the +simulation box in that dimension. +

+

The position of each wall can be specified in one of 3 ways: as the +EDGE of the simulation box, as a constant value, or as a variable. If +EDGE is used, then the corresponding boundary of the current +simulation box is used. If a numeric constant is specified then the +wall is placed at that position in the appropriate dimension (x, y, or +z). In both the EDGE and constant cases, the wall will never move. +If the wall position is a variable, it should be specified as v_name, +where name is an equal-style variable name. In this +case the variable is evaluated each timestep and the result becomes +the current position of the reflecting wall. Equal-style variables +can specify formulas with various mathematical functions, and include +thermo_style command keywords for the simulation +box parameters and timestep and elapsed time. Thus it is easy to +specify a time-dependent wall position. See examples below. +

For the wall/lj93 and wall/lj126 styles, epsilon and sigma are the usual Lennard-Jones parameters, which determine the strength and size of the particle as it interacts with the wall. Epsilon has @@ -129,56 +151,55 @@ potential and does not blow up as r -> 0, but you must use a large enough epsilon that particles always reamin on the correct side of the wall (r > 0).

-

If the vel keyword is specified, the position of all walls will move -during the simulation in a perpendicular direction, based on their -initial coord position, the specified velocity vel, and the time -elapsed since the fix was specified. A positive velocity means each -wall moves inward, towards the center of the box. I.e. an xlo wall -will move in the +x direction and an xhi wall will move in the -x -direction. A negative velocity means each wall moves outward, away -from the center of the box. If you want different walls to move with -different velocities, then you need to use multiple fix wall commands. -

-

If the wiggle/sin keyword is specified, the position of all walls -will oscillate sinusoidally during the simulation in the perpendicular -direction, according to the equation: -

-
position = coord + A sin(omega*delta) 
-
-

If the wiggle/cos keyword is specified, the position of all walls -will oscillate sinusoidally during the simulation in the perpendicular -direction, according to the equation: -

-
position = coord + A (1 - cos(omega*delta)) 
-
-

In both cases, coord is the specified initial position of the wall, -A is the amplitude, omega is 2 PI / period, and delta is the -time elapsed since the fix was specified. A positive amplitude means -each wall initially moves inward, towards the center of the box. -I.e. an xlo wall will move initially in the +x direction and an -xhi wall will move initially in the -x direction. A negative -velocity means each wall moves initially outward, away from the center -of the box. Note that the wiggle/sin option oscillates with -amplitude A around the pos0 position and the velocity of the wall is -a maximum at time 0. By contrast, for the wiggle/cos option the -wall moves up to 2A away from pos0 in one direction and the velocity -of the wall is 0 at time 0. If you want different walls to oscillate -with different amplitudes or periods, then you need to use multiple -fix wall commands. -

The units keyword determines the meaning of the distance units used -to define the position of the wall and its velocity and wiggle -amplitude. A box value selects standard distance units as defined -by the units command, e.g. Angstroms for units = real or -metal. A lattice value means the distance units are in lattice -spacings. The lattice command must have been -previously used to define the lattice spacing. Note that with the -lattice option, the wall's position is specified in lattice -spacings, the wall's velocity is specified in lattice spacings per -time, and the wall's oscillation amplitude is specified in lattice -spacings. Each of these 3 quantities may be dependent on the x,y,z -dimension, since the lattice spacings can be different in x,y,z. +to define a wall position, but only when a numeric constant is used. +It is not relevant when EDGE or a variable is used to specify a face +position.

+

A box value selects standard distance units as defined by the +units command, e.g. Angstroms for units = real or metal. +A lattice value means the distance units are in lattice spacings. +The lattice command must have been previously used to +define the lattice spacings. +

+
+ +

Here are examples of variable definitions that move the wall position +in a time-dependent fashion using equal-style +variables. +

+
variable ramp equal ramp(0,10)
+fix 1 all wall xlo v_ramp 1.0 1.0 2.5 
+
+
variable linear equal vlinear(0,20)
+fix 1 all wall xlo v_linear 1.0 1.0 2.5 
+
+
variable wiggle equal swiggle(0.0,5.0,3.0)
+fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 
+
+
variable wiggle equal cwiggle(0.0,5.0,3.0)
+fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 
+
+

The ramp(lo,hi) function adjusts the wall position linearly from lo to +hi over the course of a run. The linear(c0,velocity) function does +something similar using the equation position = c0 + velocity*delta, +where delta is the elapsed time. +

+

The swiggle(c0,A,period) function causes the wall position to +oscillate sinusoidally according to this equation, where omega = 2 PI +/ period: +

+
position = c0 + A sin(omega*delta) 
+
+

The cwiggle(c0,A,period) function causes the wall position to +oscillate sinusoidally according to this equation, which will have an +initial wall velocity of 0.0, and thus may impose a gentler +perturbation on the particles: +

+
position = c0 + A (1 - cos(omega*delta)) 
+
+
+

Restart, fix_modify, output, run start/stop, minimize info:

No information about this fix is written to binary restart diff --git a/doc/fix_wall.txt b/doc/fix_wall.txt index 8bd6a118bf..0960c14bbb 100644 --- a/doc/fix_wall.txt +++ b/doc/fix_wall.txt @@ -13,34 +13,32 @@ fix wall/harmonic command :h3 [Syntax:] -fix ID group-ID style keyword values ... :pre +fix ID group-ID style face args ... keyword value ... :pre ID, group-ID are documented in "fix"_fix.html command :ulb,l style = {wall/lj93} or {wall/lj126} or {wall/colloid} or {wall/harmonic} :l -one or more keyword/value pairs may be appended :l -keyword = {xlo} or {xhi} or {ylo} or {yhi} or {zlo} or {zhi} or {vel} or {wiggle/sin} or {wiggle/cos} or {units} :l - {xlo}, {xhi}, {ylo}, {yhi}, {zlo}, {zhi} values = coord epsilon sigma cutoff - coord = position of wall (distance units) +one or more face/arg pairs may be appended :l +face = {xlo} or {xhi} or {ylo} or {yhi} or {zlo} or {zhi} :l + args = coord epsilon sigma cutoff + coord = position of wall = EDGE or constant or variable + EDGE = current lo or hi edge of simulation box + constant = number like 0.0 or -30.0 (distance units) + variable = "equal-style variable"_variable.html like v_x or v_wiggle epsilon = strength factor for wall-particle interaction (energy or energy/distance^2 units) sigma = size factor for wall-particle interaction (distance units) - cutoff = distance from wall at which wall-particle interaction is cut off (distance units) - {vel} value = v - v = velocity of wall in perpendicular direction (velocity units) - {wiggle/sin} values = amplitude period - amplitude = size of oscillation (distance units) - period = time of oscillation (time units) - {wiggle/cos} values = amplitude period - amplitude = size of oscillation (distance units) - period = time of oscillation (time units) + cutoff = distance from wall at which wall-particle interaction is cut off (distance units) :pre +zero or more keyword/value pairs may be appended :l +keyword = {units} :l {units} value = {lattice} or {box} - lattice = the wall is defined in lattice units - box = the wall is defined in simulation box units :pre + {lattice} = the wall position is defined in lattice units + {box} = the wall position is defined in simulation box units :pre :ule [Examples:] -fix wallhi all wall/lj93 xhi 10.0 1.0 1.0 2.5 -fix wallhi all wall/lj126 xhi 23.2 1.0 1.0 2.5 vel 1.0 units box +fix wallhi all wall/lj93 xlo -1.0 1.0 1.0 2.5 units box +fix wallhi all wall/lj93 xhi EDGE 1.0 1.0 2.5 +fix wallhi all wall/lj126 v_wiggle 23.2 1.0 1.0 2.5 fix zwalls all wall/colloid zlo 0.0 1.0 1.0 0.858 zhi 40.0 1.0 1.0 0.858 :pre [Description:] @@ -74,6 +72,27 @@ particle and wall no longer interact. The energy of the wall potential is shifted so that the wall-particle interaction energy is 0.0 at the cutoff distance. +Up to 6 walls or faces can be specified in a single command: {xlo}, +{xhi}, {ylo}, {yhi}, {zlo}, {zhi}. A {lo} face interacts with +particles near the lower side of the simulation box in that dimension. +A {hi} face interacts with particles near the upper side of the +simulation box in that dimension. + +The position of each wall can be specified in one of 3 ways: as the +EDGE of the simulation box, as a constant value, or as a variable. If +EDGE is used, then the corresponding boundary of the current +simulation box is used. If a numeric constant is specified then the +wall is placed at that position in the appropriate dimension (x, y, or +z). In both the EDGE and constant cases, the wall will never move. +If the wall position is a variable, it should be specified as v_name, +where name is an "equal-style variable"_variable.html name. In this +case the variable is evaluated each timestep and the result becomes +the current position of the reflecting wall. Equal-style variables +can specify formulas with various mathematical functions, and include +"thermo_style"_thermo_style.html command keywords for the simulation +box parameters and timestep and elapsed time. Thus it is easy to +specify a time-dependent wall position. See examples below. + For the {wall/lj93} and {wall/lj126} styles, {epsilon} and {sigma} are the usual Lennard-Jones parameters, which determine the strength and size of the particle as it interacts with the wall. Epsilon has @@ -118,55 +137,54 @@ potential and does not blow up as r -> 0, but you must use a large enough {epsilon} that particles always reamin on the correct side of the wall (r > 0). -If the {vel} keyword is specified, the position of all walls will move -during the simulation in a perpendicular direction, based on their -initial {coord} position, the specified velocity {vel}, and the time -elapsed since the fix was specified. A positive velocity means each -wall moves inward, towards the center of the box. I.e. an {xlo} wall -will move in the +x direction and an {xhi} wall will move in the -x -direction. A negative velocity means each wall moves outward, away -from the center of the box. If you want different walls to move with -different velocities, then you need to use multiple fix wall commands. - -If the {wiggle/sin} keyword is specified, the position of all walls -will oscillate sinusoidally during the simulation in the perpendicular -direction, according to the equation: - -position = coord + A sin(omega*delta) :pre - -If the {wiggle/cos} keyword is specified, the position of all walls -will oscillate sinusoidally during the simulation in the perpendicular -direction, according to the equation: - -position = coord + A (1 - cos(omega*delta)) :pre - -In both cases, {coord} is the specified initial position of the wall, -{A} is the {amplitude}, {omega} is 2 PI / {period}, and {delta} is the -time elapsed since the fix was specified. A positive amplitude means -each wall initially moves inward, towards the center of the box. -I.e. an {xlo} wall will move initially in the +x direction and an -{xhi} wall will move initially in the -x direction. A negative -velocity means each wall moves initially outward, away from the center -of the box. Note that the {wiggle/sin} option oscillates with -amplitude {A} around the pos0 position and the velocity of the wall is -a maximum at time 0. By contrast, for the {wiggle/cos} option the -wall moves up to {2A} away from pos0 in one direction and the velocity -of the wall is 0 at time 0. If you want different walls to oscillate -with different amplitudes or periods, then you need to use multiple -fix wall commands. - The {units} keyword determines the meaning of the distance units used -to define the position of the wall and its velocity and wiggle -amplitude. A {box} value selects standard distance units as defined -by the "units"_units.html command, e.g. Angstroms for units = real or -metal. A {lattice} value means the distance units are in lattice -spacings. The "lattice"_lattice.html command must have been -previously used to define the lattice spacing. Note that with the -{lattice} option, the wall's position is specified in lattice -spacings, the wall's velocity is specified in lattice spacings per -time, and the wall's oscillation amplitude is specified in lattice -spacings. Each of these 3 quantities may be dependent on the x,y,z -dimension, since the lattice spacings can be different in x,y,z. +to define a wall position, but only when a numeric constant is used. +It is not relevant when EDGE or a variable is used to specify a face +position. + +A {box} value selects standard distance units as defined by the +"units"_units.html command, e.g. Angstroms for units = real or metal. +A {lattice} value means the distance units are in lattice spacings. +The "lattice"_lattice.html command must have been previously used to +define the lattice spacings. + +:line + +Here are examples of variable definitions that move the wall position +in a time-dependent fashion using equal-style +"variables"_variable.html. + +variable ramp equal ramp(0,10) +fix 1 all wall xlo v_ramp 1.0 1.0 2.5 :pre + +variable linear equal vlinear(0,20) +fix 1 all wall xlo v_linear 1.0 1.0 2.5 :pre + +variable wiggle equal swiggle(0.0,5.0,3.0) +fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 :pre + +variable wiggle equal cwiggle(0.0,5.0,3.0) +fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 :pre + +The ramp(lo,hi) function adjusts the wall position linearly from lo to +hi over the course of a run. The linear(c0,velocity) function does +something similar using the equation position = c0 + velocity*delta, +where delta is the elapsed time. + +The swiggle(c0,A,period) function causes the wall position to +oscillate sinusoidally according to this equation, where omega = 2 PI +/ period: + +position = c0 + A sin(omega*delta) :pre + +The cwiggle(c0,A,period) function causes the wall position to +oscillate sinusoidally according to this equation, which will have an +initial wall velocity of 0.0, and thus may impose a gentler +perturbation on the particles: + +position = c0 + A (1 - cos(omega*delta)) :pre + +:line [Restart, fix_modify, output, run start/stop, minimize info:] diff --git a/doc/fix_wall_reflect.html b/doc/fix_wall_reflect.html index f146402b3a..02775a9f1e 100644 --- a/doc/fix_wall_reflect.html +++ b/doc/fix_wall_reflect.html @@ -32,13 +32,13 @@ constant = number like 50.0 or 100.3 (distance units) variable = equal-style variable like v_x or v_wiggle

-
  • zero or more keyword/avlue pairs may be appended +
  • zero or more keyword/value pairs may be appended
  • keyword = units
      units value = lattice or box
    -    lattice = the geometry is defined in lattice units
    -    box = the geometry is defined in simulation box units 
    +    lattice = the wall position is defined in lattice units
    +    box = the wall position is defined in simulation box units 
     
    @@ -68,17 +68,17 @@ velocity-Verlet integration without reflective walls.

    Up to 6 walls or faces can be specified in a single command: xlo, xhi, ylo, yhi, zlo, zhi. A lo face reflects particles -that move to a coordinate less than the face position, back in the +that move to a coordinate less than the wall position, back in the hi direction. A hi face reflects particles that move to a -coordinate higher than the face position, back in the lo direction. +coordinate higher than the wall position, back in the lo direction.

    -

    The position of each face can be specified in one of 3 ways: as the +

    The position of each wall can be specified in one of 3 ways: as the EDGE of the simulation box, as a constant value, or as a variable. If EDGE is used, then the corresponding boundary of the current simulation box is used. If a numeric constant is specified then the wall is placed at that position in the appropriate dimension (x, y, or z). In both the EDGE and constant cases, the wall will never move. -If the face position is a variable, it should be specified as v_name, +If the wall position is a variable, it should be specified as v_name, where name is an equal-style variable name. In this case the variable is evaluated each timestep and the result becomes the current position of the reflecting wall. Equal-style variables @@ -88,7 +88,7 @@ box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent wall position.

    The units keyword determines the meaning of the distance units used -to define a face position, but only when a numeric constant is used. +to define a wall position, but only when a numeric constant is used. It is not relevant when EDGE or a variable is used to specify a face position.

    @@ -100,6 +100,42 @@ define the lattice spacings.


    +

    Here are examples of variable definitions that move the wall position +in a time-dependent fashion using equal-style +variables. +

    +
    variable ramp equal ramp(0,10)
    +fix 1 all wall xlo v_ramp 1.0 1.0 2.5 
    +
    +
    variable linear equal vlinear(0,20)
    +fix 1 all wall xlo v_linear 1.0 1.0 2.5 
    +
    +
    variable wiggle equal swiggle(0.0,5.0,3.0)
    +fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 
    +
    +
    variable wiggle equal cwiggle(0.0,5.0,3.0)
    +fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 
    +
    +

    The ramp(lo,hi) function adjusts the wall position linearly from lo to +hi over the course of a run. The linear(c0,velocity) function does +something similar using the equation position = c0 + velocity*delta, +where delta is the elapsed time. +

    +

    The swiggle(c0,A,period) function causes the wall position to +oscillate sinusoidally according to this equation, where omega = 2 PI +/ period: +

    +
    position = c0 + A sin(omega*delta) 
    +
    +

    The cwiggle(c0,A,period) function causes the wall position to +oscillate sinusoidally according to this equation, which will have an +initial wall velocity of 0.0, and thus may impose a gentler +perturbation on the particles: +

    +
    position = c0 + A (1 - cos(omega*delta)) 
    +
    +
    +

    Restart, fix_modify, output, run start/stop, minimize info:

    No information about this fix is written to binary restart diff --git a/doc/fix_wall_reflect.txt b/doc/fix_wall_reflect.txt index e58e17ec1b..05e6faf907 100644 --- a/doc/fix_wall_reflect.txt +++ b/doc/fix_wall_reflect.txt @@ -24,11 +24,11 @@ face = {xlo} or {xhi} or {ylo} or {yhi} or {zlo} or {zhi} :l EDGE = current hi edge of simulation box constant = number like 50.0 or 100.3 (distance units) variable = "equal-style variable"_variable.html like v_x or v_wiggle :pre -zero or more keyword/avlue pairs may be appended :l +zero or more keyword/value pairs may be appended :l keyword = {units} :l {units} value = {lattice} or {box} - {lattice} = the geometry is defined in lattice units - {box} = the geometry is defined in simulation box units :pre + {lattice} = the wall position is defined in lattice units + {box} = the wall position is defined in simulation box units :pre :ule [Examples:] @@ -57,17 +57,17 @@ velocity-Verlet integration without reflective walls. Up to 6 walls or faces can be specified in a single command: {xlo}, {xhi}, {ylo}, {yhi}, {zlo}, {zhi}. A {lo} face reflects particles -that move to a coordinate less than the face position, back in the +that move to a coordinate less than the wall position, back in the {hi} direction. A {hi} face reflects particles that move to a -coordinate higher than the face position, back in the {lo} direction. +coordinate higher than the wall position, back in the {lo} direction. -The position of each face can be specified in one of 3 ways: as the +The position of each wall can be specified in one of 3 ways: as the EDGE of the simulation box, as a constant value, or as a variable. If EDGE is used, then the corresponding boundary of the current simulation box is used. If a numeric constant is specified then the wall is placed at that position in the appropriate dimension (x, y, or z). In both the EDGE and constant cases, the wall will never move. -If the face position is a variable, it should be specified as v_name, +If the wall position is a variable, it should be specified as v_name, where name is an "equal-style variable"_variable.html name. In this case the variable is evaluated each timestep and the result becomes the current position of the reflecting wall. Equal-style variables @@ -77,7 +77,7 @@ box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent wall position. The {units} keyword determines the meaning of the distance units used -to define a face position, but only when a numeric constant is used. +to define a wall position, but only when a numeric constant is used. It is not relevant when EDGE or a variable is used to specify a face position. @@ -89,6 +89,42 @@ define the lattice spacings. :line +Here are examples of variable definitions that move the wall position +in a time-dependent fashion using equal-style +"variables"_variable.html. + +variable ramp equal ramp(0,10) +fix 1 all wall xlo v_ramp 1.0 1.0 2.5 :pre + +variable linear equal vlinear(0,20) +fix 1 all wall xlo v_linear 1.0 1.0 2.5 :pre + +variable wiggle equal swiggle(0.0,5.0,3.0) +fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 :pre + +variable wiggle equal cwiggle(0.0,5.0,3.0) +fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 :pre + +The ramp(lo,hi) function adjusts the wall position linearly from lo to +hi over the course of a run. The linear(c0,velocity) function does +something similar using the equation position = c0 + velocity*delta, +where delta is the elapsed time. + +The swiggle(c0,A,period) function causes the wall position to +oscillate sinusoidally according to this equation, where omega = 2 PI +/ period: + +position = c0 + A sin(omega*delta) :pre + +The cwiggle(c0,A,period) function causes the wall position to +oscillate sinusoidally according to this equation, which will have an +initial wall velocity of 0.0, and thus may impose a gentler +perturbation on the particles: + +position = c0 + A (1 - cos(omega*delta)) :pre + +:line + [Restart, fix_modify, output, run start/stop, minimize info:] No information about this fix is written to "binary restart diff --git a/doc/variable.html b/doc/variable.html index 18d880fadd..94dc5dc50f 100644 --- a/doc/variable.html +++ b/doc/variable.html @@ -41,12 +41,14 @@ string arg = one string equal or atom 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 + constants = PI thermo keywords = vol, ke, press, etc from thermo_style math operators = (), -x, x+y, x-y, x*y, x/y, x^y, x==y, x!=y, xy, x>=y, x&&y, x||y math functions = sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), - random(lo,hi,seed), normal(mu,sigma,seed), ceil(x), floor(x), round(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), vlinear(x,y), swiggle(x,y,z), cwiggle(x,y,z) group functions = count(group), mass(group), charge(group), xcm(group,dim), vcm(group,dim), fcm(group,dim), bound(group,xmin), gyration(group), ke(group), @@ -55,7 +57,7 @@ xcm(group,dim,region), vcm(group,dim,region), fcm(group,dim,region), bound(group,xmin,region), gyration(group,region), ke(group,reigon), angmom(group,dim,region), inertia(group,dimdim,region),omega(group,dim,region) - special functions = ramp(x,y), stagger(x,y), logfreq(x,y,z), sum(x), min(x), max(x), ave(x), trap(x) + special functions = sum(x), min(x), max(x), ave(x), trap(x) atom value = mass[i], type[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i] atom vector = mass, type, x, y, z, vx, vy, vz, fx, fy, fz compute references = c_ID, c_ID[i], c_ID[i][j] @@ -268,12 +270,13 @@ references to other variables.

    + - + - + @@ -312,6 +315,8 @@ discussion below about "Variable Accuracy".


    +

    Math Operators +

    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 @@ -344,8 +349,12 @@ whose properties satifsy one or more criteria could be calculated by taking the returned per-atom vector of ones and zeroes and passing it to the compute reduce command.

    +
    + +

    Math Functions +

    Math functions are specified as keywords followed by one or more -parenthesized arguments "x", "y", etc, each of which can themselves be +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-atom vectors. In the latter case, the math operation is performed on each element of the vector. For @@ -356,31 +365,95 @@ product of one atom's y and z coordinates.

    Most of the math functions perform obvious operations. The ln() is the natural log; log() is the base 10 log.

    -

    The random() function generates a uniform random number between lo and -hi. The normal() function generates a Gaussian variate centered on mu -with variance sigma^2. In both cases the seed is used the first time -the internal random number generator is invoked, to initialize it. -For equal-style variables, every processor uses the same seed so that -they each generate the same sequence of random numbers. For -atom-style variables, a unique seed is created for each processor, -based on the specified seed. This effectively generates a different -random number for each atom being looped over in the atom-style -variable. +

    The random(x,y,z) function takes 3 arguments: x = lo, y = hi, and z = +seed. It generates a uniform random number between lo and hi. The +normal(x,y,z) function also takes 3 arguments: x = mu, y = sigma, and +z = seed. It generates a Gaussian variate centered on mu with +variance sigma^2. In both cases the seed is used the first time the +internal random number generator is invoked, to initialize it. For +equal-style variables, every processor uses the same seed so that they +each generate the same sequence of random numbers. For atom-style +variables, a unique seed is created for each processor, based on the +specified seed. This effectively generates a different random number +for each atom being looped over in the atom-style variable. +

    +

    IMPORTANT NOTE: Internally, there is just one random number generator +for all equal-style variables and one for all atom-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, which means only one of the +specified seeds will determine the sequence of generated random +numbers.

    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.

    -

    IMPORTANT NOTE: Internally, there is just one random number generator -for equal-style variables and one for atom-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, which means only one of the specified -seeds will determine the sequence of generated random numbers. +

    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: +

    +
    value = x + (y-x) * (timestep-startstep) / (stopstep-startstep) 
    +
    +

    The run begins on startstep and ends on stopstep. Startstep and +stopstep can span multiple runs, using the start and stop keywords +of the run command. See the run command for +details of how to do this. +

    +

    The stagger(x,y) function uses the current timestep to generate a new +timestep. X,y > 0 and x > y is required. The generated timesteps +increase in a staggered fashion, as the sequence +x,x+y,2x,2x+y,3x,3x+y,etc. For any current timestep, the next +timestep in the sequence is returned. Thus if stagger(1000,100) is +used in a variable by the dump_modify every +command, it will generate the sequence of output timesteps: +

    +
    100,1000,1100,2000,2100,3000,etc 
    +
    +

    The logfreq(x,y,z) function uses the current timestep to generate a +new timestep. X,y,z > 0 and y < z is required. The generated +timesteps increase in a logarithmic fashion, as the sequence +x,2x,3x,...y*x,z*x,2*z*x,3*z*x,...y*z*x,z*z*x,2*z*x*x,etc. For any +current timestep, the next timestep in the sequence is returned. Thus +if logfreq(100,4,10) is used in a variable by the dump_modify +every command, it will generate the sequence of +output timesteps: +

    +
    100,200,300,400,1000,2000,3000,4000,10000,20000,etc 
    +
    +

    The vlinear(x,y) function takes 2 arguments: x = coord0 and y = +velocity, and uses the elapsed time to change the coordinate value by +a linear displacement due to the applied velocity over the course of a +run, according to this formula: +

    +
    value = coord0 + velocity*(timestep-startstep)*dt 
    +
    +

    where dt = the timestep size. +

    +

    The run begins on startstep. Startstep can span multiple runs, using +the start keyword of the run command. See the +run command for details of how to do this. +

    +

    The swiggle(x,y,z) and cwiggle(x,y,z) functions each take 3 arguments: +x = coord0, y = amplitude, z = period. They use the elapsed time to +oscillate the coordinate value by a sin() or cos() function over the +course of a run, according to one of these formulas, where +omega = 2 PI / period: +

    +
    value = coord0 + Amplitude * sin(omega*(timestep-startstep)*dt)
    +value = coord0 + Amplitude * (1 - cos(omega*(timestep-startstep)*dt)) 
    +
    +

    where dt = the timestep size. +

    +

    The run begins on startstep. Startstep can span multiple runs, using +the start keyword of the run command. See the +run command for details of how to do this.


    +

    Group and Region Functions +

    Group functions are specified as keywords followed by one or two parenthesized arguments. The first argument is the group-ID. The dim argument, if it exists, is x or y or z. The dir @@ -410,42 +483,11 @@ inclusion is that it be in the region.


    +

    Special Functions +

    Special functions take specific kinds of arguments, meaning their -arguments cannot be formulas themselves. For example ramp(10.0,100.0) -is valid, but ramp(2*5,sqrt(10000)) is not. +arguments cannot be formulas themselves.

    -

    Ramp(x,y) takes two integer or floating point values and uses the -current timestep to generate a scalar value: -

    -
    value = x + (y-x) * (timestep-startstep) / (stopstep-startstep) 
    -
    -

    which is a value that ramps linearly between x and y over the course of -a run. The run begins on startstep and ends on stopstep. Startstep -and stopstep can span multiple runs, using the start and stop -keywords of the run command. See the run -command for details of how to do this. -

    -

    Stagger(x,y) takes two integer values and uses the current timestep to -generate a new timestep. X,y > 0 and x > y is required. The -generated timesteps increase in a staggered fashion, as the sequence -x,x+y,2x,2x+y,3x,3x+y,etc. For any current timestep, the next -timestep in the sequence is returned. Thus if stagger(1000,100) is -used in a variable by the dump_modify every -command, it will generate the sequence of output timesteps: -

    -
    100,1000,1100,2000,2100,3000,etc 
    -
    -

    Logfreq(x,y,z) takes 3 integer values and uses the current timestep to -generate a new timestep. X,y,z > 0 and y < z is required. The -generated timesteps increase in a logarithmic fashion, as the sequence -x,2x,3x,...y*x,z*x,2*z*x,3*z*x,...y*z*x,z*z*x,2*z*x*x,etc. For any -current timestep, the next timestep in the sequence is returned. Thus -if logfreq(100,4,10) is used in a variable by the dump_modify -every command, it will generate the sequence of -output timesteps: -

    -
    100,200,300,400,1000,2000,3000,4000,10000,20000,etc 
    -

    The sum(x), min(x), max(x), ave(x), and trap(x) functions each take 1 argument which is of the form "c_ID" or "c_ID[N]" or "f_ID" or "f_ID[N]". The first two are computes and the second two are fixes; @@ -479,6 +521,8 @@ ave/correlate command.


    +

    Atom Values and Vectors +

    Atom values take a single integer argument I from 1 to N, where I is the an atom-ID, e.g. x[243], which means use the x coordinate of the atom with ID = 243. @@ -492,6 +536,8 @@ a quantity from that compute.


    +

    Compute References +

    Compute references access quantities calculated by a compute. The ID in the reference should be replaced by the ID of a compute defined elsewhere in the input script. As @@ -523,6 +569,8 @@ about "Variable Accuracy".


    +

    Fix References +

    Fix references access quantities calculated by a fix. 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 @@ -559,6 +607,8 @@ the doc pages for individual fix commands for details.


    +

    Variable References +

    Variable references access quantities calulated by other variables, which will cause those variables to be evaluated. The name in the reference should be replaced by the name of a variable defined diff --git a/doc/variable.txt b/doc/variable.txt index af5d5df062..691d849457 100644 --- a/doc/variable.txt +++ b/doc/variable.txt @@ -36,12 +36,14 @@ style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {st {string} arg = one string {equal} or {atom} 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 + constants = PI thermo keywords = vol, ke, press, etc from "thermo_style"_thermo_style.html math operators = (), -x, x+y, x-y, x*y, x/y, x^y, x==y, x!=y, xy, x>=y, x&&y, x||y math functions = sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), - random(lo,hi,seed), normal(mu,sigma,seed), ceil(x), floor(x), round(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), vlinear(x,y), swiggle(x,y,z), cwiggle(x,y,z) group functions = count(group), mass(group), charge(group), xcm(group,dim), vcm(group,dim), fcm(group,dim), bound(group,xmin), gyration(group), ke(group), @@ -50,7 +52,7 @@ style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {st xcm(group,dim,region), vcm(group,dim,region), fcm(group,dim,region), bound(group,xmin,region), gyration(group,region), ke(group,reigon), angmom(group,dim,region), inertia(group,dimdim,region),omega(group,dim,region) - special functions = ramp(x,y), stagger(x,y), logfreq(x,y,z), sum(x), min(x), max(x), ave(x), trap(x) + special functions = sum(x), min(x), max(x), ave(x), trap(x) atom value = mass\[i\], type\[i\], x\[i\], y\[i\], z\[i\], vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\] atom vector = mass, type, x, y, z, vx, vy, vz, fx, fy, fz compute references = c_ID, c_ID\[i\], c_ID\[i\]\[j\] @@ -261,9 +263,10 @@ values, atom vectors, compute references, fix references, and references to other variables. Number: 0.2, 100, 1.0e20, -15.4, etc +Constant: PI Thermo keywords: vol, pe, ebond, etc Math operators: (), -x, x+y, x-y, x*y, x/y, x^y, x==y, x!=y, xy, x>=y, x&&y, x||y -Math functions: sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(lo,hi,seed), normal(mu,sigma,seed), ceil(x), floor(x), round(x) +Math functions: sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z), vlinear(x,y), swiggle(x,y,z), cwiggle(x,y,z) Group functions: count(ID), mass(ID), charge(ID), xcm(ID,dim), \ vcm(ID,dim), fcm(ID,dim), bound(ID,dir), \ gyration(ID), ke(ID), angmom(ID,dim), \ @@ -272,8 +275,7 @@ Region functions: count(ID,IDR), mass(ID,IDR), charge(ID,IDR), \ xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), \ bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), \ angmom(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR) -Special functions: ramp(x,y), stagger(x,y), logfreq(x,y,z), \ - sum(x), min(x), max(x), ave(x), trap(x) +Special functions: sum(x), min(x), max(x), ave(x), trap(x) Atom values: mass\[i\], type\[i\], x\[i\], y\[i\], z\[i\], \ vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\] Atom vectors: mass, type, x, y, z, vx, vy, vz, fx, fy, fz @@ -312,6 +314,8 @@ discussion below about "Variable Accuracy". :line +Math Operators :h4 + 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 @@ -344,8 +348,12 @@ whose properties satifsy one or more criteria could be calculated by taking the returned per-atom vector of ones and zeroes and passing it to the "compute reduce"_compute_reduce.html command. +:line + +Math Functions :h4 + Math functions are specified as keywords followed by one or more -parenthesized arguments "x", "y", etc, each of which can themselves be +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-atom vectors. In the latter case, the math operation is performed on each element of the vector. For @@ -356,31 +364,95 @@ product of one atom's y and z coordinates. Most of the math functions perform obvious operations. The ln() is the natural log; log() is the base 10 log. -The random() function generates a uniform random number between lo and -hi. The normal() function generates a Gaussian variate centered on mu -with variance sigma^2. In both cases the seed is used the first time -the internal random number generator is invoked, to initialize it. -For equal-style variables, every processor uses the same seed so that -they each generate the same sequence of random numbers. For -atom-style variables, a unique seed is created for each processor, -based on the specified seed. This effectively generates a different -random number for each atom being looped over in the atom-style -variable. +The random(x,y,z) function takes 3 arguments: x = lo, y = hi, and z = +seed. It generates a uniform random number between lo and hi. The +normal(x,y,z) function also takes 3 arguments: x = mu, y = sigma, and +z = seed. It generates a Gaussian variate centered on mu with +variance sigma^2. In both cases the seed is used the first time the +internal random number generator is invoked, to initialize it. For +equal-style variables, every processor uses the same seed so that they +each generate the same sequence of random numbers. For atom-style +variables, a unique seed is created for each processor, based on the +specified seed. This effectively generates a different random number +for each atom being looped over in the atom-style variable. + +IMPORTANT NOTE: Internally, there is just one random number generator +for all equal-style variables and one for all atom-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, which means only one of the +specified seeds will determine the sequence of generated random +numbers. 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. -IMPORTANT NOTE: Internally, there is just one random number generator -for equal-style variables and one for atom-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, which means only one of the specified -seeds will determine the sequence of generated random numbers. +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: + +value = x + (y-x) * (timestep-startstep) / (stopstep-startstep) :pre + +The run begins on startstep and ends on stopstep. Startstep and +stopstep can span multiple runs, using the {start} and {stop} keywords +of the "run"_run.html command. See the "run"_run.html command for +details of how to do this. + +The stagger(x,y) function uses the current timestep to generate a new +timestep. X,y > 0 and x > y is required. The generated timesteps +increase in a staggered fashion, as the sequence +x,x+y,2x,2x+y,3x,3x+y,etc. For any current timestep, the next +timestep in the sequence is returned. Thus if stagger(1000,100) is +used in a variable by the "dump_modify every"_dump_modify.html +command, it will generate the sequence of output timesteps: + +100,1000,1100,2000,2100,3000,etc :pre + +The logfreq(x,y,z) function uses the current timestep to generate a +new timestep. X,y,z > 0 and y < z is required. The generated +timesteps increase in a logarithmic fashion, as the sequence +x,2x,3x,...y*x,z*x,2*z*x,3*z*x,...y*z*x,z*z*x,2*z*x*x,etc. For any +current timestep, the next timestep in the sequence is returned. Thus +if logfreq(100,4,10) is used in a variable by the "dump_modify +every"_dump_modify.html command, it will generate the sequence of +output timesteps: + +100,200,300,400,1000,2000,3000,4000,10000,20000,etc :pre + +The vlinear(x,y) function takes 2 arguments: x = coord0 and y = +velocity, and uses the elapsed time to change the coordinate value by +a linear displacement due to the applied velocity over the course of a +run, according to this formula: + +value = coord0 + velocity*(timestep-startstep)*dt :pre + +where dt = the timestep size. + +The run begins on startstep. Startstep can span multiple runs, using +the {start} keyword of the "run"_run.html command. See the +"run"_run.html command for details of how to do this. + +The swiggle(x,y,z) and cwiggle(x,y,z) functions each take 3 arguments: +x = coord0, y = amplitude, z = period. They use the elapsed time to +oscillate the coordinate value by a sin() or cos() function over the +course of a run, according to one of these formulas, where +omega = 2 PI / period: + +value = coord0 + Amplitude * sin(omega*(timestep-startstep)*dt) +value = coord0 + Amplitude * (1 - cos(omega*(timestep-startstep)*dt)) :pre + +where dt = the timestep size. + +The run begins on startstep. Startstep can span multiple runs, using +the {start} keyword of the "run"_run.html command. See the +"run"_run.html command for details of how to do this. :line +Group and Region Functions :h4 + Group functions are specified as keywords followed by one or two parenthesized arguments. The first argument is the group-ID. The {dim} argument, if it exists, is {x} or {y} or {z}. The {dir} @@ -410,41 +482,10 @@ inclusion is that it be in the region. :line +Special Functions :h4 + Special functions take specific kinds of arguments, meaning their -arguments cannot be formulas themselves. For example ramp(10.0,100.0) -is valid, but ramp(2*5,sqrt(10000)) is not. - -Ramp(x,y) takes two integer or floating point values and uses the -current timestep to generate a scalar value: - -value = x + (y-x) * (timestep-startstep) / (stopstep-startstep) :pre - -which is a value that ramps linearly between x and y over the course of -a run. The run begins on startstep and ends on stopstep. Startstep -and stopstep can span multiple runs, using the {start} and {stop} -keywords of the "run"_run.html command. See the "run"_run.html -command for details of how to do this. - -Stagger(x,y) takes two integer values and uses the current timestep to -generate a new timestep. X,y > 0 and x > y is required. The -generated timesteps increase in a staggered fashion, as the sequence -x,x+y,2x,2x+y,3x,3x+y,etc. For any current timestep, the next -timestep in the sequence is returned. Thus if stagger(1000,100) is -used in a variable by the "dump_modify every"_dump_modify.html -command, it will generate the sequence of output timesteps: - -100,1000,1100,2000,2100,3000,etc :pre - -Logfreq(x,y,z) takes 3 integer values and uses the current timestep to -generate a new timestep. X,y,z > 0 and y < z is required. The -generated timesteps increase in a logarithmic fashion, as the sequence -x,2x,3x,...y*x,z*x,2*z*x,3*z*x,...y*z*x,z*z*x,2*z*x*x,etc. For any -current timestep, the next timestep in the sequence is returned. Thus -if logfreq(100,4,10) is used in a variable by the "dump_modify -every"_dump_modify.html command, it will generate the sequence of -output timesteps: - -100,200,300,400,1000,2000,3000,4000,10000,20000,etc :pre +arguments cannot be formulas themselves. The sum(x), min(x), max(x), ave(x), and trap(x) functions each take 1 argument which is of the form "c_ID" or "c_ID\[N\]" or "f_ID" or @@ -479,6 +520,8 @@ ave/correlate"_fix_ave_correlate.html command. :line +Atom Values and Vectors :h4 + Atom values take a single integer argument I from 1 to N, where I is the an atom-ID, e.g. x\[243\], which means use the x coordinate of the atom with ID = 243. @@ -492,6 +535,8 @@ a quantity from that compute. :line +Compute References :h4 + Compute references access quantities calculated by a "compute"_compute.html. The ID in the reference should be replaced by the ID of a compute defined elsewhere in the input script. As @@ -521,6 +566,8 @@ about "Variable Accuracy". :line +Fix References :h4 + Fix references access quantities calculated by a "fix"_compute.html. 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 @@ -555,6 +602,8 @@ the doc pages for individual fix commands for details. :line +Variable References :h4 + Variable references access quantities calulated by other variables, which will cause those variables to be evaluated. The name in the reference should be replaced by the name of a variable defined

    Number 0.2, 100, 1.0e20, -15.4, etc
    Constant PI
    Thermo keywords vol, pe, ebond, etc
    Math operators (), -x, x+y, x-y, x*y, x/y, x^y, x==y, x!=y, xy, x>=y, x&&y, x||y
    Math functions sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(lo,hi,seed), normal(mu,sigma,seed), ceil(x), floor(x), round(x)
    Math functions sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z), vlinear(x,y), swiggle(x,y,z), cwiggle(x,y,z)
    Group functions count(ID), mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID), angmom(ID,dim), inertia(ID,dimdim), omega(ID,dim)
    Region functions count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), angmom(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR)
    Special functions ramp(x,y), stagger(x,y), logfreq(x,y,z), sum(x), min(x), max(x), ave(x), trap(x)
    Special functions sum(x), min(x), max(x), ave(x), trap(x)
    Atom values mass[i], type[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i]
    Atom vectors mass, type, x, y, z, vx, vy, vz, fx, fy, fz
    Compute references c_ID, c_ID[i], c_ID[i][j]