xrheed.kinematics.lattice

Functions

rotation_matrix([alpha])

Construct a 3x3 right-handed rotation matrix representing an active rotation about the global z-axis.

Classes

Lattice(a1, a2[, label])

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

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.

rotation_matrix(alpha=0.0)[source]

Construct a 3x3 right-handed rotation matrix representing an active rotation about the global z-axis.

The rotation follows the right-hand rule: a positive angle corresponds to a counterclockwise rotation when looking along the +z axis toward the origin. The matrix is intended to be applied to 3D column vectors.

Parameters:

alpha (float) – Rotation angle in degrees.

Returns:

A 3x3 rotation matrix R_z(alpha) such that:

the z-component remains unchanged,
the x-axis rotates toward the y-axis for alpha > 0.

Return type:

NDArray[np.float32]