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.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]]