How to Use the hklpy2.user Interface#

The hklpy2.user module provides a set of convenience functions designed for interactive use at the Python or IPython prompt. They are modelled on familiar SPEC commands and operate on a single active diffractometer set with set_diffractometer().

Setup#

All examples assume a diffractometer has been created and set as active:

>>> import hklpy2
>>> from hklpy2.user import *
>>> fourc = hklpy2.creator(name="fourc", geometry="E4CV", solver="hkl_soleil")
>>> set_diffractometer(fourc)

The from hklpy2.user import * form is convenient at the interactive prompt. In scripts, import only the functions you need.

Setting the active diffractometer#

All hklpy2.user functions operate on the active diffractometer. Use set_diffractometer() to select it:

>>> set_diffractometer(fourc)

To query which diffractometer is currently active:

>>> get_diffractometer()

Reporting the diffractometer state#

pa() (“print all”) prints the full diffractometer state — solver, sample, reflections, \(UB\) matrix, constraints, mode, wavelength, and current position:

>>> pa()

wh() (“where”) prints a brief summary of the current position — wavelength, pseudo axes (\(h, k, l\)), and real motor angles:

>>> wh()

Managing samples#

Add a named sample with lattice parameters:

>>> add_sample("silicon", a=hklpy2.SI_LATTICE_PARAMETER)

List all samples on the active diffractometer (the current sample is shown with a > prefix):

>>> list_samples()

Change the lattice of the current sample:

>>> set_lattice(5.431)                       # cubic: a only
>>> set_lattice(3.0, c=5.0, gamma=120)       # hexagonal: a, c, gamma
>>> set_lattice(5.0, 6.0, 7.0, gamma=109.235)    # monoclinic: a, b, c, gamma

Remove a sample by name:

>>> remove_sample("silicon")

Managing the wavelength#

Set the wavelength of the active diffractometer’s beam:

>>> set_wavelength(1.54)                     # Angstroms (default)
>>> set_wavelength(154.0, units="pm")        # picometres

Note

set_wavelength() requires write access to the beam wavelength signal. The wavelength is read-only when the source has a fixed wavelength — for example an X-ray tube or rotating anode. At a tunable synchrotron beamline, wavelength is set via the monochromator control system and the signal has write access.

Orientation reflections and UB matrix#

Record an orientation reflection (motor angles for a known \((h, k, l)\)):

>>> r1 = setor(4, 0, 0, tth=69.0966, omega=-145.451, chi=0, phi=0)
>>> r2 = setor(0, 4, 0, tth=69.0966, omega=-145.451, chi=90, phi=0)

Compute the \(UB\) matrix from two reflections:

>>> calc_UB(r1, r2)

Swap the two orienting reflections and recompute \(UB\) (equivalent to SPEC’s or_swap):

>>> or_swap()

Remove a reflection by name:

>>> remove_reflection(r1.name)

See How to Compute and Set the UB Matrix for the full UB matrix workflow.

Calculating motor positions#

Calculate motor positions for a given \((h, k, l)\) without moving any motors:

>>> cahkl(4, 0, 0)

Show a table of all allowed solutions for one or more reflections:

>>> cahkl_table((4, 0, 0), (0, 4, 0))

Moving to a reciprocal-space position#

Move the diffractometer to a given \((h, k, l)\) position directly:

>>> fourc.move(4, 0, 0)

Or from a Bluesky plan:

>>> import bluesky.plan_stubs as bps
>>> RE(bps.mv(fourc, (4, 0, 0)))

Tip

cahkl() and wh() are useful before and after a move to verify the expected and actual positions.

Inspecting solver modes and geometries#

Print a summary of all engines, modes, and axes for the active solver:

>>> solver_summary()

Set the calculation mode:

>>> fourc.core.mode = "bissector"

List all available modes:

>>> fourc.core.modes

Scanning with extra parameters fixed#

scan_extra() is a Bluesky plan generator that scans diffractometer axes while holding pseudo axes, real axes, or extra parameters fixed:

>>> from bluesky import RunEngine
>>> RE = RunEngine({})
>>> # scan omega while holding h=4, k=0, l=0 fixed
>>> RE(scan_extra([fourc], fourc.omega, -40, -30, num=11,
...               pseudos=dict(h=4, k=0, l=0)))

Quick reference#

The table below maps common SPEC commands to their hklpy2.user equivalents. See SPEC commands in hklpy2 for the full list.

SPEC command	hklpy2.user	Description
`pa`	`pa()`	Print all diffractometer settings
`wh`	`wh()`	Print current position (where)
`ca h k l`	`cahkl()`	Calculate angles for hkl, no move
`br h k l`	`move()`	Move to hkl position
`or0` / `or1`	`setor()`	Set an orienting reflection
`or_swap`	`or_swap()`	Swap the two orienting reflections
`setlat`	`set_lattice()`	Set crystal lattice parameters
`setmode`	`fourc.core.mode = "..."`	Set the forward() calculation mode
`reflex`	`refine_lattice()`	Refine lattice from 3+ reflections