dft.periodic_convergence

Axis-agnostic convergence reports for periodic DFT calculations.

import mlx_atomistic.dft.periodic_convergence

Classes

PeriodicConvergenceCriterion

class PeriodicConvergenceCriterion
    def __init__(observable: str, absolute_tolerance: float, relative_tolerance: float = 0.0)

Tolerance for one named scalar observable.

Parameters

Name	Type	Default	Description
observable	str		Observable key shared by both calculation points.
absolute_tolerance	float		Non-negative tolerance in the observable’s unit.
relative_tolerance	float	0.0	Non-negative fractional tolerance. Defaults to zero.

Methods

to_dict

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

Return the criterion as JSON-safe metadata.

Returns

• dict[str, object]

PeriodicConvergenceMetric

class PeriodicConvergenceMetric
    def __init__(observable: str, baseline_value: float, check_value: float, signed_difference: float, absolute_difference: float, relative_difference: float, allowed_difference: float, absolute_tolerance: float, relative_tolerance: float, passed: bool)

Evaluated convergence status for one scalar observable.

Parameters

Name	Type	Default	Description
observable	str
baseline_value	float
check_value	float
signed_difference	float
absolute_difference	float
relative_difference	float
allowed_difference	float
absolute_tolerance	float
relative_tolerance	float
passed	bool

Methods

to_dict

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

Return the evaluated metric as JSON-safe metadata.

Returns

• dict[str, object]

PeriodicConvergencePoint

class PeriodicConvergencePoint
    def __init__(parameter_value: float | tuple[float, ...], calculation_fingerprint: str, source_fingerprint: str, runtime_fingerprint: str, observables: Mapping[str, float])

One source-bound periodic calculation in a convergence comparison.

Parameters

Name	Type	Default	Description
parameter_value	float | tuple[float, ...]		Scalar or one-dimensional numerical axis value.
calculation_fingerprint	str		Exact calculation-contract SHA-256 identity.
source_fingerprint	str		Exact source/resource SHA-256 identity.
runtime_fingerprint	str		Exact runtime/environment SHA-256 identity.
observables	Mapping[str, float]		Named finite scalar values from the calculation.

Methods

to_dict

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

Return the source-bound point as JSON-safe metadata.

Returns

• dict[str, object]

PeriodicConvergenceReport

class PeriodicConvergenceReport
    def __init__(axis: str, baseline: PeriodicConvergencePoint, check: PeriodicConvergencePoint, metrics: tuple[PeriodicConvergenceMetric, ...], passed: bool)

Reusable comparison of two exact periodic calculation identities.

Parameters

Name	Type	Default	Description
axis	str
baseline	PeriodicConvergencePoint
check	PeriodicConvergencePoint
metrics	tuple[PeriodicConvergenceMetric, ...]
passed	bool

Methods

to_dict

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

Return the complete convergence report as JSON-safe metadata.

Returns

• dict[str, object]

Functions

compare_periodic_convergence

def compare_periodic_convergence(axis: str, baseline: PeriodicConvergencePoint, check: PeriodicConvergencePoint, criteria: Sequence[PeriodicConvergenceCriterion]) -> PeriodicConvergenceReport

Compare two source-bound periodic calculations on any numerical axis.

Parameters

Name	Type	Default	Description
axis	str		Non-empty numerical-axis label such as cutoff_hartree.
baseline	PeriodicConvergencePoint		Selected production or lower-resolution calculation.
check	PeriodicConvergencePoint		Independent refined calculation.
criteria	Sequence[PeriodicConvergenceCriterion]		Unique observable tolerances to evaluate.

Returns

• PeriodicConvergenceReport — Per-observable differences and aggregate pass/fail status.

Raises

• TypeError — If points or criteria use unsupported types.
• ValueError — If identities, the axis, criteria, or observables are invalid.