more work on beamline management

docs/before.rst

@@ -21,12 +21,12 @@ registration.
 
 .. note::
 
-   + New registration requests as well as the extensions requests for
-     expired registrations shall be submitted as soon as possible.
-   + Approvals for guest registrations can take as long as two
-     months for some non-US citizens.
+   + New registration requests as well as extension requests for
+     expired registrations should be submitted as soon as possible.
+   + Approvals for guest registrations require two months for non-US
+     citizens and longer for certain nationalities.
 
-To apply for a BNL Guest appointment: https://www.bnl.gov/ps/userguide/beforearrival.php 
+Apply for a BNL Guest appointment: https://www.bnl.gov/ps/userguide/beforearrival.php 
 
 .. caution::  Without an active appointment, you will not be allowed
 	      on site and will be turned away at the main gate. 
@@ -36,10 +36,11 @@ BNL Domain Account
 
 When your BNL Guest registration becomes active, you should receive an
 email with instructions for enabling your BNL domain account. You must
-complete that step, which includes setting your password and signing
-up for DUO Federal two-factor authentication. If you need to request
-an account, go to https://www.bnl.gov/accounts/ and click the button
-that says "Submit account registration form".
+do this, including setting your password and signing up for DUO
+Federal two-factor authentication.  
+
+If you need to request an account, go to https://www.bnl.gov/accounts/
+and click the button that says "Submit account registration form".
 
 Enabling your BNL account is non-optional. You must have an active
 account in order to unlock the computers at the beamline. 
@@ -51,14 +52,14 @@ account in order to unlock the computers at the beamline.
 Safety Approval Form
 --------------------
 
-Submit your Safety Approval Form (SAF) AT LEAST two weeks before the
-above starting date. Your SAF should provide a complete and accurate
-description of the experiment, including all samples, chemicals,
-solvents, reference materials, and equipment that will be used during
-the experiment and preparation. In addition, any additional equipment
-not provided by the beamline has to be identified and described in the
-SAF. Provide detailed information on sample processing and any safety
-measures necessary.
+Submit your Safety Approval Form (SAF) **at least** two weeks before
+the start date for your experiment.  Your SAF should provide a
+complete and accurate description of the experiment, including all
+samples, chemicals, solvents, reference materials, and equipment that
+will be used during the experiment and for sample preparation.  In
+addition, any additional equipment not provided by the beamline has to
+be identified and described in the SAF.  Provide detailed information
+on sample processing and any safety measures necessary.
 
 .. caution:: An approved SAF is required on the first day of beamtime.
 	     Without enough time for approval, you may lose your
@@ -83,15 +84,15 @@ Currently, four labs support user activities at BMM.  They are:
 + Lab 3L-L09: XAS Chemistry Lab
 + Lab 4L-L09: Electrochemistry Lab
 
-See https://www.bnl.gov/nsls2/labs/
+See https://www.bnl.gov/nsls2/labs/ for details of what equipment is
+available in each lab.
 
-If you prepare or treat samples on-site, you must request use of the
-appropriate NSLS-II User Laboratory when you submit your Safety
+If you prepare or treat samples on-site, you **must** request use of
+the appropriate NSLS-II User Laboratory when you submit your Safety
 Approval Form.
 
 You cannot request a laboratory after an SAF has been approved.  
 
-
 Here is some advice on selecting the correct lab:
 
 Unbound nanoparticles
@@ -100,7 +101,7 @@ Unbound nanoparticles
   unbound, please contact BMM beamline scientist Bruce Ravel
   ([email protected]) as soon as possible.  
 
-Solid sample preparation (pellet pressing, spreading on tape etc)
+Solid sample preparation (pellet pressing, spreading on tape, etc)
   Request Lab 3L-L06.
 
 Liquid samples (organic solvents, acids, bases)
@@ -110,20 +111,20 @@ Hydrofluoric acid treatment
   Request Lab 3L-L09 and notify Cognizant Space Manager, Syed Khalid
   at [email protected], as soon as possible. 
 
-Environment and earth science sample preparation and treatment
+Environmental and earth science sample preparation and treatment
   Request Lab 3L-L07.
 
 Electrochemistry and battery science
   Request Lab 4L-L09.
 
 Radionuclide samples must be prepared and properly contained at the
-home institution. NSLS-II has no lab available for work on
-radiological materials. Samples with depleted uranium and uranium at
-low or environmentally relevant concentrations are considered
-radiological samples at NSLS-II and must be treated accordingly.
+home institution.  NSLS-II has no lab available for work on
+radiological materials.  Samples with depleted uranium and uranium at
+low or environmentally relevant concentrations **are** considered to
+be radiological samples at NSLS-II and must be treated accordingly.
 
 Requests for using gloveboxes should be discussed prior to submitting
-the SAF, with Bruce Ravel ([email protected]) and/or Syed Khalid
+the SAF, contact Bruce Ravel ([email protected]) and/or Syed Khalid
 ([email protected])
 
 .. note:: Each lab you select on your safety approval form makes work

docs/commonchores.rst

@@ -15,6 +15,10 @@
 Common chores
 =============
 
+In this section, a variety of procedures around the beamline are
+explained in detail.
+
+
 Search the Hutch
 ----------------
 
@@ -104,8 +108,9 @@ Once the hutch is secured and you are back at the computer:
    a sensible signal on the detector.
 
 #. Record the detector position (``xafs_det.position`` or the number
-   next to ``det:`` in the display at the top of the top screen) for
-   the current sample in the spreadsheet.
+   next to ``det:`` in the :numref:`display (Section %s)
+   <cadashboard>` at the top of the top screen) for the current sample
+   in the spreadsheet.
 
 #. Move to a new sample position. To change slots on the *ex situ*
    sample wheel: ``RE(slot(##))``, where the number (``##``) is

docs/desktop.rst

@@ -0,0 +1,130 @@
+..
+   This document was developed primarily by a NIST employee. Pursuant
+   to title 17 United States Code Section 105, works of NIST employees
+   are not subject to copyright protection in the United States. Thus
+   this repository may not be licensed under the same terms as Bluesky
+   itself.
+
+   See the LICENSE file for details.
+
+.. role:: key
+    :class: key
+
+.. _desktop:
+
+BMM's Desktop
+=============
+
+This section provides an explanation of how to recover BMM's data
+collection workspace after restarting the computer.
+
+This is made a hair easier if a couple of symbolic links are made in
+``~/bin/``.  Do this:
+
+.. code-block:: sh
+
+   ln -s ~/.ipython/profile_collection/startup/consumer/run-consumer ~/bin/run-consumer
+   ln -s ~/git/BMM-beamline-configuration/tools/run-cadashboard ~/bin/run-cadashboard
+
+Monitoring
+----------
+
+To have eyeballs on the operation of the beamline, we want ``Phoebus``
+for engineering screen and the ``cadashboard`` application for the
+heads-up overview of
+
+Phoebus (engineering screens)
+  There are two ways to start Phoebus.
+
+  The more hands-on way is to open a new terminal window or tab, the
+  type ``run-phoebus`` at the command line.  This will open the
+  Phoebus window and it should remember to place it on the top screen.
+
+  It is not necessary to keep open the terminal window used to launch
+  Phoebus.  Phoebus is **very noisy**, spewing en endless stream of
+  logging messages to the screen.  Happily, it forks itself upon
+  launch, so it is not necessary to keep that terminal window open.
+  If you first opened a new window or tab, you can safely close it.
+
+  There should be an icon for Phoebus on the icon bar at the bottom of
+  the screen.  Is looks like a stylized version of this charater
+  string: ``>/``.  Click on it.
+
+  Once Phoebus is open, if the layout was not restored, click on the
+  "Window" menu, then on "Load Layout", then select "Two cameras".
+
+cadashboard
+  Open a new terminal window.  Resize the window so it is a few lines
+  tall, and the full width of the screen.  
+
+  At the command line run ``run-cadashboard``.  Make the font much
+  bigger by hitting :key:`Ctrl`-\ :key:`Shift`-\ :key:`+` several
+  times |nd| maybe as many as 10 |nd| until it takes up the full width
+  of the screen.
+
+  Resize the height to just cover the three lines of the dashboard.
+  Move the terminal to the very top of the top screen.  You can hide
+  the window decoration by using :key:`Windows`-\ :mark:`rightclick,.`
+  to position the terminal window.
+
+
+
+.. _fig-monitoring:
+.. figure:: _images/monitoring.png
+   :target: _images/monitoring.png
+   :width: 80%
+   :align: center
+
+   Once Phoebus and cadashboard are open, they should look something
+   like this.
+
+
+
+Data collection and visualization
+---------------------------------
+
+The easiest way to manage data collection and visualization is to have
+a terminal window with 3 tabs.  One tab is used for ``bsui``, the data
+acquisition program.  A second tab is for the Kafka consumer which
+handles most data visualization chores.  The third tab is just a
+normal bash command line, which is always handy to have available.
+
+Once you have a three-tab setup, go to the tab for ``bsui``.  At the
+command line type ``bsui``.  ``bsui`` startup at BMM is rather
+time-consuming, but after a couple minutes it is ready to go.
+
+
+Now go to the tab for the Kafka consumer.  At the command line, type
+``run-consumer``.  This will take a minute or so to start, eventually
+saying ``Ready to receive documents...``.  At this point, scans will
+generate plots.
+
+
+.. subfigure::  AB
+   :layout-sm: AB
+   :subcaptions: above
+   :name: startup
+   :class-grid: outline
+
+   .. image:: _images/bsui_startup2.png
+
+   .. image:: _images/consumer_startup.png
+
+   (Right) The tail end of the ``bsui`` startup messages and the
+   command prompt in the ``bsui`` tab.  (Left) The Kafka plotting
+   consumer in its tab awaiting commands from ``bsui``.
+
+
+
+
+All the rest
+------------
+
+Some other things that are handy to have on the desktop during an
+experiment:
+
++ Firefox, with tabs open to :numref:`the command cheatsheet (Section
+  %s) <cheatsheet>` and the XAS webcam.
++ Slack
++ A dolphin (file browser) window with a tab open to the current
+  experiment 

docs/details.rst

@@ -103,6 +103,14 @@ the XAFS table.
 
 Vendor link for quick-disconnect fixture: https://www.mcmaster.com/5012K122/
 
+In practice, the H\ :sub:`2`/N\ :sub:`2` and N\ :sub:`2`/Ar mixing
+channels are not much used.  Unless measuring with the incident beam
+below 5 keV or above 21 keV, it is a poor use of time to make changes
+to the gas content of the ion chambers.  This is because it takes
+quite some time for the volume of the ion chamber to equillibrate.
+
+N\ :sub:`2` is adequate for almost all experiments at BMM.
+
 
 
 Analog Video Capture

docs/index.rst

@@ -39,6 +39,7 @@ BMM is NIST's Beamline for Materials Measurement
    :numbered:
    :caption: Developer documentation
 
+   desktop.rst
    profile.rst
    plotting.rst
    ionchambers.rst

docs/intro.rst

@@ -193,43 +193,6 @@ Along with an invitation to the Slack workspace, the user will receive
 an invitation to share the Google Drive.
 
 
-.. _start_end:
-
-Starting and ending an experiment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When a new experiment begins, run the command::
-
-  BMMuser.start_experiment(name='Betty Cooper', date='2019-02-29', gup=123456, saf=654321)
-
-This will create that data folder and populate it with an
-:numref:`experimental log (Section %s) <log>`, write a template for a
-:numref:`macro file (Section %s) <macro>`, configure the logger to
-write a :numref:`user log file (Section %s) <logfile>` for this
-experiment, set the GUP and SAF numbers as metadata for output files,
-set up :numref:`snapshot (Section %s) <snap>` and :numref:`dossier
-(Section %s) <dossier>` folders, and perform other experiment start-up
-chores.
-
-.. note::
-
-   In the near future, the ``start_experiment()`` command will grab
-   metadata from PASS (or UPS, or whatever) and set access permissions
-   on data.  When that happens, the only argument needed will be the
-   SAF number.
-
-The ``name`` should be the PI's full name, preferably transliterated
-into normal ASCII.  The ``date`` should be the starting day of the
-experiment in the ``YYYY-MM-DD`` format.  The ```GUP`` and ``SAF``
-numbers can be found on the posted safety approval form.
-
-Once the experiment is finished, run this command::
-
-  BMMuser.end_experiment()
-
-This will reset the logger and the ``DATA`` variable and unset the GUP
-and SAF numbers.
-
 
 ..
   Electrochemistry experiments

docs/log.rst

@@ -105,17 +105,15 @@ The choices for ``<camera>`` are
 The image will then be written to the file specified by the
 ``filename=`` argument.
 
-The ``xafs()`` plan calls this function twice, once for the XAS webcam
-and once for the analog camera.
+The ``xafs()`` plan does something equivalent to the ``snap()``
+function for each available camera.  These are recorded to the scan's
+:numref:`dossier (Section %s) <dossier>`.
 
-Note that this function is `not` run through the Run Engine.
 
-The name of the snapshot file and the camera used are written to the
-experimental log.
 
 
-.. subfigure::  AB
-   :layout-sm: AB
+.. subfigure::  AB|CD
+   :layout-sm: AB|CD
    :gap: 8px
    :subcaptions: above
    :name: fig-snapshots
@@ -125,15 +123,26 @@ experimental log.
 
    .. image:: _images/XASwebcam.jpg
 
-   (Left) Snapshot taken with the analog camera.  (Right) 
-   Snapshot taken with the XAS web camera.
+   .. image:: _images/usbcam1.jpg
+
+   .. image:: _images/usbcam2.jpg
+
+   Snapshots from an experiment using the Linkam stage.  Note that
+   each snapshot is annotated along the bottom, visually displaying
+   the time and identifying the sample being measured.  
+   (Top left) Snapshot taken with the analog camera.  (Top right)
+   Snapshot taken with the XAS web camera. (Bottom left) Snapshot
+   taken with USB camera #1. (Bottom left) Snapshot taken with USB
+   camera #2.
 
 
 .. _video:
 
 Recording videos
 ----------------
 
+.. todo:: Does this actually work?
+
 The USB cameras can be used to record short videos of whatever they
 are pointing at.  The resulting video will be saved to a `.avi
 <https://en.wikipedia.org/wiki/Audio_Video_Interleave>`__ file in