feat: add NVE energy-conservation benchmark#146
Open
maxbortone wants to merge 1 commit into
Open
Conversation
Port the NVE energy-conservation benchmark from the internal repo. It runs short microcanonical (NVE, velocity-Verlet, no thermostat) MD trajectories for four representative systems (vacuum molecule, bulk water, two solvated peptides) and scores how well the model conserves total mechanical energy E(t) = PE(t) + KE(t). The metric is the fitted total-energy drift over the run divided by the kinetic-energy standard deviation, mapped through the standard soft-threshold scorer. - Add the benchmark module, registered and gated per-system on elements. - Add the Streamlit UI page (per-system drift curves + linear fits) and wire it into the GUI. - Mark it beta (BENCHMARKS_TO_SKIP_FOR_PUBLIC_LEADERBOARD), like the NEB benchmark. - Add unit tests and checked-in test structures, plus the generic UI-page test. - Add user-facing and API-reference docs under the General category. The NVE velocity-Verlet integrator and SimulationState.potential_energy are only on mlip's `develop` branch, not yet in a PyPI release, so pin mlip to git `develop` via [tool.uv.sources] until a release ships them. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
|
lwalew
approved these changes
Jul 1, 2026
Comment on lines
+34
to
41
| # Temporary: the NVE energy-conservation benchmark needs the NVE velocity-Verlet | ||
| # integrator (MDIntegrator.NVE_VELOCITY_VERLET) and SimulationState.potential_energy, | ||
| # which are on mlip's `develop` branch but not yet in a published PyPI release. Pin to | ||
| # git `develop` until a release ships these, then drop this source to use the PyPI build. | ||
| [tool.uv.sources] | ||
| mlip = { git = "https://github.com/instadeepai/mlip-jax.git", branch = "develop" } | ||
|
|
||
| [dependency-groups] |
Collaborator
There was a problem hiding this comment.
reminder: To remove these lines since it's now merged upstream
Comment on lines
+106
to
111
| BENCHMARKS_TO_SKIP_FOR_PUBLIC_LEADERBOARD = [ | ||
| NudgedElasticBandBenchmark, | ||
| NVEEnergyConservationBenchmark, | ||
| ] | ||
|
|
||
|
|
Collaborator
There was a problem hiding this comment.
remark: This is temporary right? We have a scoring which we'd like to display? Or not?
|
|
||
| # Scoring threshold on the energy-drift / kinetic-energy-fluctuation ratio | ||
| # computed in `_analyze_structure`. | ||
| ENERGY_DRIFT_RATIO_THRESHOLD = 1.0 |
Collaborator
There was a problem hiding this comment.
So I think from the PR open on mlipaudit-internal, tweaking this value is the only open question in this file
|
|
||
| NVE energy conservation | ||
| ======================= | ||
|
|
Collaborator
There was a problem hiding this comment.
Docs looking good :raised_hands. Maybe @Silvia can also double-check
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ports the NVE energy-conservation benchmark from the internal repo to the OSS library. It runs short microcanonical (NVE, velocity-Verlet, no thermostat) MD trajectories for four representative systems — a vacuum HCNO molecule, bulk water (500 molecules), and two solvated peptides — and scores how well the model conserves total mechanical energy
E(t) = PE(t) + KE(t).The headline metric is the magnitude of the fitted total-energy drift over the run divided by the standard deviation of the kinetic energy, mapped through the standard soft-threshold scorer. A flat total energy → score ≈ 1.0; a strong drift → score → 0.0.
What's included
src/mlipaudit/benchmarks/nve_energy_conservation/):NVEEnergyConservationBenchmark+ itsModelOutput/Resultclasses, registered viaBenchmark.__subclasses__(). Elements are gated per-system (skip_if_elements_missing = False) so a model missing one element only skips the affected systems.src/mlipaudit/ui/nve_energy_conservation.py): summary score table + per-system total-energy drift curves with their linear fits.BENCHMARKS_TO_SKIP_FOR_PUBLIC_LEADERBOARD(like the NEB benchmark) — it runs and scores but is hidden from the public leaderboard.tests/data/.Dependency note⚠️
The NVE velocity-Verlet integrator (
MDIntegrator.NVE_VELOCITY_VERLET) andSimulationState.potential_energyare only on mlip'sdevelopbranch — not in any published PyPI release (PyPI 0.2.1 has neither). This PR therefore pins mlip to gitdevelopvia[tool.uv.sources], matching the internal repo. This is temporary: once a mlip release ships NVE support, drop the[tool.uv.sources]entry to use the PyPI build.Data
The benchmark data (4 structure files) is added separately to the
InstaDeepAI/MLIPAudit-dataHF dataset asnve_energy_conservation.zip(top-levelnve_energy_conservation/directory) — handled via the data-repo PR. Tests run offline using the checked-intests/data/copies.Verification
uv run pytest→ 139 passeduv run pre-commit run --all-files→ ruff + mypy + checks all passuv run sphinx-build -W -b html docs/source docs/build/html→ build succeeded🤖 Generated with Claude Code