NVE energy conservation

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

Benchmark measuring total-energy conservation under NVE dynamics.

For each test system, a short NVE (velocity-Verlet, no thermostat) trajectory is run with velocities initialized from a Maxwell-Boltzmann distribution. The total mechanical energy PE + KE is tracked over the trajectory and its drift relative to the first frame is fitted with a linear model; the fitted drift over the run, divided by the standard deviation of the kinetic energy, is mapped to a score.

name

The unique benchmark name, nve_energy_conservation.

Type:

str

category

The UI grouping category, General.

Type:

str

result_class

The NVEEnergyConservationResult type.

Type:

type[mlipaudit.benchmark.BenchmarkResult] | None

model_output_class

The NVEEnergyConservationModelOutput type.

Type:

type[mlipaudit.benchmark.ModelOutput] | None

required_elements

The union of elements across all test systems. Used as metadata only; per-system element gating is done in run_model (see skip_if_elements_missing).

Type:

set[str] | None

skip_if_elements_missing

Set to False so the benchmark is never skipped wholesale; instead, individual systems whose elements the model cannot handle are skipped within run_model.

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 an NVE trajectory and record total energy for each system.

Systems whose elements the model does not support are skipped. For the rest, an NVE MD simulation is run and the per-snapshot potential and kinetic energies are stored in model_output.

analyze() → NVEEnergyConservationResult

Compute the drift, fit its slope and score each system.

Returns:

An NVEEnergyConservationResult with per-system drift curves, fitted slopes and scores, plus the aggregate benchmark score.

Raises:

RuntimeError – If called before run_model().

class mlipaudit.benchmarks.nve_energy_conservation.nve_energy_conservation.NVEEnergyConservationResult(*, failed: bool = False, score: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, structure_results: list[NVEStructureResult], n_skipped_unallowed_elements: int = 0)

Result object for the NVE energy-conservation benchmark.

structure_results

The list of per-system results.

Type:

list[mlipaudit.benchmarks.nve_energy_conservation.nve_energy_conservation.NVEStructureResult]

n_skipped_unallowed_elements

How many systems were skipped because the model does not support one of their elements.

Type:

int

failed

Whether all systems were skipped or failed.

Type:

bool

score

The overall benchmark score between 0 and 1.

Type:

float | None

class mlipaudit.benchmarks.nve_energy_conservation.nve_energy_conservation.NVEStructureResult(*, structure_name: str, description: str, system_class: str, num_atoms: int = 0, num_frames: int = 0, times_ps: list[float] = [], energy_drift_ev: list[float] = [], drift_slope_ev_per_ps: float | None = None, total_drift_ev: float | None = None, kinetic_energy_std_ev: float | None = None, energy_drift_ratio: float | None = None, intercept_ev: float | None = None, skipped: bool = False, failed: bool = False, score: float | None = None)

Per-system result for the NVE energy-conservation benchmark.

structure_name

The system identifier.

Type:

str

description

Human-readable description of the system.

Type:

str

system_class

One of vacuum, bulk_water or solvated.

Type:

str

num_atoms

The number of atoms in the system.

Type:

int

num_frames

The number of (finite) trajectory frames used for the fit.

Type:

int

times_ps

The snapshot times in picoseconds (x-axis of the drift plot).

Type:

list[float]

energy_drift_ev

The total-energy drift in eV at each snapshot.

Type:

list[float]

drift_slope_ev_per_ps

Slope of the linear fit to the drift (eV / ps).

Type:

float | None

total_drift_ev

Magnitude of the fitted total-energy drift over the whole trajectory (eV), i.e. |slope| * duration.

Type:

float | None

kinetic_energy_std_ev

Standard deviation of the kinetic energy along the trajectory (eV); the fluctuation scale used to normalize the drift.

Type:

float | None

energy_drift_ratio

total_drift_ev / kinetic_energy_std_ev, the dimensionless energy-conservation metric used for scoring.

Type:

float | None

intercept_ev

Intercept of the linear fit (eV).

Type:

float | None

skipped

Whether the system was skipped because the model does not support one of its elements.

Type:

bool

failed

Whether the simulation ran but failed (e.g. it blew up).

Type:

bool

score

The per-system score between 0 and 1, or None if skipped.

Type:

float | None

class mlipaudit.benchmarks.nve_energy_conservation.nve_energy_conservation.NVEEnergyConservationModelOutput(*, structure_names: list[str], num_atoms: list[int | None], times_ps: list[list[float] | None], potential_energies_ev: list[list[float] | None], kinetic_energies_ev: list[list[float] | None], skipped_structures: list[str], n_skipped_unallowed_elements: int = 0)

Raw model outputs for the NVE energy-conservation benchmark.

Per-system entries are aligned by index with structure_names. Entries are None for systems that were skipped or whose simulation failed.

structure_names

The ordered list of system identifiers that were run.

Type:

list[str]

num_atoms

The number of atoms per system.

Type:

list[int | None]

times_ps

The snapshot times in picoseconds per system.

Type:

list[list[float] | None]

potential_energies_ev

The per-snapshot potential energies (eV) per system.

Type:

list[list[float] | None]

kinetic_energies_ev

The per-snapshot kinetic energies (eV) per system.

Type:

list[list[float] | None]

skipped_structures

Systems skipped due to unsupported elements.

Type:

list[str]

n_skipped_unallowed_elements

Number of skipped systems.

Type:

int