dft.periodic_optimization

Fixed-cell ionic relaxation for the periodic plane-wave DFT runtime.

import mlx_atomistic.dft.periodic_optimization

Classes

PeriodicGeometryOptimizationConfig

class PeriodicGeometryOptimizationConfig
    def __init__(max_steps: int = 25, force_tolerance: float = 0.0005, rms_force_tolerance: float = 0.0003, displacement_tolerance: float = 0.003, initial_step_size: float = 1.0, max_step: float = 0.25, line_search_shrink: float = 0.5, line_search_min_step: float = 0.0001, max_line_search_iterations: int = 8, armijo_constant: float = 0.0001, history_size: int = 5, optimizer: PeriodicGeometryOptimizer = 'lbfgs', reuse_scf_state: bool = True, relaxation_mode: Literal['ions'] = 'ions')

Controls for periodic fixed-cell ionic relaxation.

Parameters

Name	Type	Default	Description
max_steps	int	25	Maximum accepted ionic steps.
force_tolerance	float	0.0005	Maximum per-ion force norm in Hartree/bohr.
rms_force_tolerance	float	0.0003	RMS Cartesian force in Hartree/bohr.
displacement_tolerance	float	0.003	Maximum final per-ion displacement in bohr.
initial_step_size	float	1.0	Initial inverse-Hessian scale in bohr squared/Hartree.
max_step	float	0.25	Maximum per-ion trial displacement in bohr.
line_search_shrink	float	0.5	Backtracking scale factor.
line_search_min_step	float	0.0001	Smallest inverse-Hessian scale to try.
max_line_search_iterations	int	8	Maximum SCF trials per ionic step.
armijo_constant	float	0.0001	Sufficient-decrease coefficient.
history_size	int	5	Maximum retained L-BFGS curvature pairs.
optimizer	PeriodicGeometryOptimizer	'lbfgs'	lbfgs or steepest_descent.
reuse_scf_state	bool	True	Reuse accepted density and compact eigenspaces.
relaxation_mode	Literal['ions']	'ions'	Must remain ions; cell modes fail closed.

Methods

to_dict

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

Return the canonical JSON-safe optimizer settings.

Returns

• dict[str, object]

PeriodicGeometryOptimizationResult

class PeriodicGeometryOptimizationResult
    def __init__(status: PeriodicGeometryStatus, convergence_reason: str, initial_system: PeriodicDFTSystem, final_system: PeriodicDFTSystem, final_scf: PeriodicSCFResult | None, final_force: PeriodicForceResult | None, steps: tuple[PeriodicGeometryOptimizationStep, ...], config: PeriodicGeometryOptimizationConfig, elapsed_ms: float, scf_evaluations: int, line_search_evaluations: int, continuation_density_uses: int, continuation_coefficient_uses: int, lineage: tuple[str, ...] = (), checkpoint_manifest: dict[str, object] | None = None)

Result of periodic fixed-cell ionic relaxation.

Parameters

Name	Type	Default	Description
status	PeriodicGeometryStatus
convergence_reason	str
initial_system	PeriodicDFTSystem
final_system	PeriodicDFTSystem
final_scf	PeriodicSCFResult | None
final_force	PeriodicForceResult | None
steps	tuple[PeriodicGeometryOptimizationStep, ...]
config	PeriodicGeometryOptimizationConfig
elapsed_ms	float
scf_evaluations	int
line_search_evaluations	int
continuation_density_uses	int
continuation_coefficient_uses	int
lineage	tuple[str, ...]	()
checkpoint_manifest	dict[str, object] | None	None

Properties

• converged bool — Whether every configured ionic convergence gate passed.
• final_energy float | None — Return the final periodic energy or free energy in Hartree.
• final_forces np.ndarray | None — Return final analytic periodic forces in Hartree/bohr.
• final_positions np.ndarray — Return final wrapped Cartesian positions in bohr.

Methods

to_dict

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

Return a JSON-safe summary without dense electronic arrays.

Returns

• dict[str, object]

PeriodicGeometryOptimizationStep

class PeriodicGeometryOptimizationStep
    def __init__(index: int, energy: float, energy_delta: float, armijo_limit: float, max_force: float, rms_force: float, step_norm: float, accepted_step_size: float, line_search_iterations: int, scf_iterations: int, scf_wall_ms: float, force_wall_ms: float, used_density_continuation: bool, used_coefficient_continuation: bool, positions: np.ndarray, forces: np.ndarray)

One accepted periodic ionic step.

Parameters

Name	Type	Default	Description
index	int
energy	float
energy_delta	float
armijo_limit	float
max_force	float
rms_force	float
step_norm	float
accepted_step_size	float
line_search_iterations	int
scf_iterations	int
scf_wall_ms	float
force_wall_ms	float
used_density_continuation	bool
used_coefficient_continuation	bool
positions	np.ndarray
forces	np.ndarray

Methods

to_dict

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

Return a JSON-safe accepted-step record.

Returns

• dict[str, object]

Functions

optimize_periodic_geometry

def optimize_periodic_geometry(system: PeriodicDFTSystem, *, cutoff_hartree: float, kpoint_mesh: KPointMesh, n_bands: int | None = None, config: PeriodicGeometryOptimizationConfig | None = None, scf_config: PeriodicSCFConfig | None = None, xc_functional: ExchangeCorrelationFunctional | None = None, observer: RuntimeObserver | None = None, initial_density: mx.array | None = None, initial_coefficients: Sequence[mx.array] | None = None, checkpoint_to: str | Path | None = None, checkpoint_step: int | None = None, resume_from: str | Path | None = None, provenance: Mapping[str, object] | None = None) -> PeriodicGeometryOptimizationResult

Relax ions in a fixed periodic cell using converged analytic forces.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Initial periodic GTH system.
cutoff_hartree	float		Plane-wave kinetic cutoff in Hartree.
kpoint_mesh	KPointMesh		Fixed weighted reduced-coordinate k-point mesh.
n_bands	int | None	None	Fixed computed band count.
config	PeriodicGeometryOptimizationConfig | None	None	Ionic optimizer controls.
scf_config	PeriodicSCFConfig | None	None	Exact periodic SCF controls.
xc_functional	ExchangeCorrelationFunctional | None	None	Exchange-correlation functional. Defaults to production PBE.
observer	RuntimeObserver | None	None	Optional shared runtime observer.
initial_density	mx.array | None	None	Optional density seed for the initial periodic SCF.
initial_coefficients	Sequence[mx.array] | None	None	Optional k-point orbital seeds for the initial SCF.
checkpoint_to	str | Path | None	None	Previously absent accepted-step checkpoint destination.
checkpoint_step	int | None	None	Accepted step at which to publish and stop.
resume_from	str | Path | None	None	Explicit accepted-step checkpoint to resume.
provenance	Mapping[str, object] | None	None	Optional non-identity checkpoint provenance.

Returns

• PeriodicGeometryOptimizationResult — Complete periodic optimization result and accepted-step history.

Raises

• TypeError — If the system or k-point mesh has an unsupported type.
• ValueError — If controls conflict or checkpoint settings are invalid.
• ArtifactIntegrityError — If an explicit checkpoint fails validation.