validation

Validation helpers for force terms and MD diagnostics.

import mlx_atomistic.validation

Classes

ForceValidationCase

class ForceValidationCase
    def __init__(name: str, term: ForceTerm, positions: object, seed: int, epsilon: float = 0.001, tolerance: float = 0.005, cell: Cell | None = None, pairs: object | None = None)

One finite-difference force validation case.

Parameters

Name	Type	Default	Description
name	str
term	ForceTerm
positions	object
seed	int
epsilon	float	0.001
tolerance	float	0.005
cell	Cell | None	None
pairs	object | None	None

ForceValidationResult

class ForceValidationResult
    def __init__(case_name: str, term_name: str, seed: int, atom_count: int, coordinate_count: int, epsilon: float, tolerance: float, energy: float, max_abs_error: float, rms_abs_error: float, max_force_abs: float, failing_atom: int, failing_axis: int, finite: bool, passed: bool)

Finite-difference force validation result.

Parameters

Name	Type	Default	Description
case_name	str
term_name	str
seed	int
atom_count	int
coordinate_count	int
epsilon	float
tolerance	float
energy	float
max_abs_error	float
rms_abs_error	float
max_force_abs	float
failing_atom	int
failing_axis	int
finite	bool
passed	bool

Methods

to_dict

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

Return a JSON- and CSV-friendly representation.

Returns

• dict[str, Any]

PlatformValidationEvidence

class PlatformValidationEvidence
    def __init__(name: str, status: str, fixture: str, product_runtime: str, runtime: dict[str, Any], platform_sections: tuple[str, ...], acceptance_criteria: tuple[str, ...], gap_ids: tuple[str, ...], finite_outputs: bool, reference_engine: str | None = None, reference_role: str | None = None, readiness: dict[str, Any] | None = None, metrics: dict[str, Any] | None = None)

Traceable platform proof or reference-validation evidence.

Parameters

Name	Type	Default	Description
name	str
status	str
fixture	str
product_runtime	str
runtime	dict[str, Any]
platform_sections	tuple[str, ...]
acceptance_criteria	tuple[str, ...]
gap_ids	tuple[str, ...]
finite_outputs	bool
reference_engine	str | None	None
reference_role	str | None	None
readiness	dict[str, Any] | None	None
metrics	dict[str, Any] | None	None

Methods

to_dict

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

Return a JSON-safe evidence payload.

Returns

• dict[str, Any]

Functions

build_platform_validation_evidence

def build_platform_validation_evidence(*, name: str, status: str, fixture: str, acceptance_criteria: Iterable[str], gap_ids: Iterable[str], finite_outputs: bool, reference_engine: str | None = None, reference_role: str | None = None, readiness: Mapping[str, Any] | None = None, metrics: Mapping[str, Any] | None = None) -> PlatformValidationEvidence

Bind a proof or reference-validation result to the platform boundary.

Parameters

Name	Type	Default	Description
name	str
status	str
fixture	str
acceptance_criteria	Iterable[str]
gap_ids	Iterable[str]
finite_outputs	bool
reference_engine	str | None	None
reference_role	str | None	None
readiness	Mapping[str, Any] | None	None
metrics	Mapping[str, Any] | None	None

Returns

• PlatformValidationEvidence

default_force_validation_cases

def default_force_validation_cases(*, seed: int = 7, cases_per_term: int = 1, epsilon: float = 0.001, tolerance: float = 0.005) -> tuple[ForceValidationCase, ...]

Return seeded force-validation cases for the currently supported terms.

Parameters

Name	Type	Default	Description
seed	int	7
cases_per_term	int	1
epsilon	float	0.001
tolerance	float	0.005

Returns

• tuple[ForceValidationCase, ...]

run_force_validation_suite

def run_force_validation_suite(cases: Iterable[ForceValidationCase] | None = None, *, seed: int = 7, cases_per_term: int = 1, epsilon: float = 0.001, tolerance: float = 0.005) -> tuple[ForceValidationResult, ...]

Run a seeded finite-difference force-validation suite.

Parameters

Name	Type	Default	Description
cases	Iterable[ForceValidationCase] | None	None
seed	int	7
cases_per_term	int	1
epsilon	float	0.001
tolerance	float	0.005

Returns

• tuple[ForceValidationResult, ...]

summarize_validation_results

def summarize_validation_results(results: Iterable[ForceValidationResult]) -> dict[str, Any]

Summarize force-validation results for CLIs and notebooks.

Parameters

Name	Type	Default	Description
results	Iterable[ForceValidationResult]

Returns

• dict[str, Any]

validate_force_term

def validate_force_term(term: ForceTerm, positions, *, case_name: str | None = None, seed: int = 0, epsilon: float = 0.001, tolerance: float = 0.005, cell: Cell | None = None, pairs: object | None = None) -> ForceValidationResult

Compare analytic/autodiff forces against central finite differences.

Parameters

Name	Type	Default	Description
term	ForceTerm
positions
case_name	str | None	None
seed	int	0
epsilon	float	0.001
tolerance	float	0.005
cell	Cell | None	None
pairs	object | None	None

Returns

• ForceValidationResult