erlab.plotting.bz

Utilities for plotting Brillouin zones.

Functions

plot_bz(basis, *[, reciprocal, rotate, ...])

Plot a Brillouin zone, given the basis vectors.

plot_hex_bz([a, reciprocal, rotate, offset, ax])

Plot a 2D hexagonal BZ overlay on the specified axes.

plot_in_plane_bz(bvec, *[, kz, angle, ...])

Plot Brillouin-zone boundaries on a constant-kz plane.

plot_out_of_plane_bz(bvec, *[, k_parallel, ...])

Plot Brillouin-zone boundaries on an out-of-plane momentum slice.
erlab.plotting.bz.plot_bz(basis, *, reciprocal=False, rotate=0.0, offset=(0.0, 0.0), ax=None, **kwargs)[source]

Plot a Brillouin zone, given the basis vectors.

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. With the default reciprocal=False, these are real-space lattice vectors and the plotted coordinates use the corresponding reciprocal unit. For example, lattice vectors in Å give coordinates in Å⁻¹.

  • reciprocal (bool, default: False) – If True, basis is interpreted as reciprocal lattice vectors in the same units as the plotted axes.

  • 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 as (x, y), in the plotted coordinate units.

  • ax (Axes | None, default: None) – The axes to plot the BZ on. If None, the current axes are used.

  • **kwargs – Additional keyword arguments passed to matplotlib.patches.Polygon.

Returns:

matplotlib.patches.Polygon – The polygon artist added to ax.

Return type:

Polygon

erlab.plotting.bz.plot_hex_bz(a=3.54, *, reciprocal=False, rotate=0.0, offset=(0.0, 0.0), ax=None, **kwargs)[source]

Plot a 2D hexagonal BZ overlay on the specified axes.

Parameters:

  • a (float, default: 3.54) – Real-space lattice constant. The plotted coordinates use the corresponding reciprocal unit. For example, a in Å gives coordinates in Å⁻¹.

  • reciprocal (bool, default: False) – If True, a is instead interpreted as the reciprocal lattice periodicity in the plotted coordinate units.

  • 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 as (x, y), in the plotted coordinate units.

  • ax (Axes | None, default: None) – The axes to plot the BZ on. If None, the current axes are used.

  • **kwargs – Additional keyword arguments passed to matplotlib.patches.RegularPolygon.

Returns:

matplotlib.patches.RegularPolygon or list of matplotlib.patches.RegularPolygon – The polygon artist, or one artist per axes when ax is an iterable.

Return type:

RegularPolygon | list[RegularPolygon]

erlab.plotting.bz.plot_in_plane_bz(bvec, *, kz=0.0, angle=0.0, bounds=None, ax=None, vertices=False, midpoints=False, vertex_kwargs=None, midpoint_kwargs=None, **line_kwargs)[source]

Plot Brillouin-zone boundaries on a constant-kz plane.

Parameters:

  • bvec (ndarray[tuple[Any, ...], dtype[floating]]) – Reciprocal lattice basis vectors. All momentum inputs use the same units as these vectors, typically Å⁻¹ for ARPES data.

  • kz (float, default: 0.0) – Out-of-plane momentum of the slice, in the same units as bvec.

  • angle (float, default: 0.0) – Rotation angle in degrees about the kz axis.

  • bounds (tuple[float, float, float, float] | None, default: None) – (kx_min, kx_max, ky_min, ky_max) bounds in the same units as bvec. If None, bounds are inferred from the current axes limits.

  • ax (Axes | None, default: None) – The axes to plot the BZ boundaries on. If None, the current axes are used.

  • vertices (bool, default: False) – If True, also mark BZ vertices.

  • midpoints (bool, default: False) – If True, also mark segment midpoints.

  • vertex_kwargs (dict[str, Any] | None, default: None) – Additional keyword arguments passed to matplotlib.axes.Axes.scatter() for vertices and midpoints.

  • midpoint_kwargs (dict[str, Any] | None, default: None) – Additional keyword arguments passed to matplotlib.axes.Axes.scatter() for vertices and midpoints.

  • **line_kwargs – Additional keyword arguments passed to matplotlib.axes.Axes.plot().

Returns:

lines, vertex_artist, midpoint_artist (tuple) – Line artists for the zone boundaries and optional scatter artists for the vertices and edge midpoints.

Return type:

tuple[tuple[Line2D, …], PathCollection | None, PathCollection | None]

erlab.plotting.bz.plot_out_of_plane_bz(bvec, *, k_parallel=0.0, angle=0.0, bounds=None, ax=None, vertices=False, midpoints=False, vertex_kwargs=None, midpoint_kwargs=None, **line_kwargs)[source]

Plot Brillouin-zone boundaries on an out-of-plane momentum slice.

Parameters:

  • bvec (ndarray[tuple[Any, ...], dtype[floating]]) – Reciprocal lattice basis vectors. All momentum inputs use the same units as these vectors, typically Å⁻¹ for ARPES data.

  • k_parallel (float, default: 0.0) – Fixed in-plane momentum component along angle, in the same units as bvec.

  • angle (float, default: 0.0) – Angle in degrees of the fixed in-plane momentum direction.

  • bounds (tuple[float, float, float, float] | None, default: None) – (kp_min, kp_max, kz_min, kz_max) bounds in the same units as bvec. If None, bounds are inferred from the current axes limits.

  • ax (Axes | None, default: None) – The axes to plot the BZ boundaries on. If None, the current axes are used.

  • vertices (bool, default: False) – If True, also mark BZ vertices.

  • midpoints (bool, default: False) – If True, also mark segment midpoints.

  • vertex_kwargs (dict[str, Any] | None, default: None) – Additional keyword arguments passed to matplotlib.axes.Axes.scatter() for vertices and midpoints.

  • midpoint_kwargs (dict[str, Any] | None, default: None) – Additional keyword arguments passed to matplotlib.axes.Axes.scatter() for vertices and midpoints.

  • **line_kwargs – Additional keyword arguments passed to matplotlib.axes.Axes.plot().

Returns:

lines, vertex_artist, midpoint_artist (tuple) – Line artists for the zone boundaries and optional scatter artists for the vertices and edge midpoints.

Return type:

tuple[tuple[Line2D, …], PathCollection | None, PathCollection | None]