hklpy2.misc#

Miscellaneous Support.

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.

dict_device_factory(data, **kwargs)

Create a DictionaryDevice() class using the supplied dictionary.

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.

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.

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.

ReflectionError

Custom exceptions from hklpy2.blocks.reflection.

SampleError

Custom exceptions from hklpy2.blocks.sample.

SolverError

Custom exceptions from a Solver.

SolverNoForwardSolutions

A solver did not find any 'forward()' solutions.

WavelengthError

Custom exceptions from hklpy2.wavelength_support.

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.

ReflectionError

Custom exceptions from hklpy2.blocks.reflection.

SampleError

Custom exceptions from hklpy2.blocks.sample.

SolverError

Custom exceptions from a Solver.

SolverNoForwardSolutions

A solver did not find any 'forward()' solutions.

WavelengthError

Custom exceptions from hklpy2.wavelength_support.

Classes#

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.

dict_device_factory(data, **kwargs)

Create a DictionaryDevice() class using the supplied dictionary.

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.

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

exception hklpy2.misc.SolverNoForwardSolutions[source]#

Bases: SolverError

A solver did not find any ‘forward()’ solutions.

exception hklpy2.misc.WavelengthError[source]#

Bases: Hklpy2Error

Custom exceptions from hklpy2.wavelength_support.

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.dict_device_factory(data: dict, **kwargs)[source]#

Create a DictionaryDevice() class using the supplied dictionary.

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.roundoff(value, digits=4)[source]#

Round a number to specified precision.

hklpy2.misc.solver_factory(solver_name: str, geometry: str, **kwargs)[source]#

Create a Solver object with geometry and axes.

hklpy2.misc.solvers()[source]#

Dictionary of available Solver classes, mapped by entry point name.

import hklpy2
print(hklpy2.solvers())
hklpy2.misc.unique_name(prefix='', length=7)[source]#

Short, unique name, first 7 (at most) characters of a unique, random uuid.