dft.kpoints

k-point meshes and band-structure diagnostics.

import mlx_atomistic.dft.kpoints

Classes

BandPath

class BandPath
    def __init__(points: Sequence[KPoint])

Explicit k-point path for non-SCF band diagnostics.

Parameters

Name	Type	Default	Description
points	Sequence[KPoint]

Methods

line

def line(start: Sequence[float], end: Sequence[float], *, count: int, start_label: str | None = None, end_label: str | None = None, coordinate_system: str = 'cartesian') -> BandPath

Build a linear path between two k points.

Parameters

Name	Type	Default	Description
start	Sequence[float]		Starting three-component k-point vector.
end	Sequence[float]		Ending three-component k-point vector.
count	int		Number of points, including both endpoints.
start_label	str | None	None	Optional label for the first point.
end_label	str | None	None	Optional label for the last point.
coordinate_system	str	'cartesian'	"cartesian" or "reduced". Defaults to "cartesian" for compatibility with the toy band path.

Returns

• BandPath — Explicit uniformly sampled band path.

BandStructureResult

class BandStructureResult
    def __init__(kpoints: tuple[KPoint, ...], eigenvalues: mx.array, reused_density: bool, nonlocal_available: bool = False, nonlocal_applied: bool = False, nonlocal_projector_count: int = 0)

Non-SCF band energies along a path.

Parameters

Name	Type	Default	Description
kpoints	tuple[KPoint, ...]		Cartesian k-points evaluated in path order.
eigenvalues	mx.array		Eigenvalue array with shape (n_kpoints, n_bands).
reused_density	bool		Whether the calculation reused the SCF density without another SCF cycle.
nonlocal_available	bool	False	Whether ion-backed nonlocal projector metadata was available on the system.
nonlocal_applied	bool	False	Whether nonlocal projectors were applied to the band Hamiltonian.
nonlocal_projector_count	int	0	Number of projector channels included when nonlocal projectors were applied.

Methods

to_dict

def to_dict() -> dict

Return JSON-safe band data.

Returns

• dict

GammaCenteredGrid

class GammaCenteredGrid(KPointMesh)
    def __init__(size: Sequence[int])

Regular reduced-coordinate mesh that includes the Γ point.

Parameters

Name	Type	Default	Description
size	Sequence[int]		Number of points along each reciprocal lattice vector.

KPoint

class KPoint
    def __init__(vector: Sequence[float], *, weight: float = 1.0, label: str | None = None, coordinate_system: str = 'cartesian')

One reciprocal-space k point.

Parameters

Name	Type	Default	Description
vector	Sequence[float]		Three-component k-point vector. Cartesian vectors are in the same reciprocal units as ReciprocalGrid.vectors; reduced vectors are fractional diagnostic coordinates and are not accepted by Hamiltonian evaluation.
weight	float	1.0	Positive integration weight. Defaults to 1.0.
label	str | None	None	Optional display label such as "Γ". Defaults to None.
coordinate_system	str	'cartesian'	Either "cartesian" or "reduced". Defaults to "cartesian".

Methods

gamma

def gamma() -> KPoint

Return the Γ point.

Returns

• KPoint

to_dict

def to_dict() -> dict

Return a JSON-safe representation.

Returns

• dict

KPointMesh

class KPointMesh
    def __init__(points: Sequence[KPoint], *, _symmetry_reduction: _KPointSymmetryReduction | None = None)

Weighted k-point mesh with optional point-group orbit metadata.

Parameters

Name	Type	Default	Description
points	Sequence[KPoint]
_symmetry_reduction	_KPointSymmetryReduction | None	None

Properties

• point_group_symmetry_reduced bool — Return whether SCF density orbit reconstruction is required.

Methods

from_dict

def from_dict(payload: Mapping[str, object]) -> KPointMesh

Rebuild a weighted mesh and its optional symmetry orbit metadata.

Parameters

Name	Type	Default	Description
payload	Mapping[str, object]

Returns

• KPointMesh

gamma

def gamma() -> KPointMesh

Return a one-point Γ mesh.

Returns

• KPointMesh

to_dict

def to_dict() -> dict

Return a JSON-safe representation.

Returns

• dict

MonkhorstPackGrid

class MonkhorstPackGrid(KPointMesh)
    def __init__(size: Sequence[int])

Simple Γ-centered Monkhorst-Pack-style mesh.

Parameters

Name	Type	Default	Description
size	Sequence[int]

TimeReversalOwnership

class TimeReversalOwnership
    def __init__(entries: tuple[TimeReversalOwnershipEntry, ...], active_bases_admitted: bool = False)

Deterministic owner/partner topology for an explicit k-point mesh.

Parameters

Name	Type	Default	Description
entries	tuple[TimeReversalOwnershipEntry, ...]		One ownership entry per explicit mesh point, in original order.
active_bases_admitted	bool	False	Whether exact active-basis permutations have been checked and attached.

Properties

• fallback_reasons dict[int, str] — Return independent-lane fallback reasons keyed by explicit index.
• owned_indices tuple[int, ...] — Return explicit indices whose compact states are retained.
• partner_indices tuple[int, ...] — Return explicit indices published from owner time-reversal views.
• representative_indices tuple[int, ...] — Return admitted time-reversal representative indices.

Methods

entry_for

def entry_for(explicit_index: int) -> TimeReversalOwnershipEntry

Return ownership metadata for one explicit index.

Parameters

Name	Type	Default	Description
explicit_index	int		Original mesh index.

Returns

• TimeReversalOwnershipEntry — Matching ownership entry.

Raises

• IndexError — If the index is outside the explicit mesh.

to_dict

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

Return JSON-safe topology metadata.

Returns

• dict[str, object] — Admission state, counts, and ordered ownership entries.

TimeReversalOwnershipEntry

class TimeReversalOwnershipEntry
    def __init__(explicit_index: int, reduced_kpoint: tuple[float, float, float], original_weight: float, owner_index: int, partner_index: int | None, role: str, aggregated_weight: float, reciprocal_shift: tuple[int, int, int] | None, _time_reversal_permutation: np.ndarray | None = None, fallback_reason: str | None = None)

Ownership metadata for one explicit reduced-coordinate k-point.

The time-reversal permutation maps each active compact coefficient index at this explicit point to its signed-G index at partner_index. It is populated only after active-basis admission succeeds.

Parameters

Name	Type	Default	Description
explicit_index	int		Original index in the caller’s k-point mesh.
reduced_kpoint	tuple[float, float, float]		Original reduced-coordinate point.
original_weight	float		Original normalized integration weight.
owner_index	int		Explicit point whose compact eigenstate is retained.
partner_index	int | None		Time-reversed explicit point, or None when absent.
role	str		"owner", "partner", or "independent".
aggregated_weight	float		Integration weight consumed by the owner lane.
reciprocal_shift	tuple[int, int, int] | None		Integer vector satisfying k + k_partner = reciprocal_shift.
_time_reversal_permutation	np.ndarray | None	None	Private source-to-partner compact-index permutation snapshot, or None when reuse is not admitted.
fallback_reason	str | None	None	Stable independent-lane reason, or None.

Properties

• time_reversal_permutation np.ndarray | None — Return a caller-owned copy of the signed-G permutation.

Methods

to_dict

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

Return a JSON-safe ownership record.

Returns

• dict[str, object] — Explicit point, weight, owner, partner, role, permutation, and
• dict[str, object] — fallback diagnostics.

Functions

admit_time_reversal_bases

def admit_time_reversal_bases(ownership: TimeReversalOwnership, bases: Sequence[Any]) -> TimeReversalOwnership

Admit exact signed-G permutations for active compact bases.

Parameters

Name	Type	Default	Description
ownership	TimeReversalOwnership		Geometry/weight topology built before basis construction.
bases	Sequence[Any]		One compact plane-wave basis per explicit point.

Returns

• TimeReversalOwnership — Topology with read-only source-to-partner permutations. Only pairs whose
• TimeReversalOwnership — active bases are exact one-to-one time reversals remain reused.

Raises

• ValueError — If the basis count differs or admission was already run.

build_time_reversal_ownership

def build_time_reversal_ownership(kpoint_mesh: KPointMesh) -> TimeReversalOwnership

Build deterministic reduced-coordinate owner/partner topology.

Geometry is matched modulo integer reciprocal-lattice shifts. Missing or unequal-weight partners become independent lanes, while duplicate or multiply claimed maps fail closed. Active-basis permutations are admitted separately after bases exist.

Parameters

Name	Type	Default	Description
kpoint_mesh	KPointMesh		Explicit weighted reduced-coordinate mesh.

Returns

• TimeReversalOwnership — Ordered topology without active-basis permutations.

Raises

• ValueError — If input is non-finite, non-reduced, duplicated, or has an ambiguous/multiply-claimed time-reversal map.

cubic_reciprocal_symmetry_operations

def cubic_reciprocal_symmetry_operations() -> tuple[tuple[tuple[int, ...], ...], ...]

Return the 48 signed axis permutations of the full cubic point group.

Returns

• tuple[tuple[tuple[int, ...], ...], ...] — Integer reciprocal-coordinate operations, including inversion.

reciprocal_symmetry_operations_for_cell

def reciprocal_symmetry_operations_for_cell(cell_matrix: Sequence[Sequence[float]], cartesian_operations: Sequence[Sequence[Sequence[int | float]]], *, coordinate_atol: float = 1e-12) -> tuple[tuple[tuple[int, ...], ...], ...]

Express Cartesian reciprocal symmetries in one cell’s reduced basis.

Parameters

Name	Type	Default	Description
cell_matrix	Sequence[Sequence[float]]		Full-rank direct-cell row vectors.
cartesian_operations	Sequence[Sequence[Sequence[int | float]]]		Cartesian column-vector symmetry operations.
coordinate_atol	float	1e-12	Absolute tolerance for integer reduced operations.

Returns

• tuple[tuple[tuple[int, ...], ...], ...] — Unique integer operations acting on reduced reciprocal coordinates.

Raises

• ValueError — If the cell, tolerance, operation, or transformed symmetry is invalid for the requested cell basis.

reduce_kpoint_mesh_by_symmetry

def reduce_kpoint_mesh_by_symmetry(kpoint_mesh: KPointMesh, operations: Sequence[Sequence[Sequence[int | float]]], *, coordinate_atol: float = 1e-10, weight_rtol: float = 1e-12, weight_atol: float = 1e-15) -> KPointMesh

Aggregate a reduced-coordinate mesh into explicit symmetry orbits.

This function validates the mesh action but cannot prove that the supplied operations are symmetries of a particular cell, ionic structure, or Hamiltonian. Callers must establish that scientific precondition.

Parameters

Name	Type	Default	Description
kpoint_mesh	KPointMesh		Full weighted reduced-coordinate mesh.
operations	Sequence[Sequence[Sequence[int | float]]]		Integer unimodular matrices acting on reduced k-point column vectors.
coordinate_atol	float	1e-10	Absolute modulo-lattice matching tolerance.
weight_rtol	float	1e-12	Relative tolerance for symmetry-related input weights.
weight_atol	float	1e-15	Absolute tolerance for symmetry-related input weights.

Returns

• KPointMesh — Deterministic representative points with orbit-aggregated weights.

Raises

• ValueError — If inputs are invalid, duplicated, not closed under the operations, or have unequal weights inside an orbit.

run_band_structure

def run_band_structure(system: DFTSystem, scf_result: SCFResult, band_path: BandPath, *, n_bands: int = 1, xc_functional: ExchangeCorrelationFunctional | None = None, apply_nonlocal: bool | None = None) -> BandStructureResult

Evaluate non-SCF bands on top of a converged density.

Parameters

Name	Type	Default	Description
system	DFTSystem		DFT system that supplied the SCF density.
scf_result	SCFResult		Converged or diagnostic SCF result whose density is reused.
band_path	BandPath		Explicit k-point path.
n_bands	int	1	Number of eigenvalues to report at each k-point. Defaults to 1.
xc_functional	ExchangeCorrelationFunctional | None	None	Exchange-correlation functional for the fixed-density operator; None uses LDA. Defaults to None.
apply_nonlocal	bool | None	None	Whether to include ion-backed nonlocal pseudopotential projectors. None mirrors scf_result.nonlocal_applied. Defaults to None.

Returns

• BandStructureResult — Non-SCF band energies and pseudopotential diagnostics.