diff --git a/doc/src/Eqs/fix_controller1.jpg b/doc/src/Eqs/fix_controller1.jpg deleted file mode 100644 index 25f381543f..0000000000 Binary files a/doc/src/Eqs/fix_controller1.jpg and /dev/null differ diff --git a/doc/src/Eqs/fix_controller1.tex b/doc/src/Eqs/fix_controller1.tex deleted file mode 100644 index 14f98fc303..0000000000 --- a/doc/src/Eqs/fix_controller1.tex +++ /dev/null @@ -1,12 +0,0 @@ -\documentclass[24pt]{article} - -\pagestyle{empty} -\Huge - -\begin{document} - -\begin{eqnarray*} -\frac{dc}{dt} &=&Ê -\alpha (K_p e + K_i \int_0^t e \, dt + K_d \frac{de}{dt} ) \\ -\end{eqnarray*} - -\end{document} diff --git a/doc/src/Eqs/fix_controller2.jpg b/doc/src/Eqs/fix_controller2.jpg deleted file mode 100644 index 178fd5a67e..0000000000 Binary files a/doc/src/Eqs/fix_controller2.jpg and /dev/null differ diff --git a/doc/src/Eqs/fix_controller2.tex b/doc/src/Eqs/fix_controller2.tex deleted file mode 100644 index 7bcaa333ad..0000000000 --- a/doc/src/Eqs/fix_controller2.tex +++ /dev/null @@ -1,12 +0,0 @@ -\documentclass[24pt]{article} - -\pagestyle{empty} -\Huge - -\begin{document} - -\begin{eqnarray*} -c_n &=&Ê c_{n-1} -\alpha (K_p \tau e_n + K_i \tau^2 \sum_{i=1}^n e_i + K_d (e_n - e_{n-1}) ) -\end{eqnarray*} - -\end{document} diff --git a/doc/src/fix_controller.rst b/doc/src/fix_controller.rst index 7561df6856..839c01ef5f 100644 --- a/doc/src/fix_controller.rst +++ b/doc/src/fix_controller.rst @@ -97,43 +97,49 @@ 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 +.. math:: + \frac{dc}{dt} = \hat{E} -\alpha (K_p e + K_i \int_0^t e \, dt + K_d \frac{de}{dt} ) + 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 +:math:`\alpha`, :math:`K_p`, :math:`K_i` , and :math:`K_d` are constants +set by the corresponding keywords described above. The discretized version of this equation is: -.. image:: Eqs/fix_controller2.jpg - :align: center +.. math:: -where *tau* = *Nevery* \* *timestep* is the time interval between updates, + c_n = \hat{E} c_{n-1} -\alpha \left( K_p \tau e_n + K_i \tau^2 \sum_{i=1}^n e_i + K_d (e_n - e_{n-1}) \right) + + +where :math:`\tau = \mathtt{Nevery} \cdot \mathtt{timestep}` is the time +interval between updates, and the subscripted variables indicate 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 +:math:`K_p`, :math:`K_i`, :math:`K_d` are dimensionless constants, +then :math:`\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. +the value of :math:`\alpha` to reflect this, while leaving :math:`K_p`, +:math:`K_i`, and :math:`K_d` 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 response 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 +pick a value and sign for :math:`\alpha` that is consistent with the +magnitudes and signs of *pvar* and *cvar*\ . The magnitude of :math:`K_p` +should then be tested over a large positive range keeping :math:`K_i = K_d =0`. +A good value for :math:`K_p` will produce a fast response in *pvar*\ , +without overshooting the *setpoint*\ . For many applications, proportional +feedback is sufficient, and so :math:`K_i` = K_d =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 :math:`K_d`. In situations where *pvar* plateaus without reaching *setpoint*\ , this can be -counteracted by increasing *Ki*\ . In the language of Charles Dickens, -*Kp* represents the error of the present, *Ki* the error of the past, -and *Kd* the error yet to come. +counteracted by increasing :math:`K_i`. In the language of Charles Dickens, +:math:`K_p` represents the error of the present, :math:`K_i` the error of +the past, and :math:`K_d` 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 input script via @@ -141,7 +147,7 @@ the :doc:`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. +because the value of :math:`e_n-1` is not yet defined. ----------