hklpy2.misc#

Miscellaneous Support.

VirtualPositionerBase(*[, physical_name])

Base class for a diffractometer's virtual axis.

`axes_to_dict`(input, names)	Convert any acceptable axes input to standard form (dict).
`check_value_in_list`(title, value, examples)	Raise ValueError exception if value is not in the list of examples.
`compare_float_dicts`(a1, a2[, tol])	Compare two dictionaries.
`convert_units`(value, old_units, new_units)	Convert 'value' from old units to new.
`define_real_axis`(specs, kwargs)	Return class and kwargs of a real axis from its 'specs'.
`dict_device_factory`(data, **kwargs)	Create a `DictionaryDevice()` class using the supplied dictionary.
`distance_between_pos_tuples`(pos1, pos2)	Return the RMS distance between 'pos1' and 'pos2'.
`dynamic_import`(full_path)	Import the object given its import path as text.
`flatten_lists`(xs)	Convert nested lists into single list.
`get_run_orientation`(run[, name, start_key])	Return the orientation information dictionary from a run.
`get_solver`(solver_name)	Load a Solver class from a named entry point.
`istype`(value, annotation)	Check if 'value' matches the type 'annotation'.
`list_orientation_runs`(catalog[, limit, ...])	List the runs with orientation information.
`load_yaml`(text)	Load YAML from text.
`load_yaml_file`(file)	Return contents of a YAML file as a Python object.
`make_component`(call_name, args, *kwargs)	Create an Component for a custom ophyd Device class.
`make_dynamic_instance`(call_name, args, *kwargs)	Return an instance of the Python 'call_name'.
`parse_factory_axes`(*[, space, axes, order, ...])	Parse a set of axis specifications, return Device class attributes.
`pick_closest_solution`(position, solutions)	Find the solution closest to the current real position.
`pick_first_solution`(position, solutions)	Choose first solution from list.
`roundoff`(value[, digits])	Round a number to specified precision.
`solver_factory`(solver_name, geometry, **kwargs)	Create a Solver object with geometry and axes.
`solvers`()	Dictionary of available Solver classes, mapped by entry point name.
`unique_name`([prefix, length])	Short, unique name, first 7 (at most) characters of a unique, random uuid.
`validate_and_canonical_unit`(value, target_units)	Validate that value is a unit convertible to target_units.

`IDENTITY_MATRIX_3X3`	Identity matrix, 2-D, 3 rows, 3 columns.
`SOLVER_ENTRYPOINT_GROUP`	Name by which hklpy2 Solver classes are grouped.

`AnyAxesType`	Any of these types are used to describe both pseudo and real axes.
`AxesArray`	Numpy array of axes values.
`AxesDict`	Dictionary of axes names and values.
`AxesList`	List of axes values.
`AxesTuple`	Tuple of axes values.
`Matrix3x3`	mutable orientation & rotation matrices.
`INPUT_VECTOR`	Acceptable forms of vector input for zones, ...
`NamedFloatDict`	dictionary of named floats.
`NUMERIC`	Either integer or real number.

ConfigurationRunWrapper(*devices[, knowns])

Write configuration of supported device(s) to a bluesky run.

`Hklpy2Error`	Any exception from the hklpy2 package.
`ConfigurationError`	Custom exceptions from `hklpy2.blocks.configure`.
`ConstraintsError`	Custom exceptions from `hklpy2.blocks.constraints`.
`CoreError`	Custom exceptions from `hklpy2.ops.Core`.
`DiffractometerError`	Custom exceptions from `hklpy2.diffract.DiffractometerBase`.
`LatticeError`	Custom exceptions from `hklpy2.blocks.lattice`.
`NoForwardSolutions`	A solver did not find any `forward()` solutions.
`ReflectionError`	Custom exceptions from `hklpy2.blocks.reflection`.
`SampleError`	Custom exceptions from `hklpy2.blocks.sample`.
`SolverError`	Custom exceptions from a Solver.

Attributes#

`logger`
`BlueskyPlanType`	Type of a bluesky plan.
`KeyValueMap`	Dictionary for configuration and other.
`NUMERIC`	Either integer or real number.
`INPUT_VECTOR`	Acceptable forms of vector input for zones, ...
`AxesArray`	Numpy array of axes values.
`AxesDict`	Dictionary of axes names and values.
`AxesList`	List of axes values.
`AxesTuple`	Tuple of axes values.
`AnyAxesType`	Any of these types are used to describe both pseudo and real axes.
`Matrix3x3`	mutable orientation & rotation matrices.
`NamedFloatDict`	dictionary of named floats.
`IDENTITY_MATRIX_3X3`	Identity matrix, 2-D, 3 rows, 3 columns.
`SOLVER_ENTRYPOINT_GROUP`	Name by which hklpy2 Solver classes are grouped.
`DEFAULT_DIGITS`
`DEFAULT_START_KEY`
`INTERNAL_ANGLE_UNITS`
`INTERNAL_LENGTH_UNITS`
`INTERNAL_XRAY_ENERGY_UNITS`
`UREG`
`PINT_ERRORS`	Exception from pint that we are trapping here.
`DEFAULT_MOTOR_LABELS`	Default labels applied to real-axis positioners.

Exceptions#

`Hklpy2Error`	Any exception from the hklpy2 package.
`ConfigurationError`	Custom exceptions from `hklpy2.blocks.configure`.
`ConstraintsError`	Custom exceptions from `hklpy2.blocks.constraints`.
`CoreError`	Custom exceptions from `hklpy2.ops.Core`.
`DiffractometerError`	Custom exceptions from `hklpy2.diffract.DiffractometerBase`.
`LatticeError`	Custom exceptions from `hklpy2.blocks.lattice`.
`NoForwardSolutions`	A solver did not find any `forward()` solutions.
`ReflectionError`	Custom exceptions from `hklpy2.blocks.reflection`.
`SampleError`	Custom exceptions from `hklpy2.blocks.sample`.
`SolverError`	Custom exceptions from a Solver.

Classes#

`VirtualPositionerBase`	Base class for a diffractometer's virtual axis.
`ConfigurationRunWrapper`	Write configuration of supported device(s) to a bluesky run.

Functions#

`axes_to_dict`(→ AxesDict)	Convert any acceptable axes input to standard form (dict).
`check_value_in_list`(→ None)	Raise ValueError exception if value is not in the list of examples.
`compare_float_dicts`(→ bool)	Compare two dictionaries. Values are all floats.
`convert_units`(→ float)	Convert 'value' from old units to new.
`define_real_axis`(→ tuple[str, Sequence, Mapping])	Return class and kwargs of a real axis from its 'specs'.
`dict_device_factory`(→ type)	Create a `DictionaryDevice()` class using the supplied dictionary.
`distance_between_pos_tuples`(→ float)	Return the RMS distance between 'pos1' and 'pos2'.
`dynamic_import`(→ type)	Import the object given its import path as text.
`flatten_lists`(→ BlueskyPlanType)	Convert nested lists into single list.
`get_solver`(→ hklpy2.backends.base.SolverBase)	Load a Solver class from a named entry point.
`get_run_orientation`(→ KeyValueMap)	Return the orientation information dictionary from a run.
`istype`(→ bool)	Check if 'value' matches the type 'annotation'.
`list_orientation_runs`(→ pandas.DataFrame)	List the runs with orientation information.
`load_yaml`(→ Mapping)	Load YAML from text.
`load_yaml_file`(→ Mapping)	Return contents of a YAML file as a Python object.
`make_component`(→ ophyd.Component)	Create an Component for a custom ophyd Device class.
`make_dynamic_instance`(→ Any)	Return an instance of the Python 'call_name'.
`parse_factory_axes`(→ Mapping[str, ...)	Parse a set of axis specifications, return Device class attributes.
`pick_closest_solution`(→ NamedTuple)	Find the solution closest to the current real position.
`pick_first_solution`(→ NamedTuple)	Choose first solution from list.
`roundoff`(→ float)	Round a number to specified precision.
`solver_factory`(→ hklpy2.backends.base.SolverBase)	Create a Solver object with geometry and axes.
`solvers`(→ Mapping[str, hklpy2.backends.base.SolverBase])	Dictionary of available Solver classes, mapped by entry point name.
`unique_name`(→ str)	Short, unique name, first 7 (at most) characters of a unique, random uuid.
`validate_and_canonical_unit`(→ str)	Validate that value is a unit convertible to target_units.

Module Contents#

hklpy2.misc.logger[source]#

hklpy2.misc.BlueskyPlanType[source]#: Type of a bluesky plan.

hklpy2.misc.KeyValueMap[source]#: Dictionary for configuration and other.

hklpy2.misc.NUMERIC[source]#: Either integer or real number.

hklpy2.misc.INPUT_VECTOR[source]#: Acceptable forms of vector input for zones, …

hklpy2.misc.AxesArray[source]#: Numpy array of axes values.

hklpy2.misc.AxesDict[source]#: Dictionary of axes names and values.

hklpy2.misc.AxesList[source]#: List of axes values.

hklpy2.misc.AxesTuple[source]#: Tuple of axes values.

hklpy2.misc.AnyAxesType[source]#

Any of these types are used to describe both pseudo and real axes.

description	example	type annotation
dict	{“h”: 0, “k”: 1, “l”: -1}	AxesDict
namedtuple	(h=0.0, k=1.0, l=-1.0)	AxesTuple
numpy array	numpy.array([0, 1, -1])	AxesArray
ordered list	[0, 1, -1]	AxesList
ordered tuple	(0, 1, -1)	AxesTuple

hklpy2.misc.Matrix3x3[source]#

mutable orientation & rotation matrices.

Type:: Python type annotation

hklpy2.misc.NamedFloatDict[source]#

dictionary of named floats.

Type:: Python type annotation

hklpy2.misc.IDENTITY_MATRIX_3X3: Matrix3x3 = [[1, 0, 0], [0, 1, 0], [0, 0, 1]][source]#: Identity matrix, 2-D, 3 rows, 3 columns.

hklpy2.misc.SOLVER_ENTRYPOINT_GROUP: str = 'hklpy2.solver'[source]#: Name by which hklpy2 Solver classes are grouped.

hklpy2.misc.DEFAULT_DIGITS: int = 4[source]#

hklpy2.misc.DEFAULT_START_KEY: str = 'diffractometers'[source]#

hklpy2.misc.INTERNAL_ANGLE_UNITS: str = 'degrees'[source]#

hklpy2.misc.INTERNAL_LENGTH_UNITS: str = 'angstrom'[source]#

hklpy2.misc.INTERNAL_XRAY_ENERGY_UNITS: str = 'keV'[source]#

hklpy2.misc.UREG[source]#

hklpy2.misc.PINT_ERRORS[source]#: Exception from pint that we are trapping here.

hklpy2.misc.DEFAULT_MOTOR_LABELS: Sequence[str] = ['motors'][source]#: Default labels applied to real-axis positioners.

exception hklpy2.misc.Hklpy2Error[source]#

Bases: Exception

Any exception from the hklpy2 package.

exception hklpy2.misc.ConfigurationError[source]#

Bases: Hklpy2Error

Custom exceptions from hklpy2.blocks.configure.

exception hklpy2.misc.ConstraintsError[source]#

Bases: Hklpy2Error

Custom exceptions from hklpy2.blocks.constraints.

exception hklpy2.misc.CoreError[source]#

Bases: Hklpy2Error

Custom exceptions from hklpy2.ops.Core.

exception hklpy2.misc.DiffractometerError[source]#

Bases: Hklpy2Error

Custom exceptions from hklpy2.diffract.DiffractometerBase.

exception hklpy2.misc.LatticeError[source]#

Bases: Hklpy2Error

Custom exceptions from hklpy2.blocks.lattice.

exception hklpy2.misc.NoForwardSolutions[source]#

Bases: Hklpy2Error

A solver did not find any forward() solutions.

exception hklpy2.misc.ReflectionError[source]#

Bases: Hklpy2Error

Custom exceptions from hklpy2.blocks.reflection.

exception hklpy2.misc.SampleError[source]#

Bases: Hklpy2Error

Custom exceptions from hklpy2.blocks.sample.

exception hklpy2.misc.SolverError[source]#

Bases: Hklpy2Error

Custom exceptions from a Solver.

class hklpy2.misc.VirtualPositionerBase(*, physical_name: str = '', **kwargs)[source]#

Bases: ophyd.SoftPositioner

Base class for a diffractometer’s virtual axis.

This base class also serves as an example where the virtual axis is twice the value of the physical axis. It is used as a Component of a ‘DiffractometerBase’ definition. The physical_name is the name of a sibling positioner attribute.

_setup_finished: bool = False[source]#

physical[source]#

_setup_move(position: float, status: Any) → None[source]#: Move requested to position.

forward(physical: float) → float[source]#

Return virtual position from physical position.

Subclass should override.

inverse(virtual: float) → float[source]#

Return physical position from virtual position.

Subclass should override.

_cb_update_position(value: float, **kwargs) → None[source]#: Called when physical position is changed.

_finish_setup() → None[source]#

Complete the axis setup after diffractometer is built.

This method is crucial for ensuring that the positioner is correctly initialized and ready to operate within the system, handling updates and constraints appropriately.

Update our:

Position by subscription to readback changes.
Limits from physical axis.

_recompute_limits() → None[source]#: Compute virtual axis limits from physical axis and refine constraints.

__getattribute__(name: str)[source]#

Run final setup automatically, on conditions.

This is a special method in Python that is called whenever an attribute is accessed on an object. This method is overridden here to add custom behavior when accessing attributes, particularly the ‘position’ attribute.

This implementation ensures that the setup process is completed before accessing the ‘position’ attribute, provided the object and its parent are connected. It adds robustness to the attribute access by handling potential errors gracefully and avoiding infinite recursion.

This virtual positioner must subscribe to position updates of the physical positioner to which it is related. Because that positioner might not be fully initialized and connected during construction of this virtual positioner, a final setup method must be called later. The additional steps in this method ensure that final setup is called under the correct conditions.

class hklpy2.misc.ConfigurationRunWrapper(*devices, knowns=None)[source]#

Write configuration of supported device(s) to a bluesky run.

EXAMPLE:

crw = ConfigurationRunWrapper(sim4c2)
RE.preprocessors.append(crw.wrapper)
RE(bp.rel_scan([noisy], m1, -1.2, 1.2, 11))

Disable the preprocessor:

crw.enable = False  # 'True' to enable

Remove the last preprocessor:

RE.preprocessors.pop()

Add another diffractometer:

crw.devices.append(e4cv)

`device_names`	Return list of configured device names.
`devices`	List of devices to be reported.
`enable`	Is it permitted to write device configuration?
`known_bases`	Known device base classes.
`start_key`	Top-level key in run's metadata dictionary.
`validate`(devices)	Verify all are recognized objects.
`wrapper`(plan)	Bluesky plan wrapper (preprocessor).

devices: Sequence[ophyd.Device] = [][source]#: List of devices to be reported.

known_bases: Sequence[ophyd.Device] = [][source]#

Known device base classes.

Any device (base class) that reports its configuration dictionary in the .read_configuration() method can be added to this tuple.

start_key: str = 'diffractometers'[source]#: Top-level key in run’s metadata dictionary.

property enable: bool[source]#: Is it permitted to write device configuration?

property device_names: list[str][source]#: Return list of configured device names.

validate(devices: Sequence[ophyd.Device]) → None[source]#: Verify all are recognized objects.

wrapper(plan: Iterator)[source]#

Bluesky plan wrapper (preprocessor).

Writes device(s) configuration to start document metadata.

Example:

crw = ConfigurationRunWrapper(e4cv)
RE.preprocessors.append(crw.wrapper)

hklpy2.misc.axes_to_dict(input: AnyAxesType, names: list[str]) → AxesDict[source]#

Convert any acceptable axes input to standard form (dict).

User could provide input in several forms:

dict: {"h": 0, "k": 1, "l": -1}
namedtuple: (h=0.0, k=1.0, l=-1.0)
ordered list: [0, 1, -1] (for h, k, l)
ordered tuple: (0, 1, -1) (for h, k, l)

PARAMETERS:

inputAnyAxesType: Positions, specified as dict, list, or tuple.
names[str]: Expected names of the axes, in order expected by the solver.

hklpy2.misc.check_value_in_list(title, value, examples, blank_ok=False) → None[source]#: Raise ValueError exception if value is not in the list of examples.

hklpy2.misc.compare_float_dicts(a1, a2, tol=0.0001) → bool[source]#: Compare two dictionaries. Values are all floats.

hklpy2.misc.convert_units(value: float, old_units: str, new_units: str) → float[source]#: Convert ‘value’ from old units to new.

hklpy2.misc.define_real_axis(specs: None | str | KeyValueMap, kwargs: KeyValueMap) → tuple[str, Sequence, Mapping][source]#: Return class and kwargs of a real axis from its ‘specs’.

hklpy2.misc.dict_device_factory(data: KeyValueMap, **kwargs: KeyValueMap) → type[source]#: Create a DictionaryDevice() class using the supplied dictionary.

hklpy2.misc.distance_between_pos_tuples(pos1: NamedTuple, pos2: NamedTuple) → float[source]#: Return the RMS distance between ‘pos1’ and ‘pos2’.

hklpy2.misc.dynamic_import(full_path: str) → type[source]#

Import the object given its import path as text.

Motivated by specification of class names for plugins when using apstools.devices.ad_creator().

EXAMPLES:

klass = dynamic_import("ophyd.EpicsMotor")
m1 = klass("gp:m1", name="m1")

creator = dynamic_import("hklpy2.diffract.creator")
fourc = creator(name="fourc")

From the apstools package.

hklpy2.misc.flatten_lists(xs: Sequence[bytes | collections.abc.Iterable | str]) → BlueskyPlanType[source]#

Convert nested lists into single list.

https://stackoverflow.com/questions/2158395

hklpy2.misc.get_solver(solver_name: str) → hklpy2.backends.base.SolverBase[source]#

Load a Solver class from a named entry point.

import hklpy2
SolverClass = hklpy2.get_solver("hkl_soleil")
libhkl_solver = SolverClass()

hklpy2.misc.get_run_orientation(run: Any, name=None, start_key: str = DEFAULT_START_KEY) → KeyValueMap[source]#

Return the orientation information dictionary from a run.

EXAMPLE:

In [3]: get_run_orientation(cat[9752], name="sim4c2")
Out[3]:
{'_header': {'datetime': '2025-02-27 15:54:33.364719',
'hklpy2_version': '0.0.26.dev72+gcf9a65a.d20250227',
'python_class': 'Hklpy2Diffractometer',
'source_type': 'X-ray',
'energy_units': 'keV',
'energy': 12.398419843856837,
'wavelength_units': 'angstrom',
'wavelength': 1.0},
'name': 'sim4c2',
'axes': {'pseudo_axes': ['h', 'k', 'l'],
'real_axes': ['omega', 'chi', 'phi', 'tth'],
'axes_xref': {'h': 'h',
'k': 'k',
'l': 'l',
'omega': 'omega',
'chi': 'chi',
'phi': 'phi',
'tth': 'tth'},
'extra_axes': {}},
'sample_name': 'sample',
'samples': {'sample': {'name': 'sample',
'lattice': {'a': 1,
    'b': 1,
    'c': 1,
    'alpha': 90.0,
    'beta': 90.0,
    'gamma': 90.0},
'reflections': {},
'reflections_order': [],
'U': [[1, 0, 0], [0, 1, 0], [0, 0, 1]],
'UB': [[1, 0, 0], [0, 1, 0], [0, 0, 1]],
'digits': 4}},
'constraints': {'omega': {'label': 'omega',
'low_limit': -180.0,
'high_limit': 180.0,
'class': 'LimitsConstraint'},
'chi': {'label': 'chi',
'low_limit': -180.0,
'high_limit': 180.0,
'class': 'LimitsConstraint'},
'phi': {'label': 'phi',
'low_limit': -180.0,
'high_limit': 180.0,
'class': 'LimitsConstraint'},
'tth': {'label': 'tth',
'low_limit': -180.0,
'high_limit': 180.0,
'class': 'LimitsConstraint'}},
'solver': {'name': 'hkl_soleil',
'description': "HklSolver(name='hkl_soleil', version='5.1.2', geometry='E4CV', engine_name='hkl', mode='bissector')",
'geometry': 'E4CV',
'real_axes': ['omega', 'chi', 'phi', 'tth'],
'version': '5.1.2',
'engine': 'hkl'}}

Parameters:

run (object) – Bluesky run object.
name (str) – (optional) Name of the diffractometer. (default=None, returns all available.)
start_key (str) – Metadata key where the orientation information is stored in the start document. (default=”diffractometers”)

hklpy2.misc.istype(value: Any, annotation: Type) → bool[source]#

Check if ‘value’ matches the type ‘annotation’.

EXAMPLE:

>>> istype({"a":1}, AxesDict)
True

hklpy2.misc.list_orientation_runs(catalog: Any, limit: int = 10, start_key: str = DEFAULT_START_KEY, **kwargs: Mapping) → pandas.DataFrame[source]#

List the runs with orientation information.

EXAMPLE:

In [42]: list_orientation_runs(cat, limit=5, date="_header.datetime")
Out[42]:
    scan_id      uid  sample diffractometer geometry      solver                        date
0      9752  41f71e9  sample         sim4c2     E4CV  hkl_soleil  2025-02-27 15:54:33.364719
1      9751  36e38bc  sample         sim4c2     E4CV  hkl_soleil  2025-02-27 15:54:33.364719
2      9750  62e425d  sample         sim4c2     E4CV  hkl_soleil  2025-02-27 15:54:33.364719
3      9749  18b11f0  sample         sim4c2     E4CV  hkl_soleil  2025-02-27 15:53:55.958929
4      9748  bf9912f  sample         sim4c2     E4CV  hkl_soleil  2025-02-27 15:53:55.958929

Returns:

Table of orientation runs

Return type:

Pandas DataFrame object

Parameters:

catalog (object) – Catalog of bluesky runs.
limit (int) – Limit the list to at most limit runs. (default=10) It could take a long time to search an entire catalog.
start_key (str) – Metadata key where the orientation information is stored in the start document. (default=”diffractometers”)
**kwargs (dict[str:str]) – Keyword parameters describing data column names to be displayed. The value of each column name is the dotted path to the orientation information (in the start document’s metadata).

hklpy2.misc.load_yaml(text: str) → Mapping[source]#: Load YAML from text.

hklpy2.misc.load_yaml_file(file: pathlib.Path | str) → Mapping[source]#: Return contents of a YAML file as a Python object.

hklpy2.misc.make_component(call_name: str, *args: Any, **kwargs: Any) → ophyd.Component[source]#: Create an Component for a custom ophyd Device class.

hklpy2.misc.make_dynamic_instance(call_name: str, *args: Any, **kwargs: Any) → Any[source]#: Return an instance of the Python ‘call_name’.

hklpy2.misc.parse_factory_axes(*, space: str = None, axes: KeyValueMap | None | Sequence[str] = None, order: Sequence[str] = None, canonical: Sequence[str] = None, labels: Sequence[str] = None, **_ignored: Any) → Mapping[str, ophyd.Component | Sequence[str]][source]#

Parse a set of axis specifications, return Device class attributes.

Called from the diffract.diffractometer_class_factory().

hklpy2.misc.pick_closest_solution(position: NamedTuple, solutions: list[NamedTuple]) → NamedTuple[source]#

Find the solution closest to the current real position.

Used by forward() method to pick a solution from a list of possible solutions. Assign to diffractometer’s _forward_solution method.

PARAMETERS

position tuple :: Current position.
solutions list[tuple] :: List of positions.

hklpy2.misc#

Attributes#

Exceptions#

Classes#

Functions#

Module Contents#

This Page