Module: user

Make it easier for users (especially SPEC users) to learn and remember the new tools in Bluesky’s hklpy package.

See SPEC commands in Bluesky for a table of SPEC commands and their counterparts in hklpy.

Provide a simplified interface for hklpy diffractometer users.

The user must define a diffractometer object, then register that object here. For example:

from hkl import SimulatedE4CV
from hkl.user import *

e4cv = SimulatedE4CV("", name="e4cv")
select_diffractometer(e4cv)
wh()

FUNCTIONS

cahkl(h, k, l)	Calculate motor positions for one reflection.
cahkl_table(reflections[, digits])	Print a table with motor positions for each reflection given.
calc_UB(r1, r2[, wavelength])	Compute the UB matrix with two reflections.
current_diffractometer()	Return the currently-selected diffractometer (or None).
list_samples([verbose])	List all defined crystal samples.
new_sample(nm, a, b, c, alpha, beta, gamma)	Define a new crystal sample.
or_swap()	Swap the 2 [UB] reflections, re-compute & return new [UB].
select_diffractometer([instrument])	Name the diffractometer to be used.
set_energy(value[, units, offset])	Set the energy (thus wavelength) to be used.
setor(h, k, l, *args[, wavelength])	Define a crystal reflection and its motor positions.
show_sample([sample_name, verbose])	Print the default sample name and crystal lattice.
show_selected_diffractometer([instrument])	Print the name of the selected diffractometer.
update_sample(a, b, c, alpha, beta, gamma)	Update current sample lattice.
wh()	Report (brief) where is the diffractometer.
pa()	Report (all) the diffractometer settings.

hkl.user.cahkl(h, k, l)

Calculate motor positions for one reflection.

Returns a namedtuple. Does not move motors.

hkl.user.cahkl_table(reflections, digits=5)

Print a table with motor positions for each reflection given.

Parameters:

• reflections (list(tuple(number,number,number))) –

  This is a list of reflections where each reflection is a tuple of 3 numbers specifying (h, k, l) of the reflection to compute the forward() computation.

  Example: [(1,0,0), (1,1,1)]

• digits (int) – Number of digits to roundoff each position value. Default is 5.

hkl.user.calc_UB(r1, r2, wavelength=None)

Compute the UB matrix with two reflections.

hkl.user.change_sample(sample)

Pick a known sample to be the current selection.

hkl.user.current_diffractometer()

Return the currently-selected diffractometer (or None).

hkl.user.list_samples(verbose=True)

List all defined crystal samples.

hkl.user.new_sample(nm, a, b, c, alpha, beta, gamma)

Define a new crystal sample.

hkl.user.or_swap()

Swap the 2 [UB] reflections, re-compute & return new [UB].

Example:

# define 2 reflections
r400 = hkl.user.setor(4, 0, 0, tth=69.0966, omega=-145.451, chi=0, phi=0, wavelength=1.54)
r040 = hkl.user.setor(0, 4, 0, tth=69.0966, omega=-145.451, chi=0, phi=90, wavelength=1.54)
# calculate UB
hkl.user.calc_UB(r400, r040)
# swap the two reflections (and recalculate UB)
hkl.user.or_swap()

hkl.user.pa()

Report (all) the diffractometer settings.

hkl.user.select_diffractometer(instrument=None)

Name the diffractometer to be used.

hkl.user.set_energy(value, units=None, offset=None)

Set the energy (thus wavelength) to be used.

hkl.user.setor(h, k, l, *args, wavelength=None, **kwargs)

Define a crystal reflection and its motor positions.

hkl.user.show_sample(sample_name=None, verbose=True)

Print the default sample name and crystal lattice.

hkl.user.show_selected_diffractometer(instrument=None)

Print the name of the selected diffractometer.

hkl.user.update_sample(a, b, c, alpha, beta, gamma)

Update current sample lattice.

hkl.user.wh()

Report (brief) where is the diffractometer.

---

EXAMPLES:

# work with our 4-circle simulator
select_diffractometer(fourc)

# sample is the silicon standard
a0 = hkl.SI_LATTICE_PARAMETER  # 5.4310...
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)