document version 13 spreadsheet changes

docs/automation.rst

@@ -12,11 +12,15 @@
 Beamline automation
 ===================
 
+.. caution:: Spreadsheets with version number earlier 13 **will not
+	     work** as of 1 March, 2024.
+
+
+
 BMM currently supports five categories of spreadsheet-based automation:
 
-#. Sample wheels, both single (`spreadsheet
+#. Sample wheels (`spreadsheet
    <https://github.com/NSLS-II-BMM/profile_collection/raw/master/startup/xlsx/wheel.xlsx>`__)
-   and double (`spreadsheet <https://github.com/NSLS-II-BMM/profile_collection/raw/master/startup/xlsx/doublewheel.xlsx>`__) ring  
 #. Linkam stage temperature control (`spreadsheet
    <https://github.com/NSLS-II-BMM/profile_collection/raw/master/startup/xlsx/linkam.xlsx>`__)
 #. LakeShore 331 controller for Displex cryostat (`spreadsheet <https://github.com/NSLS-II-BMM/profile_collection/raw/master/startup/xlsx/lakeshore.xlsx>`__)
@@ -43,10 +47,13 @@ differences in the columns corresponding to the different instruments.
 
 Make sure you are using the most up-to-date version of the spreadsheet.
 
-.. note:: The current spreadsheet version is **12**, as of 26
-          January, 2024.  You should *always* use a current
+.. note:: The current spreadsheet version is **13**, as of 29
+          February, 2024.  You should *always* use a current
           spreadsheet.
 
+.. caution:: Spreadsheets with version number earlier 13 **will not
+	     work** as of 1 March, 2024.
+
 
 Common features
 ---------------
@@ -100,6 +107,27 @@ spreadsheet tab.
    "repetitions", which specifies the number of repeated XAS scans of
    the sample in that row of the spreadsheet.  
 
+Fine tuning sample position and slits
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On the right hand side of each spreadsheet, there are columns for
+specifying specific positions for sample X and Y and for slit width
+and height.  This allows you to fine tune the sample position and beam
+size on a per-sample basis.
+
+The motor grid spreadsheet offers three columns for specifying motor
+positions.  The motors associated with those columns are
+user-select-able.  In this way, a grid over any beamline motor can
+programmed. 
+
+The glancing angle spreadsheet has the columns for specifying slit
+width and height.  It also has columns for specifying sample Y and
+pitch (X and pitch when in perpendicular mode) when manual alignment
+rather than automated alignment is selected.  There is no column for
+specifying the X position (or Y when in perpendicular mode) as use of
+the glancing angle stage presumes that all the samples are mounted at
+the centers of the spinners.
+
 
 Selecting a spreadsheet
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -184,7 +212,7 @@ with the name of the spreadsheet file.  If the tab in the spreadsheet
 was called :file:`mysamples`, the new BlueSky command is called
 ``mysamples_macro()``.
 
-.. todo::
+.. admonition:: Future Tech!
 
    Convert spreadsheets to Bluesky queueserver input.
 
@@ -194,25 +222,20 @@ was called :file:`mysamples`, the new BlueSky command is called
 Sample wheel automation
 -----------------------
 
-The standard *ex situ* sample holder at BMM is a plastic wheel that
-get mounted on a rotation stage.  Examples are shown in figures
-:numref:`fig-wheels`.  The rotation stage is mounted on an XY stage,
-so when one slot on the sample wheel is aligned, all the slots are
-aligned.
+The standard *ex situ* sample holder at BMM is a plastic wheel mounted
+on a rotation stage.  Examples are shown in figures
+:numref:`fig-doublewheel`.  The rotation stage is mounted on an XY
+stage, so when one slot on the sample wheel is aligned, all the slots
+are aligned.
 
-.. subfigure::  AB
-   :layout-sm: AB
-   :gap: 8px
-   :subcaptions: above
-   :name: fig-wheels
-   :class-grid: outline
 
-   .. image:: _images/Samplewheel.jpg
-
-   .. image:: _images/double_wheel_sm.jpg
+.. _fig-doublewheel:
+.. figure:: _images/double_wheel_sm.jpg
+   :target: _images/double_wheel_sm.jpg
+   :width: 50%
+   :align: center
 
-   (Left) A single-ring sample wheel with 24 sample positions.
-   (Right) Double-ring sample wheels with 48 sample positions.  There
+   Double-ring sample wheels with 48 sample positions.  There
    are options for both wheel styles with 13mm x 3 mm slots or 13mm
    diameter holes.  The rings on the double wheel are 26 mm apart
    (center to center of slots/holes).
@@ -223,7 +246,7 @@ carries one parameter of the XAFS scan.
 
 
 .. _fig-doublewheel-spreadsheet:
-.. figure::  _images/doublewheel_spreadsheet.png
+.. figure:: _images/doublewheel_spreadsheet.png
    :target: _images/doublewheel_spreadsheet.png
    :width: 70%
    :align: center
@@ -239,14 +262,6 @@ most of the columns in this spreadsheet will be quite familiar.  Most
 of the columns are used to specify the same set of parameters as in
 the INI file |nd| file name, element, edge, and so on.
 
-.. note:: February 2020
-
-   The E\ :sub:`0` column is no longer used.  E\ :sub:`0` is now
-   always taken from the tabulated value for ``element`` and
-   ``edge``. Some effort is made to read spreadsheets from before
-   Feb. 2020, but they are deprecated and no longer guaranteed to
-   work.
-
 The green cell in the first row is used to input the names of all the
 people involved in the experiment, as explained above.
 
@@ -276,10 +291,10 @@ values for element and/or edge in a row.  When specified
 and different from the previous row, a call to the ``change_edge()``
 command (:numref:`Section {number} <pds>`) is inserted into the macro.
 
-Not shown in :numref:`Figure %s <fig-wheel-spreadsheet>` are columns for
-tweaking the ``xafs_x`` and ``xafs_y`` positions, adjusting the
-horizontal size of :numref:`slits3 (see Section %s) <slits3>`, and
-adjusting the fluorescence detector position.
+Not shown in :numref:`Figure %s <fig-wheel-spreadsheet>` are columns
+for tweaking the ``xafs_x`` and ``xafs_y`` positions, adjusting the
+horizontal and vertical size of :numref:`slits3 (see Section %s)
+<slits3>`, and adjusting the fluorescence detector position.
 
 
 Again, assuming the tab in the spreadsheet was called ``mysamples``,
@@ -528,3 +543,6 @@ spreadsheet is identical to the *ex situ* sample wheel spreadsheet.
    to the `motor grid spreadsheet
    <https://github.com/NSLS-II-BMM/profile_collection/raw/master/startup/xlsx/grid.xlsx>`_.
 
+
+.. caution:: Spreadsheets with version number earlier 13 **will not
+	     work** as of 1 March, 2024.

docs/manage.rst

@@ -677,14 +677,17 @@ Provision a new beamline computer
 This is a list of notes on how to finish the provisioning of a new
 beamline computer.
 
+Firstly, make sure that ``/nsls2/data`` is a symlink to
+``/nsls2/data3``.  If it is not, ask for help from DSSI.
+
+
 install additional packages
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 + plasma-desktop (just ... better)
 + redis (essential for operation of bsui)
 + most (used as the pager in BMM's bsui profile)
 + ag (powerful ack-like grep alternative)
-+ sddm (also just ... better)
 + fswebcam (used to capture analog pinhole camera)
 + demeter and perl-Graphics-GnuplotIF (something silly, no doubt)
 + slack (communications)
@@ -695,7 +698,7 @@ To install these, do:
 
 .. code-block:: sh
 
-   dzdo dnf install redis most ag sddm fswebcam demeter perl-Graphics-GnuplotIF slack ark
+   dzdo dnf install redis most ag fswebcam demeter perl-Graphics-GnuplotIF slack ark
    dzdo dnf install --skip-broken --nobest @kde-desktop
 
 The second command installs the KDE metapackage, skipping missing

docs/pds.rst

@@ -72,7 +72,7 @@ Automating reference foil changes
 A wheel is used to hold and switch between reference foils and stable
 oxides.  The standard reference wheel has most of the elements
 accessible at BMM, including all the lanthanides (except Pm!).  A
-double wheel (:numref:`see Figure %s <fig-wheels>`) is used
+double wheel (:numref:`see Figure %s <fig-doublewheel>`) is used
 to hold the standards.  The wheel is mounted on a rotation stage which
 is, in turn, mounted on an XY stage for alignment.
 

docs/plotting.rst

@@ -64,9 +64,11 @@ chores are managed.  In each case, the document is a simple dictionary
 which the consumer parses to perform a plotting chore using
 `matplotlib <https://matplotlib.org/>`__.
 
-.. todo:: Would a browser-y solution like `Bokeh
-          <https://docs.bokeh.org/en/latest/index.html>`__ be an
-          alternative?
+.. admonition:: Future Tech!
+
+   Would a browser-y solution like `Bokeh
+   <https://docs.bokeh.org/en/latest/index.html>`__ be an
+   alternative?
 
 The dictionary sent as the document is not structured like a BlueSky
 document.  There is no schema.  The dictionary simply contains
@@ -219,8 +221,10 @@ linescan plots, but with some additional considerations:
    energy calibration standard, and a view of the raw I0 spectrum (to
    keep an eye on monochromator glitches and other issues).
 
-.. todo:: Panel for live |chi|\ (k) plots, begin plotting this panel,
-          say, 60 eV above the edge.
+.. admonition:: Future Tech!
+
+   Panel for live |chi|\ (k) plots, begin plotting this panel, say, 60
+   eV above the edge.
 
 Like with the linescan, the plot begins with a message issued to tell
 the consumer to begin preparing for an XAFS plot and providing enough

docs/xafs.rst

@@ -80,7 +80,7 @@ Here is a complete explanation of the contents of the INI file.
 
 ``element`` (line 5)
    The one- or two-letter symbol for the element.  The edge energy,
-   ``e0``, will be determined from ``element`` and ``edge``.
+   ``e0``, will be looked up using ``element`` and ``edge``.
 
 ``edge`` (line 6)
    The symbol (``K``, ``L3``, ``L2``, ``L1``) of the edge being
@@ -130,11 +130,6 @@ Here is a complete explanation of the contents of the INI file.
 
 Comments begin with the hash (``#``) character and are ignored.
 
-.. note:: 
-
-   The E\ :sub:`0` keyword in the INI file is no longer used in normal
-   operations.  E\ :sub:`0` by default determined from ``element`` and
-   ``edge``. (February 2020)
 
 
 Scan regions
@@ -758,6 +753,15 @@ elsewhere is captured in the output XDI file.
 .. todo:: Document use of ``XDI_record`` dictionary to control which
 	  xafs motors and/or temperatures get recorded in the XDI header
 
+.. admonition:: New as of 27 February, 2024
+
+		There is a new XDI header in use in BMM's datafiles:
+		``Scan.hdf5file``.  This captures the name of the
+		associated HDF5 file for fluorescence XAS measurements.
+
+		The path and file name are given relative to the assets
+		location on central storage: ``/nsls2/data3/bmm/assets/xspress3/``.
+
 .. code-block:: text
 
    # XDI/1.0 BlueSky/1.3.0
@@ -894,7 +898,7 @@ items in the list above.  For a spreadsheet, all applicable items from
 the list are added together for each row of the spreadsheet.  The
 times for each row are added up.
 
-.. caution:: The time estimate is a good faith estimate.  It should be
+.. warning:: The time estimate is a good faith estimate.  It should be
 	     used as a decent suggestion, but high accuracy should not
 	     be expected! 
 
@@ -1001,6 +1005,8 @@ one of the following:
 + a positive integer (smaller than the first energy value in the
   scan), the energy point that many steps from the *beginning* of the
   scan will be used
++ a list of any of the above, resulting in XRF spectra from each
+  energy in the list being over-plotted.
 
 For example,
 
@@ -1056,6 +1062,14 @@ While tiny, this Mn contamination had a noticeable impact on the
 measured EXAFS data.  This sort of forensic work is enabled by the
 ``xrfat`` command.
 
+The plots shown in :numref:`Ndsample` can be overplotted using the
+list argument of ``energy``, like so:
+
+.. sourcecode:: python
+
+   xrfat(uid, [6510, 6560])
+
+
 The full signature of this function is
 
 .. sourcecode:: python