Source code for nvalchemi.enhanced_sampling.biases.metadynamics
# 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.
"""Well-tempered metadynamics over one or more collective variables."""
from __future__ import annotations
from typing import TYPE_CHECKING, Any, Literal
import torch
from torch import Tensor
from nvalchemi.dynamics.hooks._utils import KB_EV
from nvalchemi.enhanced_sampling._adaptive import AdaptivePotentialMixin
from nvalchemi.enhanced_sampling._bias import ConservativeBias
from nvalchemi.enhanced_sampling._history import DepositHistoryMixin
from nvalchemi.enhanced_sampling.cv._periodic import periodic_difference
if TYPE_CHECKING:
from collections.abc import Callable, Mapping
from nvalchemi.data import Batch
from nvalchemi.dynamics.base import DynamicsStage
from nvalchemi.enhanced_sampling._adaptive import BiasContext
__all__ = ["WellTemperedMetaDynamicsBias"]
[docs]
class WellTemperedMetaDynamicsBias(
AdaptivePotentialMixin, DepositHistoryMixin, ConservativeBias
):
r"""Gaussian hills deposited along a CV, with well-tempered damping.
.. math::
V(s, t) = \sum_i h_i \exp\!\left(
-\sum_d \frac{(s_d - c_{i,d})^2}{2\sigma_d^2}\right)
Each deposition adds one hill per walker at that walker's current CV
value. In the well-tempered scheme the height decays where the bias has
already accumulated,
.. math:: h_t = h_0 \exp\!\left(-\frac{V(s_t)}{k_B T (\gamma - 1)}\right)
which makes the sum converge instead of filling forever. At convergence
the free energy is recovered as
:math:`F(s) = -\frac{\gamma}{\gamma - 1} V(s)` (Barducci, Bussi &
Parrinello 2008), available from :meth:`free_energy`.
Passing ``bias_factor=None`` gives standard metadynamics — the
:math:`\gamma \to \infty` limit, where every hill has height ``h_0`` and
:math:`F(s) = -V(s)`.
Parameters
----------
cv:
Differentiable ``cv(batch) -> Tensor[B, D]``.
height:
Initial hill height ``h_0`` in eV.
sigma:
Hill width, either a scalar shared by every CV component or shape
``[D]``. Any other length is rejected on the first evaluation
rather than broadcast into the hill table.
temperature:
Simulation temperature in Kelvin, used for the well-tempered damping.
bias_factor:
``gamma > 1``, or ``None`` for standard metadynamics.
name:
Unique bias identifier.
frequency:
Dynamics steps between depositions (the deposition pace). The
:class:`~nvalchemi.hooks.Hook` attribute, with the meaning it has
everywhere else.
storage:
``"preallocated"``, ``"grow"``, or ``"fifo"`` — see Notes.
max_hills:
Capacity. Required for ``"preallocated"`` and ``"fifo"``; the
initial chunk for ``"grow"``.
history:
``"shared"`` (every walker sees every hill), ``"state"`` (hills
belong to the thermodynamic state that deposited them), or
``"walker"`` (each walker sees only its own).
``"state"`` and ``"walker"`` require the batch to carry
``thermodynamic_state_id`` / ``walker_id`` respectively, and raise if
it does not. :class:`~nvalchemi.enhanced_sampling.EnhancedSampling`
stamps both on every step, so a runner-driven bias never sees this;
a bias evaluated directly must supply the field itself.
periods:
Period per CV component, ``0`` for non-periodic, shape ``[D]``.
Applied to the ``s - c`` difference so a hill near a branch cut
still repels from both sides. Unlike ``sigma`` a scalar is not
accepted for a multi-component CV: the entries carry per-component
meaning, so broadcasting one across all of them would quietly make
every component periodic.
ramp_depositions:
Number of *deposition events* over which a freshly added hill ramps
from zero to full height. ``0`` activates immediately. Counted in
depositions rather than dynamics steps because ``energy()`` sees the
hill table, not the step counter.
compute_stress:
Passed through to :class:`ConservativeBias`.
Raises
------
ValueError
For an invalid storage policy, history mode, non-positive height or
width, ``bias_factor <= 1``, or a missing capacity. A ``sigma`` or
``periods`` length that disagrees with the CV is raised on first
evaluation, since the CV dimension is not knowable at construction
from a plain callable.
Notes
-----
Storage policies
``preallocated`` keeps tensor shapes fixed for the whole run and
**raises** when capacity is exhausted, rather than silently changing
the physics. It is the compile-stable choice.
``grow`` allocates in chunks of ``max_hills``; each growth changes
the hill-tensor shape, which forces a recompile if ``energy()`` is
compiled. Under torch's default of static parameter shapes, Dynamo
caps retraces per code object at
``torch._dynamo.config.recompile_limit`` (8), so a compiled run
**hard-fails once past it** — mid-trajectory, after the run is
already underway.
Both settings are process-global and other code changes them:
``DistributedModel`` raises the limit to 64 *and* sets
``force_parameter_static_shapes = False``. The second matters more
than the first — with dynamic parameter shapes the hill-table
dimension is traced symbolically, growth stops triggering a retrace,
and the limit is never reached. So the three ways out are: size
``max_hills`` so growths stay under the limit, enable dynamic
parameter shapes, or use ``preallocated``, which holds one trace for
the whole run regardless.
``fifo`` bounds memory by discarding the oldest hill. This is
**scientifically meaningful, not merely a cache eviction**: the
accumulated bias is no longer the integral of everything deposited,
so the well-tempered convergence argument no longer applies and
:meth:`free_energy` is not a valid estimator. Chosen deliberately
for exploration, and the natural policy for the RMSD variant.
Multi-walker history
``shared`` is the multiple-walker scheme: every walker feels every
hill, so ``B`` walkers fill a basin roughly ``B`` times faster.
``state`` keeps a separate history per thermodynamic state, which is
what a replica-exchange ladder needs. ``walker`` runs ``B``
independent metadynamics simulations in one batch.
Examples
--------
>>> import torch
>>> from nvalchemi.enhanced_sampling import (
... WellTemperedMetaDynamicsBias, pair_distance,
... )
>>> idx = torch.tensor([0, 5])
>>> bias = WellTemperedMetaDynamicsBias(
... cv=lambda b: pair_distance(b, idx),
... height=0.01, sigma=0.1, temperature=300.0, bias_factor=10.0,
... max_hills=1000,
... )
>>> bias.hill_count.item()
0
"""
# DepositHistoryMixin: what this bias calls a deposit, and which buffers
# hold the table. hill_centers comes first, so it supplies the device.
_deposit_noun = "hill"
_capacity_option = "max_hills"
_full_advice = (
"Raise max_hills, lengthen frequency, or switch to storage='grow' "
"(recompiles when it resizes) or storage='fifo' (bounded memory, but "
"discards the oldest hills and so is no longer a converging "
"well-tempered run)."
)
_deposit_buffers = (
("hill_centers", 0.0),
("hill_heights", 0.0),
("hill_owner", -1),
("hill_step", -1),
)
_written_attr = "hills_written"
_owner_attr = "hill_owner"
def __init__(
self,
cv: Callable[[Batch], Tensor],
height: float,
sigma: Tensor | float,
temperature: float,
*,
bias_factor: float | None = None,
name: str = "metadynamics",
frequency: int = 500,
storage: Literal["preallocated", "grow", "fifo"] = "preallocated",
max_hills: int | None = None,
history: Literal["shared", "state", "walker"] = "shared",
periods: Tensor | None = None,
ramp_depositions: int = 0,
compute_stress: bool = True,
) -> None:
super().__init__(name=name, compute_stress=compute_stress)
self.validate_history_options(storage, history)
if height <= 0.0:
raise ValueError(
f"WellTemperedMetaDynamicsBias: height must be positive, got "
f"{height}. A non-positive hill would attract the walker to "
"where it has already been."
)
if bias_factor is not None and bias_factor <= 1.0:
raise ValueError(
f"WellTemperedMetaDynamicsBias: bias_factor must be greater "
f"than 1, got {bias_factor}. gamma = 1 divides by zero in the "
"well-tempered height; pass None for standard metadynamics."
)
if int(frequency) < 1:
raise ValueError(
f"WellTemperedMetaDynamicsBias: frequency must be at least 1, "
f"got {frequency}."
)
if int(ramp_depositions) < 0:
raise ValueError(
f"WellTemperedMetaDynamicsBias: ramp_depositions must be "
f"non-negative, got {ramp_depositions}."
)
if storage in ("preallocated", "fifo") and max_hills is None:
raise ValueError(
f"WellTemperedMetaDynamicsBias: storage={storage!r} needs an "
"explicit max_hills — it is the whole point of the policy, "
"either the ceiling that raises or the ring that overwrites."
)
capacity = int(max_hills) if max_hills is not None else 256
if capacity < 1:
raise ValueError(
f"WellTemperedMetaDynamicsBias: max_hills must be at least 1, "
f"got {max_hills}."
)
sigma_t = torch.as_tensor(sigma, dtype=torch.get_default_dtype()).reshape(-1)
if bool((sigma_t <= 0).any()):
raise ValueError(
f"WellTemperedMetaDynamicsBias: sigma must be positive, got "
f"{sigma_t.tolist()}. A zero width is a delta function with no "
"gradient anywhere but one point."
)
self.cv = cv
self.storage = storage
self.history = history
self.frequency = int(frequency)
self.ramp_depositions = int(ramp_depositions)
self.height = float(height)
self.temperature = float(temperature)
self.bias_factor = None if bias_factor is None else float(bias_factor)
self._capacity = capacity
self.register_buffer("sigma", sigma_t)
if periods is None:
self.periods: Tensor | None = None
else:
self.register_buffer(
"periods",
torch.as_tensor(periods, dtype=torch.get_default_dtype()).reshape(-1),
)
self._allocate(capacity, dim=sigma_t.numel())
# This bias reads thermodynamic_state_id only in "state" history, and
# even then the hills follow the state rather than the energy varying
# by state at fixed history — but the assignment does change which
# hills a walker feels, so a temperature ladder would need the
# combined acceptance rule that is not implemented.
self.state_dependent_for_exchange = history == "state"
# ------------------------------------------------------------------
# Storage
# ------------------------------------------------------------------
def _allocate(self, capacity: int, dim: int) -> None:
"""Create or replace the hill buffers at *capacity*.
Parameters
----------
capacity:
Number of hill slots.
dim:
CV dimension.
"""
dtype = self.sigma.dtype
device = self.sigma.device
self.register_buffer(
"hill_centers", torch.zeros(capacity, dim, dtype=dtype, device=device)
)
self.register_buffer(
"hill_heights", torch.zeros(capacity, dtype=dtype, device=device)
)
self.register_buffer(
"hill_owner", torch.full((capacity,), -1, dtype=torch.long, device=device)
)
self.register_buffer(
"hill_step", torch.full((capacity,), -1, dtype=torch.long, device=device)
)
# hill_count saturates at capacity (how many slots are live);
# hills_written keeps counting, which is what makes the FIFO ring
# position unambiguous once it has wrapped.
self.register_buffer(
"hill_count", torch.zeros((), dtype=torch.long, device=device)
)
self.register_buffer(
"hills_written", torch.zeros((), dtype=torch.long, device=device)
)
self.register_buffer(
"deposits", torch.zeros((), dtype=torch.long, device=device)
)
# ------------------------------------------------------------------
# Energy
# ------------------------------------------------------------------
def _hill_scale(self, step: Tensor) -> Tensor:
"""Return each hill's ramp factor, shape ``[capacity]``.
A hill that switched on at full height would deliver a force
discontinuity at the deposition event; ramping over
``ramp_depositions`` spreads that over a window instead.
Parameters
----------
step:
Current deposition counter.
Returns
-------
Tensor
Factors in ``[0, 1]``.
"""
if self.ramp_depositions <= 0:
return torch.ones_like(self.hill_heights)
age = (step - self.hill_step).to(self.hill_heights.dtype)
return torch.clamp(age / float(self.ramp_depositions), min=0.0, max=1.0)
def _validate_cv(self, values: Tensor) -> int:
"""Check the CV output against ``sigma`` and ``periods``.
Every mismatch here is a *broadcast*, not an error: a CV of width one
against a two-component ``sigma`` broadcasts into a two-column hill
table, and the exponent then sums two terms instead of one. The
Gaussian silently narrows and nothing in the run reports it.
Only tensor ranks and element counts are inspected, so this is a
compile-time guard rather than a data-dependent branch and
:meth:`gaussian_sum` still traces with ``fullgraph=True``.
Parameters
----------
values:
CV values, expected shape ``[B, D]``.
Returns
-------
int
The CV dimension ``D``.
Raises
------
ValueError
If *values* is not rank 2, or if ``sigma`` or ``periods`` has an
element count that would broadcast against ``D`` rather than
match it.
"""
if values.ndim != 2:
raise ValueError(
f"WellTemperedMetaDynamicsBias {self.name!r}: cv must return "
f"shape [B, D], got {tuple(values.shape)}. A CV returning [B] "
"for a scalar collective variable needs an explicit trailing "
"dimension — return values.unsqueeze(-1)."
)
dim = int(values.shape[1])
if self.sigma.numel() not in (1, dim):
raise ValueError(
f"WellTemperedMetaDynamicsBias {self.name!r}: cv returns "
f"{dim} component(s) but sigma has {self.sigma.numel()}. "
"sigma must be a scalar (one width shared by every component) "
f"or have exactly {dim} entries; any other count broadcasts "
"into the hill table and silently changes the Gaussian."
)
if self.periods is not None and self.periods.numel() != dim:
raise ValueError(
f"WellTemperedMetaDynamicsBias {self.name!r}: cv returns "
f"{dim} component(s) but periods has "
f"{self.periods.numel()}. periods is per-component — a 0 entry "
"marks that component non-periodic — so it must have exactly "
f"{dim} entries rather than broadcast."
)
return dim
[docs]
def gaussian_sum(self, values: Tensor, owner_key: Tensor) -> Tensor:
"""Return the accumulated bias at *values*, shape ``[B]``.
Contains no data-dependent Python branch, so it compiles with
``fullgraph=True``: the live-hill mask comes from comparing an
``arange`` against the count tensor rather than slicing by an int.
Parameters
----------
values:
CV values, shape ``[B, D]``.
owner_key:
History key per graph, shape ``[B]``.
Returns
-------
Tensor
Bias energy per graph, shape ``[B]``.
Raises
------
ValueError
If *values* does not agree with ``sigma`` and ``periods``; see
:meth:`_validate_cv`.
"""
dim = self._validate_cv(values)
if self.hill_centers.shape[1] != dim:
# The hill table is still at its provisional width, which only
# happens before the first deposition resolves the CV dimension.
# An empty history contributes nothing whatever the width is.
return values.new_zeros(values.shape[0])
slots = torch.arange(self.hill_centers.shape[0], device=values.device)
live = slots < self.hill_count
delta = periodic_difference(
values.unsqueeze(1), # [B, 1, D]
self.hill_centers.unsqueeze(0), # [1, H, D]
self.periods,
) # [B, H, D]
exponent = 0.5 * ((delta / self.sigma) ** 2).sum(dim=-1) # [B, H]
gaussians = torch.exp(-exponent)
scale = self._hill_scale(self.deposits) # [H]
weights = self.hill_heights * scale # [H]
mask = live.unsqueeze(0) # [1, H]
if self.history != "shared":
mask = mask & (self.hill_owner.unsqueeze(0) == owner_key.unsqueeze(1))
return (gaussians * weights.unsqueeze(0) * mask).sum(dim=-1)
[docs]
def energy(self, current: Batch) -> Tensor:
"""Return the accumulated metadynamics bias, shape ``[B, 1]``.
Parameters
----------
current:
Batch with strained positions supplied by
:meth:`ConservativeBias.evaluate`.
Returns
-------
Tensor
Shape ``[B, 1]`` in eV.
"""
values = self.cv(current)
owner = self._owner_key(current, values.shape[0])
return self.gaussian_sum(values, owner).unsqueeze(-1)
# ------------------------------------------------------------------
# Deposition
# ------------------------------------------------------------------
def _well_tempered_height(self, bias_at_cv: Tensor) -> Tensor:
"""Return the damped hill height per walker.
Parameters
----------
bias_at_cv:
Accumulated bias at the deposition point, shape ``[B]``.
Returns
-------
Tensor
Heights, shape ``[B]``.
"""
if self.bias_factor is None:
return torch.full_like(bias_at_cv, self.height)
damping = KB_EV * self.temperature * (self.bias_factor - 1.0)
return self.height * torch.exp(-bias_at_cv / damping)
[docs]
def update(self, ctx: BiasContext, stage: DynamicsStage) -> None:
"""Deposit one hill per walker at its current CV value.
Parameters
----------
ctx:
The capture. ``ctx.batch`` is the post-step frame; the bias's own
preceding contribution is on ``ctx.contribution``.
stage:
The stage being dispatched, always :attr:`stage`.
Raises
------
ValueError
If the CV output disagrees with ``sigma`` or ``periods``.
RuntimeError
If the CV changes dimension part-way through a run, which would
silently invalidate every hill already deposited.
"""
frames = ctx.batch
with torch.no_grad():
values = self.cv(frames).detach() # [B, D]
owner = self._owner_key(frames, values.shape[0])
bias_at_cv = self.gaussian_sum(values, owner)
heights = self._well_tempered_height(bias_at_cv)
count = values.shape[0]
dim = int(values.shape[1])
if self.hill_centers.shape[1] != dim:
# The constructor sizes the hill table from sigma, which is
# only right when sigma is per-component; a scalar sigma says
# nothing about the CV width. The first deposition is where
# the true dimension becomes known.
if int(self.hill_count) != 0:
raise RuntimeError(
f"WellTemperedMetaDynamicsBias {self.name!r}: cv "
f"returned {dim} component(s) but the "
f"{int(self.hill_count)} hill(s) already deposited "
f"have {self.hill_centers.shape[1]}. A collective "
"variable must keep its dimension for the whole run — "
"the existing history is not comparable otherwise."
)
self._allocate(self.capacity, dim)
slots = self._next_slots(count)
self.hill_centers[slots] = values.to(self.hill_centers.dtype)
self.hill_heights[slots] = heights.to(self.hill_heights.dtype)
self.hill_owner[slots] = owner
self.hill_step[slots] = self.deposits
self.deposits += 1
self.hills_written += count
self.hill_count = torch.clamp(self.hills_written, max=self.capacity)
self.bump_state_version()
# ------------------------------------------------------------------
# Analysis
# ------------------------------------------------------------------
[docs]
def free_energy(self, values: Tensor, owner_key: Tensor | None = None) -> Tensor:
"""Return the free-energy estimate at *values*.
``F(s) = -(gamma / (gamma - 1)) V(s)`` for well-tempered, or
``F(s) = -V(s)`` for standard metadynamics.
Parameters
----------
values:
CV values, shape ``[B, D]``.
owner_key:
History key per graph. Defaults to the shared history.
Returns
-------
Tensor
Free energy in eV, shape ``[B]``, up to an additive constant.
Raises
------
ValueError
If *values* does not match the deposited hills' dimension, or
disagrees with ``sigma`` or ``periods``.
RuntimeError
Under ``storage="fifo"``, where discarded hills mean the
accumulated bias is no longer the integral of everything
deposited and the well-tempered relation does not hold.
"""
if self.storage == "fifo":
raise RuntimeError(
f"WellTemperedMetaDynamicsBias {self.name!r}: free_energy() is "
"not valid under storage='fifo'. Discarding the oldest hills "
"means the accumulated bias is no longer the integral of "
"everything deposited, so the well-tempered relation between "
"bias and free energy does not hold. Use 'preallocated' or "
"'grow' for a run you intend to reconstruct a profile from."
)
# gaussian_sum answers a width mismatch with zeros, which is right for
# an empty history on the force path but reads as a flat profile here.
dim = self._validate_cv(values)
if int(self.hill_count) and self.hill_centers.shape[1] != dim:
raise ValueError(
f"WellTemperedMetaDynamicsBias {self.name!r}: free_energy() "
f"was given {dim}-component values but the deposited hills "
f"have {self.hill_centers.shape[1]}. Evaluating the profile "
"on a grid of the wrong width would return zeros, which is "
"indistinguishable from a flat free energy."
)
if owner_key is None:
owner_key = torch.full(
(values.shape[0],),
-1 if self.history == "shared" else 0,
dtype=torch.long,
device=values.device,
)
bias = self.gaussian_sum(values, owner_key)
if self.bias_factor is None:
return -bias
return -bias * (self.bias_factor / (self.bias_factor - 1.0))
[docs]
def config_fingerprint(self) -> dict[str, Any]:
"""Return the settings the deposited hills are only valid under.
``sigma`` and ``periods`` are held as buffers, so without this check
``nn.Module.load_state_dict`` would replace the caller's values with
the checkpoint's rather than reject the mismatch. ``bias_factor``
and ``temperature`` set the well-tempered damping the stored heights
were computed under, and the ratio ``free_energy`` applies to them.
``storage`` and ``history`` decide retention and ownership.
``max_hills`` is deliberately absent: ``grow`` legitimately reaches a
capacity the constructor never had, and :meth:`load_state_dict`
already resizes to match.
Returns
-------
dict[str, Any]
The checked configuration.
"""
return {
"height": self.height,
"sigma": self.sigma.reshape(-1).tolist(),
"temperature": self.temperature,
"bias_factor": self.bias_factor,
"storage": self.storage,
"history": self.history,
"ramp_depositions": self.ramp_depositions,
"periods": None
if self.periods is None
else self.periods.reshape(-1).tolist(),
}
[docs]
def load_state_dict(
self, state: Mapping[str, Any], *args: Any, **kwargs: Any
) -> Any:
"""Restore state, resizing the hill buffers to match the checkpoint.
``storage="grow"`` means the saved capacity is whatever the run had
reached, which is almost never the constructor's initial chunk —
``nn.Module.load_state_dict`` would reject the size mismatch.
Parameters
----------
state:
Mapping from :meth:`state_dict`.
*args, **kwargs:
Forwarded up the MRO.
Returns
-------
Any
Whatever the next ``load_state_dict`` returns.
"""
centers = state.get("hill_centers")
if centers is not None and tuple(centers.shape) != tuple(
self.hill_centers.shape
):
self._allocate(int(centers.shape[0]), int(centers.shape[1]))
return super().load_state_dict(state, *args, **kwargs)
def __repr__(self) -> str:
"""Return a concise description of the bias."""
gamma = "None" if self.bias_factor is None else f"{self.bias_factor:g}"
return (
f"{type(self).__name__}(name={self.name!r}, "
f"hills={int(self.hill_count)}/{self.capacity}, "
f"storage={self.storage!r}, history={self.history!r}, "
f"bias_factor={gamma})"
)