From 9163f09b69769c0ec52adf337785fd700ace005d Mon Sep 17 00:00:00 2001
From: Blaise Thompson <blaise@untzag.com>
Date: Tue, 10 Apr 2018 20:14:00 -0500
Subject: 2018-04-10 20:13

---
 acquisition/chapter.tex | 116 +++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 90 insertions(+), 26 deletions(-)

(limited to 'acquisition/chapter.tex')

diff --git a/acquisition/chapter.tex b/acquisition/chapter.tex
index 02be26a..803049e 100644
--- a/acquisition/chapter.tex
+++ b/acquisition/chapter.tex
@@ -94,6 +94,26 @@ between them.  %
 
 % TODO: describe each of the sections of this chapter
 
+In designing PyCMDS, I was inspired by the nervous system...
+
+\begin{dquote}
+  The autonomic nervous system, which innervates primarily the smooth musculature of all organs,
+  the heart and the glands, mediates the neuronal regulation of the internal milieu.  %
+  The actions of this system, as its name implies, are in general not under direct voluntary
+  control.  %
+  These characteristics distinguish the autonomic nervous system from the somatic nervous system,
+  which mediates afferent and efferent communication with the enviornment and, for the most part,
+  is subject to voluntary control and accessible to consciousness.  %
+
+  The autonomic and somatic systems operate hand in hand...
+
+  The functions of the autnomic nervous system are to keep the internal milieu of the body constant
+  (homeostasis...) or adjust it as required by changing circumstances (e.g., mechanical work, food
+  intake, water deprivation, heat or cold).  %
+
+  \dsignature{W. J\"{a}nig, Autonomic Nervous System (1989) \cite{JanigW1989a}}
+\end{dquote}
+
 \clearpage
 \section{Graphical user interface}  % =============================================================
 
@@ -385,6 +405,8 @@ which point \python{Driver.dequeue} will be called in the worker thread.  %
 There is no way for the driver to command hardware to do something in the main thread, but the
 driver can trigger signals like \python{update_ui} and modify Mutexes.  % 
 
+[PARENTS ARE VIRTUAL HARDWARE]
+
 \begin{figure}
 	\includepython{"acquisition/parent_hardware.py"}
   \caption[Parent to hardware and sensors.]{
@@ -409,8 +431,8 @@ The PyCMDS GUI must change depending on which exact hardware, sensors, and acqui
 being used on a given instrument and given day.  %
 Internally, the GUI components are made to be modular and flexable to accommodate this
 requirement.  %
-
-[programmatically defined GUI]
+Rather than having each piece placed ``by hand'', the PyCMDS GUI is defined programmatically and,
+as such, the full power of abstraction and inheritance is available to the GUI-defining code.  %
 
 To keep things simple and easy to extend, PyCMDS is made up of only a few minimalist GUI
 elements.  %
@@ -460,6 +482,8 @@ delay stage.  %
 
 PyCMDS uses pyqtgraph \cite{pyqtgraph} for interactive plotting.  %
 pyqtgraph is great because it is optimized for speed and interactivity.  %
+Currently only line plots are supported (through the \python{PyCMDS.project.widgets.Plot1D} class),
+but 2D plots are supported by pyqtgraph and could be added in future versions.  %
 
 For those wanting to learn more, all graphical components are defined in
 \bash{PyCMDS/project/widgets.py}.  %
@@ -639,39 +663,83 @@ Old boxcar: 300 ns window, ~10 micosecond delay. Onset of saturation ~2 V.
 
 \section{Autonomic} \label{aqn:sec:autonomic}  % ==================================================
 
-\begin{dquote}
-  The autonomic nervous system, which innervates primarily the smooth musculature of all organs,
-  the heart and the glands, mediates the neuronal regulation of the internal milieu.  %
-  The actions of this system, as its name implies, are in general not under direct voluntary
-  control.  %
-  These characteristics distinguish the autonomic nervous system from the somatic nervous system,
-  which mediates afferent and efferent communication with the enviornment and, for the most part,
-  is subject to voluntary control and accessible to consciousness.  %
+The autonomic system is used to define ``reflexes'' for PyCMDS---operations that are automatically
+applied when certain conditions are met.  %
+Currently the autonomic system has only functionality: \emph{offset} certain hardware as functional
+of other hardware's positions.  %
 
-  The autonomic and somatic systems operate hand in hand...
+The classic example of autonomic offsets comes from spectral delay correction (see section
+[ACT]).  %
+Spectral delay refers to the small delay changes that occur when OPAs change output frequency.  %
+To correct for spectral delay, the appropriate delay stages can simply be \emph{offset}.  %
 
-  The functions of the autnomic nervous system are to keep the internal milieu of the body constant
-  (homeostasis...) or adjust it as required by changing circumstances (e.g., mechanical work, food
-  intake, water deprivation, heat or cold).  %
+In PyCMDS, the autonomic system is fully general---that is to say, any hardware can be offset
+according to any other hardware.  %
+This means that spectral delay correction is possible for arbitrarily complex laser setups, and it
+means that PyCMDS is prepared for corrections that have not yet been fully implemented, such as
+automated power correction.  %
 
-  \dsignature{W. J\"{a}nig, Autonomic Nervous System (1989) \cite{JanigW1989a}}
-\end{dquote}
+Simple plain-text \bash{.coset} files define the offset arrays.  %
+They are automatically generated using processing scripts in \python{attune} [CITE].  %
+Their headers prevent them from being loaded in the wrong spot.  %
+These files are internally represented as instances of the \python{CoSet} class, which is capable
+of linear interpolation and extrapolation at the edges.  %
 
-% TODO: concept of additive offsets
+A single hardware can be offset by multiple other hardwares.  %
+In such cases, \emph{offsets always add}.  %
 
 \begin{figure}
-  \caption[Representative spectral delay correction]{
-    CAPTION TODO
-  }
-  \label{aqn:fig:sdc}
+  \caption{AUTONOMIC SDC SCREENSHOT}
 \end{figure}
-  
+
+\clearpage
 \section{Somatic} \label{aqn:sec:somatic} % =======================================================
 
 In contrast with the autonomic system (\autoref{aqn:sec:autonomic}), the somatic system is all
 about voluntary, user specified motion.  %
 This is where the fun stuff happens---the acquisitions!
 
+PyCMDS uses the words ``scan'' and ``acquisition'' in very careful ways.  %
+\begin{ditemize}
+  \item An acquisition is a single user-defined, enqueable, instruction.
+  \item A scan is a single traversal in the multidimensional hardware space.  %
+\end{ditemize}
+Each scan corresponds to one \bash{.data} file, and one WrightTools \python{Data} instance (see
+section ...)  %
+There can be many scans within a single acquisition.  %
+And there can be many acquisitions in a queue.  %
+
+PyCMDS saves the data that it is collecting within a nested folder structure
+queue/acquisition/scan.  %
+A \bash{.queue} file holds everything needed to recreate the queue, \python{.aqn} files define each
+acquisition in plain text and \python{.data} files hold the multidimensional data itself.  %
+
+In this section I describe each component of the somatic system in greater detail.  %
+
+\subsection{Queue manager}  % ---------------------------------------------------------------------
+
+The queue manager keeps track of all enqueued acquisitions, and tells each acquisition when to
+begin.  %
+A singleton \python{Queue} class lives in the main thread and handles interfacing to the
+\bash{.queue} plain-text file.  %
+When a user appends new acquisitions, or changes their order, the \python{queue} instance makes
+sure that those changes are reflected in the GUI and the file.  %
+
+A special singleton \python{QueueStatus} keeps track of, well, the queue status: a series of
+booleans \python{go}, \python{going}, \python{pause}, \python{paused}, \python{stop}, and
+\python{stopped}.  %
+The verb booleans (\python{go}, \python{pause}, \python{paused}), are control flags, to be
+written by the main thread.  %
+The present particple booleans (\python{going}, \python{paused}, \python{stopped}) are flags to be
+written by the worker thread to indicate status of the current acquisition.  %
+
+A singleton \python{Worker} class lives in the acquisition worker thread and carries out the actual
+operation.  %
+The \python{queue} instance pushes operations to the \python{worker}, and the \python{worker} sends
+a signal that causes \python{queue.on_action_complete} to be called.  %
+If there are more enqueued acquisitions, and \python{queue_status.go} is true, the \python{queue}
+instance pushes the next operation to the \python{worker} and the process starts over again.  %
+
 \subsection{Scans}  % -----------------------------------------------------------------------------
 
 The central loop of scans in PyCMDS.  %
@@ -731,10 +799,6 @@ Automatically do appropriate scans and process as in chapter...
 
 Dedicated to poynting (get content from Kyle S)...
 
-z\subsection{Queue manager}  % ---------------------------------------------------------------------
-
-\subsection{The central loop of PyCMDS}  % --------------------------------------------------------
-
 \subsection{The data file}  % ---------------------------------------------------------------------
 
 Does not have the same dimensionality restrictions as prior acquisition software.  %
-- 
cgit v1.2.3

