MNT #72 Merge branch 'main' into 72-reorg-docs

.coveragerc

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

RELEASE_NOTES.rst

@@ -0,0 +1,65 @@
+===============
+Release History
+===============
+
+.. subsections could include these headings (in this order)
+
+    Breaking Changes
+    New Features and/or Enhancements
+    Fixes
+    Maintenance
+    Deprecations
+
+v1.0.0 (tba)
+============
+
+Consult the 1.0.0 milestone [#]_ on GitHub for an expected
+release date.
+
+.. [#] https://github.com/bluesky/hklpy/milestone/5
+
+v0.3.15 (2020-12-20)
+====================
+
+Breaking Changes
+----------------
+
+* Diffractometer wavelength **must** use *angstrom* units to match the
+  lattice constants.  Previously, wavelength was stated to be in
+  `nm`. Instruments upgrading to this release should verify the units
+  actually in use.
+
+New Features and/or Enhancements
+--------------------------------
+
+* Diffractometer energy units can be specified.  Unit conversions
+  are handled by the *pint* [#]_ package.
+
+* Examples of E4CV, K4CV, and E6C diffractometer geometries.
+* Comparison of UB matrix calculation with SPEC data.
+* Source code documentation in `hkl.diffract`.
+* Show how to connect energy from local controls.
+
+.. [#] *pint*: https://pint.readthedocs.io/en/stable/
+
+Fixes
+-----
+
+* Limits-checking for *hkl* values now coordinated with upstream
+  ``bluesky`` code.
+
+Maintenance
+-----------
+
+* Move continuous integration processes to GitHub Actions.
+* Documentation now published with other bluesky packages:
+  https://blueskyproject.io/hklpy/
+
+Deprecations
+------------
+
+* All the previous examples have been archived and will be
+  removed for the 1.0.0 release.
+
+v0.3.14 (2020-09-28)
+====================

docs/source/api.rst

@@ -11,4 +11,5 @@ API Reference
    engine
    geometries
    sample
+   user
    util

docs/source/conf.py

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

docs/source/release_notes.rst

@@ -1,65 +1 @@
-===============
-Release History
-===============
-
-.. subsections could include these headings (in this order)
-
-    Breaking Changes
-    New Features and/or Enhancements
-    Fixes
-    Maintenance
-    Deprecations
-
-v1.0.0 (tba)
-============
-
-Consult the 1.0.0 milestone [#]_ on GitHub for an expected
-release date.
-
-.. [#] https://github.com/bluesky/hklpy/milestone/5
-
-v0.3.15 (2020-12-20)
-====================
-
-Breaking Changes
-----------------
-
-* Diffractometer wavelength **must** use *angstrom* units to match the
-  lattice constants.  Previously, wavelength was stated to be in
-  `nm`. Instruments upgrading to this release should verify the units
-  actually in use.
-
-New Features and/or Enhancements
---------------------------------
-
-* Diffractometer energy units can be specified.  Unit conversions
-  are handled by the *pint* [#]_ package.
-
-* Examples of E4CV, K4CV, and E6C diffractometer geometries.
-* Comparison of UB matrix calculation with SPEC data.
-* Source code documentation in `hkl.diffract`.
-* Show how to connect energy from local controls.
-
-.. [#] *pint*: https://pint.readthedocs.io/en/stable/
-
-Fixes
------
-
-* Limits-checking for *hkl* values now coordinated with upstream
-  ``bluesky`` code.
-
-Maintenance
------------
-
-* Move continuous integration processes to GitHub Actions.
-* Documentation now published with other bluesky packages:
-  https://blueskyproject.io/hklpy/
-
-Deprecations
-------------
-
-* All the previous examples have been archived and will be
-  removed for the 1.0.0 release.
-
-v0.3.14 (2020-09-28)
-====================
+.. include:: ../../RELEASE_NOTES.rst

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