Stability¶

class mlipaudit.benchmarks.stability.stability.StabilityBenchmark(force_field: ForceField | Calculator, data_input_dir: str | PathLike = './data', run_mode: RunMode | Literal['dev', 'fast', 'standard'] = RunMode.STANDARD)¶

Benchmark for running stability tests.

name¶

The unique benchmark name that should be used to run the benchmark from the CLI and that will determine the output folder name for the result file. The name is stability.

Type:: str

category¶

A string that describes the category of the benchmark, used for example, in the UI app for grouping. Default, if not overridden, is “General”. This benchmark’s category matches the default (“General”).

Type:: str

result_class¶

A reference to the type of BenchmarkResult that will determine the return type of self.analyze(). The result class type is StabilityResult.

Type:: type[mlipaudit.benchmark.BenchmarkResult] | None

model_output_class¶

A reference to the StabilityModelOutput class.

Type:: type[mlipaudit.benchmark.ModelOutput] | None

required_elements¶

The set of atomic element types that are present in the benchmark’s input files.

Type:: set[str] | None

skip_if_elements_missing¶

Whether the benchmark should be skipped entirely if there are some atomic element types that the model cannot handle. If False, the benchmark must have its own custom logic to handle missing atomic element types. For this benchmark, the attribute is set to True.

Type:: bool

__init__(force_field: ForceField | Calculator, data_input_dir: str | PathLike = './data', run_mode: RunMode | Literal['dev', 'fast', 'standard'] = RunMode.STANDARD) → None¶

Initializes the benchmark.

Parameters:

force_field – The force field model to be benchmarked.
data_input_dir – The local input data directory. Defaults to “./data”. If the subdirectory “{data_input_dir}/{benchmark_name}” exists, the benchmark expects the relevant data to be in there, otherwise it will download it from HuggingFace.
run_mode – Whether to run the standard benchmark length, a faster version, or a very fast development version. Subclasses should ensure that when RunMode.DEV, their benchmark runs in a much shorter timeframe, by running on a reduced number of test cases, for instance. Implementing RunMode.FAST being different from RunMode.STANDARD is optional and only recommended for very long-running benchmarks. This argument can also be passed as a string “dev”, “fast”, or “standard”.

Raises:

ChemicalElementsMissingError – If initialization is attempted with a force field that cannot perform inference on the required elements.
ValueError – If force field type is not compatible.

run_model() → None¶

Run MD for each structure.

The simulation results are stored in the model_output attribute.

analyze() → StabilityResult¶

Checks whether the trajectories exploded.

Loads the trajectory from the simulation state and first checks whether the trajectory exploded. If not, then loads in the corresponding pdb file to access bond information and checks whether hydrogens are drifting.

Returns:: A StabilityResult object with the benchmark results.
Raises:: RuntimeError – If called before run_model().

class mlipaudit.benchmarks.stability.stability.StabilityResult(*, failed: bool = False, score: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, structure_results: list[StabilityStructureResult])¶

Result object for the stability benchmark.

structure_results¶

A list of individual results per structure.

Type:: list[mlipaudit.benchmarks.stability.stability.StabilityStructureResult]

failed¶

Whether all the simulations failed and no analysis could be performed. Defaults to False.

Type:: bool

score¶

The final score for the benchmark between 0 and 1.

Type:: float | None

class mlipaudit.benchmarks.stability.stability.StabilityStructureResult(*, structure_name: str, description: str, num_frames: Annotated[int, Gt(gt=0)] = 0, num_steps: Annotated[int, Gt(gt=0)], exploded_frame: int = 0, drift_frame: int = 0, failed: bool = False, score: Annotated[float, Ge(ge=0), Le(le=1)])¶

Result object for a single structure.

structure_name¶

The name of the structure.

Type:: str

description¶

The description of the structure.

Type:: str

num_frames¶

The number of frames in the trajectory.

Type:: int

num_steps¶

The number of steps the simulation was run for.

Type:: int

exploded_frame¶

The frame at which the simulation exploded. -1 if it did not explode.

Type:: int

drift_frame¶

The first frame at which a hydrogen atom started to drift. -1 if there is no drift.

Type:: int

failed¶

Whether the simulation failed with an error, without necessarily not being stable.

Type:: bool

score¶

The final score for the structure.

Type:: float

class mlipaudit.benchmarks.stability.stability.StabilityModelOutput(*, structure_names: list[str], simulation_states: list[SimulationState | None])¶

Stores model outputs for the stability benchmark.

structure_names¶

The list of structure names.

Type:: list[str]

simulation_states¶

The list of final simulation states for the corresponding structures. None if the si simulation failed.

Type:: list[mlip.simulation.state.SimulationState | None]