Folding Stability

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

Benchmark for folding stability of biosystems.

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 folding_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 is “Biomolecules”.

Type:

str

result_class

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

Type:

type[mlipaudit.benchmark.BenchmarkResult] | None

model_output_class

A reference to the FoldingStabilityModelOutput 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

reusable_output_id

An optional ID that references other benchmarks with identical input systems and ModelOutput signatures (in form of a tuple). If present, a user or the CLI can make use of this information to reuse cached model outputs from another benchmark carrying the same ID instead of rerunning simulations or inference.

Type:

tuple[str, …] | None

__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 an MD simulation for each biosystem.

The simulation results are stored in the model_output attribute.

analyze() → FoldingStabilityResult

Analyzes the folding stability trajectories.

Loads the trajectory from the simulation state and computes the TM-score and RMSD between the trajectory and the reference structure. Note that the reference structure for the TM-score may be the same or a different structure than the one used for the simulation.

Returns:

A FoldingStabilityResult object with the benchmark results.

Raises:

RuntimeError – If called before run_model().

class mlipaudit.benchmarks.folding_stability.folding_stability.FoldingStabilityResult(*, failed: bool = False, score: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, molecules: list[FoldingStabilityMoleculeResult], avg_rmsd: float | None = None, min_rmsd: float | None = None, avg_tm_score: float | None = None, max_tm_score: float | None = None, avg_match: float | None = None, max_abs_deviation_radius_of_gyration: float | None = None)

Stores the result of the folding stability benchmark.

molecules

A list of FoldingStabilityMoleculeResult for each molecule processed in the benchmark.

Type:

list[mlipaudit.benchmarks.folding_stability.folding_stability.FoldingStabilityMoleculeResult]

avg_rmsd

Average RMSD value (averaged across molecules).

Type:

float | None

min_rmsd

Minimum RMSD value (minimum across molecules).

Type:

float | None

avg_tm_score

Average TM score (averaged across molecules).

Type:

float | None

max_tm_score

Maximum TM score (maximum across molecules).

Type:

float | None

avg_match

Average of averaged match_secondary_structure metric across molecules.

Type:

float | None

max_abs_deviation_radius_of_gyration

Maximum absolute deviation of radius of gyration from t = 0 in state in trajectory. Maximum absolute deviation across molecules.

Type:

float | None

failed

Whether all the simulations or inferences 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.folding_stability.folding_stability.FoldingStabilityMoleculeResult(*, structure_name: str, rmsd_trajectory: list[float] | None = None, tm_score_trajectory: list[float] | None = None, radius_of_gyration_deviation: list[float] | None = None, match_secondary_structure: list[float] | None = None, avg_rmsd: float | None = None, avg_tm_score: float | None = None, avg_match: float | None = None, radius_of_gyration_fluctuation: float | None = None, max_abs_deviation_radius_of_gyration: float | None = None, failed: bool = False)

Stores the result for one molecule of the folding stability benchmark.

structure_name

The name of the structure.

Type:

str

rmsd_trajectory

The RMSD values for each frame of the trajectory.

Type:

list[float] | None

tm_score_trajectory

The TM scores for each frame of the trajectory.

Type:

list[float] | None

radius_of_gyration_deviation

Radius of gyration for each frame of the trajectory.

Type:

list[float] | None

match_secondary_structure

Percentage of matches for each frame. Match means for a residue that the reference structure’s secondary structure assignment is the same.

Type:

list[float] | None

avg_rmsd

Average RMSD value.

Type:

float | None

avg_tm_score

Average TM score.

Type:

float | None

avg_match

Average of match_secondary_structure metric across trajectory.

Type:

float | None

radius_of_gyration_fluctuation

Standard deviation of radius of gyration throughout trajectory.

Type:

float | None

max_abs_deviation_radius_of_gyration

Maximum absolute deviation of radius of gyration from t = 0 in state in trajectory.

Type:

float | None

failed

Whether the simulation was stable or failed. If not stable, the other attributes will default to None.

Type:

bool

class mlipaudit.benchmarks.folding_stability.folding_stability.FoldingStabilityModelOutput(*, structure_names: list[str], simulation_states: list[SimulationState | None])

Stores model outputs for the folding stability benchmark.

structure_names

Names of structures.

Type:

list[str]

simulation_states

SimulationState or None object for each structure in the same order as the structure names. None if the simulation failed.

Type:

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