Operations#

A diffractometer’s .operator provides most of its functionality. The operator conducts transactions with the Solver on behalf of the diffractometer. These transactions include the forward() and inverse() coordinate transformations, at the core of scientific measurements using a diffractometer.

Python class	Purpose
`DiffractometerBase`	ophyd PseudoPositioner
`Operations`	The class for a diffractometer’s `.operator`.
`SolverBase`	Code for diffractometer geometries and capabilities.

In addition to Solver transactions, the .operator manages all details involving the set of samples and their lattices & reflections.

EXAMPLE:

>>> from hklpy2 import SimulatedE4CV
>>> e4cv = SimulatedE4CV(name="e4cv")
>>> e4cv.operator.sample
Sample(name='cubic', lattice=Lattice(a=1, b=1, c=1, alpha=90.0, beta=90.0, gamma=90.0))
>>> e4cv.operator.solver
HklSolver(name='hkl_soleil', version='v5.0.0.3434', geometry='E4CV', engine='hkl', mode='bissector')
>>> e4cv.operator.sample.reflections
{}
>>> e4cv.add_reflection((1, 0, 0), (10, 0, 0, 20), name="r1")
Reflection(name='r1', geometry='E4CV', pseudos={'h': 1, 'k': 0, 'l': 0}, reals={'omega': 10, 'chi': 0, 'phi': 0, 'tth': 20}, wavelength=1.0)
>>> e4cv.add_reflection((0, 1, 0), (10, -90, 0, 20), name="r2")
Reflection(name='r2', geometry='E4CV', pseudos={'h': 0, 'k': 1, 'l': 0}, reals={'omega': 10, 'chi': -90, 'phi': 0, 'tth': 20}, wavelength=1.0)
>>> e4cv.operator.sample.reflections
{'r1': {'name': 'r1', 'geometry': 'E4CV', 'pseudos': {'h': 1, 'k': 0, 'l': 0}, 'reals': {'omega': 10, 'chi': 0, 'phi': 0, 'tth': 20}, 'wavelength': 1.0, 'order': 0}, 'r2': {'name': 'r2', 'geometry': 'E4CV', 'pseudos': {'h': 0, 'k': 1, 'l': 0}, 'reals': {'omega': 10, 'chi': -90, 'phi': 0, 'tth': 20}, 'wavelength': 1.0, 'order': 1}}

Note

The Operations class provides key diffractometer features as Python properties. This enables their inclusion in the DiffractometerBase class using ophyd AttributeSignal. One such example is the Solver geometry name:

geometry = Cpt(
    AttributeSignal,
    attr="operator.geometry",
    doc="Name of backend |solver| geometry.",
    write_access=False,
    kind="config",
)
"""Name of backend |solver| geometry."""

Using the e4cv simulator, the property is:

>>> e4cv.operator.geometry
'E4CV'

From the ophyd diffractometer object reports this:

>>> e4cv.geometry.get()
'E4CV'

Source Code Documentation#

Operate the diffractometer using a Solver library and geometry.

Intermediate layer between DiffractometerBase Device and backend Solver library.

Operations(diffractometer[, default_sample])

Operate the diffractometer using a Solver.

class hklpy2.ops.Operations(diffractometer, default_sample: bool = True)[source]#

Bases: object

Operate the diffractometer using a Solver.

Parameters

solver (str): Name of the backend Solver library.
geometry (str): Name of the backend Solver geometry.

Python Methods

`_asdict`()	Describe the diffractometer as a dictionary.
`_fromdict`(config)	Redefine diffractometer from a (configuration) dictionary.
`add_reflection`(pseudos[, reals, wavelength, ...])	Add a new reflection.
`add_sample`(name, a[, b, c, alpha, beta, ...])	Add a new sample.
`assign_axes`(pseudos, reals)	Designate attributes for use by the PseudoPositioner class.
`auto_assign_axes`()	Automatically assign diffractometer axes to this solver.
`calcUB`(r1, r2)	Calculate the UB (orientation) matrix with two reflections.
`export`(file[, comment])	Export the diffractometer configuration to a YAML file.
`forward`(pseudos[, wavelength])	Compute [{names:reals}] from {names: pseudos} (hkl -> angles).
`inverse`(reals[, wavelength])	Compute (pseudos) from {names: reals} (angles -> hkl).
`refine_lattice`([reflections])	Return the sample lattice computed from 3 or more reflections.
`remove_sample`(name)	Remove the named sample.
`reset_constraints`()	Restore diffractometer constraints to default settings.
`reset_samples`()	Restore diffractometer samples to default settings.
`restore`(file[, clear, restore_constraints])	Restore the diffractometer configuration to a YAML file.
`set_solver`(name, geometry, **kwargs)	Create an instance of the backend Solver library and geometry.
`standardize_pseudos`(pseudos[, expected])	Convert user-supplied pseudos into dictionary.
`standardize_reals`(reals[, expected])	Convert user-supplied reals into dictionary.

Python Properties

`geometry`	Backend Solver geometry name.
`sample`	Current Sample (Python object).
`solver`	Backend Solver object.

class Sample(operator, name: str, lattice: Lattice)#

Bases: object

A crystalline sample mounted on a diffractometer.

Note

Internal use only.

Python Methods

refine_lattice()

Refine the lattice parameters from 3 or more reflections.

Python Properties

`_asdict`()	Describe the sample as a dictionary.
`lattice`	Sample crystal lattice.
`name`	Sample name.
`reflections`	Ordered dictionary of orientation reflections.
`U`	Return the matrix, U, crystal orientation on the diffractometer.
`UB`	Return the crystal orientation matrix, UB.

property U: list[list[float]]#: Return the matrix, U, crystal orientation on the diffractometer.

property UB: list[list[float]]#

Return the crystal orientation matrix, UB.

\(UB\) - orientation matrix
\(B\) - crystal lattice on the diffractometer
\(U\) - rotation matrix, relative orientation of crystal on diffractometer

_asdict()#: Describe the sample as a dictionary.

_fromdict(config)#: Redefine sample from a (configuration) dictionary.

property digits#: Sample crystal lattice.

property lattice#: Sample crystal lattice.

property name#: Sample name.

refine_lattice()#: Refine the lattice parameters from 3 or more reflections.

property reflections#: Ordered dictionary of orientation reflections.

_asdict()[source]#: Describe the diffractometer as a dictionary.

_axes_names_d2s(axis_dict: dict[str, float]) → dict[str, float][source]#: Convert keys of axis dictionary from diffractometer to solver.

_axes_names_s2d(axis_dict: dict[str, float]) → dict[str, float][source]#: Convert keys of axis dictionary from solver to diffractometer.

_fromdict(config)[source]#: Redefine diffractometer from a (configuration) dictionary.

_solver_setup()[source]#: Setup the backend Solver for a transaction.

add_reflection(pseudos, reals=None, wavelength=None, name=None, replace: bool = False) → Reflection[source]#

Add a new reflection.

Parameters

pseudos (various): pseudo-space axes and values.
reals (various): dictionary of real-space axes and values.
wavelength (float): Wavelength of incident radiation.
name (str): Reference name for this reflection. If None, a random name will be assigned.
replace (bool): If True, replace existing reflection of this name. (default: False)

add_sample(name: str, a: float, b: float = None, c: float = None, alpha: float = 90.0, beta: float = None, gamma: float = None, digits: int = 4, replace: bool = False) → Sample[source]#: Add a new sample.

assign_axes(pseudos: list[str], reals: list[str]) → None[source]#

Designate attributes for use by the PseudoPositioner class.

Result is re-definition of ‘self.axes_xref’.

auto_assign_axes()[source]#

Automatically assign diffractometer axes to this solver.

Note

The ordered lists of axes names could change when the Solver, or any of its settings, such as mode, are changed. The lists are defined by the Solver library.

See also

Each Solver provides ordered lists of the names it expects:

property axes_xref_reversed#: Map axis names from solver to diffractometer.

calcUB(r1: [<class 'hklpy2.operations.reflection.Reflection'>, <class 'str'>], r2: [<class 'hklpy2.operations.reflection.Reflection'>, <class 'str'>]) → None[source]#

Calculate the UB (orientation) matrix with two reflections.

The method of Busing & Levy, Acta Cryst 22 (1967) 457.

export(file, comment='')[source]#

Export the diffractometer configuration to a YAML file.

Example:

import hklpy2

e4cv = hklpy2.SimulatedE4CV(name="e4cv")
e4cv.operator.export("e4cv-config.yml", comment="example")

forward(pseudos: tuple, wavelength: float = None) → list[source]#: Compute [{names:reals}] from {names: pseudos} (hkl -> angles).

property geometry: str#: Backend Solver geometry name.

inverse(reals, wavelength: float = None) → dict[source]#: Compute (pseudos) from {names: reals} (angles -> hkl).

refine_lattice(reflections: list = None) → Lattice[source]#

Return the sample lattice computed from 3 or more reflections.

Do not change the sample lattice. Let the user decide that.

remove_sample(name)[source]#: Remove the named sample. No error if name is not known.

reset_constraints()[source]#: Restore diffractometer constraints to default settings.

reset_samples()[source]#: Restore diffractometer samples to default settings.

restore(file, clear=True, restore_constraints=True)[source]#

Restore the diffractometer configuration to a YAML file.

Example:

import hklpy2

e4cv = hklpy2.SimulatedE4CV(name="e4cv")
e4cv.operator.restore("e4cv-config.yml")

PARAMETERS

file str or pathlib.Path object:

Name (or pathlib object) of diffractometer configuration YAML file.

clear bool:

If True (default), remove any previous configuration of the diffractometer and reset it to default values before restoring the configuration.

If False, sample reflections will be append with all reflections included in the configuration data for that sample. Existing reflections will not be changed. The user may need to edit the list of reflections after restore(clear=False).

restore_constraints bool:

If True (default), restore any constraints provided.

Note: Can’t name this method “import”, it’s a reserved Python word.

property sample: Sample#: Current Sample (Python object).

property samples: dict#: Sample dictionary.

set_solver(name: str, geometry: str, **kwargs: dict) → SolverBase[source]#

Create an instance of the backend Solver library and geometry.

Parameters

solver (str): Name of the Solver library.
geometry (str): Name of the Solver geometry.
kwargs (dict): Any keyword arguments needed by the Solver.

property solver: SolverBase#: Backend Solver object.

standardize_pseudos(pseudos: list[str], expected: list[str] = None) → dict[str, str][source]#

Convert user-supplied pseudos into dictionary.

User could provide pseudos 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)

standardize_reals(reals: list[str], expected: list[str] = None) → dict[source]#

Convert user-supplied reals into dictionary.

User could provide reals in several forms:

dict: {“omega”: 120, “chi”: 35.3, “phi”: 45, “tth”: -120}
namedtuple: (omega=120, chi=35.3, phi=45, tth=-120)
None: current positions
ordered list: [120, 35.3, 45, -120] (for omega, chi, phi, tth)
ordered tuple: (120, 35.3, 45, -120) (for omega, chi, phi, tth)