Merge pull request #117 from bluesky/63-user-2021-04

simpler UI for one geometry at a time, from APS 29-ID

.coveragerc

@@ -1,5 +1,5 @@
 [run]
-source=ophyd
+source=hkl
 
 [report]
 omit=

docs/source/conf.py

@@ -26,6 +26,7 @@
 import hkl.calc
 import hkl.diffract
 import hkl.geometries
+import hkl.user
 
 # -- General configuration -----------------------------------------------------
 

docs/source/index.rst

@@ -41,6 +41,7 @@ Contents:
    engine
    geometries
    sample
+   user
    util
    examples/*
    release_notes

docs/source/user.rst

@@ -0,0 +1,86 @@
+.. _user:
+
+user
+----
+
+Make it easier for users (especially SPEC users) to learn and remember
+the new tools in Bluesky's *hklpy* package.
+
+Quick Reference Table
+
+==============  =======================================
+*SPEC*          *hklpy*
+==============  =======================================
+--              :func:`~calc_UB`
+--              :func:`~new_sample`
+--              :func:`~select_diffractometer`
+``br``          TODO:
+``cal``         :func:`cahkl`
+``cuts``        TODO: constraints
+``cz``          TODO:
+``freeze``      TODO: constraints
+``g_sect``      TODO: constraints
+``mz``          TODO:
+``or_swap``     TODO:
+``or0``         :func:`~setor`
+``or1``         :func:`~setor`
+``pa``          :func:`~pa`
+``pl``          TODO:
+``reflex_beg``  TODO:
+``reflex_end``  TODO:
+``reflex``      TODO:
+``setaz``       TODO:
+``setlat``      :func:`~update_sample`
+``setmode``     TODO: modes
+``setsector``   TODO:
+``sz``          TODO:
+``unfreeze``    TODO: constraints
+``wh``          :func:`~wh`
+==============  =======================================
+
+.. automodule:: hkl.user
+    :members:
+
+----
+
+.. _user.examples:
+
+
+EXAMPLES::
+
+    # work with our 4-circle simulator
+    select_diffractometer(fourc)
+
+    # sample is the silicon standard
+    a0 = 5.4310196; new_sample("silicon standard", a0, a0, a0, 90, 90, 90)
+
+    list_samples()
+
+    # define the first orientation reflection, specify each motor position
+    # motor values given in "diffractometer order"::
+    #     print(_geom_.calc.physical_axis_names)
+    r1 = setor(4, 0, 0, -145.451, 0, 0, 69.0966, wavelength=1.54)
+
+    # move to the position of the second reflection: (040)
+    %mov fourc.omega -145.451 fourc.chi 90 fourc.phi 0 fourc.tth 69.0966
+
+    # define the second orientation reflection, use current motor positions
+    r2 = setor(0, 4, 0)
+
+    calc_UB(r1, r2)
+
+    # calculate reflection, record motor positions before and after
+    p_before = fourc.real_position
+    fourc.forward(4, 0, 0)
+    p_after = fourc.real_position
+
+    # show if the motors moved
+    if p_before != p_after:
+        print("fourc MOVED!")
+    else:
+        print("fourc did not move.")
+
+    # cubic sample: show r2, the (040)
+    fourc.inverse(-145.5, 90, 0, 69)
+    # verify that the (0 -4 0) is half a rotation away in chi
+    fourc.inverse(-145.5, -90, 0, 69)

hkl/diffract.py

@@ -458,11 +458,23 @@ def _set_constraints(self, constraints):
             self.calc[axis].value = constraint.value
             self.calc[axis].fit = constraint.fit
 
-    def forward_solutions_table(self, reflections, full=False):
+    def forward_solutions_table(self, reflections, full=False, digits=5):
         """
-        Return table of computed solutions for each (hkl) in the supplied reflections list.
-
-        The solutions are calculated using the current UB matrix & constraints
+        Return table of computed solutions for each supplied (hkl) reflection.
+
+        The solutions are calculated using the current UB matrix & constraints.
+
+        Parameters
+        ----------
+        reflections : list of (h, k, l) reflections
+            Each reflection is a tuple of 3 numbers,
+            (h, k, l) of the reflection.
+        full : bool
+            If ``True``, show all solutions.  If ``False``,
+            only show the default solution.
+        digits : int
+            Number of digits to roundoff each position
+            value.  Default is 5.
         """
         _table = pyRestTable.Table()
         motors = self.real_positioners._fields
@@ -479,15 +491,15 @@ def forward_solutions_table(self, reflections, full=False):
             else:
                 for i, s in enumerate(solutions):
                     row = [reflection, i]
-                    row += [f"{getattr(s, m):.5f}" for m in motors]
+                    row += [round(getattr(s, m), digits) for m in motors]
                     _table.addRow(row)
                     if not full:
                         break  # only show the first (default) solution
         return _table
 
     def pa(self, all_samples=False, printing=True):
         """
-        Report the diffractometer settings.
+        Report (all) the diffractometer settings.
 
         EXAMPLE::
 
@@ -632,7 +644,7 @@ def Package(**kwargs):
 
     def wh(self, printing=True):
         """
-        report where is the diffractometer
+        Report (brief) where is the diffractometer.
 
         EXAMPLE::
 

hkl/tests/test_diffract.py

@@ -167,13 +167,13 @@ def test_forward_solutions_table(fourc):
     )
     received = str(tbl).splitlines()
     expected = [
-        "=========== ======== ======== ======== ======== =========",
-        "(hkl)       solution omega    chi      phi      tth      ",
-        "=========== ======== ======== ======== ======== =========",
-        "[1, 1, 0]   0        45.00000 45.00000 90.00000 90.00000 ",
-        "[1, 1, 1]   0        60.00000 35.26439 45.00000 120.00000",
-        "[100, 1, 1] none                                         ",
-        "=========== ======== ======== ======== ======== =========",
+        "=========== ======== ===== ======== ==== =====",
+        "(hkl)       solution omega chi      phi  tth  ",
+        "=========== ======== ===== ======== ==== =====",
+        "[1, 1, 0]   0        45.0  45.0     90.0 90.0 ",
+        "[1, 1, 1]   0        60.0  35.26439 45.0 120.0",
+        "[100, 1, 1] none                              ",
+        "=========== ======== ===== ======== ==== =====",
     ]
     for r, e in zip(received, expected):
         assert r == e