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.
`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.
`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.

`IDENTITY_MATRIX_3X3`	Identity matrix, 2-D, 3 rows, 3 columns.
`SOLVER_ENTRYPOINT_GROUP`	Name by which hklpy2 backend 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.

ConfigurationRunWrapper(*devices[, knowns])

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

`ConfigurationError`	Custom exceptions from `hklpy2.blocks.configure`.
`ConstraintsError`	Custom exceptions from `hklpy2.blocks.constraints`.
`CoreError`	Custom exceptions from `Core`.
`DiffractometerError`	Custom exceptions from `DiffractometerBase`.
`Hklpy2Error`	Any exception from the hklpy2 package.
`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`
`IDENTITY_MATRIX_3X3`	Identity matrix, 2-D, 3 rows, 3 columns.
`SOLVER_ENTRYPOINT_GROUP`	Name by which hklpy2 backend Solver classes are grouped.
`DEFAULT_START_KEY`
`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.

Exceptions#

`Hklpy2Error`	Any exception from the hklpy2 package.
`ConfigurationError`	Custom exceptions from `hklpy2.blocks.configure`.
`ConstraintsError`	Custom exceptions from `hklpy2.blocks.constraints`.
`DiffractometerError`	Custom exceptions from `DiffractometerBase`.
`LatticeError`	Custom exceptions from `hklpy2.blocks.lattice`.
`CoreError`	Custom exceptions from `Core`.
`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`(title, value, examples[, blank_ok])	Raise ValueError exception if value is not in the list of examples.
`compare_float_dicts`(a1, a2[, tol])	Compare two dictionaries. Values are all floats.
`convert_units`(→ float)	Convert 'value' from old units to new.
`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`(→ type)	Import the object given its import path as text.
`flatten_lists`(xs)	Convert nested lists into single list.
`get_solver`(solver_name)	Load a Solver class from a named entry point.
`get_run_orientation`(run[, name, start_key])	Return the orientation information dictionary from a run.
`istype`(→ bool)	Check if 'value' matches the type 'annotation'.
`list_orientation_runs`(catalog[, limit, start_key])	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.
`pick_closest_solution`(→ NamedTuple)	Find the solution closest to the current real position.
`pick_first_solution`(→ NamedTuple)	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.

Module Contents#

hklpy2.misc.logger[source]#

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

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

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

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

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.DiffractometerError[source]#

Bases: Hklpy2Error

Custom exceptions from DiffractometerBase.

exception hklpy2.misc.LatticeError[source]#

Bases: Hklpy2Error

Custom exceptions from hklpy2.blocks.lattice.

exception hklpy2.misc.CoreError[source]#

Bases: Hklpy2Error

Custom exceptions from Core.

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, status)[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, **kwargs)[source]#: Called when physical position is changed.

_finish_setup()[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)[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 = [][source]#: List of devices to be reported.

known_bases = [][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 = 'diffractometers'[source]#: Top-level key in run’s metadata dictionary.

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

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

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

wrapper(plan)[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)[source]#: Raise ValueError exception if value is not in the list of examples.

hklpy2.misc.compare_float_dicts(a1, a2, tol=0.0001)[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.dict_device_factory(data: dict, **kwargs)[source]#: Create a DictionaryDevice() class using the supplied dictionary.

hklpy2.misc.distance_between_pos_tuples(pos1: NamedTuple, pos2: NamedTuple)[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)[source]#

Convert nested lists into single list.

https://stackoverflow.com/questions/2158395

hklpy2.misc.get_solver(solver_name)[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, name=None, start_key=DEFAULT_START_KEY)[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, limit=10, start_key=DEFAULT_START_KEY, **kwargs)[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) – Instance of a databroker catalog.
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)[source]#: Load YAML from text.

hklpy2.misc.load_yaml_file(file)[source]#: Return contents of a YAML file as a Python object.

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