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

doc/html/_sources/create_atoms.txt

@@ -211,9 +211,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
 :doc:`internal-style variables <variable>` defined in the input script;
-their initial numeric value can be anything.  The *set* keyword is
+their initial numeric value can be anything.  They must be
-used to identify the names of these other variables, one variable for
+internal-style variables, because this command updates their values
-the x-coordinate of a created atom, one for y, and one for z.
+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

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 *internal* 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*
 .. parsed-literal::
 
      *delete* = no args
@@ -41,6 +41,7 @@ Syntax
      *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
@@ -87,6 +88,7 @@ Examples
    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}
@@ -121,7 +123,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::
 
@@ -161,13 +164,22 @@ simulation.
    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
-   :doc:`run <run>`.  Variables of style *python* can be used in place of
+   :doc:`run <run>`.
-   an equal-style variable so long as the associated Python function, as
+
-   defined by the :doc:`python <python>` command, returns a numeric value.
+Variables of style *internal* can be used in place of an equal-style
-   Thus any command that states it can use an equal-style variable as an
+variable, except by commands that set the value in the internal-style
-   argument, can also use such a python-style variable.  This means that
+variable.  Thus any command that states it can use an equal-style
-   when the LAMMPS command evaluates the variable, the Python function
+variable as an argument, can also use an internal-style variable.
-   will be executed.
+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
+:doc:`python <python>` 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::
 
@@ -182,12 +194,12 @@ simulation.
    script.
 
 There are two exceptions to this rule.  First, variables of style
-*string*\ , *getenv*\ , *equal*\ , *vector*\ , *atom*\ , and *python* ARE
+*string*\ , *getenv*\ , *equal*\ , *vector*\ , *atom*\ , *internal*\ , and
-redefined each time the command is encountered.  This allows these
+*python* ARE redefined each time the command is encountered.  This
-style of variables to be redefined multiple times in an input script.
+allows these style of variables to be redefined multiple times in an
-In a loop, this means the formula associated with an *equal* or *atom*
+input script.  In a loop, this means the formula associated with an
-style variable can change if it contains a substitution for another
+*equal* or *atom* style variable can change if it contains a
-variable, e.g. $x or v_x.
+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 :doc:`next <next>` command, it is removed
@@ -378,7 +390,7 @@ will be assigned to that atom.  IDs can be listed in any order.
 For the *python* style a Python function name is provided.  This needs
 to match a function name specified in a :doc:`python <python>` 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:
 
 .. parsed-literal::
 
@@ -402,6 +414,15 @@ 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:
+:doc:`create_atoms <create_atoms>` and :doc:`fix controller <fix_controller>`.  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.
+
 
 ----------
 

doc/html/create_atoms.html

@@ -310,16 +310,18 @@ keyword is the name of an <a class="reference internal" href="variable.html"><sp
 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
-<a class="reference internal" href="variable.html"><span class="doc">equal-style variables</span></a> defined in the input script, but
+<a class="reference internal" href="variable.html"><span class="doc">internal-style variables</span></a> defined in the input script;
-their formula can by anything.  The <em>set</em> keyword is used to identify
+their initial numeric value can be anything.  They must be
-the names of these other variables, one variable for the x-coordinate
+internal-style variables, because this command updates their values
-of a created atom, one for y, and one for z.</p>
+directly.  The <em>set</em> keyword is used to identify the names of these
-<p>When an atom is created, its x, y, or z coordinates override the
+other variables, one variable for the x-coordinate of a created atom,
-formula for any <em>set</em> variable that is defined.  The <em>var</em> variable is
+one for y, and one for z.</p>
-then evaluated.  If the returned value is 0.0, the atom is not
+<p>When an atom is created, its x,y,z coordinates become the values for
-created.  If it is non-zero, the atom is created.  After all atoms are
+any <em>set</em> variable that is defined.  The <em>var</em> variable is then
-created, the formulas defined for all of the <em>set</em> variables are
+evaluated.  If the returned value is 0.0, the atom is not created.  If
-restored to their original strings.</p>
+it is non-zero, the atom is created.  After all atoms are created, the
+formulas defined for all of the <em>set</em> variables are restored to their
+original strings.</p>
 <p>As an example, these commands can be used in a 2d simulation, to
 create a sinusoidal surface.  Note that the surface is &#8220;rough&#8221; due to
 individual lattice points being &#8220;above&#8221; or &#8220;below&#8221; the mathematical

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 <em>atom</em> and <em>atom/mpiio</em> styles (etc) to
 be inter-changeable.  The one exception is how the filename is
 specified for the MPI-IO styles, as explained below.</p>
+<p>The precision of values output to text-based dump files can be
+controlled by the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify format</span></a> command and
+its options.</p>
 <hr class="docutils" />
 <p>The <em>style</em> keyword determines what atom quantities are written to the
 file and in what format.  Settings made via the

doc/html/fix_controller.html

@@ -0,0 +1,397 @@
+
+
+<!DOCTYPE html>
+<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
+<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
+<head>
+  <meta charset="utf-8">
+  
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  
+  <title>fix controller command &mdash; LAMMPS documentation</title>
+  
+
+  
+  
+
+  
+
+  
+  
+    
+
+  
+
+  
+  
+    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
+  
+
+  
+    <link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
+  
+
+  
+    <link rel="top" title="LAMMPS documentation" href="index.html"/> 
+
+  
+  <script src="_static/js/modernizr.min.js"></script>
+
+</head>
+
+<body class="wy-body-for-nav" role="document">
+
+  <div class="wy-grid-for-nav">
+
+    
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-nav-search">
+        
+
+        
+          <a href="Manual.html" class="icon icon-home"> LAMMPS
+        
+
+        
+        </a>
+
+        
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+
+        
+      </div>
+
+      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
+        
+          
+          
+              <ul>
+<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance &amp; scalability</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying &amp; extending LAMMPS</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
+<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
+</ul>
+
+          
+        
+      </div>
+      &nbsp;
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+
+      
+      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
+        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+        <a href="Manual.html">LAMMPS</a>
+      </nav>
+
+
+      
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="Manual.html">Docs</a> &raquo;</li>
+      
+    <li>fix controller command</li>
+      <li class="wy-breadcrumbs-aside">
+        
+          
+            <a href="http://lammps.sandia.gov">Website</a>
+            <a href="Section_commands.html#comm">Commands</a>
+        
+      </li>
+  </ul>
+  <hr/>
+  
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+            
+  <div class="section" id="fix-controller-command">
+<span id="index-0"></span><h1>fix controller command</h1>
+<div class="section" id="syntax">
+<h2>Syntax</h2>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">fix</span> <span class="n">ID</span> <span class="n">group</span><span class="o">-</span><span class="n">ID</span> <span class="n">controller</span> <span class="n">Nevery</span> <span class="n">alpha</span> <span class="n">Kp</span> <span class="n">Ki</span> <span class="n">Kd</span> <span class="n">pvar</span> <span class="n">setpoint</span> <span class="n">cvar</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
+<li>controller = style name of this fix command</li>
+<li>Nevery = invoke controller every this many timesteps</li>
+<li>alpha = coupling constant for PID equation (see units discussion below)</li>
+<li>Kp = proportional gain in PID equation (unitless)</li>
+<li>Ki = integral gain in PID equation (unitless)</li>
+<li>Kd = derivative gain in PID equation (unitless)</li>
+<li>pvar = process variable of form c_ID, c_ID[N], f_ID, f_ID[N], or v_name</li>
+</ul>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c_ID</span> <span class="o">=</span> <span class="k">global</span> <span class="n">scalar</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">compute</span> <span class="k">with</span> <span class="n">ID</span>
+<span class="n">c_ID</span><span class="p">[</span><span class="n">I</span><span class="p">]</span> <span class="o">=</span> <span class="n">Ith</span> <span class="n">component</span> <span class="n">of</span> <span class="k">global</span> <span class="n">vector</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">compute</span> <span class="k">with</span> <span class="n">ID</span>
+<span class="n">f_ID</span> <span class="o">=</span> <span class="k">global</span> <span class="n">scalar</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">fix</span> <span class="k">with</span> <span class="n">ID</span>
+<span class="n">f_ID</span><span class="p">[</span><span class="n">I</span><span class="p">]</span> <span class="o">=</span> <span class="n">Ith</span> <span class="n">component</span> <span class="n">of</span> <span class="k">global</span> <span class="n">vector</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">fix</span> <span class="k">with</span> <span class="n">ID</span>
+<span class="n">v_name</span> <span class="o">=</span> <span class="n">value</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">an</span> <span class="n">equal</span><span class="o">-</span><span class="n">style</span> <span class="n">variable</span> <span class="k">with</span> <span class="n">name</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li>setpoint = desired value of process variable (same units as process variable)</li>
+<li>cvar = name of control variable</li>
+</ul>
+</div>
+<div class="section" id="examples">
+<h2>Examples</h2>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">fix</span> <span class="mi">1</span> <span class="nb">all</span> <span class="n">controller</span> <span class="mi">100</span> <span class="mf">1.0</span> <span class="mf">0.5</span> <span class="mf">0.0</span> <span class="mf">0.0</span> <span class="n">c_thermo_temp</span> <span class="mf">1.5</span> <span class="n">tcontrol</span>
+<span class="n">fix</span> <span class="mi">1</span> <span class="nb">all</span> <span class="n">controller</span> <span class="mi">100</span> <span class="mf">0.2</span> <span class="mf">0.5</span> <span class="mi">0</span> <span class="mf">100.0</span> <span class="n">v_pxxwall</span> <span class="mf">1.01325</span> <span class="n">xwall</span>
+<span class="n">fix</span> <span class="mi">1</span> <span class="nb">all</span> <span class="n">controller</span> <span class="mi">10000</span> <span class="mf">0.2</span> <span class="mf">0.5</span> <span class="mi">0</span> <span class="mi">2000</span> <span class="n">v_avpe</span> <span class="o">-</span><span class="mf">3.785</span> <span class="n">tcontrol</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="description">
+<h2>Description</h2>
+<p>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 &#8220;process variable&#8221; which is
+a quantity that can be monitor during a running simulation.  A desired
+target value is chosen for the process variable.  A &#8220;control variable&#8221;
+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.</p>
+<p>Here are examples of ways in which this fix can be used.  The
+examples/pid directory contains a script that implements the simple
+thermostat.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="49%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>Goal</td>
+<td>process variable</td>
+<td>control variable</td>
+</tr>
+<tr class="row-even"><td>Simple thermostat</td>
+<td>instantaneous T</td>
+<td>thermostat target T</td>
+</tr>
+<tr class="row-odd"><td>Find melting temperature</td>
+<td>average PE per atom</td>
+<td>thermostat target T</td>
+</tr>
+<tr class="row-even"><td>Control pressure in non-periodic system</td>
+<td>force on wall</td>
+<td>position of wall</td>
+</tr>
+<tr class="row-odd"><td>&nbsp;</td>
+<td>&nbsp;</td>
+<td>&nbsp;</td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">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.</p>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">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.</p>
+</div>
+<p>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 &#8220;group&#8221; definitions.</p>
+<p>The PID controller is invoked once each <em>Nevery</em> timesteps.</p>
+<p>The PID controller is implemented as a discretized version of
+the following dynamic equation:</p>
+<img alt="_images/fix_controller1.jpg" class="align-center" src="_images/fix_controller1.jpg" />
+<p>where <em>c</em> is the continuous time analog of the control variable,
+<em>e</em>=<em>pvar</em>-<em>setpoint</em> is the error in the process variable, and
+<em>alpha</em>, <em>Kp</em>, <em>Ki</em>, and <em>Kd</em> are constants set by the corresponding
+keywords described above. The discretized version of this equation is:</p>
+<img alt="_images/fix_controller2.jpg" class="align-center" src="_images/fix_controller2.jpg" />
+<p>where <em>tau</em> = <em>Nevery</em><em>timestep is the time interval between updates,
+and the subsripted variables indicated the values of *c</em> and <em>e</em> at
+successive updates.</p>
+<p>From the first equation, it is clear that if the three gain values
+<em>Kp</em>, <em>Ki</em>, <em>Kd</em> are dimensionless constants, then <em>alpha</em> must have
+units of [unit <em>cvar</em>]/[unit <em>pvar</em>]/[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 <em>Nevery</em>. Similarly, if the LAMMPS <a class="reference internal" href="units.html"><span class="doc">unit style</span></a> is changed, it should only be necessary to change
+the value of <em>alpha</em> to reflect this, while leaving <em>Kp</em>, <em>Ki</em>, and
+<em>Kd</em> unaltered.</p>
+<p>When choosing the values of the four constants, it is best to first
+pick a value and sign for <em>alpha</em> that is consistent with the
+magnitudes and signs of <em>pvar</em> and <em>cvar</em>.  The magnitude of <em>Kp</em>
+should then be tested over a large positive range keeping <em>Ki</em>=<em>Kd</em>=0.
+A good value for <em>Kp</em> will produce a fast reponse in <em>pvar</em>, without
+overshooting the <em>setpoint</em>.  For many applications, proportional
+feedback is sufficient, and so <em>Ki</em>=<em>Kd</em>=0 can be used. In cases where
+there is a substantial lag time in the response of <em>pvar</em> to a change
+in <em>cvar</em>, this can be counteracted by increasing <em>Kd</em>. In situations
+where <em>pvar</em> plateaus without reaching <em>setpoint</em>, this can be
+counteracted by increasing <em>Ki</em>.  In the language of Charles Dickens
+(or Donald Trump), <em>Kp</em> represents the error of the present, <em>Ki</em> the
+error of the past, and <em>Kd</em> the error yet to come.</p>
+<p>Because this fix updates <em>cvar</em>, 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 <em>cvar</em>
+after <em>Nevery</em> timesteps.  On the first update, the value of the
+derivative term is set to zero, because the value of <em>e_n-1</em> is not
+yet defined.</p>
+<hr class="docutils" />
+<p>The process variable <em>pvar</em> can be specified as the output of a
+<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> or <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> or the evaluation of a
+<a class="reference internal" href="variable.html"><span class="doc">variable</span></a>.  In each case, the compute, fix, or variable
+must produce a global quantity, not a per-atom or local quantity.</p>
+<p>If <em>pvar</em> begins with &#8220;<a href="#id1"><span class="problematic" id="id2">c_</span></a>&#8221;, 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 <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> 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 <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
+<p>If <em>pvar</em> begins with &#8220;<a href="#id3"><span class="problematic" id="id4">f_</span></a>&#8221;, 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 <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> 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 <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
+<p>If <em>pvar</em> begins with &#8220;<a href="#id5"><span class="problematic" id="id6">v_</span></a>&#8221;, a variable name must follow which has been
+previously defined in the input script.  Only equal-style variables
+can be referenced.  See the <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> command for
+details.  Note that variables of style <em>equal</em> 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.</p>
+<p>The target value <em>setpoint</em> for the process variable must be a numeric
+value, in whatever units <em>pvar</em> is defined for.</p>
+<p>The control variable <em>cvar</em> must be the name of an <a class="reference internal" href="variable.html"><span class="doc">internal-style variable</span></a> previously defined in the input script.  Note
+that it is not specified with a &#8220;<a href="#id7"><span class="problematic" id="id8">v_</span></a>&#8221; 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.</p>
+</div>
+<hr class="docutils" />
+<div class="section" id="restart-fix-modify-output-run-start-stop-minimize-info">
+<h2>Restart, fix_modify, output, run start/stop, minimize info</h2>
+<p>Currenlty, no information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.  None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
+are relevant to this fix.</p>
+<p>This fix produces a global vector with 3 values which can be accessed
+by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>.  The values
+can be accessed on any timestep, though they are only updated on
+timesteps that are a multiple of <em>Nevery</em>.</p>
+<p>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.</p>
+<p>The units of the vector values will be whatever units the control
+variable is in.  The vector values calculated by this fix are
+&#8220;extensive&#8221;.</p>
+<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
+the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.  This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
+</div>
+<div class="section" id="restrictions">
+<h2>Restrictions</h2>
+<blockquote>
+<div>none</div></blockquote>
+</div>
+<div class="section" id="related-commands">
+<h2>Related commands</h2>
+<p><a class="reference internal" href="fix_adapt.html"><span class="doc">fix adapt</span></a></p>
+<p><strong>Default:</strong> none</p>
+</div>
+</div>
+
+
+           </div>
+          </div>
+          <footer>
+  
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>
+        &copy; Copyright 2013 Sandia Corporation.
+    </p>
+  </div>
+  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
+
+</footer>
+
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+  
+
+
+  
+
+    <script type="text/javascript">
+        var DOCUMENTATION_OPTIONS = {
+            URL_ROOT:'./',
+            VERSION:'',
+            COLLAPSE_INDEX:false,
+            FILE_SUFFIX:'.html',
+            HAS_SOURCE:  true
+        };
+    </script>
+      <script type="text/javascript" src="_static/jquery.js"></script>
+      <script type="text/javascript" src="_static/underscore.js"></script>
+      <script type="text/javascript" src="_static/doctools.js"></script>
+      <script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+      <script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
+      <script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
+      <script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
+
+  
+
+  
+  
+    <script type="text/javascript" src="_static/js/theme.js"></script>
+  
+
+  
+  
+  <script type="text/javascript">
+      jQuery(function () {
+          SphinxRtdTheme.StickyNav.enable();
+      });
+  </script>
+   
+
+</body>
+</html>

doc/html/genindex.html

@@ -1034,6 +1034,10 @@
   </dt>
 
       
+  <dt><a href="fix_controller.html#index-0">fix controller</a>
+  </dt>
+
+      
   <dt><a href="fix_deform.html#index-0">fix deform</a>
   </dt>
 

doc/html/thermo_modify.html

@@ -230,8 +230,8 @@ is more than one field.  The <em>int</em> and <em>float</em> keywords take a sin
 format argument and are applied to all integer or floating-point
 quantities output.  The setting for <em>M string</em> 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 &#8220;format
+e.g. the 5th column is output in high precision for &#8220;format 5
-5 %20.15g&#8221;.</p>
+%20.15g&#8221;.</p>
 <p>The <em>format</em> keyword can be used multiple times.  The precedence is
 that for each value in a line of output, the <em>M</em> format (if specified)
 is used, else the <em>int</em> or <em>float</em> setting (if specified) is used,

doc/html/variable.html

@@ -133,7 +133,7 @@
 </div>
 <ul class="simple">
 <li>name = name of variable to define</li>
-<li>style = <em>delete</em> or <em>index</em> or <em>loop</em> or <em>world</em> or <em>universe</em> or <em>uloop</em> or <em>string</em> or <em>format</em> or <em>getenv</em> or <em>file</em> or <em>atomfile</em> or <em>python</em> or <em>equal</em> or <em>vector</em> or <em>atom</em></li>
+<li>style = <em>delete</em> or <em>index</em> or <em>loop</em> or <em>world</em> or <em>universe</em> or <em>uloop</em> or <em>string</em> or <em>format</em> or <em>getenv</em> or <em>file</em> or <em>atomfile</em> or <em>python</em> or <em>internal</em> or <em>equal</em> or <em>vector</em> or <em>atom</em></li>
 </ul>
 <pre class="literal-block">
 <em>delete</em> = no args
@@ -163,6 +163,7 @@
 <em>file</em> arg = filename
 <em>atomfile</em> arg = filename
 <em>python</em> arg = function
+<em>internal</em> arg = numeric value
 <em>equal</em> or <em>vector</em> or <em>atom</em> 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 <em>python</em> can be hooked to Python functions using code you
 provide, so that the variable gets its value from the evaluation of
-the Python code.</p>
+the Python code.  Variables of style <em>internal</em> are used by a few
+commands in LAMMPS which set their value directly.</p>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
 <p class="last">As discussed in <a class="reference internal" href="Section_commands.html#cmd-2"><span class="std std-ref">Section 3.2</span></a> of the
@@ -277,14 +280,21 @@ when it is invoked.</p>
 <p class="last">Variables of style <em>equal</em> and <em>vector</em> and <em>atom</em> can be used
 as inputs to various other LAMMPS commands which evaluate their
 formulas as needed, e.g. at different timesteps during a
-<a class="reference internal" href="run.html"><span class="doc">run</span></a>.  Variables of style <em>python</em> can be used in place of
+<a class="reference internal" href="run.html"><span class="doc">run</span></a>.</p>
-an equal-style variable so long as the associated Python function, as
-defined by the <a class="reference internal" href="python.html"><span class="doc">python</span></a> 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.</p>
 </div>
+<p>Variables of style <em>internal</em> 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.</p>
+<p>Variables of style <em>python</em> can be used in place of an equal-style
+variable so long as the associated Python function, as defined by the
+<a class="reference internal" href="python.html"><span class="doc">python</span></a> 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.</p>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
 <p class="last">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.</p>
 </div>
 <p>There are two exceptions to this rule.  First, variables of style
-<em>string</em>, <em>getenv</em>, <em>equal</em>, <em>vector</em>, <em>atom</em>, and <em>python</em> ARE
+<em>string</em>, <em>getenv</em>, <em>equal</em>, <em>vector</em>, <em>atom</em>, <em>internal</em>, and
-redefined each time the command is encountered.  This allows these
+<em>python</em> ARE redefined each time the command is encountered.  This
-style of variables to be redefined multiple times in an input script.
+allows these style of variables to be redefined multiple times in an
-In a loop, this means the formula associated with an <em>equal</em> or <em>atom</em>
+input script.  In a loop, this means the formula associated with an
-style variable can change if it contains a substitution for another
+<em>equal</em> or <em>atom</em> style variable can change if it contains a
-variable, e.g. $x or v_x.</p>
+substitution for another variable, e.g. $x or v_x.</p>
 <p>Second, as described below, if a variable is iterated on to the end of
 its list of strings via the <a class="reference internal" href="next.html"><span class="doc">next</span></a> command, it is removed
 from the list of active variables, and is thus available to be
@@ -463,7 +473,7 @@ appear in the set, will remain 0.0.</p>
 <p>For the <em>python</em> style a Python function name is provided.  This needs
 to match a function name specified in a <a class="reference internal" href="python.html"><span class="doc">python</span></a> command
 which returns a value to this variable as defined by its <em>return</em>
-keyword.  For exampe these two commands would be self-consistent:</p>
+keyword.  For example these two commands would be self-consistent:</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">variable</span> <span class="n">foo</span> <span class="n">python</span> <span class="n">myMultiply</span>
 <span class="n">python</span> <span class="n">myMultiply</span> <span class="k">return</span> <span class="n">v_foo</span> <span class="nb">format</span> <span class="n">f</span> <span class="n">file</span> <span class="n">funcs</span><span class="o">.</span><span class="n">py</span>
 </pre></div>
@@ -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.</p>
+<p>For the <em>internal</em> 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
+<em>internal</em> variables as inputs, because they reset them:
+<a class="reference internal" href="create_atoms.html"><span class="doc">create_atoms</span></a> and <a class="reference internal" href="fix_controller.html"><span class="doc">fix controller</span></a>.  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.</p>
 <hr class="docutils" />
 <p>For the <em>equal</em> and <em>vector</em> and <em>atom</em> styles, a single string is
 specified which represents a formula that will be evaluated afresh

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
+their initial numeric value can be anything.  They must be
-used to identify the names of these other variables, one variable for
+internal-style variables, because this command updates their values
-the x-coordinate of a created atom, one for y, and one for z.
+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

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
+"run"_run.html.  
-an equal-style variable so long as the associated Python function, as
+
-defined by the "python"_python.html command, returns a numeric value.
+Variables of style {internal} can be used in place of an equal-style
-Thus any command that states it can use an equal-style variable as an
+variable, except by commands that set the value in the internal-style
-argument, can also use such a python-style variable.  This means that
+variable.  Thus any command that states it can use an equal-style
-when the LAMMPS command evaluates the variable, the Python function
+variable as an argument, can also use an internal-style variable.
-will be executed.
+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
+{string}, {getenv}, {equal}, {vector}, {atom}, {internal}, and
-redefined each time the command is encountered.  This allows these
+{python} ARE redefined each time the command is encountered.  This
-style of variables to be redefined multiple times in an input script.
+allows these style of variables to be redefined multiple times in an
-In a loop, this means the formula associated with an {equal} or {atom}
+input script.  In a loop, this means the formula associated with an
-style variable can change if it contains a substitution for another
+{equal} or {atom} style variable can change if it contains a
-variable, e.g. $x or v_x.
+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