diff --git a/doc/html/_sources/create_atoms.txt b/doc/html/_sources/create_atoms.txt index a51f1b5289..d15f7107cf 100644 --- a/doc/html/_sources/create_atoms.txt +++ b/doc/html/_sources/create_atoms.txt @@ -210,17 +210,17 @@ keyword is the name of an :doc:`equal-style variable ` which 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 -:doc:`equal-style variables ` defined in the input script, but -their formula can by 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. +:doc:`internal-style variables ` 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. -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. +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 diff --git a/doc/html/_sources/dump.txt b/doc/html/_sources/dump.txt index cdbc64418e..7cbf12d6fd 100644 --- a/doc/html/_sources/dump.txt +++ b/doc/html/_sources/dump.txt @@ -207,6 +207,10 @@ 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 :doc:`dump_modify format ` command and +its options. + ---------- diff --git a/doc/html/_sources/fix_controller.txt b/doc/html/_sources/fix_controller.txt new file mode 100644 index 0000000000..523b118f49 --- /dev/null +++ b/doc/html/_sources/fix_controller.txt @@ -0,0 +1,229 @@ +.. index:: fix controller + +fix controller command +====================== + +Syntax +"""""" + +.. parsed-literal:: + + fix ID group-ID controller Nevery alpha Kp Ki Kd pvar setpoint cvar + +* ID, group-ID are documented in :doc:`fix ` command +* 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 +.. parsed-literal:: + + 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 +"""""""" + +.. parsed-literal:: + + 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: + +.. image:: Eqs/fix_controller1.jpg + :align: center + +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: + +.. image:: Eqs/fix_controller2.jpg + :align: center + +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 :doc:`unit style ` is changed, it should only be necessary to change +the value of *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 +:doc:`compute ` or :doc:`fix ` or the evaluation of a +:doc:`variable `. In each case, the compute, fix, or variable +must produce a global quantity, not a per-atom or local quantity. + +If *pvar* begins with "c_", a compute ID must follow which has been +previously defined in the input script and which generates a global +scalar or vector. See the individual :doc:`compute ` doc page +for details. If no bracketed integer is appended, the scalar +calculated by the compute is used. If a bracketed integer is +appended, the Ith value of the vector calculated by the compute is +used. Users can also write code for their own compute styles and :doc:`add them to LAMMPS `. + +If *pvar* begins with "f_", a fix ID must follow which has been +previously defined in the input script and which generates a global +scalar or vector. See the individual :doc:`fix ` doc page for +details. Note that some fixes only produce their values on certain +timesteps, which must be compatible with when fix controller +references the values, or else an error results. If no bracketed integer +is appended, the scalar calculated by the fix is used. If a bracketed +integer is appended, the Ith value of the vector calculated by the fix +is used. Users can also write code for their own fix style and :doc:`add them to LAMMPS `. + +If *pvar* begins with "v_", a variable name must follow which has been +previously defined in the input script. Only equal-style variables +can be referenced. See the :doc:`variable ` command for +details. Note that variables of style *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 :doc:`internal-style variable ` previously defined in the input script. Note +that it is not specified with a "v_" prefix, just the name of the +variable. It must be an internal-style variable, because this fix +updates its value directly. Note that other commands can use an +equal-style versus internal-style variable interchangeably. + + +---------- + + +Restart, fix_modify, output, run start/stop, minimize info +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Currenlty, no information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix_modify ` options +are relevant to this fix. + +This fix produces a global vector with 3 values which can be accessed +by various :ref:`output commands `. The values +can be accessed on any timestep, though they are only updated on +timesteps that are a multiple of *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 :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. + +Restrictions +"""""""""""" + none + +Related commands +"""""""""""""""" + +:doc:`fix adapt ` + +**Default:** none + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Section_commands.html#comm diff --git a/doc/html/_sources/thermo_modify.txt b/doc/html/_sources/thermo_modify.txt index fa9eb7bac7..40b3e3b6f1 100644 --- a/doc/html/_sources/thermo_modify.txt +++ b/doc/html/_sources/thermo_modify.txt @@ -117,8 +117,8 @@ is more than one field. The *int* and *float* keywords take a single 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) diff --git a/doc/html/_sources/variable.txt b/doc/html/_sources/variable.txt index 0a5d3321fe..166a9c6359 100644 --- a/doc/html/_sources/variable.txt +++ b/doc/html/_sources/variable.txt @@ -11,7 +11,7 @@ Syntax variable name style args ... * 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 *equal* or *internal* or *vector* or *atom* .. parsed-literal:: *delete* = no args