Source code for nvalchemi.enhanced_sampling.biases.abf

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Adaptive biasing force over a pair-distance collective variable."""

from __future__ import annotations

from collections import OrderedDict
from typing import TYPE_CHECKING, Any

import torch
from torch import Tensor, nn

from nvalchemi.dynamics.base import DynamicsStage
from nvalchemi.dynamics.hooks._utils import KB_EV
from nvalchemi.enhanced_sampling._adaptive import AdaptivePotentialMixin
from nvalchemi.enhanced_sampling.cv.pair_distance import pair_displacement
from nvalchemi.models._utils import DIAGNOSTIC_PREFIX
from nvalchemi.models.base import BaseModelMixin, ModelConfig

if TYPE_CHECKING:
    from nvalchemi._typing import ModelOutputs
    from nvalchemi.data import AtomicData, Batch
    from nvalchemi.enhanced_sampling._adaptive import BiasContext

__all__ = ["AdaptiveBiasingForce"]


[docs] class AdaptiveBiasingForce(AdaptivePotentialMixin, nn.Module, BaseModelMixin): r"""Estimate and cancel the mean force along a pair distance. Metadynamics fills a basin with hills; ABF instead measures the mean force :math:`\partial A/\partial \xi` in each bin of the collective variable and applies its negative, so the residual force along the CV averages to zero and the walker diffuses freely. The estimate *is* the free-energy gradient, so no reweighting is needed at the end — :meth:`free_energy` integrates it directly. For the pair distance :math:`r = |\mathbf{r}_j - \mathbf{r}_i|` the estimator is .. math:: \frac{\partial A}{\partial r} = \left\langle -\frac{(\mathbf{F}_j - \mathbf{F}_i)\cdot\hat{\mathbf{u}}}{2} \;-\; \frac{2 k_B T}{r} \right\rangle_r with :math:`\hat{\mathbf{u}} = (\mathbf{r}_j - \mathbf{r}_i)/r`. The second term is the **metric correction**, and it is not optional: see Notes. Parameters ---------- atom_indices: The pair ``(i, j)``, shape ``[2]`` for the same pair in every graph or ``[B, 2]`` for one per graph. Indices are local to each graph. temperature: Simulation temperature in Kelvin. Enters the metric correction, so it must match the thermostat; a mismatch biases the estimate. cv_range: ``(r_min, r_max)`` in angstrom, the binned interval. Outside it no force is applied and no sample is recorded. name: Unique bias identifier. n_bins: Number of uniform bins across ``cv_range``. min_samples: Samples a bin needs before *any* bias force is applied from it. An estimate from a handful of samples is noise, and applying it would drive the walker on the strength of that noise. full_samples: Samples at which the applied fraction reaches 1. Defaults to ``2 * min_samples``. Between the two the force ramps linearly; equal to ``min_samples`` it is a step, applying nothing until the threshold and full force at it. max_force: Optional cap on ``|dA/dr|`` in eV/A. A bin that has been visited once at a bad geometry can hold a large estimate; the cap bounds what that can do to the trajectory. frequency: Steps between :meth:`update` calls. ``1`` (every step) is the usual choice — ABF wants every uncorrelated sample it can get. Raises ------ ValueError For a malformed ``atom_indices``, a non-positive temperature, an empty or inverted ``cv_range``, fewer than one bin, a negative ``min_samples``, ``full_samples < min_samples``, or a non-positive ``max_force``. Notes ----- The metric correction is not optional Projecting Cartesian forces onto :math:`\nabla\xi` and averaging gives the mean force in the *constrained* ensemble, not the gradient of the free energy of the unconstrained one. The two differ by the Jacobian of the coordinate change — for a distance in three dimensions the shell volume grows as :math:`r^2`, contributing :math:`-2k_B T/r`. Omitting it does not produce noise, it produces a smoothly wrong answer: two non-interacting particles would be reported as having a flat PMF when the true one is :math:`-2k_B T\ln r`. That is why this class takes an atom **pair** rather than a general ``cv`` callable — the correction is specific to this coordinate, and accepting an arbitrary CV would mean applying a distance-shaped correction to something that is not a distance. Force-only, and therefore excluded from replica exchange :meth:`forward` returns ``forces`` and no ``energy``. There is no potential to report: the applied force is not the gradient of any function the bias holds, which is exactly what makes ABF non-conservative. ``supplies_exchange_energy`` is ``False``, and :class:`~nvalchemi.enhanced_sampling.ReplicaExchange` refuses such a bias rather than evaluating an acceptance rule that needs a cross-state bias energy. Observation ordering :attr:`~nvalchemi.enhanced_sampling.AdaptivePotentialMixin.stage` is ``AFTER_COMPUTE``, where ``batch.forces`` still holds the **unbiased** physical force. Observing after the bias is applied would feed the estimator its own output, and it would converge to whatever it had already decided. Examples -------- >>> import torch >>> from nvalchemi.enhanced_sampling import AdaptiveBiasingForce >>> abf = AdaptiveBiasingForce( ... atom_indices=torch.tensor([0, 1]), ... temperature=300.0, ... cv_range=(2.0, 6.0), ... n_bins=40, ... ) >>> int(abf.bin_counts.sum()) 0 """ #: The acceptance rule needs a cross-state bias energy; this has none. supplies_exchange_energy: bool = False def __init__( self, atom_indices: Tensor, temperature: float, cv_range: tuple[float, float], *, name: str = "abf", n_bins: int = 100, min_samples: int = 200, full_samples: int | None = None, max_force: float | None = None, frequency: int = 1, ) -> None: super().__init__() indices = torch.as_tensor(atom_indices, dtype=torch.long) if indices.dim() == 1: if indices.numel() != 2: raise ValueError( f"AdaptiveBiasingForce: atom_indices must name exactly two " f"atoms, got {indices.numel()}." ) elif indices.dim() != 2 or indices.shape[-1] != 2: raise ValueError( f"AdaptiveBiasingForce: atom_indices must have shape [2] or " f"[B, 2], got {tuple(indices.shape)}." ) if bool((indices < 0).any()): raise ValueError( f"AdaptiveBiasingForce: atom_indices must be non-negative " f"per-graph indices, got {indices.tolist()}." ) if bool((indices[..., 0] == indices[..., 1]).any()): raise ValueError( f"AdaptiveBiasingForce: atom_indices names the same atom twice " f"({indices.tolist()}); the distance would be identically zero." ) if temperature <= 0.0: raise ValueError( f"AdaptiveBiasingForce: temperature must be positive, got " f"{temperature}. It scales the metric correction, so it must " "match the thermostat." ) low, high = (float(v) for v in cv_range) if not high > low: raise ValueError( f"AdaptiveBiasingForce: cv_range must be increasing, got " f"({low}, {high})." ) if low < 0.0: raise ValueError( f"AdaptiveBiasingForce: cv_range lower bound must be " f"non-negative for a distance, got {low}." ) if int(n_bins) < 1: raise ValueError( f"AdaptiveBiasingForce: n_bins must be at least 1, got {n_bins}." ) if int(min_samples) < 0: raise ValueError( f"AdaptiveBiasingForce: min_samples must be non-negative, got " f"{min_samples}." ) ramp_end = 2 * int(min_samples) if full_samples is None else int(full_samples) if ramp_end < int(min_samples): raise ValueError( f"AdaptiveBiasingForce: full_samples ({ramp_end}) must be at " f"least min_samples ({int(min_samples)}) — the force ramps up " "between the two." ) if max_force is not None and max_force <= 0.0: raise ValueError( f"AdaptiveBiasingForce: max_force must be positive, got {max_force}." ) if int(frequency) < 1: raise ValueError( f"AdaptiveBiasingForce: frequency must be at least 1, got {frequency}." ) self.name = name self.temperature = float(temperature) self.cv_range = (low, high) self.n_bins = int(n_bins) self.min_samples = int(min_samples) self.full_samples = ramp_end self.max_force = None if max_force is None else float(max_force) self.frequency = int(frequency) self.stage = DynamicsStage.AFTER_COMPUTE self.model_config = ModelConfig( outputs=frozenset({"forces"}), autograd_outputs=frozenset(), supports_pbc=True, needs_pbc=False, active_outputs={"forces"}, ) dtype = torch.get_default_dtype() self.register_buffer("atom_indices", indices) self.register_buffer("bin_counts", torch.zeros(self.n_bins, dtype=torch.long)) self.register_buffer("force_sum", torch.zeros(self.n_bins, dtype=dtype)) # ------------------------------------------------------------------ # Geometry and binning # ------------------------------------------------------------------ @property def bin_width(self) -> float: """Return the width of one CV bin, in angstrom.""" low, high = self.cv_range return (high - low) / self.n_bins @property def bin_centers(self) -> Tensor: """Return the CV value at the middle of each bin, shape ``[n_bins]``.""" low, _ = self.cv_range offsets = torch.arange( self.n_bins, dtype=self.force_sum.dtype, device=self.force_sum.device ) return low + (offsets + 0.5) * self.bin_width
[docs] def bin_index(self, values: Tensor) -> Tensor: """Return the bin each CV value falls in, shape ``[...]``. Values outside ``cv_range`` are reported as ``-1``; they contribute no sample and receive no force, so they belong to no bin. Parameters ---------- values: CV values in angstrom. Returns ------- Tensor Integer bin indices, or ``-1`` for out-of-range values. """ index, in_range = self._bin_of(torch.as_tensor(values)) return torch.where(in_range, index, torch.full_like(index, -1))
def _align_device(self, reference: Tensor) -> None: """Move this bias's buffers to *reference*'s device if they differ. Parameters ---------- reference: Any tensor from the live batch; its device is the target. """ if self.force_sum.device != reference.device: self.to(reference.device) def _geometry(self, current: Batch) -> tuple[Tensor, Tensor, Tensor, Tensor]: """Return ``(distance, unit_vector, global_i, global_j)``. Parameters ---------- current: The live batch. Returns ------- tuple[Tensor, Tensor, Tensor, Tensor] Distances ``[B]``, unit displacements ``[B, 3]``, and the two global row indices ``[B]`` the bias force is written to. """ # pair_displacement validates atom_indices and applies the minimum # image convention, so the resolution repeated below is known good. delta = pair_displacement(current, self.atom_indices) # [B, 3] distance = torch.linalg.vector_norm(delta, dim=-1) # [B] unit = delta / distance.clamp(min=torch.finfo(delta.dtype).tiny).unsqueeze(-1) offsets = current.batch_ptr[:-1] # [B] indices = self.atom_indices.to(offsets.device) if indices.dim() == 1: indices = indices.unsqueeze(0).expand(offsets.numel(), 2) return distance, unit, offsets + indices[:, 0], offsets + indices[:, 1] def _bin_of(self, distance: Tensor) -> tuple[Tensor, Tensor]: """Return ``(bin_index, in_range)`` for CV values *distance*. Parameters ---------- distance: CV values, shape ``[B]``. Returns ------- tuple[Tensor, Tensor] Bin indices clamped into range, and a boolean mask marking which samples actually fell inside ``cv_range``. The clamp makes the index always safe to gather with, but it also means an out-of-range value silently names the nearest edge bin. Every caller must therefore mask what it gathers with the second return value, not just the quantities that reach the force. """ low, high = self.cv_range raw = ((distance - low) / self.bin_width).floor().to(torch.long) in_range = (distance >= low) & (distance < high) return raw.clamp(0, self.n_bins - 1), in_range # ------------------------------------------------------------------ # Estimate # ------------------------------------------------------------------
[docs] def mean_force(self) -> Tensor: """Return the per-bin mean-force estimate, shape ``[n_bins]``. Returns ------- Tensor ``dA/dr`` in eV/A per bin. Unvisited bins are ``nan`` rather than zero: a bin with no samples has no estimate, and zero is a perfectly plausible mean force that would hide that. """ counts = self.bin_counts.to(self.force_sum.dtype) estimate = self.force_sum / counts return torch.where(self.bin_counts > 0, estimate, torch.nan)
def _applied_gradient(self) -> Tensor: """Return the ramped, capped ``dA/dr`` actually applied, ``[n_bins]``. Returns ------- Tensor Zero wherever no force should be applied yet, so this is safe to index with any bin. """ counts = self.bin_counts.to(self.force_sum.dtype) estimate = torch.where( self.bin_counts > 0, self.force_sum / counts.clamp(min=1.0), 0.0 ) if self.max_force is not None: estimate = estimate.clamp(-self.max_force, self.max_force) # Reuses ramp_fraction rather than repeating it: two copies of the # same schedule are two places for the endpoint to disagree. return estimate * self.ramp_fraction()
[docs] def ramp_fraction(self) -> Tensor: """Return the applied fraction per bin, shape ``[n_bins]``. Zero at or below ``min_samples``, one at or above ``full_samples``, linear between. Ramping rather than switching on at the threshold avoids a force discontinuity of exactly the size the threshold exists to prevent. ``full_samples == min_samples`` is a step: nothing until the threshold, full force at it. That is a legitimate choice — it is the classic hard-threshold form, and it is what ``min_samples=0`` gives by default — so it is handled rather than rejected. It needs its own branch because the linear form would divide by a zero span, and clamping that span to 1 would delay full force by one sample. A bin with no samples has no estimate, so it reports zero whatever the thresholds are. Returns ------- Tensor Fractions in ``[0, 1]``. """ counts = self.bin_counts.to(self.force_sum.dtype) span = self.full_samples - self.min_samples if span <= 0: fraction = (self.bin_counts >= self.full_samples).to(counts.dtype) else: fraction = ((counts - self.min_samples) / span).clamp(0.0, 1.0) return torch.where(self.bin_counts > 0, fraction, torch.zeros_like(fraction))
# ------------------------------------------------------------------ # BaseModelMixin required surface # ------------------------------------------------------------------ @property def embedding_shapes(self) -> dict[str, tuple[int, ...]]: """No embeddings: ABF applies a tabulated force, not a network.""" return {}
[docs] def compute_embeddings( self, data: AtomicData | Batch, **kwargs: Any ) -> AtomicData | Batch: """Not implemented — ABF produces no embeddings. Parameters ---------- data: The input system. **kwargs: Unused; accepted for interface compatibility. Returns ------- AtomicData | Batch Never returns. Raises ------ NotImplementedError Always. """ raise NotImplementedError(f"{type(self).__name__} does not produce embeddings.")
# ------------------------------------------------------------------ # Contribution # ------------------------------------------------------------------
[docs] def forward(self, data: AtomicData | Batch, **kwargs: Any) -> ModelOutputs: """Return the bias force, with no energy. Read-only with respect to the estimator: the current estimate is applied but never updated here, so it is safe to call repeatedly on the same batch. Parameters ---------- data: The live batch. **kwargs: Unused; accepted for interface compatibility with model wrappers. Returns ------- ModelOutputs ``forces``, this bias's ``state_version``, and per-walker ``diagnostics/*``: the CV value, its ``bin`` (``-1`` outside ``cv_range``, matching :meth:`bin_index`), the ``applied_gradient`` actually used (ramped and capped, so not the same as :meth:`mean_force`), the bin's sample count, its ramp fraction, and ``in_range``. Every per-bin quantity reads zero for a walker outside the range, so the diagnostics agree with the force rather than reporting the nearest edge bin's statistics. There is no ``energy``: the applied force is not the gradient of any function this bias holds. """ current = data self._align_device(current.positions) with torch.no_grad(): distance, unit, global_i, global_j = self._geometry(current) bins, in_range = self._bin_of(distance) gradient = self._applied_gradient()[bins] # [B] gradient = torch.where(in_range, gradient, torch.zeros_like(gradient)) # V_bias = -A, so F_bias = +grad A = (dA/dr) grad r, and # grad_i r = -u while grad_j r = +u. contribution = gradient.unsqueeze(-1) * unit # [B, 3] forces = torch.zeros_like(current.positions) forces.index_add_(0, global_j, contribution) forces.index_add_(0, global_i, -contribution) # Every per-bin diagnostic is masked the same way the gradient is. # _bin_of clamps the index so it is always safe to gather with, # which means an out-of-range walker would otherwise read the # nearest edge bin's statistics and report them as its own — a # converged-looking sample count and ramp next to in_range == 0. zero_long = torch.zeros_like(self.bin_counts[bins]) ramp = self.ramp_fraction()[bins] # Named applied_gradient, not mean_force: this is the ramped and # capped value actually used, which is not what mean_force() # returns. Reusing that name would invite reading a # threshold-suppressed zero as a measured zero mean force. diagnostics = { "cv": distance.unsqueeze(-1), "bin": torch.where(in_range, bins, torch.full_like(bins, -1)).unsqueeze( -1 ), "applied_gradient": gradient.unsqueeze(-1), "samples": torch.where( in_range, self.bin_counts[bins], zero_long ).unsqueeze(-1), "ramp": torch.where(in_range, ramp, torch.zeros_like(ramp)).unsqueeze( -1 ), "in_range": in_range.to(forces.dtype).unsqueeze(-1), } outputs: ModelOutputs = OrderedDict(forces=forces) for key, value in diagnostics.items(): outputs[f"{DIAGNOSTIC_PREFIX}{key}"] = value return self.stamp_state_version(outputs, current)
[docs] def update(self, ctx: BiasContext, stage: DynamicsStage) -> None: """Accumulate one mean-force sample per walker. Parameters ---------- ctx: The ``AFTER_COMPUTE`` capture, whose ``ctx.batch.forces`` are the unbiased physical forces. ``ctx.contribution`` is this bias's own preceding output and is deliberately unused: an estimator fed its own output converges to whatever it had already decided. stage: The stage being dispatched, always :attr:`stage`. Raises ------ ValueError If the captured frame carries no forces to project. """ frames = ctx.batch physical = getattr(frames, "forces", None) if physical is None: raise ValueError( f"AdaptiveBiasingForce {self.name!r}: the observed frame has no " "forces, so there is no mean force to sample. This bias " "observes at AFTER_COMPUTE, where the batch must already carry " "the physical forces from the model." ) with torch.no_grad(): self._align_device(physical) distance, unit, global_i, global_j = self._geometry(frames) bins, in_range = self._bin_of(distance) # Projected force along the CV, then the Jacobian term. See the # class Notes for why the second is not optional. projected = ( -((physical[global_j] - physical[global_i]) * unit).sum(dim=-1) / 2.0 ) metric = 2.0 * KB_EV * self.temperature / distance sample = (projected - metric).to(self.force_sum.dtype) keep = in_range & torch.isfinite(sample) if not bool(keep.any()): return bins = bins[keep] self.force_sum.index_add_(0, bins, sample[keep]) self.bin_counts.index_add_(0, bins, torch.ones_like(bins)) # Only bump when the applied force actually changed. A bin still # below its threshold contributes nothing, so re-priming forces # over it would be pure cost — this is the case # AdaptivePotentialMixin.bump_state_version documents. Asking # ramp_fraction rather than re-deriving the threshold keeps the # two from disagreeing at the endpoint. changed = bool((self.ramp_fraction()[bins] > 0.0).any()) if changed: self.bump_state_version()
# ------------------------------------------------------------------ # Analysis # ------------------------------------------------------------------
[docs] def config_fingerprint(self) -> dict[str, Any]: """Return the settings the accumulated histogram is only valid under. ``cv_range`` and ``n_bins`` decide what each bin *means*; restoring a histogram under a different pair silently relabels every bin. ``temperature`` scales the metric correction already folded into ``force_sum``, so samples taken at 300 K cannot be extended at 900 K. ``atom_indices`` names the coordinate itself. ``min_samples`` / ``full_samples`` / ``max_force`` change what the same counts apply. Returns ------- dict[str, Any] The checked configuration. """ return { "atom_indices": self.atom_indices.reshape(-1).tolist(), "cv_range": list(self.cv_range), "n_bins": self.n_bins, "temperature": self.temperature, "min_samples": self.min_samples, "full_samples": self.full_samples, "max_force": self.max_force, }
[docs] def free_energy(self) -> Tensor: """Return the PMF at each bin center, shape ``[n_bins]``. Integrates the mean-force estimate by the trapezoid rule, shifted so the minimum over sampled bins is zero. This is the payoff of the method: unlike metadynamics there is nothing to deconvolve, because the accumulated quantity already *is* the free-energy gradient. Returns ------- Tensor Free energy in eV. Bins never visited are ``nan``. Raises ------ RuntimeError If no bin has been sampled, or if an unvisited bin sits between two visited ones. Integration carries the profile across the gap, so a hole in the middle would silently contaminate every value beyond it. """ visited = self.bin_counts > 0 if not bool(visited.any()): raise RuntimeError( f"AdaptiveBiasingForce {self.name!r}: no bin has been sampled, " "so there is no free energy to report. Check that cv_range " "covers the CV values the run actually visits." ) indices = visited.nonzero(as_tuple=False).squeeze(-1) first, last = int(indices[0]), int(indices[-1]) if not bool(visited[first : last + 1].all()): missing = (~visited[first : last + 1]).nonzero(as_tuple=False).squeeze( -1 ) + first raise RuntimeError( f"AdaptiveBiasingForce {self.name!r}: bin(s) " f"{missing.tolist()} were never visited but lie between bins " f"{first} and {last} that were. Integrating the mean force " "carries the profile across the gap, so every value beyond it " "would be wrong by an unknown constant. Run longer, widen the " "bins, or narrow cv_range." ) gradient = self.force_sum[first : last + 1] / self.bin_counts[ first : last + 1 ].to(self.force_sum.dtype) profile = torch.full_like(self.force_sum, torch.nan) if gradient.numel() == 1: profile[first] = 0.0 return profile midpoints = 0.5 * (gradient[:-1] + gradient[1:]) * self.bin_width integrated = torch.cat( [ torch.zeros(1, dtype=gradient.dtype, device=gradient.device), torch.cumsum(midpoints, dim=0), ] ) profile[first : last + 1] = integrated - integrated.min() return profile
def __repr__(self) -> str: """Return a concise description of the bias.""" low, high = self.cv_range sampled = int((self.bin_counts > 0).sum()) return ( f"{type(self).__name__}(name={self.name!r}, " f"cv_range=({low:g}, {high:g}), n_bins={self.n_bins}, " f"sampled_bins={sampled}/{self.n_bins}, " f"samples={int(self.bin_counts.sum())})" )