git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@15439 f3b2605a-c512-4ea7-a41b-209d697bcdaa

doc/src/create_atoms.txt

@@ -195,17 +195,17 @@ keyword is the name of an "equal-style variable"_variable.html 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
-"equal-style variables"_variable.html 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.
+"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.
 
-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

doc/src/dump.txt

@@ -166,6 +166,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 "dump_modify format"_dump_modify.html command and
+its options.
+
 :line
 
 The {style} keyword determines what atom quantities are written to the

doc/src/fix_controller.txt

@@ -0,0 +1,206 @@
+"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Section_commands.html#comm)
+
+:line
+
+fix controller command :h3
+
+[Syntax:]
+
+fix ID group-ID controller Nevery alpha Kp Ki Kd pvar setpoint cvar :pre
+
+ID, group-ID are documented in "fix"_fix.html command :ulb,l
+controller = style name of this fix command :l
+Nevery = invoke controller every this many timesteps :l
+alpha = coupling constant for PID equation (see units discussion below) :l
+Kp = proportional gain in PID equation (unitless) :l
+Ki = integral gain in PID equation (unitless) :l
+Kd = derivative gain in PID equation (unitless) :l
+pvar = process variable of form c_ID, c_ID\[N\], f_ID, f_ID\[N\], or v_name :l
+  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 :pre
+setpoint = desired value of process variable (same units as process variable) :l
+cvar = name of control variable :l
+:ule
+
+[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 :pre
+
+[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
+:tb(s=|)
+
+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:
+
+:c,image(Eqs/fix_controller1.jpg)
+
+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:
+
+:c,image(Eqs/fix_controller2.jpg)
+
+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"_units.html 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.
+
+:line
+
+The process variable {pvar} can be specified as the output of a
+"compute"_compute.html or "fix"_fix.html or the evaluation of a
+"variable"_variable.html.  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 "compute"_compute.html 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 "add
+them to LAMMPS"_Section_modify.html.
+
+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 "fix"_fix.html 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 "add
+them to LAMMPS"_Section_modify.html.
+
+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 "variable"_variable.html 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 "internal-style
+variable"_variable.html 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.
+
+:line
+
+[Restart, fix_modify, output, run start/stop, minimize info:]
+
+Currenlty, no information about this fix is written to "binary restart
+files"_restart.html.  None of the "fix_modify"_fix_modify.html options
+are relevant to this fix.
+
+This fix produces a global vector with 3 values which can be accessed
+by various "output commands"_Section_howto.html#howto_15.  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 "run"_run.html command.  This fix is not invoked during "energy
+minimization"_minimize.html.
+
+[Restrictions:] none
+
+[Related commands:]
+
+"fix adapt"_fix_adapt.html
+
+[Default:] none

doc/src/thermo_modify.txt

@@ -111,8 +111,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)

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 {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 {equal} or {internal} or {vector} or {atom} :l
   {delete} = no args
   {index} args = one or more strings
   {loop} args = N