`. As mentioned above, an
+internal-style variable can be used in place of an equal-style
+variable anywhere else in an input script, e.g. as an argument to
+another command that allows for equal-style variables.
+
----------
diff --git a/doc/html/create_atoms.html b/doc/html/create_atoms.html
index e7b3d635fd..aca55ff5fd 100644
--- a/doc/html/create_atoms.html
+++ b/doc/html/create_atoms.html
@@ -310,16 +310,18 @@ keyword is the name of an equal-style variables set keyword is used to identify
-the names of these other variables, one variable for the x-coordinate
-of a created atom, one for y, and one for z.
-When an atom is created, its x, y, or z coordinates override the
-formula for any set variable that is defined. The var variable is
-then evaluated. If the returned value is 0.0, the atom is not
-created. If it is non-zero, the atom is created. After all atoms are
-created, the formulas defined for all of the set variables are
-restored to their original strings.
+internal-style variables set keyword is used to identify the names of these
+other variables, one variable for the x-coordinate of a created atom,
+one for y, and one for z.
+When an atom is created, its x,y,z coordinates become the values for
+any set variable that is defined. The var variable is then
+evaluated. If the returned value is 0.0, the atom is not created. If
+it is non-zero, the atom is created. After all atoms are created, the
+formulas defined for all of the set variables are restored to their
+original strings.
As an example, these commands can be used in a 2d simulation, to
create a sinusoidal surface. Note that the surface is “rough” due to
individual lattice points being “above” or “below” the mathematical
diff --git a/doc/html/dump.html b/doc/html/dump.html
index fc5f4c89c6..d87465df8e 100644
--- a/doc/html/dump.html
+++ b/doc/html/dump.html
@@ -310,6 +310,9 @@ parallel via the MPI-IO library. For the remainder of this doc page,
you should thus consider the atom and atom/mpiio styles (etc) to
be inter-changeable. The one exception is how the filename is
specified for the MPI-IO styles, as explained below.
+The precision of values output to text-based dump files can be
+controlled by the dump_modify format
The style keyword determines what atom quantities are written to the
file and in what format. Settings made via the
diff --git a/doc/html/fix_controller.html b/doc/html/fix_controller.html
new file mode 100644
index 0000000000..f80bc97a82
--- /dev/null
+++ b/doc/html/fix_controller.html
@@ -0,0 +1,397 @@
+
+
+
+
+
+
+ fix controller command — LAMMPS documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ LAMMPS
+
+
+
+
+
+
+
+
+
+
+
+
fix controller command
+
+
Syntax
+
fix ID group - ID controller Nevery alpha Kp Ki Kd pvar setpoint cvar
+
+
+
+ID, group-ID are documented in fix
+controller = style name of this fix command
+Nevery = invoke controller every this many timesteps
+alpha = coupling constant for PID equation (see units discussion below)
+Kp = proportional gain in PID equation (unitless)
+Ki = integral gain in PID equation (unitless)
+Kd = derivative gain in PID equation (unitless)
+pvar = process variable of form c_ID, c_ID[N], f_ID, f_ID[N], or v_name
+
+
c_ID = global scalar calculated by a compute with ID
+c_ID [ I ] = Ith component of global vector calculated by a compute with ID
+f_ID = global scalar calculated by a fix with ID
+f_ID [ I ] = Ith component of global vector calculated by a fix with ID
+v_name = value calculated by an equal - style variable with name
+
+
+
+setpoint = desired value of process variable (same units as process variable)
+cvar = name of control variable
+
+
+
+
Examples
+
fix 1 all controller 100 1.0 0.5 0.0 0.0 c_thermo_temp 1.5 tcontrol
+fix 1 all controller 100 0.2 0.5 0 100.0 v_pxxwall 1.01325 xwall
+fix 1 all controller 10000 0.2 0.5 0 2000 v_avpe - 3.785 tcontrol
+
+
+
+
+
Description
+
This fix enables control of a LAMMPS simulation using a control loop
+feedback mechanism known as a proportional-integral-derivative (PID)
+controller. The basic idea is to define a “process variable” which is
+a quantity that can be monitor during a running simulation. A desired
+target value is chosen for the process variable. A “control variable”
+is also defined which is an adjustable attribute of the simulation
+which the process variable will respond to. The PID controller
+continuously adjusts the control variable based on the difference
+between the process variable and the target.
+
Here are examples of ways in which this fix can be used. The
+examples/pid directory contains a script that implements the simple
+thermostat.
+
+
+
+
+Goal
+process variable
+control variable
+Simple thermostat
+instantaneous T
+thermostat target T
+Find melting temperature
+average PE per atom
+thermostat target T
+Control pressure in non-periodic system
+force on wall
+position of wall
+
+
+
+
+
+
+
Note
+
For this fix to work, the control variable must actually induce
+a change in a running LAMMPS simulation. Typically this will only
+occur if there is some other command (e.g. a thermostat fix) which
+uses the control variable as an input parameter. This could be done
+directly or indirectly, e.g. the other command uses a variable as
+input whose formula uses the control variable. The other command
+should alter its behavior dynamically as the variable changes.
+
+
+
Note
+
If there is a command you think could be used in this fashion,
+but does not currently allow a variable as an input parameter, please
+notify the LAMMPS developers. It is often not difficult to enable a
+command to use a variable as an input parameter.
+
+
The group specified with this command is ignored. However, note that
+the process variable may be defined by calculations performed by
+computes and fixes which store their own “group” definitions.
+
The PID controller is invoked once each Nevery timesteps.
+
The PID controller is implemented as a discretized version of
+the following dynamic equation:
+
+
where c is the continuous time analog of the control variable,
+e =pvar -setpoint is the error in the process variable, and
+alpha , Kp , Ki , and Kd are constants set by the corresponding
+keywords described above. The discretized version of this equation is:
+
+
where tau = Nevery timestep is the time interval between updates,
+and the subsripted variables indicated the values of *c and e at
+successive updates.
+
From the first equation, it is clear that if the three gain values
+Kp , Ki , Kd are dimensionless constants, then alpha must have
+units of [unit cvar ]/[unit pvar ]/[unit time] e.g. [ eV/K/ps
+]. The advantage of this unit scheme is that the value of the
+constants should be invariant under a change of either the MD timestep
+size or the value of Nevery . Similarly, if the LAMMPS unit style alpha to reflect this, while leaving Kp , Ki , and
+Kd unaltered.
+
When choosing the values of the four constants, it is best to first
+pick a value and sign for alpha that is consistent with the
+magnitudes and signs of pvar and cvar . The magnitude of Kp
+should then be tested over a large positive range keeping Ki =Kd =0.
+A good value for Kp will produce a fast reponse in pvar , without
+overshooting the setpoint . For many applications, proportional
+feedback is sufficient, and so Ki =Kd =0 can be used. In cases where
+there is a substantial lag time in the response of pvar to a change
+in cvar , this can be counteracted by increasing Kd . In situations
+where pvar plateaus without reaching setpoint , this can be
+counteracted by increasing Ki . In the language of Charles Dickens
+(or Donald Trump), Kp represents the error of the present, Ki the
+error of the past, and Kd the error yet to come.
+
Because this fix updates cvar , but does not initialize its value,
+the initial value is that assigned by the user in the internal-style
+variable command. This value is used (by the other LAMMPS command that
+used the variable) until this fix performs its first update of cvar
+after Nevery timesteps. On the first update, the value of the
+derivative term is set to zero, because the value of e_n-1 is not
+yet defined.
+
+
The process variable pvar can be specified as the output of a
+compute fix variable
+
If pvar begins with “c_ compute add them to LAMMPS
+
If pvar begins with “f_ fix add them to LAMMPS
+
If pvar begins with “v_ variable equal define a formula which
+can reference individual atom properties or thermodynamic keywords, or
+they can invoke other computes, fixes, or variables when they are
+evaluated, so this is a very general means of specifying the process
+variable.
+
The target value setpoint for the process variable must be a numeric
+value, in whatever units pvar is defined for.
+
The control variable cvar must be the name of an internal-style variable v_
+
+
+
+
Restart, fix_modify, output, run start/stop, minimize info
+
Currenlty, no information about this fix is written to binary restart files fix_modify
+
This fix produces a global vector with 3 values which can be accessed
+by various output commands Nevery .
+
The three values are the most recent updates made to the control
+variable by each of the 3 terms in the PID equation above. The first
+value is the proportional term, the second is the integral term, the
+third is the derivative term.
+
The units of the vector values will be whatever units the control
+variable is in. The vector values calculated by this fix are
+“extensive”.
+
No parameter of this fix can be used with the start/stop keywords of
+the run energy minimization
+
+
+
+
+
+
+
+
+
+
+
+
+
+
fix controller
+ fix deform
int and float keywords take a sin
format argument and are applied to all integer or floating-point
quantities output. The setting for M string also takes a single
format argument which is used for the Mth value output in each line,
-e.g. the 5th column of output is output in high precision for “format
-5 %20.15g”.
+e.g. the 5th column is output in high precision for “format 5
+%20.15g”.
The format keyword can be used multiple times. The precedence is
that for each value in a line of output, the M format (if specified)
is used, else the int or float setting (if specified) is used,
diff --git a/doc/html/variable.html b/doc/html/variable.html
index 1250ca06d3..0e2c81b885 100644
--- a/doc/html/variable.html
+++ b/doc/html/variable.html
@@ -133,7 +133,7 @@
name = name of variable to define
-style = delete or index or loop or world or universe or uloop or string or format or getenv or file or atomfile or python or equal or vector or atom
+style = delete or index or loop or world or universe or uloop or string or format or getenv or file or atomfile or python or internal or equal or vector or atom
delete = no args
@@ -163,6 +163,7 @@
file arg = filename
atomfile arg = filename
python arg = function
+internal arg = numeric value
equal or vector 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, version, on, off, true, false, yes, no
@@ -205,6 +206,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 foo internal 3.5
variable myPy python increase
variable f file values.txt
variable temp world 300.0 310.0 320.0 ${Tfinal}
@@ -239,7 +241,8 @@ input script that atom-style variables are used; they get their
per-atom values from a file rather than from a formula. Variables of
style python can be hooked to Python functions using code you
provide, so that the variable gets its value from the evaluation of
-the Python code.
+the Python code. Variables of style internal are used by a few
+commands in LAMMPS which set their value directly.
Note
As discussed in Section 3.2
Variables of style equal and vector and atom can be used
as inputs to various other LAMMPS commands which evaluate their
formulas as needed, e.g. at different timesteps during a
-run python can be used in place of
-an equal-style variable so long as the associated Python function, as
-defined by the python
+
run .
+Variables of style internal can be used in place of an equal-style
+variable, except by commands that set the value in the internal-style
+variable. Thus any command that states it can use an equal-style
+variable as an argument, can also use an internal-style variable.
+This means that when the LAMMPS command evaluates the variable, it
+will use the value set (internally) by another LAMMPS command.
+Variables of style python can be used in place of an equal-style
+variable so long as the associated Python function, as defined by the
+python
Note
When a variable command is encountered in the input script and
@@ -298,12 +308,12 @@ will override a corresponding index variable setting in the input
script.
There are two exceptions to this rule. First, variables of style
-string , getenv , equal , vector , atom , and python ARE
-redefined each time the command is encountered. This allows these
-style of variables to be redefined multiple times in an input script.
-In a loop, this means the formula associated with an equal or atom
-style variable can change if it contains a substitution for another
-variable, e.g. $x or v_x.
+string , getenv , equal , vector , atom , internal , and
+python ARE redefined each time the command is encountered. This
+allows these style of variables to be redefined multiple times in an
+input script. In a loop, this means the formula associated with an
+equal or atom style variable can change if it contains a
+substitution for another variable, e.g. $x or v_x.
Second, as described below, if a variable is iterated on to the end of
its list of strings via the next
For the python style a Python function name is provided. This needs
to match a function name specified in a python return
-keyword. For exampe these two commands would be self-consistent:
+keyword. For example these two commands would be self-consistent:
variable foo python myMultiply
python myMultiply return v_foo format f file funcs . py
@@ -482,6 +492,14 @@ it is a numeric value (integer or floating point), then the
python-style variable can be used in place of an equal-style variable
anywhere in an input script, e.g. as an argument to another command
that allows for equal-style variables.
+
For the internal style a numeric value is provided. This value will
+be assigned to the variable until a LAMMPS command sets it to a new
+value. There are currently only two LAMMPS commands that require
+internal variables as inputs, because they reset them:
+create_atoms fix controller
For the equal and vector and atom styles, a single string is
specified which represents a formula that will be evaluated afresh
diff --git a/doc/src/create_atoms.txt b/doc/src/create_atoms.txt
index cf739ac79c..4bc93f4e3b 100644
--- a/doc/src/create_atoms.txt
+++ b/doc/src/create_atoms.txt
@@ -196,9 +196,11 @@ should evaluate to a zero or non-zero value based on one or two or
three variables which will store the x, y, or z coordinates of an atom
(one variable per coordinate). If used, these other variables must be
"internal-style variables"_variable.html defined in the input script;
-their initial numeric value can be anything. The {set} keyword is
-used to identify the names of these other variables, one variable for
-the x-coordinate of a created atom, one for y, and one for z.
+their initial numeric value can be anything. They must be
+internal-style variables, because this command updates their values
+directly. The {set} keyword is used to identify the names of these
+other variables, one variable for the x-coordinate of a created atom,
+one for y, and one for z.
When an atom is created, its x,y,z coordinates become the values for
any {set} variable that is defined. The {var} variable is then
diff --git a/doc/src/variable.txt b/doc/src/variable.txt
index afd1c90f2f..8213c0ad26 100644
--- a/doc/src/variable.txt
+++ b/doc/src/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 {format} or {getenv} or {file} or {atomfile} or {python} or {equal} or {internal} or {vector} or {atom} :l
+style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {string} or {format} or {getenv} or {file} or {atomfile} or {python} or {internal} or {equal} or {vector} or {atom} :l
{delete} = no args
{index} args = one or more strings
{loop} args = N
@@ -41,6 +41,7 @@ style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {st
{file} arg = filename
{atomfile} arg = filename
{python} arg = function
+ {internal} arg = numeric value
{equal} or {vector} 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, version, on, off, true, false, yes, no
@@ -83,6 +84,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 foo internal 3.5
variable myPy python increase
variable f file values.txt
variable temp world 300.0 310.0 320.0 $\{Tfinal\}
@@ -119,7 +121,8 @@ input script that atom-style variables are used; they get their
per-atom values from a file rather than from a formula. Variables of
style {python} can be hooked to Python functions using code you
provide, so that the variable gets its value from the evaluation of
-the Python code.
+the Python code. Variables of style {internal} are used by a few
+commands in LAMMPS which set their value directly.
NOTE: As discussed in "Section 3.2"_Section_commands.html#cmd_2 of the
manual, an input script can use "immediate" variables, specified as
@@ -153,13 +156,22 @@ when it is invoked.
NOTE: Variables of style {equal} and {vector} and {atom} can be used
as inputs to various other LAMMPS commands which evaluate their
formulas as needed, e.g. at different timesteps during a
-"run"_run.html. Variables of style {python} can be used in place of
-an equal-style variable so long as the associated Python function, as
-defined by the "python"_python.html command, returns a numeric value.
-Thus any command that states it can use an equal-style variable as an
-argument, can also use such a python-style variable. This means that
-when the LAMMPS command evaluates the variable, the Python function
-will be executed.
+"run"_run.html.
+
+Variables of style {internal} can be used in place of an equal-style
+variable, except by commands that set the value in the internal-style
+variable. Thus any command that states it can use an equal-style
+variable as an argument, can also use an internal-style variable.
+This means that when the LAMMPS command evaluates the variable, it
+will use the value set (internally) by another LAMMPS command.
+
+Variables of style {python} can be used in place of an equal-style
+variable so long as the associated Python function, as defined by the
+"python"_python.html command, returns a numeric value. Thus any
+command that states it can use an equal-style variable as an argument,
+can also use such a python-style variable. This means that when the
+LAMMPS command evaluates the variable, the Python function will be
+executed.
NOTE: When a variable command is encountered in the input script and
the variable name has already been specified, the command is ignored.
@@ -172,12 +184,12 @@ will override a corresponding index variable setting in the input
script.
There are two exceptions to this rule. First, variables of style
-{string}, {getenv}, {equal}, {vector}, {atom}, and {python} ARE
-redefined each time the command is encountered. This allows these
-style of variables to be redefined multiple times in an input script.
-In a loop, this means the formula associated with an {equal} or {atom}
-style variable can change if it contains a substitution for another
-variable, e.g. $x or v_x.
+{string}, {getenv}, {equal}, {vector}, {atom}, {internal}, and
+{python} ARE redefined each time the command is encountered. This
+allows these style of variables to be redefined multiple times in an
+input script. In a loop, this means the formula associated with an
+{equal} or {atom} style variable can change if it contains a
+substitution for another variable, e.g. $x or v_x.
Second, as described below, if a variable is iterated on to the end of
its list of strings via the "next"_next.html command, it is removed
@@ -360,7 +372,7 @@ appear in the set, will remain 0.0.
For the {python} style a Python function name is provided. This needs
to match a function name specified in a "python"_python.html command
which returns a value to this variable as defined by its {return}
-keyword. For exampe these two commands would be self-consistent:
+keyword. For example these two commands would be self-consistent:
variable foo python myMultiply
python myMultiply return v_foo format f file funcs.py :pre
@@ -382,6 +394,16 @@ python-style variable can be used in place of an equal-style variable
anywhere in an input script, e.g. as an argument to another command
that allows for equal-style variables.
+For the {internal} style a numeric value is provided. This value will
+be assigned to the variable until a LAMMPS command sets it to a new
+value. There are currently only two LAMMPS commands that require
+{internal} variables as inputs, because they reset them:
+"create_atoms"_create_atoms.html and "fix
+controller"_fix_controller.html. As mentioned above, an
+internal-style variable can be used in place of an equal-style
+variable anywhere else in an input script, e.g. as an argument to
+another command that allows for equal-style variables.
+
:line
For the {equal} and {vector} and {atom} styles, a single string is
+
+