artifacts

Strict loaders for prepared MLX molecular mechanics artifacts.

import mlx_atomistic.artifacts

Classes

MLXCompatibilityError

class MLXCompatibilityError(ValueError)

Raised when a prepared artifact cannot be run faithfully by MLX.

PreparedMLXArtifact

class PreparedMLXArtifact
    def __init__(base_dir: Path, metadata: dict[str, Any], arrays: dict[str, np.ndarray], unit_system: MDUnitSystem | None)

Loaded prepared-system arrays plus validated production metadata.

Parameters

Name	Type	Default	Description
base_dir	Path
metadata	dict[str, Any]
arrays	dict[str, np.ndarray]
unit_system	MDUnitSystem | None

Properties

• atom_count int — Number of atoms in the prepared system.
• cell Cell | None — Periodic cell reconstructed from the artifact arrays, or None if aperiodic.
• hmr_state dict[str, Any] — Return serialized HMR state without treating it as a force term.

Functions

artifact_readiness_report

def artifact_readiness_report(metadata: dict[str, Any], *, require_production: bool = False, arrays: dict[str, np.ndarray] | None = None) -> ReadinessReport

Return the artifact compatibility gate as a shared readiness report.

Parameters

Name	Type	Default	Description
metadata	dict[str, Any]
require_production	bool	False
arrays	dict[str, np.ndarray] | None	None

Returns

• ReadinessReport

build_mlx_system_from_artifact

def build_mlx_system_from_artifact(artifact: PreparedMLXArtifact, *, restraint_k: float = 0.0, constraint_max_iterations: int = 20, eager_nonbonded_pair_limit: int | None = DEFAULT_EAGER_NONBONDED_PAIR_LIMIT) -> tuple[MMSystem, list, DistanceConstraints | None]

Convert a prepared artifact into MMSystem, force terms, and constraints.

Parameters

Name	Type	Default	Description
artifact	PreparedMLXArtifact
restraint_k	float	0.0
constraint_max_iterations	int	20
eager_nonbonded_pair_limit	int | None	DEFAULT_EAGER_NONBONDED_PAIR_LIMIT

Returns

• tuple[MMSystem, list, DistanceConstraints | None]

load_prepared_mlx_artifact

def load_prepared_mlx_artifact(path: str | Path, *, require_production: bool = False) -> PreparedMLXArtifact

Load and validate a prepared MLX artifact directory or JSON path.

Parameters

Name	Type	Default	Description
path	str | Path
require_production	bool	False

Returns

• PreparedMLXArtifact

validate_mlx_compatibility

def validate_mlx_compatibility(metadata: dict[str, Any], *, require_production: bool = False, arrays: dict[str, np.ndarray] | None = None) -> MDUnitSystem | None

Validate fail-closed compatibility metadata for MLX execution.

Parameters

Name	Type	Default	Description
metadata	dict[str, Any]
require_production	bool	False
arrays	dict[str, np.ndarray] | None	None

Returns

• MDUnitSystem | None