dft.periodic_forces

Analytic fixed-cell forces for converged periodic plane-wave DFT.

import mlx_atomistic.dft.periodic_forces

Classes

PeriodicForceResult

class PeriodicForceResult
    def __init__(forces: mx.array, local: mx.array, nonlocal_force: mx.array, ion_ewald: mx.array, timings: dict[str, float], provenance: dict[str, str])

Hellmann—Feynman force decomposition at a converged SCF state.

Parameters

Name	Type	Default	Description
forces	mx.array		Total ionic forces in Hartree/bohr.
local	mx.array		Local GTH electron-ion contribution.
nonlocal_force	mx.array		Nonlocal GTH projector contribution.
ion_ewald	mx.array		Periodic ion-ion Ewald contribution.
timings	dict[str, float]		Wall-clock phase timings in milliseconds.
provenance	dict[str, str]		Method and stationarity metadata.

Properties

• max_force float — Return the largest ionic force norm in Hartree/bohr.
• net_force tuple[float, float, float] — Return the translational force residual in Hartree/bohr.

Methods

to_dict

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

Return a JSON-safe force decomposition.

Returns

• dict[str, object]

Functions

periodic_scf_forces

def periodic_scf_forces(system: PeriodicDFTSystem, result: PeriodicSCFResult, *, ewald_tolerance: float = 1e-10) -> PeriodicForceResult

Evaluate fixed-cell periodic forces from a converged SCF result.

The local and nonlocal electron-ion terms use analytic derivatives of the GTH phase factors. The ion-ion term uses the analytic Ewald derivative. There is no ionic Pulay term because the fixed-cell plane-wave basis does not depend on ion positions.

Parameters

Name	Type	Default	Description
system	PeriodicDFTSystem		Exact periodic system used for the SCF calculation.
result	PeriodicSCFResult		Converged periodic SCF result retaining compact occupied states.
ewald_tolerance	float	1e-10	Real/reciprocal Ewald truncation target. Defaults to 1e-10.

Returns

• PeriodicForceResult — Total forces, component forces, timings, and provenance.

Raises

• TypeError — If system or result has an unsupported type.
• ValueError — If the SCF state is unconverged, mismatched, incomplete, or non-finite.