Lattices (erlab.lattice)

Tools related to the real and reciprocal lattice.

Functions

angle_between(v1, v2)

Return the angle between two vectors.

abc2avec(a, b, c, alpha, beta, gamma)

Construct lattice vectors from lattice parameters.

avec2abc(avec)

Determine lattice parameters from lattice vectors.

to_reciprocal(avec)

Construct the reciprocal lattice vectors from real lattice vectors.

to_real(bvec)

Construct the real lattice vectors from reciprocal lattice vectors.
erlab.lattice.abc2avec(a, b, c, alpha, beta, gamma)[source]

Construct lattice vectors from lattice parameters.

Parameters:

  • a (float) – Lattice parameter \(a\).

  • b (float) – Lattice parameter \(b\).

  • c (float) – Lattice parameter \(c\).

  • alpha (float) – Lattice parameter \(\alpha\) in degrees.

  • beta (float) – Lattice parameter \(\beta\) in degrees.

  • gamma (float) – Lattice parameter \(\gamma\) in degrees.

Returns:

avec – Real lattice vectors, given as a 3 by 3 numpy array with each basis vector given in each row.

Return type:

ndarray[tuple[Any, …], dtype[floating]]

erlab.lattice.angle_between(v1, v2)[source]

Return the angle between two vectors.

Parameters:

  • v1 (array-like) – 1D array of length 3, specifying a vector.

  • v2 (array-like) – 1D array of length 3, specifying a vector.

Returns:

float – The angle in degrees.

Return type:

float

erlab.lattice.avec2abc(avec)[source]

Determine lattice parameters from lattice vectors.

Parameters:

avec (ndarray[tuple[Any, ...], dtype[floating]]) – Real lattice vectors, given as a 3 by 3 numpy array with each basis vector given in each row.

Returns:

a, b, c, alpha, beta, gamma

Return type:

tuple[float, float, float, float, float, float]

erlab.lattice.get_2d_vertices(basis, *, reciprocal=True, rotate=0.0, offset=(0.0, 0.0))[source]

Get the vertices of a 2D Brillouin zone.

Unlike get_bz_edge(), this function only returns the vertices of the BZ. The vertices are ordered such that they can be used to create a polygon. Also, this function allows for rotation and offset of the BZ.

Parameters:

  • basis (ndarray[tuple[Any, ...], dtype[floating]]) – A 2D or 3D numpy array with shape (N, N) where N = 2 or 3, containing the basis vectors of the lattice. If N is 3, only the upper left 2x2 submatrix is used.

  • reciprocal (bool, default: True) – If True, the basis are treated as reciprocal lattice vectors. If False, the basis are treated as real space lattice vectors.

  • rotate (float, default: 0.0) – Rotation angle in degrees to apply to the BZ.

  • offset (tuple[float, float], default: (0.0, 0.0)) – Offset for the Brillouin zone center in the form of a tuple (x, y).

Returns:

vertices (array-like) – Vertices of the BZ.

Return type:

ndarray[tuple[Any, …], dtype[floating]]

erlab.lattice.get_bz_edge(basis, reciprocal=True, extend=None)[source]

Calculate the edge of the first Brillouin zone (BZ) from lattice vectors.

Parameters:

  • basis (ndarray[tuple[Any, ...], dtype[floating]]) – (N, N) numpy array where N = 2 or 3 with each row containing the lattice vectors.

  • reciprocal (bool, default: True) – If False, the basis are given in real space lattice vectors.

  • extend (tuple[int, ...] | None, default: None) – Tuple of positive integers specifying the number of times to extend the BZ in each direction. If None, only the first BZ is returned (equivalent to (1,) * N).

Returns:

  • lines (array-like) – (M, 2, N) array that specifies the endpoints of the M lines that make up the BZ edge, where N = len(basis).

  • vertices (array-like) – Vertices of the BZ.

Return type:

tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

erlab.lattice.get_bz_slice(bvec, plane_point, plane_normal, plane_bounds, *, pad_cells=1, eps=1e-10, return_3d=False, return_midpoints=False)[source]

Get Brillouin zone boundaries along an arbitrary 2D slicing plane.

Parameters:

  • bvec ((3, 3) array_like) – Reciprocal lattice basis vectors. Columns are the basis used for grid @ bvec.

  • plane_point ((3,) array_like) – A point on the slicing plane, in the same coordinate system as bvec.

  • plane_normal ((3,) array_like) – Normal vector of the slicing plane.

  • plane_bounds (tuple of float) – Bounds (xmin, xmax, ymin, ymax) of the rectangular window in the plane’s local (u, v) coordinates.

  • pad_cells (int, optional) – Extra integer padding on the reciprocal lattice translation grid to ensure coverage. Default is 1.

  • eps (float, optional) – Numerical tolerance used for coplanarity and parallel tests. Default is 1e-10.

  • return_3d (bool, optional) – If True, returns all coordinates in 3D momentum space. If False, returns 2D coordinates in the plane’s basis. Default is False.

  • return_midpoints (bool, optional) – If True, also return the midpoints of each segment.

Returns:

  • segments ((S, 2, 2) or (S, 2, 3) numpy array) – 2D segments in plane coordinates (u, v) (if return_3d is False) or 3D segments in the original coordinate system (if return_3d is True).

  • vertices ((V, 2) or (V, 3) numpy array) – Unique vertices of the segments, in 2D plane coordinates (u, v) (if return_3d is False) or 3D momentum space coordinates (if return_3d is True).

  • midpoints ((S, 2) or (S, 3) numpy array) – Midpoints of each segment, in 2D plane coordinates (u, v) (if return_3d is False) or 3D momentum space coordinates (if return_3d is True).

Return type:

tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]] | tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

erlab.lattice.get_in_plane_bz(bvec, kz, angle, bounds, **kwargs)[source]

Get the Brillouin zone boundary sliced by a constant kz plane.

Given a constant out-of-plane momentum kz, computes the BZ boundary of in-plane momenta, rotated by angle.

Parameters:

  • bvec ((3, 3) array_like) – Reciprocal lattice basis vectors.

  • kz (float) – Out-of-plane momentum.

  • angle (float) – Rotation angle (in degrees) of the Brillouin zone about the kz axis.

  • bounds (tuple of float) – (kx_min, kx_max, ky_min, ky_max) bounds of the in-plane momenta.

  • kwargs – Additional keyword arguments passed to get_bz_slice().

erlab.lattice.get_out_of_plane_bz(bvec, k_parallel, angle, bounds, **kwargs)[source]

Get the Brillouin zone boundaries along kz.

Given a line along in-plane momentum defined by k_parallel and angle, computes the BZ boundaries along the out-of-plane momentum.

Parameters:

  • bvec ((3, 3) array_like) – Reciprocal lattice basis vectors.

  • k_parallel (float) – In-plane momentum magnitude.

  • angle (float) – Angle (in degrees) of the in-plane momentum direction, measured from the positive kx axis toward the positive ky axis.

  • bounds (tuple of float) – (kp_min, kp_max, kz_min, kz_max) bounds, where kp is the in-plane momentum in the direction perpendicular to the one defined by angle.

  • kwargs – Additional keyword arguments passed to get_bz_slice().

erlab.lattice.get_surface_bz(bvec, plot_x, plot_y, surface, *, pad_cells=1, eps=1e-10, return_midpoints=False)[source]

Get Brillouin zone boundaries on an arbitrary sampled 2D momentum surface.

This function evaluates the repeated-zone Brillouin-zone boundaries on a regular 2D display grid whose points are embedded in 3D momentum space. Unlike get_bz_slice(), the sampled surface does not need to be planar; each point in surface may have its own (kx, ky, kz) coordinates.

It is primarily useful for exact overlays on displays whose carried momentum coordinates are no longer scalar, such as hv-dependent previews in erlab.interactive.ktool(). Those previews cannot be described by a single constant-k_parallel plane, so the BZ boundary must be evaluated on the sampled surface itself.

The algorithm computes the nearest reciprocal-lattice point for every sampled surface point, detects only the neighboring reciprocal cells that are actually adjacent on the displayed grid, and contours the exact equality \(d_i^2 - d_j^2 = 0\) for those active pairs. A short endpoint-snapping pass is applied afterward so neighboring contour segments meet cleanly on the display grid.

Parameters:

  • bvec (ndarray[tuple[Any, ...], dtype[floating]]) – Reciprocal lattice basis vectors.

  • plot_x (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – One-dimensional display coordinates for the surface grid. The returned polylines are expressed in this coordinate system.

  • plot_y (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – One-dimensional display coordinates for the surface grid. The returned polylines are expressed in this coordinate system.

  • surface (ndarray[tuple[Any, ...], dtype[floating]]) – Sampled momentum surface with shape (len(plot_y), len(plot_x), 3). The last axis contains the 3D momentum coordinates corresponding to each display-grid point.

  • pad_cells (int, default: 1) – Extra integer padding on the reciprocal-lattice translation grid used to ensure coverage near the displayed surface boundary.

  • eps (float, default: 1e-10) – Numerical tolerance used when deduplicating contour segments and derived marker points.

  • return_midpoints (bool, default: False) – If True, an empty midpoint array is returned for API compatibility. Unlike planar BZ slices, curved surface intersections do not have a well-defined reciprocal-space midpoint between symmetry points.

Returns:

  • lines – A list of polyline arrays in (plot_x, plot_y) coordinates.

  • vertices – Deduplicated contour endpoints that lie within the displayed bounds. Closed loops contribute no endpoints.

  • midpoints – Empty (0, 2) array returned only if return_midpoints is True.

Return type:

tuple[list[ndarray[tuple[Any, …], dtype[floating]]], ndarray[tuple[Any, …], dtype[floating]]] | tuple[list[ndarray[tuple[Any, …], dtype[floating]]], ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

Notes

For planar slices, get_bz_slice(), get_in_plane_bz(), or get_out_of_plane_bz() are usually cheaper and return analytically cleaner segment geometry. This function is intended for cases where the displayed coordinates correspond to a curved or otherwise non-planar sampled surface.

erlab.lattice.to_primitive(avec, centering_type)[source]

Convert lattice vectors to primitive cell vectors.

Transforms the given conventional cell lattice vectors into primitive cell basis given the centering type.

Parameters:

  • avec (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – Conventional cell basis vectors, shape (3, 3). Each row represents a lattice vector in Cartesian coordinates.

  • centering_type ({"P", "A", "B", "C", "I", "F", "R"}) –

    Bravais lattice centering type:

    • ”P”: Primitive (no change)

    • ”A”: Extra point on bc face

    • ”B”: Extra point on ac face

    • ”C”: Extra point on ab face

    • ”F”: Face-centered (extra points on all faces)

    • ”I”: Body-centered (extra point in cell center)

    • ”R”: Rhombohedral (in hexagonal setting)

Returns:

avec_p – Primitive cell lattice vectors, shape (3, 3). Each row represents a primitive lattice vector in Cartesian coordinates.

Return type:

ndarray[tuple[Any, …], dtype[_ScalarT]]

Example

>>> import erlab
>>> avec = np.eye(3) * 2.0  # 2 Å conventional cubic cell
>>> avec_prim = erlab.lattice.to_primitive(avec, "I")  # Body-centered cubic
erlab.lattice.to_real(bvec)[source]

Construct the real lattice vectors from reciprocal lattice vectors.

Parameters:

bvec (ndarray[tuple[Any, ...], dtype[floating]]) – Reciprocal lattice vectors, given as a 3 by 3 numpy array with each basis vector given in each row.

Returns:

avec – The real lattice vectors.

Return type:

ndarray[tuple[Any, …], dtype[floating]]

erlab.lattice.to_reciprocal(avec)[source]

Construct the reciprocal lattice vectors from real lattice vectors.

Parameters:

avec (ndarray[tuple[Any, ...], dtype[floating]]) – Real lattice vectors, given as a 3 by 3 numpy array with each basis vector given in each row.

Returns:

bvec – The reciprocal lattice vectors.

Return type:

ndarray[tuple[Any, …], dtype[floating]]