Solvent Density

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

Benchmark for the equilibrium density of molecular solvents.

Runs the same NPT simulations as SolventRadialDistributionBenchmark (reusing their output when both are run together) and scores how closely the equilibrium density of each solvent matches its reference.

name

The unique benchmark name. The name is solvent_density.

Type:

str

category

The benchmark’s category, "Molecular Liquids".

Type:

str

data_name

The input-data directory shared with the solvent RDF benchmark.

Type:

str | None

result_class

SolventDensityResult.

Type:

type[mlipaudit.benchmark.BenchmarkResult] | None

model_output_class

SolventDensityModelOutput.

Type:

type[mlipaudit.benchmark.ModelOutput] | None

required_elements

The set of atomic element types present in the input files.

Type:

set[str] | None

reusable_output_id

Shared with SolventRadialDistributionBenchmark so the solvent NPT simulations are only run once when both benchmarks are run together.

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 structure using the NPT ensemble.

The MD simulation is performed using the JAX MD engine and starts from the reference structure. The NPT integrator uses Langevin dynamics with a Monte Carlo barostat.

analyze() → SolventDensityResult

Compute the equilibrium density of each solvent and its deviation.

Returns:

A SolventDensityResult object.

Raises:

RuntimeError – If called before run_model().

class mlipaudit.benchmarks.solvent_density.solvent_density.SolventDensityResult(*, failed: bool = False, score: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, structure_names: list[str], structures: list[SolventDensityStructureResult], avg_density_deviation: Annotated[float, Ge(ge=0)] | None = None)

Result object for the solvent density benchmark.

structure_names

The names of the structures.

Type:

list[str]

structures

List of per structure results.

Type:

list[mlipaudit.benchmarks.solvent_density.solvent_density.SolventDensityStructureResult]

avg_density_deviation

The average density deviation across all structures.

Type:

float | None

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.solvent_density.solvent_density.SolventDensityStructureResult(*, structure_name: str, densities: list[float] | None = None, average_density: float | None = None, density_deviation: Annotated[float, Ge(ge=0)] | None = None, reference_density: float | None = None, failed: bool = False, score: float = 0.0)

Stores the density result for a single structure.

structure_name

The structure name.

Type:

str

densities

List of per-frame densities in g/cm3.

Type:

list[float] | None

average_density

Average density over the final four fifths of the frames.

Type:

float | None

density_deviation

Absolute deviation of the average density from the reference.

Type:

float | None

reference_density

The reference density in g/cm3.

Type:

float | None

failed

Whether the simulation was successful. If unsuccessful, the other attributes will be not be set.

Type:

bool

score

The score for the molecule.

Type:

float

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

Model output containing the final simulation states for each structure.

Shares its field signature with SolventRadialDistributionModelOutput so that the NPT simulations can be reused between the two benchmarks (see reusable_output_id).

structure_names

The names of the 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]