run_utils#

Import: hklpy2.run_utils

Bluesky run-engine and databroker integration for hklpy2.

These utilities write diffractometer configuration into Bluesky run metadata and retrieve orientation information from previously recorded runs.

`ConfigurationRunWrapper`(*devices[, knowns])	Write configuration of supported device(s) to a bluesky run.
`simulator_from_config`(config)	Create a simulated diffractometer from a saved configuration.
`get_run_orientation`(run[, name, start_key])	Return the orientation information dictionary from a run.
`list_orientation_runs`(catalog[, limit, ...])	List the runs with orientation information.

Module Contents#

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

Import: hklpy2.run_utils.ConfigurationRunWrapper

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

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

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

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

known_bases: Sequence[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.

validate(devices: Sequence[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.run_utils.get_run_orientation(run: Any, name=None, start_key: str = DEFAULT_START_KEY) → KeyValueMap[source]#

Import: hklpy2.run_utils.get_run_orientation

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.run_utils.list_orientation_runs(catalog: Any, limit: int = 10, start_key: str = DEFAULT_START_KEY, **kwargs: Mapping) → DataFrame[source]#

Import: hklpy2.run_utils.list_orientation_runs

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.run_utils.register_aux_reconstructor(category: str, builder: Callable[[Mapping[str, Any]], Any]) → None[source]#

Import: hklpy2.run_utils.register_aux_reconstructor

Register a builder for a given aux-record category.

The builder receives a normalised record (dict with at least name and category) and returns whatever creator() accepts as a reals= value:

None for a scalar SoftPositioner (the historic default);
a dict spec of the form {"class": <callable or import path>, ...kwargs} for any nested device.

Built-in categories — "scalar" and "pseudo_positioner" — may be overridden by a later registration.

PARAMETERS

categorystr: The category value the builder handles (e.g. a custom "device_group").
buildercallable: builder(record) -> creator-reals-spec.

hklpy2.run_utils.simulator_from_config(config)[source]#

Import: hklpy2.run_utils.simulator_from_config

Create a simulated diffractometer from a saved configuration.

All axes are soft positioners — no hardware connections are made. Auxiliary axes and solver mode saved by export() are restored automatically.

If the diffractometer requires auxiliary axes that are not in the configuration file, use creator() with restore() instead:

sim = hklpy2.creator(name="e4cv", reals=dict(..., extra_axis=None))
sim.restore("e4cv-config.yml")

PARAMETERS

configdict, str, pathlib.Path, or DiffractometerBase

One of:

a configuration dictionary,
a path to a YAML configuration file previously saved with diffractometer.export(), or
a DiffractometerBase instance (its current configuration snapshot will be used).

RETURNS

DiffractometerBase: A fully configured simulated diffractometer instance.

EXAMPLE:

>>> import hklpy2
>>> sim = hklpy2.simulator_from_config("e4cv-config.yml")
>>> sim.wh()

Or directly from an existing diffractometer::

>>> sim = hklpy2.simulator_from_config(diffractometer)

Solver construction kwargs

Every key in the persisted solver: block except the reserved set {"name", "description", "geometry", "real_axes", "version", "mode"} is forwarded to the solver’s constructor as a solver_kwargs entry. This lets a solver persist arbitrary construction state by overriding its _metadata property and accepting the matching keyword in its __init__. See issue #405. Solver authors are responsible for choosing _metadata key names that do not collide with the reserved set.