dft.band_unfolding

Primitive-cell interpretation of commensurate supercell band structures.

import mlx_atomistic.dft.band_unfolding

Classes

FoldedBandPath

class FoldedBandPath
    def __init__(primitive_path: BandPath, supercell_path: BandPath, primitive_cell: np.ndarray, supercell_cell: np.ndarray, supercell_transform: np.ndarray, volume_ratio: int, reciprocal_shifts: np.ndarray, path_distances: np.ndarray)

Mapping from a primitive reciprocal path into a commensurate supercell.

Parameters

Name	Type	Default	Description
primitive_path	BandPath		Original reduced-coordinate primitive-cell path.
supercell_path	BandPath		Equivalent reduced-coordinate supercell path.
primitive_cell	np.ndarray		Primitive direct-lattice row vectors in bohr.
supercell_cell	np.ndarray		Supercell direct-lattice row vectors in bohr.
supercell_transform	np.ndarray		Integer direct-lattice transform from primitive cell to supercell.
volume_ratio	int		Number of primitive cells contained in the supercell.
reciprocal_shifts	np.ndarray		Integer supercell reciprocal shifts removed while folding every path point into the canonical first zone.
path_distances	np.ndarray		Cumulative primitive reciprocal-space distance.

Methods

to_dict

def to_dict() -> dict[str, object]

Return a JSON-safe mapping summary.

Returns

• dict[str, object]

PeriodicUnfoldedBandStructureResult

class PeriodicUnfoldedBandStructureResult
    def __init__(folded_path: FoldedBandPath, bands: PeriodicBandStructureResult, spectral_weights: mx.array, primitive_occupied_band_count: int)

Supercell eigenvalues decorated with primitive-cell spectral weights.

Parameters

Name	Type	Default	Description
folded_path	FoldedBandPath		Primitive-to-supercell path mapping.
bands	PeriodicBandStructureResult		Underlying production supercell band result.
spectral_weights	mx.array		Primitive Bloch-character weights with shape (n_kpoints, n_bands).
primitive_occupied_band_count	int		Doubly occupied primitive-cell bands.

Methods

to_dict

def to_dict() -> dict[str, object]

Return JSON-safe unfolded energies and spectral weights.

Returns

• dict[str, object]

Functions

fold_band_path_to_supercell

def fold_band_path_to_supercell(primitive_cell: Sequence[Sequence[float]], supercell_cell: Sequence[Sequence[float]], band_path: BandPath, *, commensurability_tolerance: float = 1e-08) -> FoldedBandPath

Fold a primitive reduced-coordinate path into a commensurate supercell.

Direct lattice vectors are rows. The returned supercell points are reduced modulo integer reciprocal vectors into the half-open interval [-0.5, 0.5).

Parameters

Name	Type	Default	Description
primitive_cell	Sequence[Sequence[float]]		Primitive direct-lattice row vectors in bohr.
supercell_cell	Sequence[Sequence[float]]		Supercell direct-lattice row vectors in bohr.
band_path	BandPath		Primitive reduced-coordinate path.
commensurability_tolerance	float	1e-08	Absolute tolerance for the integer direct-lattice transform.

Returns

• FoldedBandPath — Validated path mapping and primitive reciprocal-space distances.

unfold_periodic_band_structure

def unfold_periodic_band_structure(bands: PeriodicBandStructureResult, folded_path: FoldedBandPath, *, reciprocal_tolerance: float = 2e-05) -> PeriodicUnfoldedBandStructureResult

Compute primitive Bloch-character weights from compact plane waves.

A supercell plane wave contributes to primitive point k when its Cartesian wavevector differs from k by a primitive reciprocal-lattice vector. Summing squared coefficients over that exact reciprocal coset gives the unfolding spectral weight without materializing full FFT grids.

Parameters

Name	Type	Default	Description
bands	PeriodicBandStructureResult		Production bands evaluated along folded_path.supercell_path.
folded_path	FoldedBandPath		Commensurate primitive-to-supercell path mapping.
reciprocal_tolerance	float	2e-05	Integer-coordinate admission tolerance.

Returns

• PeriodicUnfoldedBandStructureResult — Underlying eigenvalues and primitive spectral weights.