dft.scf

Spin-unpolarized Γ-point plane-wave SCF driver.

import mlx_atomistic.dft.scf

Classes

`SCFConfig`

class SCFConfig
    def __init__(max_iterations: int = 25, tolerance: float = 1e-05, mixing: float = 0.35, step_size: float = 0.15, solver: SCFSolver = 'auto', max_dense_grid_points: int = 512, seed: int = 0, density_floor: float = 1e-12, mixer: SCFMixer | LinearMixer | PulayDIISMixer = 'linear', convergence_mode: SCFConvergenceMode = 'density', min_iterations: int = 1, record_timing: bool = True, potential_tolerance: float | None = None, orbital_tolerance: float | None = None, max_density_residual: float | None = 1000000.0, max_orthonormality_error: float = 0.001, apply_nonlocal: bool = True, eigensolver_config: EigensolverConfig = EigensolverConfig())

Configuration for the toy SCF driver.

Parameters

Name	Type	Default
`max_iterations`	`int`	`25`
`tolerance`	`float`	`1e-05`
`mixing`	`float`	`0.35`
`step_size`	`float`	`0.15`
`solver`	`SCFSolver`	`'auto'`
`max_dense_grid_points`	`int`	`512`
`seed`	`int`	`0`
`density_floor`	`float`	`1e-12`
`mixer`	`SCFMixer \| LinearMixer \| PulayDIISMixer`	`'linear'`
`convergence_mode`	`SCFConvergenceMode`	`'density'`
`min_iterations`	`int`	`1`
`record_timing`	`bool`	`True`
`potential_tolerance`	`float \| None`	`None`
`orbital_tolerance`	`float \| None`	`None`
`max_density_residual`	`float \| None`	`1000000.0`
`max_orthonormality_error`	`float`	`0.001`
`apply_nonlocal`	`bool`	`True`
`eigensolver_config`	`EigensolverConfig`	`EigensolverConfig()`

`SCFResult`

class SCFResult
    def __init__(converged: bool, iterations: int, solver: str, fft_backend: str, electron_count: float, total_energy: float, residual: float, density: mx.array, orbitals: mx.array, effective_potential: mx.array, energy_by_term: dict[str, float], history: list[dict[str, float | int | str | None]], status: str, convergence_reason: str, failure_reason: str | None, timings: dict[str, float], forces: mx.array | None = None, mixer_metadata: dict | None = None, orbital_eigenvalues: mx.array | None = None, orbital_residuals: mx.array | None = None, orthonormality_error: float = 0.0, electronic_energy: float | None = None, center_center_energy: float = 0.0, force_consistency: dict | None = None, pseudopotential_format: str | None = None, ion_count: int | None = None, valence_electron_count: float | None = None, nonlocal_available: bool = False, nonlocal_applied: bool = False, nonlocal_projector_count: int = 0, force_provenance: dict | None = None, solver_metadata: dict | None = None)

Result bundle for a toy DFT SCF calculation.

Parameters

Name	Type	Default
`converged`	`bool`
`iterations`	`int`
`solver`	`str`
`fft_backend`	`str`
`electron_count`	`float`
`total_energy`	`float`
`residual`	`float`
`density`	`mx.array`
`orbitals`	`mx.array`
`effective_potential`	`mx.array`
`energy_by_term`	`dict[str, float]`
`history`	`list[dict[str, float \| int \| str \| None]]`
`status`	`str`
`convergence_reason`	`str`
`failure_reason`	`str \| None`
`timings`	`dict[str, float]`
`forces`	`mx.array \| None`	`None`
`mixer_metadata`	`dict \| None`	`None`
`orbital_eigenvalues`	`mx.array \| None`	`None`
`orbital_residuals`	`mx.array \| None`	`None`
`orthonormality_error`	`float`	`0.0`
`electronic_energy`	`float \| None`	`None`
`center_center_energy`	`float`	`0.0`
`force_consistency`	`dict \| None`	`None`
`pseudopotential_format`	`str \| None`	`None`
`ion_count`	`int \| None`	`None`
`valence_electron_count`	`float \| None`	`None`
`nonlocal_available`	`bool`	`False`
`nonlocal_applied`	`bool`	`False`
`nonlocal_projector_count`	`int`	`0`
`force_provenance`	`dict \| None`	`None`
`solver_metadata`	`dict \| None`	`None`

Methods

`to_dict`

def to_dict() -> dict

Return a JSON-safe summary without dense array payloads.

Returns

dict — A JSON-serializable dict of the scalar results, energy terms, history, and timings (dense arrays such as the density are reduced to shapes/lists).

Functions

`run_scf`

def run_scf(system_or_grid: DFTSystem | RealSpaceGrid, local_potential: LocalGaussianPseudopotential | LocalPseudopotentialField | mx.array | Sequence[float] | None = None, *, electron_count: float | None = None, n_orbitals: int | None = None, config: SCFConfig | None = None, initial_orbitals: mx.array | None = None, initial_density: mx.array | None = None, xc_functional: ExchangeCorrelationFunctional | None = None) -> SCFResult

Run a minimal spin-unpolarized Γ-point SCF calculation.

Parameters

Name	Type	Default	Description
`system_or_grid`	`DFTSystem \| RealSpaceGrid`		Either a `DFTSystem` (carrying grid, ions, and electron count) or a bare `RealSpaceGrid`.
`local_potential`	`LocalGaussianPseudopotential \| LocalPseudopotentialField \| mx.array \| Sequence[float] \| None`	`None`	External local potential — a Gaussian/field pseudopotential, a grid array, or `None` when supplied by `system_or_grid`. Defaults to `None`.
`electron_count`	`float \| None`	`None`	Total electron count; `None` takes it from the system. Defaults to `None`.
`n_orbitals`	`int \| None`	`None`	Number of orbitals to solve; `None` derives it from the electron count. Defaults to `None`.
`config`	`SCFConfig \| None`	`None`	SCF controls (max iterations, tolerances, mixer, solver); `None` uses defaults. Defaults to `None`.
`initial_orbitals`	`mx.array \| None`	`None`	Optional starting orbitals; `None` uses a deterministic guess. Defaults to `None`.
`initial_density`	`mx.array \| None`	`None`	Optional starting density; `None` builds it from the initial orbitals. Defaults to `None`.
`xc_functional`	`ExchangeCorrelationFunctional \| None`	`None`	Exchange-correlation functional; `None` uses `LDAExchangeCorrelation`. Defaults to `None`.

Returns

SCFResult — An SCFResult with the converged density, orbitals, energy decomposition, and convergence/timing diagnostics.