xrheed.kinematics

Submodule kinematics provides tools for constructing 2D lattices and performing Ewald constructions. These tools can be used to calculate and visualize diffraction spot positions based on kinematic theory.

class Ewald(lattice, image=None, stack_index=0)[source]

Bases: object

Class for calculating and analyzing the Ewald sphere construction in RHEED.

This class combines experimental RHEED image metadata with a reciprocal lattice model to predict diffraction spot positions on the screen.

Azimuthal angle convention

Three azimuthal angles are distinguished:

  • image_azimuthal_angle

    Experimental azimuth of the RHEED image, read from image metadata. This value defines the reference frame and is treated as immutable.

  • ewald_azimuthal_rotation

    User-defined relative rotation of the Ewald construction with respect to the image azimuth. This does not modify the image metadata.

  • Ewald azimuthal angles (effective)

    The azimuthal angles actually used in the Ewald construction, derived as

    image_azimuthal_angle ± ewald_azimuthal_rotation

    When mirror symmetry is enabled, both ± rotations are used.

This separation preserves the experimental reference frame while allowing controlled relative rotation of the theoretical Ewald construction.

SPOT_HEIGHT_MM = 5.0
SPOT_WIDTH_MM = 1.5
__init__(lattice, image=None, stack_index=0)[source]

Initialize an Ewald object for RHEED spot calculations.

Parameters:

  • lattice (Lattice) – Lattice object representing the crystal structure.

  • image (Optional[xr.DataArray], optional) – RHEED image data. Can be a single image or a stack of images. If None, default values are used.

  • stack_index (int, optional) – Index of the image to use from a stack (default is 0).

calculate_ewald(**kwargs)[source]

Calculate the Ewald construction and update spot positions.

Updates

self.ew_sxNDArray

Spot x-coordinates (mm).

self.ew_syNDArray

Spot y-coordinates (mm).

calculate_match(normalize=True)[source]

Calculate the match coefficient between predicted and observed spots.

Parameters:

normalize (bool) – If True, normalize the coefficient by the number of spots.

Returns:

Match coefficient.

Return type:

np.uint32

property ewald_azimuthal_angle
property ewald_azimuthal_rotation
property ewald_roi
property image_azimuthal_angle
property incident_angle
property lattice_scale
match_alpha(alpha_vector, normalize=True, tqdm_disable=True)[source]

Calculate match coefficients over a range of azimuthal angles.

Parameters:

  • alpha_vector (NDArray[np.float64]) – Array of alpha (azimuthal) angles in degrees.

  • normalize (bool, optional) – If True, normalize the coefficients (default: True).

  • tqdm_disable (bool, optional) – If False, show the tqdm progress bar (default: True).

Returns:

Match coefficients with alpha as coordinate.

Return type:

xr.DataArray

match_alpha_scale(alpha_vector, scale_vector, normalize=True, flatten=True, tqdm_disable=True)[source]

Calculate the match coefficient for a grid of alpha angles and scale values.

Parameters:

  • alpha_vector (NDArray) – Array of azimuthal angles to test.

  • scale_vector (NDArray) – Array of scale values to test.

  • normalize (bool, optional) – If True, normalize the match coefficient (default: True).

  • flatten (bool, optional) –

    If True, the result map is flatten by subtracting quadratic background fitted along scale direction

    (default: True).

  • tqdm_disable (bool, optional) – If False, show the tqdm progress bar (default: True).

Returns:

Match coefficients for each (alpha, scale) pair.

Return type:

xr.DataArray

match_scale(scale_vector, normalize=True, tqdm_disable=True)[source]

Calculate the match coefficient for a series of lattice scale values.

Parameters:

  • scale_vector (NDArray) – Array of scale values to test.

  • normalize (bool, optional) – If True, normalize the match coefficient (default: True).

  • tqdm_disable (bool, optional) – If False, show the tqdm progress bar (default: True).

Returns:

Match coefficients for each scale value.

Return type:

xr.DataArray

plot(ax=None, show_image=True, show_roi=False, auto_levels=0.0, show_center_lines=False, **kwargs)[source]

Plot the calculated spot positions and optionally the RHEED image.

Parameters:

  • ax (Optional[Axes], optional) – Matplotlib axes to plot on. If None, a new figure is created.

  • show_image (bool, optional) – If True, plot the RHEED image (default: True).

  • show_roi (bool, optional) – If True, overlay the ROI boundary (default: False).

  • auto_levels (float, optional) – Contrast enhancement factor for image plotting.

  • show_center_lines (bool, optional) – If True, plot center cross lines (default: False).

  • **kwargs – Additional keyword arguments for the scatter plot.

Returns:

The axes with the plotted data.

Return type:

matplotlib.axes.Axes

plot_spots(ax=None, show_image=False, **kwargs)[source]

Plot the spot mask used for spot matching on a RHEED image.

Parameters:

  • ax (matplotlib.axes.Axes, optional) – Matplotlib Axes to plot on. If None, a new figure and axes are created.

  • show_image (bool, default=False) – If True, overlay the spot mask on the original RHEED image. If False, only the mask is displayed.

  • **kwargs – Additional keyword arguments passed to ax.imshow(), e.g., cmap, alpha.

Returns:

The axes containing the plotted mask (and optionally the image).

Return type:

matplotlib.axes.Axes

Raises:

ValueError – If show_image=True but no RHEED image is attached (self.image is None).

Notes

  • The mask is automatically generated by self._generate_mask().

  • The image coordinates (sx, sy) are used to set the extent of the plot.

  • The default colormap for the mask is grayscale.

set_spot_size(width, height)[source]

Set the spot size used for mask generation.

Parameters:

  • width (float) – Spot width in mm.

  • height (float) – Spot height in mm.

property stack_index

Index of the current image in a stack.

Type:

int

class Lattice(a1, a2, label=None)[source]

Bases: object

Represents a 2D lattice defined by two basis vectors (a1 and a2), or constructed from a specified plane of a cubic crystal.

This class provides methods for:

  • Creating a lattice from custom basis vectors or from common cubic crystal planes (e.g., FCC (111)).

  • Generating both real-space and reciprocal-space lattices.

  • Rotating and scaling the lattice.

  • Plotting the real and reciprocal lattices.

a1

First lattice basis vector in real space.

Type:

Vector

a2

Second lattice basis vector in real space.

Type:

Vector

b1

First reciprocal lattice vector.

Type:

Vector

b2

Second reciprocal lattice vector.

Type:

Vector

real_lattice

Array of real-space lattice points.

Type:

NDArray

recirpocal_lattice

Array of reciprocal-space lattice points.

Type:

NDArray

label

Optional label for identifying the lattice instance in plots and analysis.

Type:

Optional[str]

__init__(a1, a2, label=None)[source]

Initializes a Lattice object with two basis vectors.

Parameters:

  • a1 (List[float] | Vector) – The first basis vector of the lattice, as a list of floats or a Vector object.

  • a2 (List[float] | Vector) – The second basis vector of the lattice, as a list of floats or a Vector object. label (Optional[str], optional): Label for identifying the lattice instance in plots and analysis. Defaults to None.

Raises:

ValueError – If the provided vectors are invalid or cannot be validated.

classmethod from_bulk_cubic(a=1.0, cubic_type='FCC', plane='111', label=None)[source]

Create a 2D lattice from a bulk cubic crystal.

Parameters:

  • a (float) – Lattice constant.

  • cubic_type (str) – Type of cubic crystal (‘SC’, ‘BCC’, ‘FCC’).

  • plane (str) – Miller indices of the plane (‘111’, ‘110’, ‘100’). label (Optional[str], optional): Label for identifying the lattice instance in plots and analysis. Defaults to None.

Returns:

A Lattice object constructed from the specified cubic crystal and plane.

Return type:

Lattice

Raises:

NotImplementedError – If the specified cubic type or plane is not supported.

classmethod from_surface_hex(a=1.0, label=None)[source]

Create a 2D hexagonal lattice from the given lattice constant.

Parameters:

a (float, optional) – Lattice constant, the length of the primitive vectors. Defaults to 1.0. label (Optional[str], optional): Label for identifying the lattice instance in plots and analysis. Defaults to None.

Returns:

An instance of the Lattice class initialized with hexagonal lattice vectors.

Return type:

Lattice

static generate_lattice(v1, v2, space_size=70.0)[source]

Generate a grid of lattice points within a specified space size.

Parameters:

  • v1 (Vector) – First lattice vector.

  • v2 (Vector) – Second lattice vector.

  • space_size (float) – The size of the rectangular area in which to generate lattice points.

Returns:

Array of lattice points within the specified area.

Return type:

NDArray

static hex_lattice(a)[source]

Generate basis vectors for a 2D hexagonal lattice.

Parameters:

a (float) – Lattice constant.

Returns:

Two basis vectors for the hexagonal lattice.

Return type:

Tuple[Vector, Vector]

plot_real(ax=None, space_size=10.0, show_vectors=True, **kwargs)[source]

Plot the real-space lattice points and basis vectors on a 2D matplotlib Axes.

Parameters:

  • ax (plt.Axes, optional) – Matplotlib Axes object to plot on. If None, a new figure and axes are created.

  • space_size (float) – Range for axis limits.

  • show_vectors (bool) – Whether to draw the a1 and a2 basis vectors.

  • **kwargs – Additional keyword arguments passed to plt.plot.

Returns:

The matplotlib Axes object used for plotting.

Return type:

Axes

plot_reciprocal(ax=None, space_size=5.0, **kwargs)[source]

Plot the reciprocal-space lattice points on a 2D matplotlib Axes.

Parameters:

  • ax (plt.Axes, optional) – Matplotlib Axes object to plot on. If None, a new figure and axes are created.

  • space_size (float) – Range for axis limits.

  • **kwargs – Additional keyword arguments passed to plt.plot.

Returns:

The matplotlib Axes object used for plotting.

Return type:

Axes

property real_lattice_size

Get the current real lattice generation radius.

property reciprocal_lattice_size
rotate(alpha=0.0)[source]

Rotate the lattice by a given angle (in degrees).

Parameters:

alpha (float) – Rotation angle in degrees.

scale(lattice_scale=1.0)[source]

Scale the lattice vectors by a given factor.

Parameters:

lattice_scale (float) – Scaling factor for the lattice vectors.

Modules

cache_utils

ewald

lattice