src/pyafm/auxiliary.tex

   1 \section{Auxiliary packages}
   2 \label{sec:pyafm:auxiliary}
   3
   4 The previous section covered the core of the experiment stack
   5 (\cref{sec:pyafm:stack}), but skipped over some of the more peripheral
   6 packages.
   7
   8 \subsection{h5config}
   9 \label{sec:pyafm:h5config}
  10
  11 The \hFconfig\ package makes it easy to save and load configuration
  12 classes from disk.  After populating base configuration classes with
  13 parameters (\cref{fig:h5config}), \hFconfig\ automatically generates
  14 \citetalias{hdf5} and \citetalias{yaml} backends for saving and
  15 loading that class.
  16
  17 \begin{figure}
  18   \begin{center}
  19 \begin{minted}[mathescape]{python}
  20 import h5config.config as _config
  21
  22 class AxisConfig (_config.Config):
  23     "Configure a single piezo axis"
  24     settings = [
  25         _config.FloatSetting(
  26             name='gain',
  27             help=(
  28                 'Volts applied at piezo per volt output from the DAQ card '
  29                 '(e.g. if your DAQ output is amplified before driving the '
  30                 'piezo),')),
  31         _config.FloatSetting(
  32             name='sensitivity',
  33             help='Meters of piezo deflection per volt applied to the piezo.'),
  34         # $\ldots$
  35         _config.ConfigSetting(
  36             name='channel',
  37             help='Configure the underlying DAC channel.',
  38             config_class=OutputChannelConfig,
  39             default=None),
  40         # $\ldots$
  41         ]
  42 \end{minted}
  43     \caption{Portions of the configuration class for a single piezo
  44       axis (from \pypiezo, \cref{sec:pyafm:pypiezo}).  The more
  45       generic analog output channel configuration is nested under the
  46       \imint{python}|channel| setting.\label{fig:h5config}}
  47   \end{center}
  48 \end{figure}
  49
  50 Basic configuration types include booleans, integers, floating point
  51 numbers, enumerated choices, and freeform text.  There is also support
  52 for lists of these basic types (e.g.~lists of integers).  The key
  53 feature is nesting configuration classes.  This means that your higher
  54 level tools can have their own configuration settings and also include
  55 the configuration settings for their lower level components.  For
  56 example, the piezo axis configuration given in \cref{fig:h5config}
  57 contains configuration settings specific to piezo axes, and it also
  58 contains a reference to the configuration settings for a generic
  59 analog output channel.  The piezo axis code doesn't need to know what
  60 the analog output channel configuration settings are, those are
  61 defined somewhere else.
  62
  63 The nesting continues all the way up the stack, to the
  64 \unfoldprotein\ configuration.  This means that a single file
  65 (\imint{console}|~/.config/unfold_protein.yaml|) contains every
  66 configurable setting required for the whole experiment in an
  67 easy-to-edit text format.  Adding additional configuration settings at
  68 any level of the experiment stack is just a matter of adjusting a
  69 single \imint{python}|h5config.config.Config| subclass the
  70 corresponding entry in the configuration file.  There is no need to
  71 adjust the higher level code, the new setting is passed down the stack
  72 to its point of use automatically.
  73
  74 Besides making it easy to configure your experiment, \hFconfig\ also
  75 makes it easy to save the configuration alongside your data.  The
  76 section of \unfoldprotein\ that writes the whole configuration stack
  77 into the per-pull HDF5 file is only four lines long.  This makes
  78 post-processing much easier, because almost every setting needed to
  79 analyze the data is already stored in the data file (the only missing
  80 values are those that you did not need during the experiment control
  81 phase).
  82
  83 \subsection{stepper}
  84 \label{sec:pyafm:stepper}
  85
  86 The \stepper\ package provides Python control of stepper
  87 motors\cite{jones95}.  The package is mostly concerned with the
  88 maintenance of internal motor state:
  89
  90 \begin{description}
  91   \item[position] is a half-step counter that records the current
  92     motor position.
  93   \item[full step] selects full or half stepping.
  94   \item[logic] selects active high or active low operation.
  95   \item[delay] sets the time delay between steps in seconds, in case
  96     the motor response is slower than the digital output driver.
  97   \item[step size] approximates the step size in meters.
  98   \item[backlash] estimates the drive chain backlash in half-steps.
  99 \end{description}
 100
 101 Actualizing the motor control signal is left up to the caller, in this
 102 case \pyafm.
 103
 104 TODO: backlash and step-size graphics.
 105
 106 \subsection{pypid}
 107 \label{sec:pyafm:pypid}
 108
 109 The final component of the experiment control stack is \pypid, which
 110 uses \citetalias{pymodbus} to communicate with a Melcor Series MTCA
 111 Thermoelectric Cooler Controller\citep{melcor} over a serial line.
 112 The controller monitors the fluid cell temperature with a
 113 thermocouple, and reading temperatures from the controller is fairly
 114 straightforward (\cref{fig:unfold-protein:unfolder}).  Temperature
 115 control is via a peltier mounted underneath the sample surface
 116 (\cref{fig:peltier}).
 117
 118 \begin{figure}
 119   \begin{center}
 120     % TODO: peltier image
 121   \end{center}
 122   \caption{TODO.\label{fig:peltier}}
 123 \end{figure}
 124
 125 The controller tries to keep the measured temperature at the setpoint
 126 temperature via a modified proportional-integral-derivative (PID)
 127 feedback algorithm.  PID systems have been around for a
 128 while\citep{ziegler42}, but finding appropriate feedback terms for
 129 sensitive systems is not trivial.  There are a number of tuning
 130 procedures which characterize the system by evaluating its response
 131 under simpler driving conditions.  The \pypid\ package implements
 132 Ziegler--Nichols' step response\citep{ziegler42}, bang-bang
 133 response\citep{TODO}, ultimate cycle response\citep{ziegler42} tuning
 134 rules, as well as Cohen--Coon's\citep{cohen53} and
 135 Wang--Juang--Chan's\citep{wang95} step response tuning
 136 rules\citep{astrom93}.
 137
 138 \nomenclature{PID}{Proportional-integral-derivative feedback.  For a
 139   process value $p$, setpoint $p_0$, and manipulated variable $m$, the
 140   standard PID algorithm is
 141   \begin{align}
 142     m(t) &= K_p e(t) + K_i \integral{0}{t}{\tau}{e(\tau)}
 143             + K_d \deriv{t}{e(t)} \\
 144     e(t) &= p_0 - p \;,
 145   \end{align}
 146   where $e$ is the error function, $K_p$ is the proportional gain,
 147   $K_i$ is the integral gain, and $K_d$ is the derivative gain.}