Tautomers

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

Benchmark for relative vacuum energy differences of tautomers.

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 tautomers.

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 “Small Molecules”.

Type:

str

result_class

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

Type:

type[mlipaudit.benchmark.BenchmarkResult] | None

model_output_class

A reference to the TautomersModelOutput 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 single point energy calculations on tautomer structures.

Note: The benchmark only runs single point energy calculations on the input structures, assuming they are already minimized using xtb.

analyze() → TautomersResult

Checks the energy of tautomers is in check with the reference data.

Returns:

A TautomersResult object with the benchmark results.

Raises:

RuntimeError – If called before run_model().

class mlipaudit.benchmarks.tautomers.tautomers.TautomersResult(*, failed: bool = False, score: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, molecules: list[TautomersMoleculeResult], mae: float | None = None, rmse: float | None = None)

Results object for tautomers benchmark.

molecules

List of benchmark results for each molecule/tautomer pair, including those that failed inference.

Type:

list[mlipaudit.benchmarks.tautomers.tautomers.TautomersMoleculeResult]

mae

Mean absolute error from the reference for tautomer energies.

Type:

float | None

rmse

Root-mean-square error from the refrence for tautomer energies.

Type:

float | None

failed

Whether all the 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.tautomers.tautomers.TautomersMoleculeResult(*, structure_id: str, abs_deviation: float | None = None, predicted_energy_diff: float | None = None, ref_energy_diff: float | None = None, failed: bool = False)

Results object for one molecule/tautomer pair in the tautomers benchmark.

All units in kcal/mol.

structure_id

ID of the structure pair.

Type:

str

abs_deviation

Absolute deviation in tautomer energy.

Type:

float | None

predicted_energy_diff

Predicted energy difference between the tautomers.

Type:

float | None

ref_energy_diff

Reference energy difference between the tautomers.

Type:

float | None

failed

Whether the inference failed for the tautomer. defaults to false.

Type:

bool

class mlipaudit.benchmarks.tautomers.tautomers.TautomersModelOutput(*, structure_ids: list[str], predictions: list[tuple[float, float] | None])

Stores model outputs for the conformer selection benchmark.

structure_ids

IDs of the structure (i.e. tautomer) pairs.

Type:

list[str]

predictions

The energy predictions for the tautomer pairs. None if the inference failed.

Type:

list[tuple[float, float] | None]