airsspy.jf.ml_runners

ML interatomic potential runners.

Two backends:

• torchsim (preferred): GPU-accelerated batch processing via torch_sim. Handles all structures in a single batch for maximum throughput.

• ASE (fallback): Uses any ASE-compatible calculator with ASE optimizers. Processes structures one at a time; works without torchsim.

The torch_sim package is an optional dependency (pip install airsspy[ml]). When unavailable, the ASE fallback is used automatically.

Model specification format (torchsim)::

backend:model_id

For example mace:medium, mace:/path/to/model.pt, sevennet:sevennet-mf-ompa.

ASE calculator specification format::

module.path:ClassName@model

For example mace.calculators:MACECalculator@medium.

Module Contents

Classes

AirssMlSinglePointRunner	Run a single-point energy/forces/stress calculation using an ASE calculator.
AirssMlRelaxRunner	Run geometry optimisation using an ASE calculator and ASE optimizer.
TorchSimRunner	Reusable torch-sim model context for chunked ML runs.

Functions

compose_ml_task_doc	Extract results from a completed ML calculation.
has_torchsim	Check whether torch_sim is importable.

Data

logger
EV_PER_ANG3_TO_GPA
StructureInput

API

airsspy.jf.ml_runners.logger

‘getLogger(…)’

airsspy.jf.ml_runners.EV_PER_ANG3_TO_GPA

160.21766208

airsspy.jf.ml_runners.StructureInput

None

class airsspy.jf.ml_runners.AirssMlSinglePointRunner(calculator_spec: str, calculator_kwargs: Optional[dict] = None)

Run a single-point energy/forces/stress calculation using an ASE calculator.

Initialization

clean_failed(struct_name: str) → None

run(struct_name: str, structure_input: airsspy.jf.ml_runners.StructureInput) → int

Attach calculator, compute energy/forces/stress, save results.

Args: struct_name: Structure name (without extension). structure_input: Content of a .cell file or an ASE Atoms object.

Returns: 0 on success, 1 on failure.

class airsspy.jf.ml_runners.AirssMlRelaxRunner(calculator_spec: str, calculator_kwargs: Optional[dict] = None, optimizer: str = 'FIRE', fmax: float = 0.05, max_steps: int = 500, pressure: float = 0.0)

Run geometry optimisation using an ASE calculator and ASE optimizer.

Initialization

clean_failed(struct_name: str) → None

run(struct_name: str, structure_input: airsspy.jf.ml_runners.StructureInput) → int

Attach calculator, run ASE optimizer, save results.

Args: struct_name: Structure name (without extension). structure_input: Content of a .cell file or an ASE Atoms object.

Returns: 0 if converged, 1 if not converged or failed.

airsspy.jf.ml_runners.compose_ml_task_doc(struct_name: str, calculator_spec: str = '') → dict

Extract results from a completed ML calculation.

Reads the .extxyz output file (with SinglePointCalculator attached), creates an ASE Atoms object, writes a .res file, and returns a dictionary suitable for constructing an AirssResultDoc.

Args: struct_name: Structure name (without extension). calculator_spec: The calculator spec string (for REM metadata).

Returns: Dictionary with energy, structure, volume, formula, etc.

airsspy.jf.ml_runners.has_torchsim() → bool

Check whether torch_sim is importable.

class airsspy.jf.ml_runners.TorchSimRunner(model_spec: str, *, device: Optional[str] = None)

Reusable torch-sim model context for chunked ML runs.

Initialization

relax_batch(struct_names: list[str], structures: list[airsspy.jf.ml_runners.StructureInput], *, max_steps: int = 300, force_tol: float = 0.05, optimizer: str = 'fire', cell_filter: str = 'frechet', convergence_mode: str = 'force_stress', scalar_pressure: float = 0.0) → dict[str, int]

Relax one batch of structures using the loaded model.

static_batch(struct_names: list[str], structures: list[airsspy.jf.ml_runners.StructureInput]) → dict[str, int]

Run one static batch using the loaded model.