dft.periodic_scf

Public self-consistent and fixed-density periodic DFT entry points.

import mlx_atomistic.dft.periodic_scf

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.

The ionic, Hartree, and exchange-correlation potentials are built once from source and reused unchanged at every path point.

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 around the requested boundary.
config	PeriodicDavidsonConfig | None	None	Davidson controls. Defaults to PeriodicDavidsonConfig.
xc_functional	ExchangeCorrelationFunctional | None	None	Exchange-correlation functional. Defaults to production PBE.
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 computed bands. Fixed occupations default to half the electron count. Smearing requires enough additional bands to retain at least one partially empty state.
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.