All the variables specified with the next command are incremented by -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. +one value from their respective list of values. A file-style +variable reads the next line from its associated file. An +atomfile-style variable reads the next set of lines (one per atom) +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 @@ -54,19 +56,24 @@ 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. +File-style and atomfile-style variables are exhausted when the +end-of-file is reached.
-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. +
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 file-style variables, the next line is +read from its file and the string assigned to the variable. When the +next command is used with atomfile-style variables, the next set of +per-atom values is read from its file and assigned to the variable. +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 4e3f2b2ce2..1f8199086a 100644 --- a/doc/next.txt +++ b/doc/next.txt @@ -40,10 +40,12 @@ then all must be of the same variable style: {index}, {loop}, {file}, {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 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. +one value from their respective list of values. A {file}-style +variable reads the next line from its associated file. An +{atomfile}-style variable reads the next set of lines (one per atom) +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 @@ -51,19 +53,24 @@ 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. +{File}-style and {atomfile}-style variables are exhausted when the +end-of-file is reached. -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. +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 {file}-style variables, the next line is +read from its file and the string assigned to the variable. When the +next command is used with {atomfile}-style variables, the next set of +per-atom values is read from its file and assigned to the variable. +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 a212a3f0df..44fe7cc2ca 100644 --- a/doc/variable.html +++ b/doc/variable.html @@ -17,7 +17,7 @@
delete = no args
index args = one or more strings
@@ -40,6 +40,7 @@
pad = all values will be same length, e.g. 001, 002, ..., 100
string arg = one string
file arg = filename
+ atomfile 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
@@ -106,7 +107,9 @@ a formula which when evaluated produces one numeric value per atom
which can be output to a dump file (see the dump custom
command) or used as input to an averaging fix (see the fix
ave/spatial and fix ave/atom
-commands).
+commands). Variables of style atomfile can be used similar to
+atom-style variables, except they get their per-atom values from a
+file rather than from a formula.
In the discussion that follows, the "name" of the variable is the
arbitrary string that is the 1st argument in the variable command.
@@ -245,7 +248,7 @@ 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
+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.
@@ -263,6 +266,36 @@ 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 atomfile style, a filename is provided which contains one or
+more sets of values, to assign on a per-atom basis to the variable.
+The format of the file is described below.
+
+When an atomfile-style variable is defined, the file is opened and the
+first set of per-atom values are read and stored with the variable.
+This means the variable can then be evaluated as many times as desired
+and will return those values. There are two ways to cause the next
+set of per-atom values from the file to be read: use the
+next command or the next() function in an atom-style
+variable, as discussed below.
+
+The rules for formatting the file are as follows. Each time a set of
+per-atom values is read, a non-blank line is searched for in the file.
+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 read as
+the count N of per-atom lines to immediately follow. N can be be the
+total number of atoms in the system, or only a subset. The next N
+lines have the following format
+
+ID value
+
+where ID is an atom ID and value is the per-atom numeric value that
+will be assigned to that atom. IDs can be listed in any order.
+
+IMPORTANT NOTE: Every time a set of per-atom lines is read, the value
+for all atoms is first set to 0.0. Thus values for atoms whose ID
+does not appear in the set, will remain 0.0.
+
For the equal and atom styles, a single string is specified which
@@ -589,18 +622,29 @@ variables. It returns a 1 for atoms that are in both the group and
region, and a 0 for atoms that are not in both.
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.
+"v_foo", just "foo"). It must be for a file-style or atomfile-style
+variable. Each time the next() function is invoked (i.e. each time
+the equal-style or atom-style variable is evaluated), the following
+steps occur.
+
+For file-style variables, the current string value stored by the
+file-style variable is converted to a numeric value and returned by
+the function. And the next string value in the file is read and
+stored. Note that if the line previously read from the file was not a
+numeric string, then it will typically evaluate to 0.0, which is
+likely not what you want.
+
+For atomfile-style variables, the current per-atom values stored by
+the atomfile-style variable are returned by the function. And the
+next set of per-atom values in the file is read and stored.
+
+Since file-style and atomfile-style variables read and store the first
+line of the file or first set of per-atoms values when they are
+defined in the input script, these are the value(s) that will be
+returned the first time the next() function is invoked. If next() is
+invoked more times than there are lines or sets of lines in the file,
+the variable is deleted, similar to how the next command
+operates.
@@ -698,16 +742,16 @@ 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.
+scalar numeric value; atom-style and atomfile-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 or atomfile-style (unless only a single
+value from the 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 or atomfile-style variables.
Examples of different kinds of variable references are as follows.
There is no ambiguity as to what a reference means, since variables
diff --git a/doc/variable.txt b/doc/variable.txt
index 86e3aac43f..1c8ce21896 100644
--- a/doc/variable.txt
+++ b/doc/variable.txt
@@ -13,7 +13,7 @@ variable command :h3
variable name style args ... :pre
name = name of variable to define :ulb,l
-style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {string} or {file} or {equal} or {atom} :l
+style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {string} or {file} or {atomfile} or {equal} or {atom} :l
{delete} = no args
{index} args = one or more strings
{loop} args = N
@@ -35,6 +35,7 @@ style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {st
pad = all values will be same length, e.g. 001, 002, ..., 100
{string} arg = one string
{file} arg = filename
+ {atomfile} 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
@@ -100,7 +101,9 @@ a formula which when evaluated produces one numeric value per atom
which can be output to a dump file (see the "dump custom"_dump.html
command) or used as input to an averaging fix (see the "fix
ave/spatial"_fix_ave_spatial.html and "fix ave/atom"_fix_ave_atom.html
-commands).
+commands). Variables of style {atomfile} can be used similar to
+atom-style variables, except they get their per-atom values from a
+file rather than from a formula.
In the discussion that follows, the "name" of the variable is the
arbitrary string that is the 1st argument in the variable command.
@@ -239,7 +242,7 @@ 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
+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.
@@ -257,6 +260,36 @@ 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 {atomfile} style, a filename is provided which contains one or
+more sets of values, to assign on a per-atom basis to the variable.
+The format of the file is described below.
+
+When an atomfile-style variable is defined, the file is opened and the
+first set of per-atom values are read and stored with the variable.
+This means the variable can then be evaluated as many times as desired
+and will return those values. There are two ways to cause the next
+set of per-atom values from the file to be read: use the
+"next"_next.html command or the next() function in an atom-style
+variable, as discussed below.
+
+The rules for formatting the file are as follows. Each time a set of
+per-atom values is read, a non-blank line is searched for in the file.
+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 read as
+the count N of per-atom lines to immediately follow. N can be be the
+total number of atoms in the system, or only a subset. The next N
+lines have the following format
+
+ID value :pre
+
+where ID is an atom ID and value is the per-atom numeric value that
+will be assigned to that atom. IDs can be listed in any order.
+
+IMPORTANT NOTE: Every time a set of per-atom lines is read, the value
+for all atoms is first set to 0.0. Thus values for atoms whose ID
+does not appear in the set, will remain 0.0.
+
:line
For the {equal} and {atom} styles, a single string is specified which
@@ -589,18 +622,29 @@ variables. It returns a 1 for atoms that are in both the group and
region, and a 0 for atoms that are not in both.
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.
+"v_foo", just "foo"). It must be for a file-style or atomfile-style
+variable. Each time the next() function is invoked (i.e. each time
+the equal-style or atom-style variable is evaluated), the following
+steps occur.
+
+For file-style variables, the current string value stored by the
+file-style variable is converted to a numeric value and returned by
+the function. And the next string value in the file is read and
+stored. Note that if the line previously read from the file was not a
+numeric string, then it will typically evaluate to 0.0, which is
+likely not what you want.
+
+For atomfile-style variables, the current per-atom values stored by
+the atomfile-style variable are returned by the function. And the
+next set of per-atom values in the file is read and stored.
+
+Since file-style and atomfile-style variables read and store the first
+line of the file or first set of per-atoms values when they are
+defined in the input script, these are the value(s) that will be
+returned the first time the next() function is invoked. If next() is
+invoked more times than there are lines or sets of lines in the file,
+the variable is deleted, similar to how the "next"_next.html command
+operates.
:line
@@ -694,16 +738,16 @@ 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.
+scalar numeric value; atom-style and atomfile-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 or atomfile-style (unless only a single
+value from the 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 or atomfile-style variables.
Examples of different kinds of variable references are as follows.
There is no ambiguity as to what a reference means, since variables