From 8c9fc50d417809d7c5ad1b512f55c83307a83364 Mon Sep 17 00:00:00 2001
From: Blaise Thompson <blaise@untzag.com>
Date: Tue, 27 Mar 2018 00:25:35 -0500
Subject: 2018-03-27 00:25

---
 acquisition/chapter.tex | 156 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 155 insertions(+), 1 deletion(-)

(limited to 'acquisition/chapter.tex')

diff --git a/acquisition/chapter.tex b/acquisition/chapter.tex
index 8e75cc1..1525b9e 100644
--- a/acquisition/chapter.tex
+++ b/acquisition/chapter.tex
@@ -26,8 +26,156 @@ PyCMDS has, through software improvements alone, dramatically lessened scan time
 	\item ideal axis positions \ref{acq:sec:ideal_axis_positions}
 \end{ditemize}
 
+% TODO: screenshot
+
+% TODO: modularity
+
+% TODO: n-dimensional scans...
+
+% TODO: calibration
+
+\section{Structure}  % ============================================================================
+
+I think of PyCMDS as a central program with three kinds of modular ``plugins'' that can be extended
+indefinitely:
+\begin{ditemize}
+  \item Hardware: things that can be set to a position (\autoref{aqn:sec:hardware}).
+  \item Sensors: things that can be used to measure a signal (\autoref{aqn:sec:sensors}).
+  \item Acquisition modules: things that can be used to define and carry out an acquisition, and
+    associated post-processing (\autoref{aqn:sec:somatic}).
+\end{ditemize}
+The first design rule for PyCMDS is that these three things should be easy for the average
+(motivated) user to add by herself.  %
+Modularity and extensibility is important for all software projects, but it is of paramount
+importance for acquisition software simply because the diversity of hardware and experimental
+configurations is so great.  %
+It is conceivable to imagine 90\% overlap between the data processing and simulation needs of one
+spectroscopist to the next, but there is almost no overlap between hardware configurations even in
+the two primary instruments maintained by the Wright Group.  %
+Besides the extendable modular pieces, the rest of PyCMDS is a mostly-static code-base that accepts
+modules and does the necessary things to handle display of information from, and communication
+between them.  %
+
+For the kinds of acquisitions that the Wright Group has done the acquisition software spends the
+vast majority of its run-time waiting---waiting for user input through mouse clicks or keyboard
+presses, waiting for hardware to finish moving or for sensors to finish reading and return
+signals.  %
+Despite all of this downtime, it is crucial that the software respond very quickly when
+instructions or signals are recieved.  %
+A multi-threaded implementation is necessary to achieve this.  %
+The main thread handles the graphical user interface (GUI) and other top level things.  %
+Everything else happens in child threads.  %
+Each hardware instance (e.g. a delay stage) lives in its own thread, as does each sensor.  %
+Since only one scan happens at a time, all acquisition modules share a single thread that handles
+the orchestration of hardware motion, sensor operation, and data processing that the chosen
+acquisition requires. %
+
+Threads are powerful because they allow for ``semi-synchronous'' operation.  %
+Imagine PyCMDS is in the middle of a 2D delay-delay scan, and the scan thread has just told each of
+the two delay stages to head to their positions.  %
+PyCMDS must sit in a tight loop to keep track of the position as closely as possible during motor
+motion.  %
+In a single-threaded configuration, this tight loop would only run for one delay at a time, such
+that PyCMDS would have to finish shepherding one delay stage before turning its attention to the
+second.  %
+In a multi-threaded configuration, each thread will run simultaniously, switching off CPU cycles at
+a low level far faster than human comprehension.  %
+This switching is handled in an OS and hardware specific way---luckily it is all abstracted through
+platform-agnostic Qt threads.  %
+
+Threads are dangerous because it is hard to pass information between them.  %
+Thus, mutexes... signals and slots...
+
+Without getting into details, let's investigate the key ``signals and slots'' that hardware and
+sensors have.  %
+% TODO: elaborate
+
+The central loop of scans in PyCMDS.  %
+\begin{codefragment}{python, label=aqn:lst:loop_simple}
+for coordinates in list_of_coordinates:
+  for hardware, coordinate in zip(hardwares, coordinates):
+      hardware.set(coordinate)
+  for hardware in hardwares:
+      hardware.wait_until_still()
+  for sensor in sensors:
+      sensor.read()    
+  for sensor in sensors:
+      sensor.wait_until_done() 
+\end{codefragment}
+
+\subsection{Conditional validity}  % --------------------------------------------------------------
+
+The central conceit of the PyCMDS modular hardware abstraction is that experiments can be boiled
+down to a set of orthogonal axes that can be set separately from other hardware and sensor
+status.  %
+This requirement is loosened by the autonomic and expression systems, such that any experiment
+could \emph{probably} be forced into PyCMDS, but still the conceit stands---PyCMDS is probably
+\emph{not} the correct framework if your experiment cannot be reduced in this way.  %
+From this we can see that it is useful to talk about the conditional validity of the modular
+hardware abstraction.  %
+
+The important axis is hardware complexity vs measurement complexity.
+
+For hardware-complex problems, the challenge is coordination.  %
+MR-CMDS is the perfect example of a hardware-complex problem.  %
+MR-CMDS is composed of a collection (typically 5 to 10 members) of relatively simple hardware
+components.  %
+The challenge is that experiments involve complex ``dances'', including expressions, of the
+component hardwares.  %
+
+For measurement-complex problems, the challenge is, well, the measurement.  %
+These are experiments where every little piece of the instrument is tied together into a complex
+network of inseparable parts.  %
+These are often time-domain or ``single shot'' measurements.  %
+Consider work of (GRAPES INVENTOR).  %
+Such instruments are typically much faster at data acquisition and more reliable.  %
+This comes at a price of flexibility: often such instruments cannot be modified or enhanced without
+touching everything.  %
+
+From an acquisition software perspective, measurement-complex problems are not amenable to general
+purpose modular software design.  %
+The instrument is so custom that it certainly requires entirely custom software.  %
+
+Measurements can be neither hardware-complex nor software-complex (simple) or both (expensive).  %
+Conceptually, can imagine a 4 quadrant system.  %
+
+Thus PyCMDS can be proud to try and generalize the hardware-complex part of acquisition software
+because indeed that is all that can be generalized.  %
+
+% TODO: 4 quadrants of complexity figure
+
+\section{Hardware} \label{aqn:sec:hardware}  % ====================================================
+
+\section{Sensors (devices)} \label{aqn:sec:sensors}  % ============================================
+
+\subsection{Sensors as axes}  % -------------------------------------------------------------------
+
+\section{Autonomic}  % ============================================================================
+
+% TODO: concept of additive offsets
+
+\section{Somatic} \label{aqn:sec:somatic} % =======================================================
+
+\subsection{Acquisition modules}  % ---------------------------------------------------------------
+
+% TODO: the aqn file
+
+% TODO: list of modules, descriptions thereof
+
+\subsection{Queue manager}  % ---------------------------------------------------------------------
+
+\subsection{The central loop of PyCMDS}  % --------------------------------------------------------
+
+\subsection{The data file}  % ---------------------------------------------------------------------
+
+\subsection{Automatic processing}  % --------------------------------------------------------------
+
 \section{Future directions}  % ====================================================================
 
+\subsection{Spectral delay correction module}  % --------------------------------------------------
+
+\subsection{``Headless'' hardware, sensors}  % ----------------------------------------------------
+
 \subsection{Ideal Axis Positions} \label{acq:sec:ideal_axis_positions}  % -------------------------
 
 Frequency domain multidimensional spectroscopy is a time-intensive process.  %
@@ -138,4 +286,10 @@ S_n &=& (1-c)\left(\frac{n}{N}\right)^{\frac{\tau_{\mathrm{step}}}{\tau_{\mathrm
 
 \subsubsection{Lorentzian}
 
-\subsubsection{Bimolecular}
\ No newline at end of file
+\subsubsection{Bimolecular}
+
+\subsection{Simultanious acquisitions}  % ---------------------------------------------------------
+
+\subsection{Enhanced modularity}  % ---------------------------------------------------------------
+
+\subsection{wt5 savefile}  % ----------------------------------------------------------------------
\ No newline at end of file
-- 
cgit v1.2.3

