user#

Import: hklpy2.user

Simplified interface for hklpy2 diffractometer users.

add_reflection(h, k, l, *reals[, ...])

Define an ORienting reflection.

add_sample(name, a[, b, c, alpha, beta, ...])

Add (and select) a new crystal sample.

cahkl(h, k, l)

Calculate motor positions for specified 'h, k l' - DOES NOT MOVE motors.

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.

get_diffractometer()

Return the currently-selected diffractometer (or None).

list_samples([full])

Summarize diffractometer's samples.

or_swap()

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

remove_reflection(name[, error])

Pop the named reflection and remove it from list of orienting reflections.

pa([digits])

Report (all) the diffractometer settings.

remove_sample(name[, error])

Pop the named sample, set "selected" sample name to a valid one.

scan_extra(detectors, *args[, num, pseudos, ...])

Scan diffractometer parameter(s) at constant pseudos or reals.

scan_psi(detectors, *, h, k, l, hkl2, ...[, ...])

Scan the azimuthal angle (ψ) at a fixed (h, k, l) using the selected diffractometer.

set_diffractometer([diffractometer])

Declare the diffractometer to be used.

set_lattice(a[, b, c, alpha, beta, gamma, ...])

Redefine the sample's lattice.

set_wavelength(value[, units])

Set the wavelength; if Signal has write access, changes control system.

setor(h, k, l, *reals[, wavelength, name])

Define an ORienting reflection.

solver_summary([write])

Table of diffractometer solver's modes, axes, ...

wh([digits])

Report (brief) where is the diffractometer.

See also

Quickstart

Module Contents#

hklpy2.user.add_reflection[source]#
hklpy2.user.add_sample(name: str, a: float, b: float | None = None, c: float | None = None, alpha: float = 90, beta: float | None = None, gamma: float | None = None, digits: int = 4, replace: bool = False) → Sample[source]#

Import: hklpy2.user.add_sample

Add (and select) a new crystal sample.

EXAMPLE:

>>> add_sample("example", 2, 4, 5)
Sample(name='example',
    lattice=Lattice(a=2, b=4, c=5, system='orthorhombic'))

See also

list_samples() remove_sample()

hklpy2.user.cahkl(h: float, k: float, l: float) → list | str[source]#

Import: hklpy2.user.cahkl

Calculate motor positions for specified ‘h, k l’ - DOES NOT MOVE motors.

Returns a ‘RealPos’ object or the text of the exception.

EXAMPLE:

>>> cahkl(1,-1, 1)
Hklpy2DiffractometerRealPos(
    omega=12.254918848391,
    chi=-35.26440860898,
    phi=45.015980687529,
    tth=24.509837696782)
hklpy2.user.cahkl_table(*reflections: list[AxesTuple], digits=4) → Table[source]#

Import: hklpy2.user.cahkl_table

Print a table with motor positions for each reflection given.

EXAMPLE:

 1>>> cahkl_table((1, 1, 0), (1, 1, 1))
 2======= = ====== ========= ====== ======
 3(hkl)   # omega  chi       phi    tth
 4======= = ====== ========= ====== ======
 5(1 1 0) 1 45.0   45.0      90.0   90.0
 6(1 1 0) 2 -45.0  -45.0     -90.0  -90.0
 7(1 1 0) 3 45.0   135.0     -90.0  90.0
 8(1 1 0) 4 -135.0 -45.0     -90.0  90.0
 9(1 1 0) 5 -45.0  -135.0    90.0   -90.0
10(1 1 0) 6 -135.0 -135.0    90.0   90.0
11(1 1 1) 1 60.0   35.2644   45.0   120.0
12(1 1 1) 2 -60.0  -35.2644  -135.0 -120.0
13(1 1 1) 3 -60.0  -144.7356 45.0   -120.0
14(1 1 1) 4 -120.0 -35.2644  -135.0 120.0
15(1 1 1) 5 -120.0 -144.7356 45.0   120.0
16(1 1 1) 6 60.0   144.7356  -135.0 120.0
17======= = ====== ========= ====== ======
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.

hklpy2.user.calc_UB(r1: Reflection | str, r2: Reflection | str, wavelength: float | None = None) → Matrix3x3[source]#

Import: hklpy2.user.calc_UB

Compute the UB matrix with two reflections.

EXAMPLE:

1>>> r400 = setor(name='r400', 4, 0, 0, omega=-145.451, chi=0, phi=0, tth=69.066)
2>>> r004 = setor(name='r004', 0, 0, 4, omega=-145.451, chi=90, phi=0, tth=69.066)
3>>> calc_UB(r400, r004)
4[[-0.000279252712, 0.999999913446, -0.000279252646],
5[0.0, -0.000279400627, -1.000000132342],
6[-1.000000087766, -0.000280008582, 2.82915e-07]]
hklpy2.user.get_diffractometer() → DiffractometerBase | None[source]#

Import: hklpy2.user.get_diffractometer

Return the currently-selected diffractometer (or None).

EXAMPLE:

 1>>> get_diffractometer()
 2Hklpy2Diffractometer(
 3    prefix='',
 4    name='e4cv',
 5    settle_time=0.0,
 6    timeout=None, egu='',
 7    limits=(0, 0),
 8    source='computed',
 9    read_attrs=['h', 'h.readback', 'h.setpoint', 'k', 'k.readback', 'k.setpoint', 'l', 'l.readback', 'l.setpoint', 'omega', 'chi', 'phi', 'tth'],
10    configuration_attrs=['geometry', 'solver', 'wavelength', 'h', 'k', 'l'],
11    concurrent=True)
hklpy2.user.list_samples(full=False) → None[source]#

Import: hklpy2.user.list_samples

Summarize diffractometer’s samples.

Current sample appears first (with prefix "> ").

EXAMPLE:

1>>> list_samples()
2> Sample(name='vibranium', lattice=Lattice(a=6.2832, system='cubic'))
3Sample(name='sample', lattice=Lattice(a=1, system='cubic'))

See also

add_sample() remove_sample()

hklpy2.user.or_swap() → Matrix3x3[source]#

Import: hklpy2.user.or_swap

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

Note

The SPEC user community knows this function as or_swap (swap the first two orienting reflections).

EXAMPLE:

1>>> # define 2 reflections
2>>> r400 = setor(4, 0, 0, tth=69.0966, omega=-145.451, chi=0, phi=0, wavelength=1.54)
3>>> r040 = setor(0, 4, 0, tth=69.0966, omega=-145.451, chi=0, phi=90, wavelength=1.54)
4>>> # calculate UB
5>>> calc_UB(r400, r040)
6>>> # swap the two reflections (and recalculate UB)
7>>> or_swap()

See also

setor()

hklpy2.user.pa(digits=4) → None[source]#

Import: hklpy2.user.pa

Report (all) the diffractometer settings.

EXAMPLE:

 1>>> pa()
 2diffractometer='e4cv'
 3HklSolver(name='hkl_soleil', version='5.1.2', geometry='E4CV', engine_name='hkl', mode='bissector')
 4Sample(name='vibranium', lattice=Lattice(a=6.2832, system='cubic'))
 5U=[[0.000278604397, -0.99999996119, -3.9081e-08], [1.6307e-08, 3.9086e-08, -1.0], [0.99999996119, 0.000278604397, 1.6317e-08]]
 6UB=[[0.000278604432, -0.999999952659, -1.87102e-07], [1.6307e-08, 3.9086e-08, -1.000000171333], [1.000000087947, 0.000279360313, -1.88574e-07]]
 7Reflection(name='r400', geometry='E4CV', pseudos={'h': 4, 'k': 0, 'l': 0}, reals={'omega': -145.451, 'chi': 0, 'phi': 0, 'tth': 69.066}, wavelength=1.54, digits=4)
 8Reflection(name='r040', geometry='E4CV', pseudos={'h': 0, 'k': 4, 'l': 0}, reals={'omega': -145.451, 'chi': 0, 'phi': 90, 'tth': 69.066}, wavelength=1.54, digits=4)
 9Reflection(name='r004', geometry='E4CV', pseudos={'h': 0, 'k': 0, 'l': 4}, reals={'omega': -145.451, 'chi': 90, 'phi': 0, 'tth': 69.066}, wavelength=1.54, digits=4)
10Orienting reflections: ['r040', 'r004']
11constraint: -180.2 <= omega <= 180.2
12constraint: -180.2 <= chi <= 180.2
13constraint: -180.2 <= phi <= 180.2
14constraint: -180.2 <= tth <= 180.2
15h=0, k=0, l=0
16wavelength=1.54
17omega=0, chi=0, phi=0, tth=0

See also

wh()

hklpy2.user.remove_reflection(name: str, error: bool = True) → None[source]#

Import: hklpy2.user.remove_reflection

Pop the named reflection and remove it from list of orienting reflections.

EXAMPLE:

>>> remove_reflection("r100")

PARAMETERS

name: str

Reflection name to be removed.

error: bool

When True (default), KeyError is raised if name is not found. Provide error=False to skip the exception.

See also

add_reflection(), or_swap(), setor()

hklpy2.user.remove_sample(name: str, error: bool = True) → None[source]#

Import: hklpy2.user.remove_sample

Pop the named sample, set “selected” sample name to a valid one.

EXAMPLE:

>>> remove_sample("sample")

PARAMETERS

name: str

Sample name to be removed.

error: bool

When error=True (default):

and

will raise

name is not found.

KeyError

name is the only sample.

CoreError

Provide error=False to avoid raising an exception.

See also

add_sample() list_samples()

hklpy2.user.scan_extra(detectors: Iterable[Readable], *args: Movable | Any, num: int | None = 2, pseudos: dict | None = None, reals: dict | None = None, extras: dict | None = None, fail_on_exception: bool | None = False, md: dict | None = None) → BlueskyPlanType[source]#

Import: hklpy2.user.scan_extra

Scan diffractometer parameter(s) at constant pseudos or reals.

Uses selected diffractometer.

Example

 1>>> import hklpy2
 2>>> from hklpy2.user import *
 3>>> e6c = hklpy2.creator(name="e6c", geometry="E6C")
 4>>> set_diffractometer(e6c)
 5>>> e6c.core.mode = "psi_constant_vertical"
 6>>> RE(
 7    scan_extra(
 8        [noisy_det, e6c],
 9        "psi", 0, 150,
10        num=15,
11        pseudos=dict(h=0, k=0, l=2),
12        extras=dict(h2=1, k2=2, l2=0)
13    )
14)

Parameters

detectors: Iterable[Readable]

List of readable objects.

args: Any

Specification of scan axes. The specification is a repeating pattern of axis (str), start (float), stop (float).

In general:

axis1, start1, stop1,
axis2, start2, stop2,
...,
axisN, startN, stopN

Axis is any extra axis name supported by the current diffractometer geometry and mode.

num: int

Number of points.

pseudos: dict

Dictionary of pseudo axes positions to be held constant during the scan.

reals: dict

Dictionary of real axes positions to be held constant during the scan.

extras: dict

Dictionary of extra axes positions to be held constant during the scan.

fail_on_exception: bool

When True (default: False), scan will raise any exceptions. When False, all exceptions during the scan will be printed to console.

md: dict

Dictionary of user-supplied metadata.

hklpy2.user.scan_psi(detectors, *, h: float, k: float, l: float, hkl2, psi_start: float, psi_stop: float, num: int, mode: str | None = None, psi_axis: str | None = None, fail_on_exception: bool = False, md: dict | None = None)[source]#

Import: hklpy2.user.scan_psi

Scan the azimuthal angle (ψ) at a fixed (h, k, l) using the selected diffractometer.

Thin wrapper around scan_psi() that obtains the diffractometer from get_diffractometer().

Example

 1>>> import hklpy2
 2>>> from hklpy2.user import *
 3>>> fourc = hklpy2.creator(name="fourc")
 4>>> set_diffractometer(fourc)
 5>>> # ... set up sample and UB matrix ...
 6>>> RE(
 7    scan_psi(
 8        [noisy_det, fourc],
 9        h=2, k=2, l=0,
10        hkl2=(1, -1, 0),
11        psi_start=0, psi_stop=180,
12        num=7,
13    )
14)

Parameters

detectors:

List of readable objects.

h, k, l: float

Fixed reflection coordinates.

hkl2: sequence of float

Reference reflection (h2, k2, l2) defining psi = 0. Must not be parallel to (h, k, l).

psi_start: float

Starting azimuthal angle (degrees).

psi_stop: float

Ending azimuthal angle (degrees).

num: int

Number of points (inclusive of endpoints).

mode: str, optional

Psi mode name override. Auto-detected when None.

psi_axis: str, optional

Psi extra axis name override. Auto-detected when None.

fail_on_exception: bool

When True, raise on failed forward solutions. Default False.

md: dict, optional

User-supplied metadata.

See also

scan_psi()

hklpy2.user.set_diffractometer(diffractometer: DiffractometerBase | None = None) → None[source]#

Import: hklpy2.user.set_diffractometer

Declare the diffractometer to be used.

EXAMPLE:

>>> set_diffractometer(e4cv)

See also

get_diffractometer()

hklpy2.user.set_lattice(a: float, b: float | None = None, c: float | None = None, alpha: float = 90, beta: float | None = None, gamma: float | None = None, digits: int = 4) → None[source]#

Import: hklpy2.user.set_lattice

Redefine the sample’s lattice.

EXAMPLE:

>>> set_lattice(3, c=4, gamma=120)
hklpy2.user.set_wavelength(value: float, units=None) → None[source]#

Import: hklpy2.user.set_wavelength

Set the wavelength; if Signal has write access, changes control system.

EXAMPLE:

>>> set_wavelength(123.45, units="pm")
hklpy2.user.setor(h, k, l, *reals: NUMERIC, wavelength=None, name=None, **kwreals: AxesDict) → Reflection[source]#

Import: hklpy2.user.setor

Define an ORienting reflection.

Aliases: add_reflection(), setor()

A reflection is defined by its reciprocal space coordinates (pseudos) and its motor positions (reals). For convenience of the user, each reflection is named.

Note

The SPEC user community knows this function as setor.

EXAMPLES:

>>> setor(4, 0, 0)
Reflection(name='r_4ad1', geometry='E4CV', pseudos={'h': 4, 'k': 0, 'l': 0},
    reals={'omega': -145.451, 'chi': 0, 'phi': 0, 'tth': 69.0966}, wavelength=1.54, digits=4)

>>> setor(0, 4, 0, -145.451, 0, 90, 69.0966, name="r040")
Reflection(name='r040', geometry='E4CV', pseudos={'h': 0, 'k': 4, 'l': 0},
    reals={'omega': -145.451, 'chi': 0, 'phi': 90, 'tth': 69.0966}, wavelength=1.54, digits=4)

>>> setor(0, 0, 4, omega=-145.451, chi=90, phi=0, tth=69.0966, name="r004")
Reflection(name='r004', geometry='E4CV', pseudos={'h': 0, 'k': 0, 'l': 4},
    reals={'omega': -145.451, 'chi': 90, 'phi': 0, 'tth': 69.0966}, wavelength=1.54, digits=4)

PARAMETERS

h, k, l: float

Reciprocal-space coordinates of this reflection.

reals: NUMERIC

(optional) Real-space values of this reflection. Must provide all values in the order expected by the geometry. See Positions tip below.

kwreals: AxesDict

(optional) Real-space axis names and values of this reflection. Must provide all axes expected by the geometry. See Positions tip below.

wavelength: float

(optional) Wavelength of this reflection. When not specified, use the current diffractometer value.

name: str

(optional) Reference text identifying this reflection. When not specified, a unique name will be assigned.

Tip

Positions (reals, kwreals, or omitted entirely):

  • Specified by values (in reals). Must use expected order. Will skip kwreals if also provided.

  • Specified by names (in kwreals). Axes, can appear in any order.

  • reals and kwreals can be omitted entirely (use current values from diffractometer)

See the examples above.

hklpy2.user.solver_summary(write=True) → Table | None[source]#

Import: hklpy2.user.solver_summary

Table of diffractometer solver’s modes, axes, …

EXAMPLE:

 1>>> import hklpy2
 2>>> from hklpy2.user import *
 3>>> e4cv = hklpy2.creator(name="e4cv")
 4>>> set_diffractometer(e4cv)
 5>>> solver_summary()
 6========= ================== ================== ==================== ==================== ===============
 7engine    mode               pseudo(s)          real(s)              writable(s)          extra(s)
 8========= ================== ================== ==================== ==================== ===============
 9hkl       bissector          h, k, l            omega, chi, phi, tth omega, chi, phi, tth
10hkl       constant_omega     h, k, l            omega, chi, phi, tth chi, phi, tth
11hkl       constant_chi       h, k, l            omega, chi, phi, tth omega, phi, tth
12hkl       constant_phi       h, k, l            omega, chi, phi, tth omega, chi, tth
13hkl       double_diffraction h, k, l            omega, chi, phi, tth omega, chi, phi, tth h2, k2, l2
14hkl       psi_constant       h, k, l            omega, chi, phi, tth omega, chi, phi, tth h2, k2, l2, psi
15psi       psi                psi                omega, chi, phi, tth omega, chi, phi, tth h2, k2, l2
16q         q                  q                  tth                  tth
17incidence incidence          incidence, azimuth omega, chi, phi                           x, y, z
18emergence emergence          emergence, azimuth omega, chi, phi, tth                      x, y, z
19========= ================== ================== ==================== ==================== ===============

See also

Available Solver Geometry Tables, hklpy2.backends.base.SolverBase.summary()

hklpy2.user.wh(digits=4) → None[source]#

Import: hklpy2.user.wh

Report (brief) where is the diffractometer.

EXAMPLE:

1>>> wh()
2h=0, k=0, l=0
3wavelength=1.0
4omega=0, chi=0, phi=0, tth=0

See also

pa()