From b39e06358bdee394d9a4942996546e7d79bc39f4 Mon Sep 17 00:00:00 2001
From: Blaise Thompson <blaise@untzag.com>
Date: Wed, 11 Apr 2018 18:15:27 -0500
Subject: 2018-04-11 18:15

---
 acquisition/chapter.tex | 103 ++++++++++++++++++++++++++++++++++--------------
 1 file changed, 74 insertions(+), 29 deletions(-)

(limited to 'acquisition/chapter.tex')

diff --git a/acquisition/chapter.tex b/acquisition/chapter.tex
index 86c5c8c..e60e0a7 100644
--- a/acquisition/chapter.tex
+++ b/acquisition/chapter.tex
@@ -141,6 +141,9 @@ acquiring a multidimensional scan.  %
 \clearpage
 \section{Graphical user interface}  % =============================================================
 
+In this section I introduce the GUI of PyCMDS, with the goal of introducing the basic structure as
+experienced by a first time user of the software.  %
+
 When PyCMDS starts up, the GUI is constructed out of modules depending on which hardware and
 sensors the user has instructed the program to address.  %
 A screenshot of the PyCMDS GUI, running on the fs table, is shown in
@@ -154,7 +157,7 @@ display.  %
 Each hardware knows its own limits, displayed in a tool tip when hovering over the control.  %
 Users cannot type values outside of hardware limits into the controls.  %
 Each hardware also has an ``ADVANCED'' button, which takes the user to a more extensive GUI to
-control lots more features (see section ....)  %
+control lots more features [SECTION].  %
 At the very top, on the left hand side, is the ``SHUT DOWN'' button.  %
 
 On the right hand side there is a extensive set of nested tabs.  %
@@ -166,19 +169,9 @@ Some of these elements are themselves tabbed, like the ``Somatic'' tab (active i
 At the top of the right hand side there is a progress bar and queue status display, which I will
 discuss further in future sections.  %
 
-\begin{landscape}
-\begin{figure}
-	\includegraphics[scale=0.5]{"acquisition/screenshots/005"}
-  \caption[PyCMDS at startup.]{
-    PyCMDS at startup, on the fs system.  %
-  }
-  \label{aqn:fig:pycmds_screenshot}
-\end{figure}
-\end{landscape}
-
 When PyCMDS opens (\autoref{aqn:fig:pycmds_screenshot}), the user is first greeted with the
 ``Somatic/Queue'' tab on the right hand side of the GUI.  %
-This is where the tells PyCMDS to do acquisitions.  %
+This is where she may instruct PyCMDS to do acquisitions.  %
 In PyCMDS, all acquisitions are done in a queue system.  %
 A queue is just a list of acquisitions, where the acquisitions are carried out one by one in
 order.  %
@@ -186,18 +179,29 @@ order.  %
 To instruct PyCMDS to do an acquisition, the user must first create a queue by entering in a chosen
 name (default is ``queue''), and pressing the ``MAKE NEW QUEUE'' button.  %
 Alternatively the user may open an existing queue using ``OPEN QUEUE''.  %
-
 Next, the user must add the desired acquisition(s) to the queue.  %
-There are several acquisition modules, each with a different purpose.  %
+There are several acquisition modules, each with a different purpose [SECTION].  %
 Choose an acquisition module using the drop down menu.  %
 Enter a name for your acquisition, and any additional info that you might want to keep track of.  %
 Finally, fill out any additional information that acquisition module might require, and press
 ``APPEND TO QUEUE''.  %
-
 Once there are acquisitions in the queue, the user can press ``RUN QUEUE''.  %
+
+\autoref{aqn:fig:pycmds_queue_screenshot} is a screenshot of the ``Somatic/Queue'' tab while a
+queue is in progress.  %
+In this screen shot there are seven enqueued items, and PyCMDS is in the process of acquiring the
+final one (index 6).  %
+For each item the status, start time, exit time, and description are shown.  %
+Users may enqueue new items at any time, even while the queue is running.  %
+They may delete items which are enqueued but not yet started.
+Using the green ``LOAD'' button in each row, users may populate the right hand input menu with the
+parameters from that acquisition.  %
+This is useful when repeating an acquisition with slightly changed parameters, or simply when
+inspecting what parameters were used in a given item.  %
+
 \autoref{aqn:fig:pycmds_screenshot_during_scan} is a screenshot of PyCMDS during a representative
 acquisition.  %
-This time, thee ``Somatic/Scan'' tab is chosen.  %
+This time, the ``Somatic/Scan'' tab is chosen.  %
 On the left hand side, we can see that the ``SHUT DOWN'' and ``SET'' buttons are grayed out and
 unclickable, since the somatic system is in control of PyCMDS.  %
 At the moment when this screen shot was taken, PyCMDS is waiting for w3 (OPA-800CG) to finish
@@ -215,21 +219,51 @@ On the far right-hand side, the device and channel to display can be chosen via
 Under ``Status'', the loop time and scan index help users gauge the progress of their scan.  %
 In this case, the displayed pixel (index 6, 40) took 2.448 seconds to acquire.  %
 
+The other tabs are for more advanced interactions, and will be discussed further in future
+sections.  % 
+The ``Program'' tab contains various rarely-needed displays and inputs to configure PyCMDS.  %
+The ``Hardware'' tab is where the advanced menu for each hardware appears [SECTION].  %
+The ``Devices'' tab is where sensor settings live [SECTION].  %
+The ``Autonomic'' tab is where users configure the autonomic system for active correction
+[SECTION].  %
+The ``Somatic'' tab has already been described in this section.  %
+Finally, the ``Plot'' tab was intended to be a interactive, graphical post processing
+environment.  %
+This functionality has not yet been implemented.  %
+
+\begin{landscape}
+\begin{figure}
+	\includegraphics[scale=0.5]{"acquisition/screenshots/005"}
+  \caption[PyCMDS at startup.]{
+    PyCMDS at startup, on the fs system.  %
+  }
+  \label{aqn:fig:pycmds_screenshot}
+\end{figure}
+\end{landscape}
+
+\begin{landscape}
+\begin{figure}
+  \includegraphics[width=9in]{"acquisition/screenshots/004"}
+  \caption[PyCMDS queue.]{
+    PyCMDS queue while acquiring data, on the ps system.  % 
+  }
+  \label{aqn:fig:pycmds_queue_screenshot}
+\end{figure}
+\end{landscape}
+
 \begin{landscape}
 \begin{figure}
   \includegraphics[width=9in]{"acquisition/screenshots/000"}
   \caption[PyCMDS while scanning.]{
-    PyCMDS while acquiring data, on the ps system.  % 
+    PyCMDS scan tab while acquiring data, on the ps system.  % 
   }
   \label{aqn:fig:pycmds_screenshot_during_scan}
 \end{figure}
 \end{landscape}
 
-% TODO: queue figure
-
 \section{Internal structure}  % ===================================================================
 
-In this section I discuss the internal structure of PyCMDS.  %
+In this section I describe the internal structure of PyCMDS.  %
 While there are a huge number of details not worthy of discussion (at time of writing, PyCMDS
 consists of 16,582 lines of source code), PyCMDS is made to be maintained and extended by future
 graduate students, so some insight into the internal structure is warranted.  %
@@ -257,12 +291,12 @@ 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.  %
+In a multi-threaded configuration, each thread will run simultaniously, switching off CPU cycles
+quickly at a low level.  %
 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.  %
+It is hard to pass information between threads.  %
 Without any special protection, two threads have no reason not to simultaneously edit and read the
 same location in memory.  %
 If a delay stage is writing its position to memory as a 64-bit double at the same time as the
@@ -291,7 +325,7 @@ Finally, PyCMDS makes extensive use of the ``signals and slots'' construct, whic
 unique (and certainly original) to Qt.  %
 Signals and slots are powerful because they allow threads without instruction to go completely
 silent, making them essentially free in terms of CPU usage.  %
-Normally, a thread needs to sit in a loop merely listening for instructions.  %
+Normally, a thread needs to sit in a loop to listen for instructions.  %
 Within the Qt framework, a thread can be ``woken'' by a signal without needing that thread to
 explicitly ``listen''.  %
 These concepts fit within the broader umbrella of ``event-driven programming'', a concept that has
@@ -354,7 +388,7 @@ driver-specific code, typically \python{start}, \python{set} and \python{close}.
 This means that code is more maintainable and less repeated.  %
 For example, when I added the autonomic system to PyCMDS, I edited the parent \python{Delay} class
 to respect a new method \python{set_offset}.  %
-I did \python{not} need to modify any of the child classes, because nothing about communicating
+I did \emph{not} need to modify any of the child classes, because nothing about communicating
 with the particular delay stages, in native units, had changed.  %
 This allowed me to implement the core of the autonomic system in just one weekend, something that
 probably would have taken weeks to do without inheritance.  %
@@ -370,8 +404,8 @@ For those that want to dig deeper, most of these top level classes are defined i
 
 \subsubsection{Data types}  % ---------------------------------------------------------------------
 
-PyCMDS is made to be enhanced and extended by chemistry graduate students who may not have time or
-energy to learn about Mutexes, signals, slots and threads.  %
+PyCMDS is made to be enhanced and extended by chemistry graduate students who may not have time,
+energy or enthusiasm to learn about Mutexes, signals, slots, and threads.  %
 They probably also don't have time to read Qt documentation and learn the details of GUI design and
 layout.  %
 PyCMDS does its very best to abstract these details away from developers by offering a set of
@@ -429,8 +463,6 @@ 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.]{
@@ -547,6 +579,14 @@ hardware currently supported by PyCMDS.  %
 In general the nesting is type/model, although there can be additional levels of nesting when
 required, as can be seen in the case of OPA/TOPAS/TOPAS-C and OPA/TOPAS/TOPAS-800.  %
 
+The ``kind-defining'' classes (\python{Delay}, \python{Filter}, \python{OPA},
+\python{Spectrometer}) are particularly important.  %
+Each of these defines \emph{what it means} to be that kind of hardware, as far as PyCMDS is
+concerned.  %
+To put it another way, these classes are minimum viable versions of their hardware kind.  %
+Each of these classes can be directly instantiated as a minimum-viable instance, which allows for
+``virtual'' hardware and offline development.  %
+
 \begin{figure}
 	\includepython{"acquisition/hardware.py"}
   \caption[Parent hardware class.]{
@@ -712,9 +752,14 @@ of linear interpolation and extrapolation at the edges.  %
 A single hardware can be offset by multiple other hardwares.  %
 In such cases, \emph{offsets always add}.  %
 
+[DESCRIPTION OF FIGURE]
+
+\begin{landscape}
 \begin{figure}
+  \includegraphics[width=9in]{"acquisition/screenshots/009"}
   \caption{AUTONOMIC SDC SCREENSHOT}
 \end{figure}
+\end{landscape}
 
 \clearpage
 \section{Somatic} \label{aqn:sec:somatic} % =======================================================
-- 
cgit v1.2.3

