dft.periodic_scf

Self-consistent weighted k-point plane-wave DFT.

import mlx_atomistic.dft.periodic_scf

Classes

PeriodicBandPointResult

class PeriodicBandPointResult
    def __init__(requested_kpoint: KPoint, basis: PlaneWaveBasis, eigen: PeriodicEigenResult)

One fixed-density periodic eigensolve along a band path.

Parameters

Name	Type	Default	Description
requested_kpoint	KPoint		Reduced-coordinate path point requested by the caller.
basis	PlaneWaveBasis		Point-specific cutoff-projected plane-wave basis.
eigen	PeriodicEigenResult		Lowest periodic eigenpairs returned by Davidson.

Methods

to_dict

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

Return a JSON-safe point summary.

Returns

• dict[str, object]

PeriodicBandStructureResult

class PeriodicBandStructureResult
    def __init__(kpoints: tuple[KPoint, ...], eigenvalues: mx.array, residuals: mx.array, points: tuple[PeriodicBandPointResult, ...], occupied_band_count: int, cutoff_hartree: float, density_source: str, timings: dict[str, float], guard_band_count: int = 0)

Production non-self-consistent bands from one frozen periodic density.

Parameters

Name	Type	Default	Description
kpoints	tuple[KPoint, ...]		Evaluated reduced-coordinate path points.
eigenvalues	mx.array		Eigenvalues in Hartree with shape (n_kpoints, n_bands).
residuals	mx.array		Direct eigensolver residuals with the same shape.
points	tuple[PeriodicBandPointResult, ...]		Basis and compact eigenspace retained for each path point.
occupied_band_count	int		Number of doubly occupied bands in the source SCF.
cutoff_hartree	float		Plane-wave kinetic cutoff in Hartree.
density_source	str		"scf_result" or "frozen_density".
timings	dict[str, float]		Wall-clock phase timings in milliseconds.
guard_band_count	int	0	Additional unpublished states used to stabilize the requested eigenspace boundary.

Properties

• n_bands int — Return the number of bands solved at every k-point.

Methods

to_dict

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

Return JSON-safe bands without materializing orbital coefficients.

Returns

• dict[str, object]

PeriodicDFTSystem

class PeriodicDFTSystem
    def __init__(cell_lengths: Sequence[float], grid_shape: Sequence[int], positions: Sequence[Sequence[float]], pseudopotential: PseudopotentialData | None = None, electron_count: float | None = None, *, pseudopotentials: Sequence[PseudopotentialData] | None = None)

Orthorhombic periodic DFT system with per-ion GTH pseudopotentials.

Parameters

Name	Type	Default	Description
cell_lengths	Sequence[float]		Orthorhombic cell lengths in bohr.
grid_shape	Sequence[int]		FFT grid shape.
positions	Sequence[Sequence[float]]		Ionic Cartesian positions in bohr.
pseudopotential	PseudopotentialData | None	None	Shared GTH pseudopotential for every ion. Mutually exclusive with pseudopotentials.
electron_count	float | None	None	Total valence electron count. Defaults to the neutral pseudopotential charge sum.
pseudopotentials	Sequence[PseudopotentialData] | None	None	Ordered one-per-ion GTH pseudopotentials.

Properties

• charges tuple[float, ...] — Valence point charges used by the periodic Ewald term.
• fingerprint str — Stable identity of the periodic cell and per-ion Hamiltonian.
• ion_count int — Number of ions in the periodic cell.
• is_homogeneous bool — Whether every ion uses an identical pseudopotential.
• pseudopotential PseudopotentialData — Return the shared pseudopotential of a homogeneous system.
• symbols tuple[str, ...] — Element symbol assigned to every ion in position order.

PeriodicDavidsonConfig

class PeriodicDavidsonConfig
    def __init__(max_iterations: int = 30, tolerance: float = 1e-05, max_subspace_size: int = 64, preconditioner_floor: float = 0.25)

Controls for the incremental block Davidson/Rayleigh-Ritz eigensolver.

Parameters

Name	Type	Default	Description
max_iterations	int	30
tolerance	float	1e-05
max_subspace_size	int	64
preconditioner_floor	float	0.25

PeriodicEigenResult

class PeriodicEigenResult
    def __init__(eigenvalues: mx.array, coefficients: mx.array, residuals: mx.array, orthonormality_error: float, iterations: int, converged: bool, subspace_size: int, restart_count: int, *, basis: PlaneWaveBasis | None = None)

Lowest eigenspace result with compact runtime-owned coefficients.

Public construction accepts full-grid coefficients only with an explicit basis. Runtime code uses the private compact factory, so no dense fallback is retained.

Parameters

Name	Type	Default	Description
eigenvalues	mx.array		Lowest eigenvalues in Hartree.
coefficients	mx.array		Public full-grid coefficient stack.
residuals	mx.array		Direct H(X) - epsilon X norm per returned eigenpair.
orthonormality_error	float		Maximum overlap error.
iterations	int		Davidson iteration count.
converged	bool		Whether the requested tolerance was reached.
subspace_size	int		Final Davidson subspace width.
restart_count	int		Number of Davidson restarts.
basis	PlaneWaveBasis | None	None	Optional basis used to pack the public full-grid coefficient input. When omitted, the legacy eight-argument constructor stores only the input’s exact nonzero support for round-trip compatibility.

Properties

• coefficients mx.array — Materialize a fresh full-grid coefficient stack.
• is_time_reversal_view bool — Whether coefficients are an uncached time-reversed owner view.

Methods

to_dict

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

Return a JSON-safe eigensolver summary.

Returns

• dict[str, object] — Eigenvalues, residuals, convergence, and subspace diagnostics.

PeriodicFrozenDensity

class PeriodicFrozenDensity
    def __init__(density: mx.array, cutoff_hartree: float, electron_count: float, system_fingerprint: str | None = None)

Portable fixed-density input for a periodic non-SCF calculation.

Parameters

Name	Type	Default	Description
density	mx.array		Converged electron density on system.grid.
cutoff_hartree	float		Plane-wave kinetic cutoff used by the source SCF.
electron_count	float		Electron count represented by the density.
system_fingerprint	str | None	None	Optional source-system identity. Required when the density is reused for a multi-element calculation.

PeriodicKPointResult

class PeriodicKPointResult
    def __init__(reduced_kpoint: tuple[float, float, float], weight: float, basis: PlaneWaveBasis, eigen: PeriodicEigenResult, explicit_index: int | None = None, aggregated_weight: float | None = None, ownership_role: str = 'independent', fallback_reason: str | None = None)

One weighted k-point result in a periodic SCF calculation.

Parameters

Name	Type	Default	Description
reduced_kpoint	tuple[float, float, float]
weight	float
basis	PlaneWaveBasis
eigen	PeriodicEigenResult
explicit_index	int | None	None
aggregated_weight	float | None	None
ownership_role	str	'independent'
fallback_reason	str | None	None

Properties

• integration_weight float — Return the owner-aggregated or original integration weight.

Methods

to_dict

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

Return a JSON-safe k-point summary.

Returns

• dict[str, object] — Reduced k-point, weight, basis metadata, and eigensolver summary.

PeriodicKohnShamOperator

class PeriodicKohnShamOperator
    def __init__(basis: PlaneWaveBasis, effective_local_potential: mx.array, nonlocal_operator: PeriodicGTHNonlocalOperator | None = None, observer: RuntimeObserver | None = None)

Fixed-density periodic Kohn-Sham operator in coefficient space.

Parameters

Name	Type	Default	Description
basis	PlaneWaveBasis
effective_local_potential	mx.array
nonlocal_operator	PeriodicGTHNonlocalOperator | None	None
observer	RuntimeObserver | None	None

Properties

• effective_local_potential mx.array — Return a fresh caller-owned copy of the fixed local potential.

Methods

apply

def apply(coefficients: mx.array, *, observer: RuntimeObserver | None = None) -> mx.array

Apply kinetic, local, and optional nonlocal terms.

Parameters

Name	Type	Default	Description
coefficients	mx.array		One coefficient grid or an orbital stack.
observer	RuntimeObserver | None	None	Optional observer overriding an absent operator observer.

Returns

• mx.array — Hamiltonian action with matching shape.

rayleigh_quotients

def rayleigh_quotients(coefficients: mx.array, *, observer: RuntimeObserver | None = None) -> mx.array

Return one Rayleigh quotient per orbital.

Parameters

Name	Type	Default	Description
coefficients	mx.array		Orbital stack in coefficient space.
observer	RuntimeObserver | None	None	Optional runtime observer.

Returns

• mx.array — Real energy estimates in Hartree.

PeriodicSCFConfig

class PeriodicSCFConfig
    def __init__(max_iterations: int = 40, density_tolerance: float = 1e-05, energy_tolerance: float = 1e-06, orbital_tolerance: float = 1e-05, min_iterations: int = 2, mixing_beta: float = 0.35, mixer: str = 'diis', davidson: PeriodicDavidsonConfig = PeriodicDavidsonConfig(), kpoint_batch_size: int = 8, max_batch_padding_fraction: float = _CompactBatch._DEFAULT_MAX_PADDING_FRACTION, max_batch_transient_bytes: int = _CompactBatch._DEFAULT_MAX_TRANSIENT_BYTES, hpsi_shape_policy: str = 'finite-buckets', adaptive_eigensolver_tolerance: bool = False, initial_eigensolver_tolerance: float = 0.01, eigensolver_tolerance_scale: float = 0.1)

Controls for weighted k-point self-consistent field iteration.

Parameters

Name	Type	Default	Description
max_iterations	int	40
density_tolerance	float	1e-05
energy_tolerance	float	1e-06
orbital_tolerance	float	1e-05
min_iterations	int	2
mixing_beta	float	0.35
mixer	str	'diis'
davidson	PeriodicDavidsonConfig	PeriodicDavidsonConfig()
kpoint_batch_size	int	8
max_batch_padding_fraction	float	_CompactBatch._DEFAULT_MAX_PADDING_FRACTION
max_batch_transient_bytes	int	_CompactBatch._DEFAULT_MAX_TRANSIENT_BYTES
hpsi_shape_policy	str	'finite-buckets'
adaptive_eigensolver_tolerance	bool	False
initial_eigensolver_tolerance	float	0.01
eigensolver_tolerance_scale	float	0.1

Methods

batch_policy

def batch_policy() -> dict[str, int | float | str | list[int]]

Return the exact bounded compact-batch policy.

Returns

• dict[str, int | float | str | list[int]]

PeriodicSCFResult

class PeriodicSCFResult
    def __init__(converged: bool, status: str, iterations: int, total_energy: float, electron_count: float, density_residual: float, energy_delta: float | None, density: mx.array, kpoints: tuple[PeriodicKPointResult, ...], energy_by_term: dict[str, float], history: tuple[dict[str, float | int | str | None], ...], timings: dict[str, float], time_reversal_ownership: TimeReversalOwnership | None = None, batch_policy: dict[str, int | float | str | list[int]] = dict(), numerical_status: str = 'not_evaluated', resume_integrity_status: str = 'fresh', timing_admission_status: str = 'fresh', lineage: tuple[str, ...] = (), system_fingerprint: str | None = None, _owned_kpoints: tuple[PeriodicKPointResult, ...] | None = None, _checkpoint_state: _PeriodicSCFContinuationState | None = None, _artifact_execution_contract_fingerprint: str | None = None, _artifact_calculation_fingerprint: str | None = None)

Result bundle for a weighted periodic plane-wave SCF calculation.

Parameters

Name	Type	Default	Description
converged	bool
status	str
iterations	int
total_energy	float
electron_count	float
density_residual	float
energy_delta	float | None
density	mx.array
kpoints	tuple[PeriodicKPointResult, ...]
energy_by_term	dict[str, float]
history	tuple[dict[str, float | int | str | None], ...]
timings	dict[str, float]
time_reversal_ownership	TimeReversalOwnership | None	None
batch_policy	dict[str, int | float | str | list[int]]	dict()
numerical_status	str	'not_evaluated'
resume_integrity_status	str	'fresh'
timing_admission_status	str	'fresh'
lineage	tuple[str, ...]	()
system_fingerprint	str | None	None
_owned_kpoints	tuple[PeriodicKPointResult, ...] | None	None
_checkpoint_state	_PeriodicSCFContinuationState | None	None
_artifact_execution_contract_fingerprint	str | None	None
_artifact_calculation_fingerprint	str | None	None

Properties

• continuation_coefficients tuple[object, ...] — Return an explicit owner-aware initial-coefficient sequence.
• owned_kpoints tuple[PeriodicKPointResult, ...] — Return the compact-state-owning k-point results.

Methods

to_dict

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

Return a JSON-safe periodic SCF summary.

Returns

• dict[str, object] — Convergence, energy, k-point, history, and timing diagnostics without
• dict[str, object] — dense orbital or density payloads.

Functions

run_periodic_band_structure

def run_periodic_band_structure(system: PeriodicDFTSystem, source: PeriodicSCFResult | PeriodicFrozenDensity, band_path: BandPath, *, n_bands: int | None = None, guard_bands: int = 0, config: PeriodicDavidsonConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None, observer: RuntimeObserver | None = None) -> PeriodicBandStructureResult

Solve production periodic bands on top of a converged frozen density.

This is a non-self-consistent calculation: the ionic, Hartree, and exchange-correlation potentials are built once from source and reused unchanged at every path point. Each k-point still receives its own cutoff-projected plane-wave basis and complete local plus nonlocal GTH Hamiltonian.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Periodic GTH system matching the source SCF calculation.
source	PeriodicSCFResult | PeriodicFrozenDensity		Converged periodic SCF result or validated portable density.
band_path	BandPath		Explicit reduced-coordinate k-point path.
n_bands	int | None	None	Lowest bands to return. Defaults to occupied bands plus eight.
guard_bands	int	0	Extra unpublished states used to contain degeneracies at the requested eigenspace boundary. Defaults to zero.
config	PeriodicDavidsonConfig | None	None	Davidson controls. Defaults to PeriodicDavidsonConfig.
xc_functional	ExchangeCorrelationFunctional | None	None	Exchange-correlation functional. Defaults to production PBE, matching run_periodic_scf.
observer	RuntimeObserver | None	None	Optional progress and work observer.

Returns

• PeriodicBandStructureResult — Fixed-density band energies, residuals, bases, and compact eigenstates.

Raises

• RuntimeError — If a path-point Davidson solve does not converge.
• TypeError — If source has an unsupported type.
• ValueError — If source, path, density, or band metadata are inconsistent.

run_periodic_scf

def run_periodic_scf(system: PeriodicDFTSystem, *, cutoff_hartree: float, kpoint_mesh: KPointMesh, n_bands: int | None = None, config: PeriodicSCFConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None, initial_density: mx.array | None = None, initial_coefficients: Sequence[mx.array] | None = None, observer: RuntimeObserver | None = None) -> PeriodicSCFResult

Run weighted self-consistent periodic plane-wave DFT.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Periodic GTH system.
cutoff_hartree	float		Kinetic cutoff in Hartree.
kpoint_mesh	KPointMesh		Weighted reduced-coordinate k-point mesh.
n_bands	int | None	None	Number of occupied bands. Defaults to half the electron count.
config	PeriodicSCFConfig | None	None	SCF controls. Defaults to PeriodicSCFConfig.
xc_functional	ExchangeCorrelationFunctional | None	None	Exchange-correlation functional. Defaults to production PBE.
initial_density	mx.array | None	None	Optional starting density on the FFT grid.
initial_coefficients	Sequence[mx.array] | None	None	Optional orbital stack per k-point.
observer	RuntimeObserver | None	None	Optional progress, synchronized timing, and work observer.

Returns

• PeriodicSCFResult — Periodic SCF result with complete weighted k-point diagnostics.

solve_periodic_eigenproblem

def solve_periodic_eigenproblem(operator: PeriodicKohnShamOperator, *, n_bands: int, config: PeriodicDavidsonConfig | None = None, initial_coefficients: mx.array | None = None, observer: RuntimeObserver | None = None) -> PeriodicEigenResult

Solve the lowest periodic eigenpairs with block Davidson/Rayleigh-Ritz.

Parameters

Name	Type	Default	Description
operator	PeriodicKohnShamOperator		Fixed-density periodic Kohn-Sham operator.
n_bands	int		Number of lowest states to return.
config	PeriodicDavidsonConfig | None	None	Davidson controls. Defaults to PeriodicDavidsonConfig.
initial_coefficients	mx.array | None	None	Optional initial orbital stack. Defaults to the lowest kinetic plane waves.
observer	RuntimeObserver | None	None	Optional progress and work observer. Defaults to the observer carried by operator.

Returns

• PeriodicEigenResult — Converged or exhausted result sealed by direct final residuals.