Documentation updates

docs/source/experiment.rst

@@ -95,7 +95,7 @@ called ``nxrefine``, of the instrument's ``experiment`` directory::
         .
 
 The name of this sub-directory is defined in the server settings, which
-are defined in the Server section.
+are described in the Server section.
 
 Experiment Sub-Directories
 --------------------------
@@ -202,21 +202,21 @@ defined in the customized beamline classes described later.
 For example, at CHESS, the 'raw' and 'analysis' paths are defined in
 parallel directory trees as follows (with generic experiment names)::
 
-    /nfs/chess/id4b                 /nfs/chess/id4baux
-    ├── 2023-1                      ├── 2023-1
-    ├── 2023-2                      ├── 2023-2
-    └── 2023-2                      └── 2023-2
-        ├── experiment1                 ├── experiment1
-        ├── experiment2                 ├── experiment2
-        └── experiment3                 └── experiment3
-            └── raw6M                       └── nxrefine
-                ├── sample1                     ├── sample1
-                ├── sample2                     ├── sample2
-                └── sample3                     └── sample3
-                    └── label1                      └── label1
-                        ├── 100                         ├── 100
-                        ├── 200                         ├── 200
-                        └── 300                         └── 300
+    /nfs/chess/id4b                         /nfs/chess/id4baux
+    ├── 2023-1                              ├── 2023-1
+    ├── 2023-2                              ├── 2023-2
+    └── 2023-2                              └── 2023-2
+        ├── experiment1                         ├── experiment1
+        ├── experiment2                         ├── experiment2
+        └── experiment3                         └── experiment3
+            └── raw6M                               └── nxrefine
+                ├── sample1                             ├── sample1
+                ├── sample2                             ├── sample2
+                └── sample3                             └── sample3
+                    └── label1                              └── label1
+                        ├── 100                                 ├── 100
+                        ├── 200                                 ├── 200
+                        └── 300                                 └── 300
 
 Here is a list of instrument parameters.
 
@@ -278,7 +278,7 @@ a file browser in order to select a directory. There are two scenarios.
 
 .. figure:: /images/new-experiment-CHESS.png
    :align: center
-   :width: 90%
+   :width: 40%
 
 2. If ``raw_home`` is blank, the file browser will default to the
    ``analysis_home`` directory, from where a new directory can be

docs/source/introduction.rst

@@ -1,28 +1,30 @@
 Introduction
 ============
 NXRefine implements a complete workflow for both data acquisition and 
-reduction of single crystal x-ray scattering, collected by the sample
+reduction of single crystal x-ray scattering collected by the sample
 rotation method. NXRefine generates a three-dimensional mesh of
-scattering intensity, *i.e.*, S(Q), which can be used either to model
-diffuse scattering in reciprocal space or to transform the data to
+scattering intensity, *i.e.*, S(**Q**), which can be used either to
+model diffuse scattering in reciprocal space or to transform the data to
 produce three-dimensional pair-distribution-functions (PDF), which
-represent the summed probabilities of all possible interatomic vectors.
-In crystallography, these are known as Patterson maps. If the Bragg
-peaks are eliminated before these transforms, using a process known as
-'punch-and-fill,' only those probabilities that deviate from the average
-crystalline structure are retained, generating 'difference' Patterson,
-or 3D-ΔPDF, maps. The final stage of the NXRefine workflow is to
-generate such 3D-ΔPDF maps.
+represent the summed probabilities of all possible interatomic vectors
+in real space, *i.e.*, Patterson maps. If the Bragg peaks are eliminated
+before these transforms, using a process known as 'punch-and-fill,' only
+those probabilities that deviate from the average crystalline structure
+are retained, generating 'difference' Patterson, or 3D-ΔPDF, maps. The
+final stage of the NXRefine workflow is to generate such 3D-ΔPDF maps.
 
 The uncompressed raw data from such measurements comprises tens (and
 sometimes hundreds) of gigabytes, often collected in under 30 minutes.
-This allows such measurements to be repeated multiple times as a
-function of a parametric variable, such as temperature. Ideally, such
-data should be transformed into reciprocal space as quickly as it is
-measured, so that scientists can inspect the results before a set of
-scans is complete. For this reason, NXRefine enables the workflow to be
-run automatically once an initial refinement of the sample orientation
-has been determined.
+The speed of data collection allows such measurements to be repeated
+multiple times as a function of a parametric variable, such as
+temperature. Ideally, such data should be transformed into reciprocal
+space as quickly as it is measured, so that scientists can inspect the
+results before a set of scans is complete. For this reason, the NXRefine
+workflow is designed to be run automatically once an initial refinement
+of the sample orientation has been determined.
+
+NXRefine is currently in use on Sector 6-ID-D at the Advanced Photon
+Source and the QM2 beamline at CHESS. 
 
 Experimental Geometry
 ---------------------
@@ -38,11 +40,12 @@ monochromatic x-ray beam and rotated continuously about a Φ-axis that is
 approximately perpendicular to the beam. Images are collected on an area
 detector placed in transmission geometry behind the sample. Detectors
 such as the Dectris Pilatus series consist of a set of chips with small
-gaps between them, so sample rotation scans are often repeated three
-times with small detector translations between each one. However, it is
-also possible to fill in the gaps just by adjusting the orientation of
-the Φ-axis itself. NXRefine reduces the data independently for each
-rotation scan before merging them to create a single 3D data volume.
+gaps between them, so sample rotation scans are often repeated multiple
+times (usually three) with small detector translations between each one
+to fill in these gaps. However, it is also possible to accomplish this
+just by adjusting the orientation of the Φ-axis itself. NXRefine reduces
+the data independently for each rotation scan before merging them to
+create a single 3D data volume.
 
 The Φ-axis is approximately perpendicular to the beam. The Φ-axis motor
 is on a χ-circle (not shown), with χ = 0° corresponding to a vertical
@@ -54,16 +57,16 @@ plane by ω and in the vertical plane by θ.
           defined by H. You [see Fig. 1 in J. Appl. Cryst. **32**, 614
           (1999)], with θ and ω corresponding to η and μ, respectively.
           At present, NXRefine assumes that the two angles coupled to
-          the detector (δ and ν in You's paper), are fixed to 0°, with detector
-          misalignments handled by the yaw and pitch angles refined in
-          powder calibrations.
+          the detector (δ and ν in You's paper), are fixed to 0°, with
+          detector misalignments handled by the yaw and pitch angles
+          refined in powder calibrations.
 
 .. warning:: In earlier versions of NXRefine, θ was called the
              goniometer pitch angle, since it corresponds to a tilting
-             of the χ-circle about the horizontal axis. It is still
-             referred to as 'gonpitch' in CCTW, the C++ program called
-             by NXRefine to transform the detector coordinates to
-             reciprocal space.
+             or pitch of the goniometer's χ-circle about the horizontal
+             axis. It is still referred to as 'gonpitch' in CCTW, the
+             C++ program called by NXRefine to transform the detector
+             coordinates to reciprocal space.
 
 NXRefine uses the following conventions to define a set of Cartesian
 coordinates as laboratory coordinates when all angles are set to 0.
@@ -80,7 +83,19 @@ array, the detector X-axis corresponds to the fastest-changing
 direction, which is normally horizontal, so the orthogonal Y-axis is
 usually vertical. The two coordinate systems are then related by:
 
-    | +X(det) = -Y(lab), +Y(det) = +Z(lab), and +Z(det) = -X(lab)
+    | +X(det) = -Y(lab), +Y(det) = -Z(lab), and +Z(det) = -X(lab)
 
 This is defined by an orientation matrix, which can in principle be
 changed, although it is currently fixed.
+
+Sample Orientation
+------------------
+To transform data collected in this experimental geometry, it is
+necessary to determine an orientation matrix using Bragg peaks measured
+in the course of the sample rotation. With high-energy x-rays, the area
+detector covers reciprocal space volumes that can exceed
+10×10×10Å\ :sup:`3`. Depending on the size of the crystal unit cell,
+such volumes contain hundreds, if not thousands, of Brillouin Zones.
+NXRefine has a peak-search algorithm for identifying all the peaks above
+a certain intensity threshold, which are then used to generate an
+orientation matrix that is refined on many, if not all, Bragg peaks.