Describe geometry engines, modes, and axes

[prjemian]

• close geometry mode updates which axes? #305

(Re)build tables of diffractometer geometry, engines, and modes from libhkl API.

[prjemian]

@mrakitin @padraic-shafer @strempfer - This is ready for review. Here is an example of a table from the console UI:

(bluesky_2024_1) prjemian@arf:~/.../Bluesky/hklpy$ ipython
Python 3.11.6 | packaged by conda-forge | (main, Oct  3 2023, 10:40:35) [GCC 12.3.0]
Type 'copyright', 'credits' or 'license' for more information
IPython 8.17.2 -- An enhanced Interactive Python. Type '?' for help.

In [1]: from hkl import SimulatedK4CV

In [2]: sim4k = SimulatedK4CV("", name="sim4k")

In [3]: sim4k.geometry_table()
Geometry: K4CV
  real axes: komega, kappa, kphi, tth
  pseudo axes: depends on the engine

========= ================== ================== ======================== ======================== ================
engine    pseudo axes        mode               axes read                axes written             extra parameters
========= ================== ================== ======================== ======================== ================
emergence emergence, azimuth emergence          komega, kappa, kphi, tth                          x, y, z         
eulerians omega, chi, phi    eulerians          komega, kappa, kphi      komega, kappa, kphi      solutions       
hkl       h, k, l            bissector          komega, kappa, kphi, tth komega, kappa, kphi, tth                 
hkl       h, k, l            constant_chi       komega, kappa, kphi, tth komega, kappa, kphi, tth chi             
hkl       h, k, l            constant_omega     komega, kappa, kphi, tth komega, kappa, kphi, tth omega           
hkl       h, k, l            constant_phi       komega, kappa, kphi, tth komega, kappa, kphi, tth phi             
hkl       h, k, l            double_diffraction komega, kappa, kphi, tth komega, kappa, kphi, tth h2, k2, l2      
hkl       h, k, l            psi_constant       komega, kappa, kphi, tth komega, kappa, kphi, tth h2, k2, l2, psi 
incidence incidence, azimuth incidence          komega, kappa, kphi                               x, y, z         
psi       psi                psi                komega, kappa, kphi, tth komega, kappa, kphi, tth h2, k2, l2      
q         q                  q                  tth                      tth                                      
========= ================== ================== ======================== ======================== ================

[padraic-shafer]

This is a great addition!

[prjemian]

Note that the real axes names are the canonical names defined by the lower-level support library (libhkl), as access through the calc module. For a diffractometer with redefined axis names, the rename map comes from the Diffractometer in the diffract module. This is a user-level module. The Diffractometer.geometry_table() could be modified to supply the rename map. The lower-level CalcRecip.geometry_table() would need this additional dictionary to build the actual table.

But, let's not complicate this PR with this additional change.

[prjemian]

@rodolakis Added you as a reviewer.

[prjemian]

Could add properties for axes_r (real-space axes as defined by libhkl that are used to calculate forward reflection) and axes_w (the axes to be updated by forward calculation). The axes in axes_r that are missing from axes_w are the ones held constant (a question posed recently by @strempfer), a new property called axes_c.

If the engine module has these properties, they would use the canonical names. Then, the calc module could also define the same properties and replace canonical with renamed axes. Makes it easier for the user to understand a given mode and engine.

[mrakitin]

Looks good!

[prjemian]

@padraic-shafer , @mrakitin Thanks for the reviews!

@strempfer , @jwkim-anl : Thanks for the suggestion!

[padraic-shafer]

Suggested change

	"cname": gonio.__class__.__name__[4:], # 4 = len("Calc") as in "CalcE4CV"
	"cname": gonio.__class__.__name__[len("Calc"):],