ES/05 metadynamics

[samarjeet]

ALCHEMI Toolkit Pull Request

WellTemperedMetaDynamicsBias (all three storage policies; periodic CV; independent and state-owned history); RMSDMetaDynamicsBias (xTB-style); unit + GPU integration tests; gallery examples

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Performance improvement
• Documentation update
• Refactoring (no functional changes)
• CI/CD or infrastructure change

Related Issues

Changes Made

Testing

• Unit tests pass locally (make pytest)
• Linting passes (make lint)
• New tests added for new functionality meets coverage expectations?

Checklist

• I have read and understand the Contributing Guidelines
• I have updated the CHANGELOG.md
• I have performed a self-review of my code
• I have added docstrings to new functions/classes
• I have updated the documentation (if applicable)

Additional Notes

Tip

This repository uses Greptile, an AI code review service, to help conduct
pull request reviews. We encourage contributors to read and consider suggestions
made by Greptile, but note that human maintainers will provide the necessary
reviews for merging: Greptile's comments are not a qualitative judgement
of your code, nor is it an indication that the PR will be accepted/rejected.
We encourage the use of emoji reactions to Greptile comments, depending on
their usefulness and accuracy.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[greptile-apps]

Greptile Summary

This PR introduces the enhanced-sampling framework, including conservative and adaptive biases, replica exchange, checkpoint/restore support, metadynamics variants, collective variables, documentation, examples, and tests.

• Adds well-tempered and RMSD metadynamics with configurable history and storage policies.
• Adds synchronous replica exchange and thermodynamic-state rebinding for supported NVT integrators.
• Adds transactional enhanced-sampling checkpoints and force-priming lifecycle integration.
• Deprecates the legacy biased-potential hook in favor of the conservative-bias API.

Important Files Changed

Filename	Overview
nvalchemi/enhanced_sampling/biases/metadynamics.py	Implements well-tempered metadynamics and storage/history policies, but free_energy() silently selects owner 0 for private histories.
nvalchemi/enhanced_sampling/biases/rmsd_metad.py	Adds batched, non-periodic RMSD metadynamics with reference storage, atom selection, and rigid-motion-invariant energy.
nvalchemi/enhanced_sampling/_runner.py	Coordinates bias evaluation, hook ordering, adaptive updates, force priming, exchange, and checkpoint lifecycle.
nvalchemi/enhanced_sampling/_exchange.py	Implements synchronous temperature and umbrella exchange with deterministic pairing and acceptance draws.
nvalchemi/enhanced_sampling/_checkpoint.py	Adds checksummed transactional serialization for runner, dynamics, bias, exchange, and batch state.
nvalchemi/enhanced_sampling/_bias.py	Defines conservative autograd-derived bias outputs and aggregation across independent biases.
nvalchemi/dynamics/base.py	Adds dynamics state serialization and thermodynamic-state extension points used by enhanced sampling.
nvalchemi/dynamics/integrators/nvt_langevin.py	Adds temperature-state rebinding and corresponding velocity rescaling for replica exchange.
nvalchemi/dynamics/integrators/nvt_nose_hoover.py	Adds temperature rebinding that consistently transforms velocities and thermostat-chain state.
docs/userguide/enhanced_sampling.md	Documents enhanced-sampling concepts, supported biases, replica exchange, lifecycle guarantees, and checkpoint workflows.

_{Reviews (1): Last reviewed commit: "biases now raise for history=walker/stat..." | Re-trigger Greptile}

[greptile-apps]

Private history defaults to owner zero

When free_energy(values) is called for history="walker" or history="state" without an owner_key, this branch silently selects owner 0 and excludes every other owner's hills, causing an incomplete but plausible free-energy profile despite the docstring claiming a shared-history default.