dgamore.brillouin_zone#

Module to handle operations within the (irreducible) Brillouin zone. Heavily inspired by DGApy.

Functions

`apply_symmetries`(mat, symmetries)	Applies a sequence of lattice symmetries to `mat` in place (see `apply_symmetry()`).
`apply_symmetry`(mat, sym)	Applies a single known lattice symmetry to `mat` in place.
`get_k_point_from_string`(string)	Parses a whitespace-separated coordinate string into a fractional k-point.
`get_lattice_symmetries_from_string`(...)	Returns the lattice symmetries from a string.
`inv_sym`(mat, axis)	Applies an inversion symmetry along `axis` to `mat` in place, assuming the grid runs over \([0, 2\pi)\) so that the zero point does not map.
`is_auto_symmetries`(symmetries)	Tests whether a symmetries value requests auto-detection.
`kpath_segment`(k_start, k_end, nk)	Builds the integer k-index points of a straight segment between two fractional corner points, wrapping indices back into the grid.
`quasi_one_dimensional_square_symmetries`()	Returns the standard symmetry set of a quasi-one-dimensional square lattice.
`quasi_two_dimensional_square_symmetries`()	Returns the standard symmetry set of a quasi-two-dimensional square lattice.
`simultaneous_x_y_inversion`()	Returns the symmetry set for a simultaneous x-and-y inversion.
`three_dimensional_cubic_symmetries`()	Returns the standard symmetry set of a three-dimensional cubic lattice.
`two_dimensional_nematic_symmetries`()	Returns the standard symmetry set of a two-dimensional nematic lattice.
`two_dimensional_square_symmetries`()	Returns the standard symmetry set of a two-dimensional square lattice.
`x_y_inv`(mat)	Applies the simultaneous x-and-y inversion symmetry to `mat` in place.
`x_y_sym`(mat)	Applies the x-y reflection symmetry to `mat` in place (see `_pairwise_sym()`).
`x_z_sym`(mat)	Applies the x-z reflection symmetry to `mat` in place (see `_pairwise_sym()`).
`y_z_sym`(mat)	Applies the y-z reflection symmetry to `mat` in place (see `_pairwise_sym()`).

class dgamore.brillouin_zone.KGrid(nk: tuple = None, symmetries: list[KnownSymmetries] = None)[source]#

Bases: object

Class to build the k-grid for the Brillouin zone.

The symmetries argument accepts the usual list of KnownSymmetries and the special “auto” mode (passed as the AUTO_SYMMETRIES_SENTINEL, typically obtained from get_lattice_symmetries_from_string("auto")). In auto mode the symmetry group is discovered from a Hamiltonian H(k) at runtime: instantiate the grid with the sentinel, then call specify_auto_symmetries() with the Hamiltonian. Until that call the grid behaves as if no symmetries were applied (full BZ = IBZ).

Parameters:

nk (tuple)
symmetries (list[KnownSymmetries])

get_irrq_list() → ndarray[source]#

Lists the integer index triplets of all irreducible-BZ q-points.

Returns:: The integer index triplets of all q-points in the irreducible BZ, shape [nk_irr, 3].
Return type:: ndarray

get_q_list() → ndarray[source]#

Lists the integer index triplets of all full-BZ q-points.

Returns:: The integer index triplets of all q-points in the full BZ, shape [nk_tot, 3].
Return type:: ndarray

property grid: tuple#

The three k-axis arrays of the grid.

Returns:: The k-grid as the tuple of axis arrays (kx, ky, kz).

property is_auto: bool#

Whether auto-discovered symmetry data is available on this grid.

Returns:: True if this KGrid is in auto-discovered symmetry mode and specify_auto_symmetries() has populated the transformation data.

property kmesh: ndarray#

The momentum meshgrid over the full BZ.

Returns:: The meshgrid of {kx, ky, kz} (shape [3, nx, ny, nz], "ij" indexing).

property kmesh_ind: ndarray#

The integer index meshgrid over the full BZ.

Returns:: The integer index meshgrid of {kx, ky, kz}. Only valid for meshes spanning \([0, 2\pi)\).

property kmesh_list#

The flattened momentum meshgrid.

Returns:: The k-meshgrid flattened to shape [3, nk_tot].

property kx_shift: float#: Returns the kx grid shifted by \(\pi\) in the half-open interval i.e. \([-\pi,\pi)\).

property kx_shift_closed: ndarray#: Returns the kx grid shifted by \(\pi\) in the closed interval i.e. \([-\pi,\pi]\).

property ky_shift: float#: Returns the ky grid shifted by \(\pi\) in the half-open interval i.e. \([-\pi,\pi)\).

property ky_shift_closed: ndarray#: Returns the ky grid shifted by \(\pi\) in the closed interval i.e. \([-\pi,\pi]\).

property kz_shift: float#: Returns the kz grid shifted by \(\pi\) in the half-open interval i.e. \([-\pi,\pi)\).

property kz_shift_closed: ndarray#: Returns the kz grid shifted by \(\pi\) in the closed interval i.e. \([-\pi,\pi]\).

property nk_irr: int#

The number of irreducible-BZ k-points.

Returns:: The number of k-points in the irreducible BZ.

property nk_tot#

The total number of full-BZ k-points.

Returns:: The total number of k-points in the full BZ.

set_fbz2irrk() → None[source]#

Builds the full-BZ-to-irreducible-BZ index field by applying the lattice symmetries to the flat index grid.

Returns:: None.
Return type:: None

set_irrk_maps() → None[source]#

Derives the irreducible-BZ index list, the inverse map back to the full BZ, the multiplicities, and the per-point symmetry map from fbz2irrk.

Returns:: None.
Return type:: None

set_irrk_mesh() → None[source]#

Builds and stores the k-mesh restricted to the irreducible BZ.

Returns:: None.
Return type:: None

set_k_axes() → None[source]#

Builds the three k-axis arrays spanning \([0, 2\pi)\) for the full BZ.

Returns:: None.
Return type:: None

specify_auto_symmetries(hk: ndarray, atol: float = 1e-08, verbose: bool = False, include_antiunitary: bool = False) → None[source]#

Auto-detects the symmetry group of the Hamiltonian hk and replay the IBZ reduction onto this grid.

Only applicable when this KGrid was constructed in auto mode (symmetries is the AUTO_SYMMETRIES_SENTINEL). Discovers all operations (M, q, U, sigma, conj) that leave H(k) invariant, then repopulates fbz2irrk, irrk_ind, irrk_inv, irrk_count, irr_kmesh, and stores per-k transformation data used by _map_to_full_bz to apply the orbital transformation when expanding IBZ -> FBZ.

Parameters:

hk (ndarray) – Complex Hermitian Hamiltonian of shape (nk[0], nk[1], nk[2], nb, nb) indexed on the same grid as this KGrid, with axes along the primitive reciprocal-lattice basis (fractional coordinate along \(b_i\)).
atol (float) – Absolute tolerance for symmetry validation.
verbose (bool) – If True, print diagnostics about the discovered group.
include_antiunitary (bool) – If False (default), anti-unitary symmetries (conj=True, i.e. \(H(k) = H(k)^*\)-style time-reversal) are dropped after discovery. They are valid symmetries of H but, for frequency-dependent quantities, additionally require a Matsubara-frequency flip that _map_to_full_bz does not perform; keeping False makes the IBZ-to-FBZ expansion safe for any object with the same lattice symmetry as H, at the cost of a possibly larger IBZ.

Returns:

None.

Raises:

RuntimeError – If the grid was not constructed in auto mode.
ValueError – If hk’s shape does not match the grid or is not (nx, ny, nz, nb, nb).

Return type:

None

class dgamore.brillouin_zone.KPath(nk, path, kx=None, ky=None, kz=None, path_deliminator='-')[source]#

Bases: object

Object to generate paths in the Brillouin zone. It is currently assumed that the BZ grid is from (0,2*pi).

build_k_path()[source]#

Builds the discretized k-path by concatenating the segments between consecutive corner points.

Returns:: A tuple (k_path, nkp) of the integer path-index array and the per-segment point counts.

property cind#

The corner-point indices within the concatenated path.

Returns:: The indices of the corner points within the concatenated path.

property ckps#

The corner-point label strings of the path.

Returns:: The list of corner-point label strings obtained by splitting path.

corner_k_points()[source]#

Resolves the corner-point labels of the path to their fractional k-coordinates (known labels via KnownKPoints, otherwise parsed from the string).

Returns:: The corner k-points as an array of shape [n_corners, 3].

get_bands(ek)[source]#

Diagonalizes the band dispersion at each path point to obtain the (sorted, real) band energies.

Parameters:: ek – The band dispersion indexed as [kx, ky, kz, o1, o2].
Returns:: The band energies along the path, shape [nk_path, n_bands].

get_kpath_val()[source]#

Maps the path indices to their k-axis values.

Returns:: The k-axis values along the path as a list [kx_vals, ky_vals, kz_vals].

get_kpoints()[source]#

Stacks the path k-axis values into a coordinate array.

Returns:: The path k-points as an array of shape [nk_tot, 3].

property ikx#

The kx index of each path point.

Returns:: The integer kx index of each point along the path.

property iky#

The ky index of each path point.

Returns:: The integer ky index of each point along the path.

property ikz#

The kz index of each path point.

Returns:: The integer kz index of each point along the path.

property k_axis#

The normalized arc-length coordinate along the path.

Returns:: The cumulative arc-length coordinate of each path point, normalized to [0, 1] (for plotting).

property labels#

The plot labels for the path corner points.

Returns:: The plot labels (LaTeX where known) for the corner points along the path.

map_to_kpath(mat)[source]#

Selects the values of a BZ-gridded array along the k-path.

Parameters:: mat – Array indexed as [kx, ky, kz, ...] over the full BZ.
Returns:: The array restricted to the path points (leading axis runs along the path).

property nk_seg#

The number of points per path segment.

Returns:: The number of points in each path segment between corner points.

property nk_tot#

The total number of path points.

Returns:: The total number of points along the path.

set_kgrid(k_in, nk)[source]#

Returns an explicit k-axis if given, otherwise builds a \([0, 2\pi)\) grid of nk points.

Parameters:

k_in – Explicit k-axis array, or None to build a default grid.
nk – Number of points in the default grid.

Returns:

The k-axis array.

property x_ticks#

The x-axis tick positions at the path corner points.

Returns:: The x-axis tick positions (at the corner points) for plotting along the path.

class dgamore.brillouin_zone.KnownKPoints(*values)[source]#

Bases: Enum

Known high-symmetry k-points in the Brillouin zone, as fractional coordinates.

Variables:

GAMMA – Zone center \(\Gamma = (0, 0, 0)\).
X – \((0.5, 0, 0)\).
Y – \((0, 0.5, 0)\).
Z – \((0, 0, 0.5)\).
M – \((0.5, 0.5, 0)\).
M2 – \((0.25, 0.25, 0)\).
R – \((0.5, 0, 0.5)\).
A – \((0.5, 0.5, 0.5)\).
T – \((0, 0.5, 0.5)\).

class dgamore.brillouin_zone.KnownSymmetries(*values)[source]#

Bases: Enum

Known symmetries of the Brillouin zone.

Variables:

X_INV – Inversion along \(k_x\).
Y_INV – Inversion along \(k_y\).
Z_INV – Inversion along \(k_z\).
X_Y_SYM – Exchange symmetry between \(k_x\) and \(k_y\).
X_Z_SYM – Exchange symmetry between \(k_x\) and \(k_z\).
Y_Z_SYM – Exchange symmetry between \(k_y\) and \(k_z\).
X_Y_INV – Simultaneous inversion of \(k_x\) and \(k_y\).

class dgamore.brillouin_zone.Labels(*values)[source]#

Bases: Enum

Plot labels for the high-symmetry k-points, each a (key, latex) pair (lookup key and rendered LaTeX label).

Variables:

GAMMA – The \(\Gamma\) point label.
X – The X point label.
Y – The Y point label.
Z – The Z point label.
M – The M point label.
M2 – The M2 point label.
R – The R point label.
A – The A point label.
T – The T point label.

static from_string(s: str)[source]#

Looks up a Labels member by its string key (case-insensitive).

Parameters:: s (str) – The label key to look up.
Returns:: The matching Labels member.
Raises:: ValueError – If no label matches s.

property key#

The lowercase lookup key of the label.

Returns:: The lowercase string key of the label (first tuple element).

property latex#

The LaTeX/plot string of the label.

Returns:: The LaTeX/plot label string (second tuple element).

dgamore.brillouin_zone.apply_symmetries(mat: ndarray, symmetries: list[KnownSymmetries]) → None[source]#

Applies a sequence of lattice symmetries to mat in place (see apply_symmetry()).

Parameters:

mat (ndarray) – The (at least 3D) array to symmetrize in place.
symmetries (list[KnownSymmetries]) – The list of KnownSymmetries to apply in order (empty/None is a no-op).

Returns:

None.

Return type:

None

dgamore.brillouin_zone.apply_symmetry(mat: ndarray, sym: KnownSymmetries) → None[source]#

Applies a single known lattice symmetry to mat in place.

Parameters:

mat (ndarray) – The (at least 3D) array to symmetrize in place.
sym (KnownSymmetries) – The KnownSymmetries operation to apply.

Returns:

None.

Return type:

None

dgamore.brillouin_zone.get_k_point_from_string(string)[source]#

Parses a whitespace-separated coordinate string into a fractional k-point.

Parameters:: string – A string of space-separated floats, e.g. "0.5 0.5 0.0".
Returns:: The parsed coordinates as a numpy array.

dgamore.brillouin_zone.get_lattice_symmetries_from_string(symmetry_string: str | tuple | list) → list[KnownSymmetries][source]#

Returns the lattice symmetries from a string.

The special string "auto" signals that symmetries should be auto-detected from a Hamiltonian H(k) at runtime via specify_auto_symmetries(). In that case an empty list is returned here, but a marker is set so that the KGrid defers building fbz2irrk until specify_auto_symmetries() is called.

Parameters:

symmetry_string (str | tuple | list) – A named preset (e.g. "two_dimensional_square"), the special "auto", an empty string/"none", or a list/tuple (or its string repr) of KnownSymmetries values.

Returns:

The corresponding list of KnownSymmetries, an empty list, or the AUTO_SYMMETRIES_SENTINEL.

Raises:

ValueError – If the string cannot be parsed as a known preset or a Python literal.
NotImplementedError – If a listed symmetry is not a known symmetry.

Return type:

list[KnownSymmetries]

dgamore.brillouin_zone.inv_sym(mat: ndarray, axis) → None[source]#

Applies an inversion symmetry along axis to mat in place, assuming the grid runs over \([0, 2\pi)\) so that the zero point does not map.

Parameters:

mat (ndarray) – The (at least 3D) array to symmetrize in place; the leading three axes are the momentum axes.
axis – The momentum axis (0, 1 or 2) to invert.

Returns:

None.

Return type:

None

dgamore.brillouin_zone.is_auto_symmetries(symmetries) → bool[source]#

Tests whether a symmetries value requests auto-detection.

Parameters:: symmetries – A symmetries value (list, sentinel, etc.).
Returns:: True if symmetries is the AUTO_SYMMETRIES_SENTINEL.
Return type:: bool

dgamore.brillouin_zone.kpath_segment(k_start, k_end, nk)[source]#

Builds the integer k-index points of a straight segment between two fractional corner points, wrapping indices back into the grid.

Parameters:

k_start – Fractional coordinates of the segment start point.
k_end – Fractional coordinates of the segment end point.
nk – Number of k-points per spatial direction.

Returns:

A tuple (k_segment, nkp) of the integer index array along the segment and the number of points.

dgamore.brillouin_zone.quasi_one_dimensional_square_symmetries() → list[KnownSymmetries][source]#

Returns the standard symmetry set of a quasi-one-dimensional square lattice.

Returns:: The lattice symmetries of a quasi-one-dimensional square lattice.
Return type:: list[KnownSymmetries]

dgamore.brillouin_zone.quasi_two_dimensional_square_symmetries() → list[KnownSymmetries][source]#

Returns the standard symmetry set of a quasi-two-dimensional square lattice.

Returns:: The lattice symmetries of a quasi-two-dimensional square lattice.
Return type:: list[KnownSymmetries]

dgamore.brillouin_zone.simultaneous_x_y_inversion() → list[KnownSymmetries][source]#

Returns the symmetry set for a simultaneous x-and-y inversion.

Returns:: The symmetry list for a simultaneous inversion in the x and y directions.
Return type:: list[KnownSymmetries]

dgamore.brillouin_zone.three_dimensional_cubic_symmetries() → list[KnownSymmetries][source]#

Returns the standard symmetry set of a three-dimensional cubic lattice.

Returns:: The lattice symmetries of a three-dimensional cubic lattice.
Return type:: list[KnownSymmetries]

dgamore.brillouin_zone.two_dimensional_nematic_symmetries() → list[KnownSymmetries][source]#

Returns the standard symmetry set of a two-dimensional nematic lattice.

Returns:: The lattice symmetries of a two-dimensional nematic lattice.
Return type:: list[KnownSymmetries]

dgamore.brillouin_zone.two_dimensional_square_symmetries() → list[KnownSymmetries][source]#

Returns the standard symmetry set of a two-dimensional square lattice.

Returns:: The lattice symmetries of a two-dimensional square lattice.
Return type:: list[KnownSymmetries]

dgamore.brillouin_zone.x_y_inv(mat: ndarray) → None[source]#

Applies the simultaneous x-and-y inversion symmetry to mat in place.

Parameters:: mat (ndarray) – The (at least 3D) array to symmetrize in place.
Returns:: None.
Return type:: None

dgamore.brillouin_zone.x_y_sym(mat: ndarray) → None[source]#

Applies the x-y reflection symmetry to mat in place (see _pairwise_sym()).

Parameters:: mat (ndarray) – The (at least 3D) array to symmetrize in place.
Returns:: None.
Return type:: None

dgamore.brillouin_zone.x_z_sym(mat: ndarray) → None[source]#

Applies the x-z reflection symmetry to mat in place (see _pairwise_sym()).

Parameters:: mat (ndarray) – The (at least 3D) array to symmetrize in place.
Returns:: None.
Return type:: None

dgamore.brillouin_zone.y_z_sym(mat: ndarray) → None[source]#

Applies the y-z reflection symmetry to mat in place (see _pairwise_sym()).

Parameters:: mat (ndarray) – The (at least 3D) array to symmetrize in place.
Returns:: None.
Return type:: None