The specified filename determines how the dump file(s) is written. The default is to write one large text file, which is opened when the diff --git a/doc/dump.txt b/doc/dump.txt index 3ffdf408c1..b81277ea73 100644 --- a/doc/dump.txt +++ b/doc/dump.txt @@ -296,12 +296,14 @@ minimization converges. Note that this means a dump will not be performed on the initial timestep after the dump command is invoked, if the current timestep is not a multiple of N. This behavior can be changed via the "dump_modify first"_dump_modify.html command, which -can be useful if the dump command is invoked after a minimization +can also be useful if the dump command is invoked after a minimization ended on an arbitrary timestep. N can be changed between runs by using the "dump_modify every"_dump_modify.html command (not allowed for {dcd} style). The "dump_modify every"_dump_modify.html command also allows a variable to be used to determine the sequence of -timesteps on which dump files are written. +timesteps on which dump files are written. In this mode a dump on the +first timestep of a run will also not be written unless the +"dump_modify first"_dump_modify.html command is used. The specified filename determines how the dump file(s) is written. The default is to write one large text file, which is opened when the diff --git a/doc/dump_modify.html b/doc/dump_modify.html index 331141c8c0..726eae7fdf 100644 --- a/doc/dump_modify.html +++ b/doc/dump_modify.html @@ -365,16 +365,22 @@ which should be specified as v_name, where name is the variable name.
In this case, the variable is evaluated at the beginning of a run to determine the next timestep at which a dump snapshot will be written -out. On that timestep, the variable will be evaluated again to +out. On that timestep the variable will be evaluated again to determine the next timestep, etc. Thus the variable should return timestep values. See the stagger() and logfreq() and stride() math functions for equal-style variables, as examples of useful functions to use in this context. Other similar math functions could easily be added as options for equal-style -variables. When using the variable option with the -every keyword, you also need to use the first option if you want -an initial snapshot written to the dump file. The every keyword -cannot be used with the dump dcd style. +variables. Also see the next() function, which allows +use of a file-style variable which reads successive values from a +file, each time the variable is evaluated. Used with the every +keyword, if the file contains a list of ascending timesteps, you can +output snapshots whenever you wish. +
+Note that when using the variable option with the every keyword, you +need to use the first option if you want an initial snapshot written +to the dump file. The every keyword cannot be used with the dump +dcd style.
For example, the following commands will write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc: @@ -383,6 +389,25 @@ write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc: dump 1 all atom 100 tmp.dump dump_modify 1 every v_s first yes +
The following commands would write snapshots at the timesteps listed +in file tmp.times: +
+variable f file tmp.times +variable s equal next(f) +dump 1 all atom 100 tmp.dump +dump_modify 1 every v_s ++
IMPORTANT NOTE: When using a file-style variable with the every +keyword, the file of timesteps must list a first timestep that is +beyond the current timestep (e.g. it cannot be 0). And it must list +one or more timesteps beyond the length of the run you perform. This +is because the dump command will generate an error if the next +timestep it reads from the file is not a value greater than the +current timestep. Thus if you wanted output on steps 0,15,100 of a +100-timestep run, the file should contain the values 15,100,101 and +you should also use the dump_modify first command. Any final value > +100 could be used in place of 101. +
The first keyword determines whether a dump snapshot is written on diff --git a/doc/dump_modify.txt b/doc/dump_modify.txt index e1f2176465..6b820bde40 100644 --- a/doc/dump_modify.txt +++ b/doc/dump_modify.txt @@ -358,16 +358,22 @@ which should be specified as v_name, where name is the variable name. In this case, the variable is evaluated at the beginning of a run to determine the next timestep at which a dump snapshot will be written -out. On that timestep, the variable will be evaluated again to +out. On that timestep the variable will be evaluated again to determine the next timestep, etc. Thus the variable should return timestep values. See the stagger() and logfreq() and stride() math functions for "equal-style variables"_variable.html, as examples of useful functions to use in this context. Other similar math functions could easily be added as options for "equal-style -variables"_variable.html. When using the variable option with the -{every} keyword, you also need to use the {first} option if you want -an initial snapshot written to the dump file. The {every} keyword -cannot be used with the dump {dcd} style. +variables"_variable.html. Also see the next() function, which allows +use of a file-style variable which reads successive values from a +file, each time the variable is evaluated. Used with the {every} +keyword, if the file contains a list of ascending timesteps, you can +output snapshots whenever you wish. + +Note that when using the variable option with the {every} keyword, you +need to use the {first} option if you want an initial snapshot written +to the dump file. The {every} keyword cannot be used with the dump +{dcd} style. For example, the following commands will write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc: @@ -376,6 +382,25 @@ variable s equal logfreq(10,3,10) dump 1 all atom 100 tmp.dump dump_modify 1 every v_s first yes :pre +The following commands would write snapshots at the timesteps listed +in file tmp.times: + +variable f file tmp.times +variable s equal next(f) +dump 1 all atom 100 tmp.dump +dump_modify 1 every v_s :pre + +IMPORTANT NOTE: When using a file-style variable with the {every} +keyword, the file of timesteps must list a first timestep that is +beyond the current timestep (e.g. it cannot be 0). And it must list +one or more timesteps beyond the length of the run you perform. This +is because the dump command will generate an error if the next +timestep it reads from the file is not a value greater than the +current timestep. Thus if you wanted output on steps 0,15,100 of a +100-timestep run, the file should contain the values 15,100,101 and +you should also use the dump_modify first command. Any final value > +100 could be used in place of 101. + :line The {first} keyword determines whether a dump snapshot is written on diff --git a/doc/next.html b/doc/next.html index 31be8e0f5f..f9ad104f29 100644 --- a/doc/next.html +++ b/doc/next.html @@ -38,14 +38,15 @@ be used in an input script command as $a or $z. If it is multiple letters, it can be used as ${myTemp}.
If multiple variables are used as arguments to the next command, -then all must be of the same variable style: index, loop, +then all must be of the same variable style: index, loop, file, universe, or uloop. An exception is that universe- and uloop-style variables can be mixed in the same next command.
All the variables specified with the next command are incremented by -one value from their respective list or values. String- or atom- -or equal- or world-style variables cannot be used with the the -next command, since they only store a single value. +one value from their respective list of values. A file-style variable +reads the next line from its associated file. String- or atom- or +equal- or world-style variables cannot be used with the the next +command, since they only store a single value.
When any of the variables in the next command has no more values, a flag is set that causes the input script to skip the next @@ -53,18 +54,19 @@ flag is set that causes the input script to skip the next a next command to exit. As explained in the variable command, the variable that has exhausted its values is also deleted. This allows it to be used and re-defined later in the input script. +File-style variables are exhausted when the end-of-file is reached.
-When the next command is used with index- or loop-style variables, -the next value is assigned to the variable for all processors. When -the next command is used with universe- or uloop-style variables, -the next value is assigned to whichever processor partition executes -the command first. All processors in the partition are assigned the -same value. Running LAMMPS on multiple partitions of processors via -the "-partition" command-line switch is described in this -section of the manual. Universe- and -uloop-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. +
When the next command is used with index- or loop-style or +file-style variables, the next value is assigned to the variable for +all processors. When the next command is used with universe- or +uloop-style variables, the next value is assigned to whichever +processor partition executes the command first. All processors in the +partition are assigned the same value. Running LAMMPS on multiple +partitions of processors via the "-partition" command-line switch is +described in this section of the manual. +Universe- and uloop-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.
Here is an example of running a series of simulations using the next command with an index-style variable. If this input script is named diff --git a/doc/next.txt b/doc/next.txt index f0be628871..4e3f2b2ce2 100644 --- a/doc/next.txt +++ b/doc/next.txt @@ -35,14 +35,15 @@ be used in an input script command as $a or $z. If it is multiple letters, it can be used as $\{myTemp\}. If multiple variables are used as arguments to the {next} command, -then all must be of the same variable style: {index}, {loop}, +then all must be of the same variable style: {index}, {loop}, {file}, {universe}, or {uloop}. An exception is that {universe}- and {uloop}-style variables can be mixed in the same {next} command. All the variables specified with the next command are incremented by -one value from their respective list or values. {String-} or {atom}- -or {equal}- or {world}-style variables cannot be used with the the -next command, since they only store a single value. +one value from their respective list of values. A {file}-style variable +reads the next line from its associated file. {String-} or {atom}- or +{equal}- or {world}-style variables cannot be used with the the next +command, since they only store a single value. When any of the variables in the next command has no more values, a flag is set that causes the input script to skip the next @@ -50,18 +51,19 @@ flag is set that causes the input script to skip the next a next command to exit. As explained in the "variable"_variable.html command, the variable that has exhausted its values is also deleted. This allows it to be used and re-defined later in the input script. +{File}-style variables are exhausted when the end-of-file is reached. -When the next command is used with {index}- or {loop}-style variables, -the next value is assigned to the variable for all processors. When -the next command is used with {universe}- or {uloop}-style variables, -the next value is assigned to whichever processor partition executes -the command first. All processors in the partition are assigned the -same value. Running LAMMPS on multiple partitions of processors via -the "-partition" command-line switch is described in "this -section"_Section_start.html#start_7 of the manual. {Universe}- and -{uloop}-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. +When the next command is used with {index}- or {loop}-style or +{file}-style variables, the next value is assigned to the variable for +all processors. When the next command is used with {universe}- or +{uloop}-style variables, the next value is assigned to whichever +processor partition executes the command first. All processors in the +partition are assigned the same value. Running LAMMPS on multiple +partitions of processors via the "-partition" command-line switch is +described in "this section"_Section_start.html#start_7 of the manual. +{Universe}- and {uloop}-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. Here is an example of running a series of simulations using the next command with an {index}-style variable. If this input script is named diff --git a/doc/variable.html b/doc/variable.html index 7051914f05..af6cd728a0 100644 --- a/doc/variable.html +++ b/doc/variable.html @@ -17,7 +17,7 @@
delete = no args
index args = one or more strings
@@ -39,6 +39,7 @@
N = integer size of loop
pad = all values will be same length, e.g. 001, 002, ..., 100
string arg = one string
+ file arg = filename
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
@@ -59,7 +60,7 @@
bound(group,xmin,region), gyration(group,region), ke(group,reigon),
angmom(group,dim,region), torque(group,dim,region),
inertia(group,dimdim,region), omega(group,dim,region)
- special functions = sum(x), min(x), max(x), ave(x), trap(x), gmask(x), rmask(x), grmask(x,y)
+ special functions = sum(x), min(x), max(x), ave(x), trap(x), gmask(x), rmask(x), grmask(x,y), next(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]
@@ -79,6 +80,7 @@ variable b equal xcm(mol1,x)/2.0
variable b equal c_myTemp
variable b atom x*y/vol
variable foo string myfile
+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
@@ -154,13 +156,13 @@ 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 then exited from.
+
As described below, for variable styles index, loop, file,
+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 then exited from.
As explained above, an exhausted variable can be re-used in an input
script. The delete style also removes the variable, the same as if
@@ -235,6 +237,32 @@ 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 string style, a single string is assigned to the variable.
+The only difference between this and using the index style with a
+single string is that a variable with string style can be redefined.
+E.g. by another command later in the input script, or if the script is
+read again in a loop.
+
+For the file 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.
+
+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 next command or the
+next() function in an equal- or atom-style variable, as discussed
+below.
+
+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.
+
For the equal and atom styles, a single string is specified which
@@ -279,7 +307,7 @@ references to other variables.
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), stride(x,y,z), vdisplace(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), torque(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), torque(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR) Special functions sum(x), min(x), max(x), ave(x), trap(x), gmask(x), rmask(x), grmask(x,y) Special functions sum(x), min(x), max(x), ave(x), trap(x), gmask(x), rmask(x), grmask(x,y), next(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] 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
+atom-style variable is evaluated), the current string value stored by
+the file-style variable is converted to a numeric value returned by
+the function, and the next value from 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. Since the file-style variable reads and stores the
+first line of the file when it is 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 value for the last line is repeatedly returned.
+
Atom Values and Vectors
@@ -649,20 +691,26 @@ 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
-elsewhere in the input script. As discussed on this doc page,
-atom-style variables generate a per-atom vector of values; all other
-variable styles generate a global scalar value. An equal-style
-variable can only use scalar values, which means another equal-style
-variable or an element of an atom-style variable. Atom-style
-variables can use the same scalar values. They can also use other
-atom-style variables.
+
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.
+
+As discussed on this doc page, equal-style variables generate a global
+scalar numeric value; atom-style variables generate a per-atom vector
+of numeric values; all other variables store a string. The formula
+for an equal-style variable can use any style of variable except an
+atom-style (unless only a single value from the atom-style variable is
+accessed via a subscript). 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. The formula for an atom-style
+variable can use any style of variable, including other atom-style
+variables.
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-atom vectors, never both.
+produce only a global scalar or a per-atom vector, never both.
v_name scalar, or per-atom vector