lots of edits and typos

NSLS-II-BMM · Jul 22, 2024 · 9ac8d9f · 9ac8d9f
1 parent 380e23e
commit 9ac8d9f
Show file tree

Hide file tree

Showing 13 changed files with 283 additions and 154 deletions.
diff --git a/docs/_static/Binder-instructions.pdf b/docs/_static/Binder-instructions.pdf
diff --git a/docs/automation.rst b/docs/automation.rst
@@ -325,6 +325,7 @@ explicit arguments for the filled-in spreadsheet cells.
    yield from xafs('MnFewheel.ini', filename='Fe-Spessartine', sample='Mn3Al2(SiO4)3', comment='Grants Mining District; New Mexico')
    close_last_plot()
 
+.. _auto_linkam:
 
 Linkam stage automation
 -----------------------
@@ -375,6 +376,8 @@ names.
    using the Linkam stage.  Link to the `Linkam spreadsheet
    <https://github.com/NSLS-II-BMM/profile_collection/raw/master/startup/xlsx/linkam.xlsx>`_
 
+.. _auto_lakeshore:
+
 LakeShore/Displex automation
 ----------------------------
 
@@ -438,6 +441,8 @@ cryostat.  There are three power settings.
    The CSS screen for the LakeShore 331.
 
 
+.. _auto_ga:
+
 Glancing angle stage automation
 -------------------------------
 

diff --git a/docs/before.rst b/docs/before.rst
@@ -182,9 +182,9 @@ knowledge of the equipment coming to the beamline.
 	     experiment.  Equipment that cannot pass EEI may not be used
 	     at NSLS-II.
 
-Note that some pre-approved electrical equipment (e.g., potentiostat,
-heaters, temperature meters, and controllers) is available at the
-beamline.
+Note that some already-approved electrical equipment (e.g.,
+potentiostat, heaters, cryostats, temperature controllers, sample
+spinners, and more) is available at the beamline.
 
 
 Research Equipment Pool

diff --git a/docs/cheatsheet.rst b/docs/cheatsheet.rst
@@ -49,10 +49,10 @@ Most common commands
   Move TO an energy value
 
 ``RE(mv(xafs_y, <value>))``
-  Move any named motor TO a position (``xafs_y`` is an example)
+  Move any named motor TO a position (``xafs_y`` is an example,see :numref:`Section %s <sample_stages>`)
 
 ``RE(mvr(xafs_y, <value>))``
-  Move any named motor BY an amount (``xafs_y`` is an example)
+  Move any named motor BY an amount (``xafs_y`` is an example, see :numref:`Section %s <sample_stages>`)
 
 ``RE(change_edge('Xx'))``
   setup beamline for an absorption edge, ``Xx`` = 1- or 2-letter symbol,
@@ -185,10 +185,12 @@ engine will complain with this hint:
    +------------------------------------------+----------------------------------------------------------------------------+
    | |mquad| |mquad| |mquad| |mquad| |mquad| **Glancing angle stage**                                                      |
    +------------------------------------------+----------------------------------------------------------------------------+
-   | ``RE(ga.to(N))``                         |    move glancing angle stage to sample N (1 |le| N |le| 8) + start spinner |
+   | ``RE(ga.to(N))``                         |    move stage to sample N (1 |le| N |le| 8) + start spinner                |
    +------------------------------------------+----------------------------------------------------------------------------+
    | ``RE(ga.auto_align(pitch))``             |    automatically align glancing angle stage and move to pitch              |
    +------------------------------------------+----------------------------------------------------------------------------+
+   | ``RE(ga.flatten())``                     |    return to the flat position found during ``auto_align()``               |
+   +------------------------------------------+----------------------------------------------------------------------------+
    | |mquad| |mquad| |mquad| |mquad| |mquad| **Linkam stage**                                                              |
    +------------------------------------------+----------------------------------------------------------------------------+
    | ``RE(mv(linkam, T))``                    |    move Linkam stage to temperature T                                      |
@@ -213,7 +215,7 @@ engine will complain with this hint:
    +------------------------------------------+----------------------------------------------------------------------------+
    | |mquad| |mquad| |mquad| |mquad| |mquad| **Reference wheel**                                                           |
    +------------------------------------------+----------------------------------------------------------------------------+
-   | ``RE(reference('Xx'))``                  |    Move to reference 'Xx'                                                  |
+   | ``RE(reference('Xx'))``                  |    Move to reference element 'Xx'                                          |
    +------------------------------------------+----------------------------------------------------------------------------+
    | |mquad| |mquad| |mquad| |mquad| |mquad| **Get help**                                                                  |
    +------------------------------------------+----------------------------------------------------------------------------+
@@ -267,11 +269,10 @@ Vertical center
   ``slits3.vcenter`` (nominally 0 mm)
 
   The vertical center should never be changed.  Instead, align the
-  slits using ``dm3_bct`` and the ``slit_height()`` plan
+  slits by moving ``dm3_bct`` or running the ``slit_height()`` plan
   (:numref:`Section %s <special-linescans>`)
 
 
-
 Example movement: ``RE(mv(slits3.vsize, 0.5))``
 
 Individual slits are named ``slits3.top``, ``slits3.bottom``,

diff --git a/docs/data.rst b/docs/data.rst
@@ -22,42 +22,84 @@ Yubi key.
 
 The beamline operator account does not have access to user's data.
 
-This section of the beamline manual explains how to access you data
+This section of the beamline manual explains how to access your data
 during and after your experiment.
 
 Downloading data
 ----------------
 
-You will need an sftp client.  The recommendation of BMM staff is to
-use `FileZilla <https://filezilla-project.org/>`__.  This is a free
-program available for Windows, Apple, and Linux.  The explanation
-below will be made using FileZilla.
+SFTP Client
+~~~~~~~~~~~
 
-:Windows users: Another option is `WinSCP
-		<https://winscp.net/eng/index.php>`__. Be careful at
-		the WinSCP website.  You will see multiple pop-up adds
-		with download links to other software packages.  Be
-		sure to click on the link to the WinSCP package.
+You will need an sftp client.  
 
-:Mac users: Another options are `Termius
-	    <https://apps.apple.com/us/app/termius-ssh-sftp-client/id1176074088?mt=12>`__
-	    and `Flow <http://fivedetails.com/flow/>`__.
++ **Cross-platform:** `FileZilla <https://filezilla-project.org/>`__.
+  This is a free program available for Windows, Apple, and Linux.  The
+  explanation below will be made using FileZilla.
 
-:Linux users: Your desktop file manager likely has an sftp client
-	      built in.  Try typing
-	      ``sftp://<username>@sftp.nsls2.bnl.gov`` into your file
-	      manager.
++ **Windows users:** A popular option is `WinSCP
+  <https://winscp.net/eng/index.php>`__. Be careful at the WinSCP
+  website.  You will see multiple pop-up adds with download links to
+  other software packages.  Be careful to click on the link to the
+  WinSCP package.
 
-.. admonition:: The short version
++ **Mac users:** Other options are `Termius
+  <https://apps.apple.com/us/app/termius-ssh-sftp-client/id1176074088?mt=12>`__
+  and `Flow <http://fivedetails.com/flow/>`__.
 
-   #. Connect to sftp://sftp.nsls2.bnl.gov
++ **Linux users:** Your desktop file manager likely has an sftp client
+  built in.  Try typing
+  ``sftp://<username>@sftp.nsls2.bnl.gov`` into your file
+  manager or creat a new network drive using ``ssh`` and
+  ``sftp.nsls2.bnl.gov``.
+
+  `sshfs <https://github.com/libfuse/sshfs>`__ is an
+  excellent solution.  ``sshfs`` allows you to easily
+  mount the remote sftp site to a local mount point,
+  allowing you to browse the remote site as if it were a
+  local folder.  For example, I do the following to mount
+  the data folder locally on my laptop:
+
+  .. code-block:: bash
+		  
+     sshfs bravel@sftp.nsls2.bnl.gov:/nsls2/data/bmm ~/mnt/bmm -o follow_symlinks
+
+  and this to unmount the data folder
+
+  .. code-block:: bash
+
+     fusermount -u mnt/bmm  
+
+
+
+The Short Version
+~~~~~~~~~~~~~~~~~
+
+
+.. admonition:: Executive Summary
+
+   #. Connect to sftp.nsls2.bnl.gov in your sftp client
    #. Authenticate using your BNL username/password and DUO two-factor
       authentication
    #. Navigate to ``/nsls2/data/bmm/proposals/``, then to the cycle
       folder corresponding to the date of your experiment, then to the
-      folder with your proposal number.
+      folder with your proposal number.  So, something like 
+      ``/nsls2/data/bmm/proposals/2024-2/pass-333333``.
    #. Transfer your data to your local computer.
 
+If you preserve the folder structure from the remote host, the
+:numref:`the dossier files (Section %s) <dossier>` will work as
+expected.
+
+The ``assets`` folder contains raw image and HDF5 from your
+experiment.  Those files will have database-friendly but
+user-unfriendly names.  The HDF5 files are rather large and will take
+some time to download.  The can skip downloading the ``assets`` folder
+if you do not plan on using the HDF5 files directly.
+
+
+A Guide with Pictures
+~~~~~~~~~~~~~~~~~~~~~
 
 What follows is a guide with screenshots of using FileZilla to connect
 to the SFTP download site and begin downloading data.
@@ -179,25 +221,64 @@ Your data is now on your computer.  Yay!
 Using the VDI virtual Desktop
 -----------------------------
 
-.. todo:: Need to flesh this out.
+.. todo:: Details needed
 
 
 Accessing data from the beamline computers
 ------------------------------------------
 
-In a terminal window ``su - <username>``, enter password and respond
-to DUO push.
+Under the new data security regime, the beamline computer does not
+have normal access to your data.  This is because all users run their
+experiment as the beamline operator.  If the beamline operator |nd|
+``xf06bm`` |nd| could see data, than any could look at anyone's data.
+
+Instead, data are stored on central storage with read permission
+granted to everyone named on the user proposal.  In this way, data are
+secured from other users and access to the data requires
+authentication.
+
+To look at your data while at the beamline, do the following
+
++ Open a terminal window.  Normally a terminal window with a white
+  background is open on screen and intended for this purpose.
+  ``bsui`` is typically run from a window with a black background, so
+  the white background is meant as a visual cue indicating that it is
+  the place for data access.
+
++ In that terminal window type
+
+  .. code-block:: bash
 
-``cd`` to ``/nsls2/data3/bmm/proposals/2024-2/pass-123456``, replacing
-``2024-2`` with the cycle of your visit and ``123456`` with your
-proposal number.
+     ``su - <username>``
 
-``dathena`` at the command line to use Athena.  Or use jupyter.
+  replacing ``<username>`` with your actual user name. Enter your
+  password and respond to DUO push.
 
++ ``cd`` to ``/nsls2/data3/bmm/proposals/2024-2/pass-123456``, replacing
+  ``2024-2`` with the cycle of your visit and ``123456`` with your
+  proposal number.
+
+Athena can be launched from the command line.  The best way to do this
+is to type
+
+.. code-block:: bash
+
+   dathena 2&>1 &
+
+at the command line.  That incantation will suppress spurious screen
+messages and put Athena into the background so you can continue using
+the command line.  From there, simply use `Athena's File menu
+<https://bruceravel.github.io/demeter/documents/Athena/import/index.html>`__
+to load data from your proposal folder.
 
 
 
 Accessing data via Tiled
 ------------------------
 
-.. todo:: Need to flesh this out.
+.. todo:: Details needed
+
+Accessing data via Jupyter
+--------------------------
+
+.. todo:: Details needed