dgamore.symmetry_reduction#

Automatic symmetry reduction of a k-space Hamiltonian H[kx,ky,kz,o1,o2] to the irreducible Brillouin zone (IBZ), with an inverse map back to the full BZ.

Convention#

H is indexed on a uniform grid (j_1, j_2, j_3) with j_i in {0, …, N_i - 1}, corresponding to k = (j_1/N_1) b_1 + (j_2/N_2) b_2 + (j_3/N_3) b_3, where b_1, b_2, b_3 are the primitive reciprocal-lattice vectors. Gamma is at (0,0,0). In this lattice basis, every crystallographic point group is a finite subgroup of GL(3, Z), and its generators have entries in {-1, 0, +1}.

Symmetries searched#

Operations (M, q, U, sigma, conj) such that for every k in the grid,

H((M k + q) mod N) = sigma * U @ H(k)^{[*]} @ U^dagger

where:

  • M is a 3x3 integer matrix with entries in {-1, 0, +1} and det = +/- 1. Enumerated exhaustively (6960 matrices), filtered to those compatible with the grid shape.

  • q is any integer translation vector in [0, N_1) x [0, N_2) x [0, N_3). For each M, valid q’s are found via FFT-based cross-correlation of the eigenvalue field (fast: O(N^3 log N) per M).

  • U is an arbitrary unitary in orbital space, found by simultaneous diagonalization with per-eigenspace gauge fixing. NOT enumerated: works for any number of orbitals and any U (not just signed perms).

  • sigma in {+1, -1} covers anti-symmetries (chiral / particle-hole).

  • conj covers anti-unitary symmetries (time-reversal-like).

Algorithm#

  1. Enumerate {-1,0,+1}-matrix candidates M (grid-compatible).

  2. For each M and each (sigma, conj), use FFT cross-correlation on the eigenvalue field to find all q for which the eigenvalue pre-screen holds.

  3. For each surviving (M, q, sigma, conj), solve for U.

  4. Close the discovered operations under composition.

  5. Orbit-collapse the k-grid using the closed group; canonical representative = smallest flat index in each orbit.

  6. expand / expand_tensor: vectorized reconstruction of arbitrary-rank tensors T[k, o_1, …, o_r] from their IBZ values.

Reference#

The integer-matrix enumeration covers all crystallographic point groups, but discovery requires that H be expressed in the primitive reciprocal basis (not Cartesian). For models given in Cartesian coordinates of a non-cubic lattice (e.g. hexagonal kx, ky, kz axes), the rotations are not integer matrices and will not be detected. Re-grid H onto the lattice basis first.

Functions

apply_auto_orbital_transform(mat, us, ...)

Applies the auto-discovered per-k orbital transformation (sigma_k, U_k, conj_k) to a tensor whose leading axis enumerates k-points (or a contiguous slice thereof).

get_symmetry_reduction(H[, atol, verbose, ...])

Discovers the symmetries of H[kx, ky, kz, o1, o2] (on the primitive reciprocal-lattice grid) and produces an irreducible-BZ reduction together with reconstruction callables.
dgamore.symmetry_reduction.apply_auto_orbital_transform(mat: ndarray, us: ndarray, sigmas: ndarray, conjs: ndarray, num_orbital_dimensions: int) → ndarray[source]#

Applies the auto-discovered per-k orbital transformation (sigma_k, U_k, conj_k) to a tensor whose leading axis enumerates k-points (or a contiguous slice thereof).

The transformation follows the operator ordering \(G_{abcd} := \langle T[c_a c^\dagger_b c_c c^\dagger_d]\rangle\), with annihilation indices (positions 1, 3) transforming with \(U\) and creation indices (positions 2, 4) with \(U^\dagger\), combined with \(\sigma\) and conjugation:

\[\begin{split}M_{ab}(k) &= \sigma_k\, U_{aa'} [M_{a'b'}(k_{\mathrm{rep}})]^{[*\mathrm{conj}_k]} U^\dagger_{b'b} \\ M_{abcd}(k) &= \sigma_k^2\, U_{aa'} [M_{a'b'c'd'}(k_{\mathrm{rep}})]^{[*\mathrm{conj}_k]} U^\dagger_{b'b} U_{cc'} U^\dagger_{d'd}\end{split}\]

Since \(\sigma_k = \pm 1\), \(\sigma_k^2 = 1\); the 4-index case effectively has no sign factor, which is the correct physics for vertex quantities under particle-hole-like antisymmetries.

Parameters:

  • mat (ndarray) – Input tensor of shape (k_local, nb, [nb, nb,] nb, ...). The leading axis may be the full FBZ or a contiguous slice of it; us, sigmas and conjs must be sliced consistently.

  • us (ndarray) – Per-k unitary matrices of shape (k_local, nb, nb), complex.

  • sigmas (ndarray) – Per-k antisymmetry signs of shape (k_local,), values in {+1, -1}.

  • conjs (ndarray) – Per-k anti-unitary flags of shape (k_local,), dtype bool.

  • num_orbital_dimensions (int) – 2 (single-particle, e.g. H, G) or 4 (two-particle vertex); determines both the einsum pattern and the effective power of sigma_k.

Returns:

The transformed tensor with the same shape as mat (the same backing array, with identity rows left untouched).

Return type:

ndarray

dgamore.symmetry_reduction.get_symmetry_reduction(H, atol=1e-08, verbose=False, include_antiunitary=False)[source]#

Discovers the symmetries of H[kx, ky, kz, o1, o2] (on the primitive reciprocal-lattice grid) and produces an irreducible-BZ reduction together with reconstruction callables.

Parameters:

  • H – Hamiltonian of shape (nx, ny, nz, norb, norb) in the primitive reciprocal-lattice basis.

  • atol – Absolute tolerance for symmetry validation.

  • verbose – If True, print diagnostics about discovery and group closure.

  • include_antiunitary – If False (default), anti-unitary symmetries (conj=True, e.g. time-reversal-like \(H(k) = H(k)^*\)) are discarded after discovery. They are valid symmetries of H, but for frequency-dependent objects they additionally require a Matsubara-frequency flip \(\imath\omega \to -\imath\omega\) that the FBZ-mapping path does not perform; keep the default unless reducing a strictly static quantity (such as H itself or a band structure).

Returns:

A dict with keys 'group' (the discovered _GroupElement list), 'irrk_ind' (flat IBZ representative indices), 'fbz2irrk' (per-k representative field), 'expand' (callable mapping IBZ Hamiltonian values to the full BZ), 'expand_tensor' (callable for arbitrary-rank tensors with per-axis ket/bra character), 'generators' (raw discovered ops), 'n_ibz', 'n_fbz', and the per-k transform data 'pos_in_irrk', 'Us', 'sigmas', 'conjs'.