diffcalc.ub.calc

Routines for UB matrix calculation.

This module provides a number of objects and functions for setting UB matrix and reference/surface normal vectors based on reflections and/or orientations and crystal miscut information.

Classes

ReferenceVector(n_ref, rlv)

Class representing reference vector information.

UBCalculation([name])

Class containing information required for for UB matrix calculation.
class diffcalc.ub.calc.ReferenceVector(n_ref: Tuple[float, float, float], rlv: bool)[source]

Class representing reference vector information.

Reference vector object is used to define orientations in reciprocal and laboratory coordinate systems e.g. to represent an azimuthat direction or a surface normal.

n_ref

Tuple with vector coordinates.

Type

Tuple[float, float, float]

rlv

Flag indicating if coordinates are in reciprocal or laboratory coordinate system. True: for reciprocal space vector. False: for real space vector.

Type

bool

get_array(UB: Optional[np.ndarray] = None) → np.ndarray[source]

Return reference vector as 3x1 NumPy array.

set_array(n_ref: np.ndarray) → Tuple[float, float, float][source]

Set reference vector coordinates from 3x1 NumPy array.

Attributes
asdict

Serialise the object into a JSON compatible dictionary.

Methods

get_array([UB])

Return reference vector coordinates from (3, 1) NumPy array.

set_array(n_ref)

Set reference vector coordinates from NumPy array.
n_ref: Tuple[float, float, float]
rlv: bool
get_array(UB: Optional[ndarray] = None) → ndarray[source]

Return reference vector coordinates from (3, 1) NumPy array.

Return reference vector coordinates in reciprocal of laboratory coordinate system. UB matrix is required when converting between alternative coordinate systems.

Parameters

UB (np.ndarray, optional) – UB matrix as (3, 3) NumPy array object. Use UB matrix to convert coordinates between reciprocal and laboratory coordinate systems. (default: None, do not convert coordinates into the alternative system).

Returns

Returns reference vector coordinates as (3, 1) NumPy array.

Return type

np.ndarray

Raises

DiffcalcException – If UB matrix is not a (3, 3) NumPy array.

set_array(n_ref: ndarray) → None[source]

Set reference vector coordinates from NumPy array.

Parameters

n_ref (np.ndarray) – NumPy (3, 1) array with reference vector coordinates.

Return type

None

Raises

DiffcalcException – If input parameter is not (3, 1) NumPy array.

property asdict: Dict[str, Any]

Serialise the object into a JSON compatible dictionary.

Returns

Dictionary containing properties of this class. Can be unpacked directly by calling ReferenceVector(**resulting_dict).

Return type

Dict[str, Any]

class diffcalc.ub.calc.UBCalculation(name: Optional[str] = None)[source]

Class containing information required for for UB matrix calculation.

name

Name for UB calculation. Default is to generate UUID value.

Type

str, defalut = UUID

crystal

Object containing crystal lattice parameters.

Type

Crystal

reflist

List of reference reflections for UB matrix calculation.

Type

ReflectionList

orientlist

List of crystal orientations for UB matrix calculation.

Type

OrientationList

reference

Object representing azimuthal reference vector.

Type

ReferenceVector

surface

Object representing surface normal vector.

Type

ReferenceVector

U

U matrix as a NumPy array.

Type

np.ndarray

UB

UB matrix as a NumPy array.

Type

np.ndarray

Attributes
asdict

Serialise the object into a JSON compatible dictionary.

n_hkl

Return reference vector property represented using miller indices.

n_phi

Return reference vector property represented laboratory space coordinates.

surf_nhkl

Return surface normal vector property represented using miller indices.

surf_nphi

Return surface normal vector represented using laboratory space coordinates.

Methods

add_orientation(hkl, xyz[, position, tag])

Add a reference orientation.

add_reflection(hkl, position, energy[, tag])

Add a reference reflection.

calc_ub([idx1, idx2])

Calculate UB matrix.

del_orientation(idx)

Delete a reference orientation.

del_reflection(idx)

Delete a reference reflection.

edit_orientation(idx, hkl, xyz[, position, tag])

Change a reference orientation.

edit_reflection(idx, hkl, position, energy)

Change a reference reflection.

fit_ub(indices[, refine_lattice, refine_umatrix])

Refine UB matrix using reference reflections.

fromdict(data)

Construct UBCalculation instance from a JSON compatible dictionary.

get_miscut()

Calculate miscut angle and axis from U matrix.

get_miscut_from_hkl(hkl, pos)

Calculate miscut angle and axis from a single reflection.

get_number_orientations()

Get a number of stored reference orientations.

get_number_reflections()

Get a number of stored reference reflections.

get_orientation(idx)

Get a reference orientation.

get_reflection(idx)

Get a reference reflection.

get_tag_orient_num(tag)

Get a reference orientation index.

get_tag_refl_num(tag)

Get a reference reflection index.

get_ttheta_from_hkl(hkl, en)

Calculate two-theta scattering angle for a reflection.

load(filename)

Load current UB matrix calculation from a pickle file.

pickle(filename)

Save current UB matrix calculation as a pickle file.

refine_ub(hkl, position, wavelength[, ...])

Refine UB matrix to using single reflection.

set_lattice(name[, system, a, b, c, alpha, ...])

Set crystal lattice parameters using shortform notation.

set_miscut(xyz, angle[, add_miscut])

Calculate U matrix using a miscut axis and an angle.

set_u(matrix)

Manually sets U matrix.

set_ub(matrix)

Manually sets UB matrix.

swap_orientations(idx1, idx2)

Swap indices of two reference orientations.

swap_reflections(idx1, idx2)

Swap indices of two reference reflections.
static load(filename: str) → UBCalculation[source]

Load current UB matrix calculation from a pickle file.

Parameters

filename (str) – Pickle file name.

Returns

UB calculation object.

Return type

UBCalculation

Raises

DiffcalcException – If object in pickle file isn’t UBcalculation class instance.

pickle(filename: str) → None[source]

Save current UB matrix calculation as a pickle file.

Parameters

filename (str) – Pickle file name.

set_lattice(name: str, system: Optional[Union[str, float]] = None, a: Optional[float] = None, b: Optional[float] = None, c: Optional[float] = None, alpha: Optional[float] = None, beta: Optional[float] = None, gamma: Optional[float] = None) → None[source]

Set crystal lattice parameters using shortform notation.

Following combinations of system and lattice parameters are supported:

(‘Cubic’, a) – sets Cubic system (‘Tetragonal’, a, c) – sets Tetragonal system (‘Hexagonal’, a, c) – sets Hexagonal system (‘Orthorhombic’, a, b, c) – sets Orthorombic system (‘Rhombohedral’, a, alpha) – sets Rhombohedral system (‘Monoclinic’, a, b, c, beta) – sets Monoclinic system (‘Triclinic’, a, b, c, alpha, beta, gamma) – sets Triclinic system

Crystal system can be inferred from the lattice parameters for the following cases:

(a,) – assumes Cubic system (a, c) – assumes Tetragonal system (a, b, c) – assumes Orthorombic system (a, b, c, angle) – assumes Monoclinic system with beta not equal to 90 or

Hexagonal system if a = b and gamma = 120

(a, b, c, alpha, beta, gamma) – sets Triclinic system

Parameters

  • name (str) – Crystal name.

  • system (Optional[float], default = None) – Crystal lattice type.

  • a (Optional[float], default = None) – Crystal lattice parameter.

  • b (Optional[float], default = None) – Crystal lattice parameter.

  • c (Optional[float], default = None) – Crystal lattice parameter.

  • alpha (Optional[float], default = None) – Crystal lattice angle.

  • beta (Optional[float], default = None) – Crystal lattice angle.

  • gamma (Optional[float], default = None) – Crystal lattice angle.

property n_hkl: ndarray

Return reference vector property represented using miller indices.

Returns

Reference vector represented as (3,1) NumPy array.

Return type

np.ndarray

property n_phi: ndarray

Return reference vector property represented laboratory space coordinates.

Returns

Reference vector represented as (3,1) NumPy array.

Return type

np.ndarray

property surf_nhkl: ndarray

Return surface normal vector property represented using miller indices.

Returns

Surface normal vector represented as (3,1) NumPy array.

Return type

np.ndarray

property surf_nphi: ndarray

Return surface normal vector represented using laboratory space coordinates.

Returns

Reference vector represented as (3,1) NumPy array.

Return type

np.ndarray

add_reflection(hkl: Tuple[float, float, float], position: Position, energy: float, tag: Optional[str] = None)[source]

Add a reference reflection.

Adds a reflection position in degrees and in the systems internal representation.

Parameters

  • hkl (Tuple[float, float, float]) – hkl index of the reflection.

  • position (Position) – List of diffractometer angles in internal representation in degrees.

  • energy (float) – Energy of the x-ray beam.

  • tag (Optional[str], default = None) – Identifying tag for the reflection.

edit_reflection(idx: Union[str, int], hkl: Tuple[float, float, float], position: Position, energy: float, tag: Optional[str] = None)[source]

Change a reference reflection.

Changes a reflection position in degrees and in the systems internal representation.

Parameters

  • idx (Union[str, int]) – Index or tag of the reflection to be changed.

  • hkl (Tuple[float, float, float]) – hkl index of the reflection.

  • position (Position) – List of diffractometer angles in internal representation in degrees.

  • energy (float) – Energy of the x-ray beam.

  • tag (Optional[str], default = None) – Identifying tag for the reflection.

get_reflection(idx: Union[str, int]) → Reflection[source]

Get a reference reflection.

Get a reflection position in degrees and in the systems internal representation.

Parameters

idx (Union[str, int]) – Index or tag of the reflection.

get_number_reflections() → int[source]

Get a number of stored reference reflections.

Returns

Number of reference reflections.

Return type

int

get_tag_refl_num(tag: str) → int[source]

Get a reference reflection index.

Get a reference reflection index for the provided reflection tag.

Parameters

tag (str) – Identifying tag for the reflection.

Returns

Reference reflection index

Return type

int

del_reflection(idx: Union[str, int]) → None[source]

Delete a reference reflection.

Parameters

idx (str or int) – Index or tag of the deleted reflection.

swap_reflections(idx1: Union[str, int], idx2: Union[str, int]) → None[source]

Swap indices of two reference reflections.

Parameters

  • idx1 (str or int) – Index or tag of the first reflection to be swapped.

  • idx2 (str or int) – Index or tag of the second reflection to be swapped.

add_orientation(hkl, xyz, position=None, tag=None)[source]

Add a reference orientation.

Adds a reference orientation in the diffractometer coordinate system.

Parameters

  • hkl (tuple of numbers) – hkl index of the reference orientation.

  • xyz (tuple of numbers) – xyz coordinate of the reference orientation.

  • position (list or tuple of numbers) – List of diffractometer angles in internal representation in degrees.

  • tag (str) – Identifying tag for the reflection.

edit_orientation(idx, hkl, xyz, position=None, tag=None)[source]

Change a reference orientation.

Changes a reference orientation in the diffractometer coordinate system.

Parameters

  • idx (str or int) – Index or tag of the orientation to be changed.

  • hkl (tuple of numbers) – h index of the reference orientation.

  • xyz (tuple of numbers) – x coordinate of the reference orientation.

  • position (list or tuple of numbers) – List of diffractometer angles in internal representation in degrees.

  • tag (str) – Identifying tag for the reflection.

get_orientation(idx)[source]

Get a reference orientation.

Get a reference orientation in the diffractometer coordinate system.

Parameters

idx (str or int) – Index or tag of the reference orientation.

get_number_orientations()[source]

Get a number of stored reference orientations.

Returns

Number of reference orientations.

Return type

int

get_tag_orient_num(tag)[source]

Get a reference orientation index.

Get a reference orientation index for the provided orientation tag.

Parameters

tag (str) – Identifying tag for the orientation.

Returns

Reference orientation index.

Return type

int

del_orientation(idx)[source]

Delete a reference orientation.

Parameters

idx (str or int) – Index or tag of the deleted orientation.

swap_orientations(idx1, idx2)[source]

Swap indices of two reference orientations.

Parameters

  • idx1 (str or int) – Index or tag of the first orientation to be swapped.

  • idx2 (str or int) – Index or tag of the second orientation to be swapped.

set_u(matrix: Union[ndarray, List[List[float]], Tuple[Tuple[float, float, float], Tuple[float, float, float], Tuple[float, float, float]]]) → None[source]

Manually sets U matrix.

Set U matrix from input values. Update UB matrix if crystal lattice information is set.

Parameters

matrix (Union(np.ndarray,) –

List[List[float]],
Tuple[Tuple[float, float, float],

Tuple[float, float, float], Tuple[float, float, float]]

Collection containing U matrix coordinates.

Raises

ValueError – If collection isn’t (3, 3) shape.

set_ub(matrix: Union[ndarray, List[List[float]], Tuple[Tuple[float, float, float], Tuple[float, float, float], Tuple[float, float, float]]]) → None[source]

Manually sets UB matrix.

Parameters

matrix (Union(np.ndarray,) –

List[List[float]],
Tuple[Tuple[float, float, float],

Tuple[float, float, float], Tuple[float, float, float]]

Collection containing UB matrix coordinates.

Raises

ValueError – If collection isn’t (3, 3) shape.

calc_ub(idx1=None, idx2=None)[source]

Calculate UB matrix.

Calculate UB matrix using two reference reflections and/or reference orientations.

By default use the first two reference reflections when provided. If one or both reflections are not available use one or two reference orientations to complement mission reflection data.

Parameters

  • idx1 (int or str, optional) – The index or the tag of the first reflection or orientation.

  • idx2 (int or str, optional) – The index or the tag of the second reflection or orientation.

refine_ub(hkl: Tuple[float, float, float], position: Position, wavelength: float, refine_lattice=False, refine_umatrix=False)[source]

Refine UB matrix to using single reflection.

Refine UB matrix to match diffractometer position for the specified reflection. Refined U matrix will be accurate up to an azimuthal rotation around the specified scattering vector.

Parameters

  • hkl (Tuple[float, float, float]) – Miller indices of the reflection.

  • pos (Position) – Diffractometer position object.

  • wavelength (float) – Radiation wavelength.

  • refine_lattice (Optional[bool], default = False) – Apply refined lattice parameters to the current UB calculation object.

  • refine_umatrix (Optional[bool], default = False) – Apply refined U matrix to the current UB calculation object.

Returns

Refined U matrix as NumPy array and refined crystal lattice parameters.

Return type

Tuple[np.ndarray, Tuple[str, float, float, float, float, float, float]]

fit_ub(indices: Sequence[Union[str, int]], refine_lattice: Optional[bool] = False, refine_umatrix: Optional[bool] = False) → Tuple[ndarray, Tuple[str, float, float, float, float, float, float]][source]

Refine UB matrix using reference reflections.

Parameters

  • indices (Sequence[Union[str, int]]) – List of reference reflection indices or tags.

  • refine_lattice (Optional[bool], default = False) – Apply refined lattice parameters to the current UB calculation object.

  • refine_umatrix (Optional[bool], default = False) – Apply refined U matrix to the current UB calculation object.

Returns

Refined U matrix as NumPy array and refined crystal lattice parameters.

Return type

Tuple[np.ndarray, Tuple[str, float, float, float, float, float, float]]

get_miscut() → Tuple[float, ndarray][source]

Calculate miscut angle and axis from U matrix.

Returns

Miscut angle and miscut axis as (3,1) NumPy array.

Return type

Tuple[float, np.ndarray]

get_miscut_from_hkl(hkl: Tuple[float, float, float], pos: Position) → Tuple[float, Tuple[float, float, float]][source]

Calculate miscut angle and axis from a single reflection.

Using single reflection U matrix can be accurate up to an azimuthal rotation around the specified scattering vector.

Parameters

  • hkl (Tuple[float, float, float]) – Miller indices of the reflection.

  • pos (Position) – Diffractometer position object.

Returns

The miscut angle and the corresponding miscut rotation axis.

Return type

Tuple[float, Tuple[float, float, float]]

set_miscut(xyz: Tuple[float, float, float], angle: float, add_miscut: Optional[bool] = False) → None[source]

Calculate U matrix using a miscut axis and an angle.

Parameters

  • xyz (Tuple[float, float, float]) – Rotation axis corresponding to the crystal miscut.

  • angle (float) – The miscut angle.

  • add_miscut (Optional[bool], default = False) – If False, set crystal miscut to the provided parameters. If True, apply provided miscut parameters to the existing settings.

get_ttheta_from_hkl(hkl: Tuple[float, float, float], en: float) → float[source]

Calculate two-theta scattering angle for a reflection.

Parameters

  • hkl (Tuple[float, float, float]) – Miller indices of the reflection.

  • en (float) – Beam energy.

Returns

Two-theta angle for the reflection.

Return type

float

Raises

ValueError – If reflection is unreachable at the provided energy.

property asdict: Dict[str, Any]

Serialise the object into a JSON compatible dictionary.

Returns

Dictionary containing properties of this class. Can be unpacked to recreate this object using fromdict class method below.

Return type

Dict[str, Any]

classmethod fromdict(data: Dict[str, Any]) → UBCalculation[source]

Construct UBCalculation instance from a JSON compatible dictionary.

Parameters

data (Dict[str, Any]) – Dictionary containing properties of this class, must have the equivalent structure to the asdict property.

Returns

Instance of this class created from the dictionary.

Return type

UBCalculation