ES/06 Adaptive Biasing Force

[samarjeet]

ALCHEMI Toolkit Pull Request

AdaptiveBiasingForce (pair_distance, scalar only): pair-distance metric correction; sample threshold and force ramp; force-only BiasResult; ABF + exchange rejection; checkpoint; unit + GPU integration tests; gallery example

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

The PR introduces a comprehensive enhanced-sampling framework centered on Adaptive Biasing Force, alongside conservative biases, metadynamics, replica exchange, and exact checkpoint restoration.

• Adds bias abstractions, adaptive-state lifecycle handling, CV utilities, ABF, umbrella/wall potentials, and two metadynamics variants.
• Integrates bias evaluation and adaptive updates with the dynamics hook lifecycle, including unbiased ABF observations and force re-priming.
• Adds synchronous replica exchange with thermostat-state rebinding and deterministic acceptance draws.
• Adds transactional, checksummed Zarr checkpoints for batches, integrators, biases, runner state, and exchange state.
• Deprecates the legacy force-and-energy-only bias hook and adds documentation, examples, and extensive tests.

Important Files Changed

Filename	Overview
nvalchemi/enhanced_sampling/_runner.py	Introduces the hook-driven enhanced-sampling lifecycle, identity stamping, bias aggregation, exactly-once adaptive updates, exchange coordination, and force re-priming; no actionable defect was established.
nvalchemi/enhanced_sampling/biases/abf.py	Implements pair-distance ABF with metric correction, sample ramping, force-only output, profile integration, diagnostics, and checkpoint configuration validation.
nvalchemi/enhanced_sampling/_exchange.py	Implements deterministic synchronous replica exchange, even/odd pair scheduling, temperature and umbrella acceptance, and assignment bookkeeping.
nvalchemi/enhanced_sampling/_checkpoint.py	Adds transactional Zarr checkpoint serialization with manifest commit semantics, component and batch integrity checks, and shape-preserving tensor decoding.
nvalchemi/enhanced_sampling/_bias.py	Defines detached bias results, structural bias contracts, conservative autograd force/stress derivation, and contribution aggregation.
nvalchemi/dynamics/base.py	Adds serializable integrator state, restore support, state redistribution, thermodynamic-state rebinding contracts, and per-graph velocity scaling.
nvalchemi/dynamics/integrators/nvt_langevin.py	Adds temperature-state rebinding and queued velocity rescaling for Langevin replica exchange.
nvalchemi/dynamics/integrators/nvt_nose_hoover.py	Adds coordinated temperature, chain-mass, chain-velocity, and atomic-velocity transformations for replica exchange.
.claude/skills/nvalchemi-dynamics-hooks/SKILL.md	Updates agent guidance to deprecate the legacy bias hook and accurately direct new bias implementations to enhanced sampling.
docs/userguide/enhanced_sampling.md	Documents the new enhanced-sampling architecture, built-in methods, lifecycle constraints, replica exchange, checkpointing, and usage examples.

_{Reviews (1): Last reviewed commit: "docs: record why BiasResult's physics fi..." | Re-trigger Greptile}