# 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.
"""Harmonic umbrella bias for umbrella sampling."""
from __future__ import annotations
from typing import TYPE_CHECKING, Any
import torch
from torch import Tensor
from nvalchemi.enhanced_sampling._bias import ConservativeBias
from nvalchemi.enhanced_sampling.cv._periodic import periodic_difference
if TYPE_CHECKING:
from collections.abc import Callable
from nvalchemi._typing import ModelOutputs
from nvalchemi.data import Batch
__all__ = ["HarmonicUmbrellaBias"]
[docs]
class HarmonicUmbrellaBias(ConservativeBias):
r"""Multi-dimensional harmonic restraint on one or more collective variables.
.. math::
E_b = \tfrac{1}{2}\,\Delta^\top K \,\Delta,
\qquad \Delta = s(x) - s_0
with ``s(x)`` the CV value, ``s_0`` the window center, and ``K`` the
stiffness matrix. Forces and stress come from
:class:`~nvalchemi.enhanced_sampling.ConservativeBias`, so they are
guaranteed consistent with this energy.
Per-state parameters
--------------------
``centers`` and ``stiffness`` may carry a leading state dimension ``S``.
Each graph then selects its row by ``batch.thermodynamic_state_id``,
which is what makes a batch of umbrella windows a single batched run
rather than ``S`` separate simulations. Without that field every graph
uses state ``0``.
A **single-window** bias ignores the field entirely rather than treating
it as an index. That is what lets one shared restraint run alongside a
multi-rung temperature ladder, where the ids address the ladder and have
nothing to do with windows.
Parameters
----------
cv:
Any differentiable ``cv(batch) -> Tensor[B, D]``. A plain callable;
no base class, no registration.
centers:
Window centers. Shape ``[D]`` (shared) or ``[S, D]`` (per state).
stiffness:
Force constants, in energy per CV-unit squared. Accepted as:
* scalar — isotropic, ``k·I``
* ``[D]`` — diagonal
* ``[D, D]`` — full matrix, shared across states
* ``[S, D, D]`` — full matrix per state
name:
Unique bias identifier.
periods:
Period per CV component, shape ``[D]``; ``0`` marks a non-periodic
component. See
:func:`~nvalchemi.enhanced_sampling.cv._periodic.periodic_difference`.
compute_stress:
Passed through to :class:`ConservativeBias`.
Raises
------
ValueError
If shapes are inconsistent, or if a stiffness matrix is not
symmetric positive-semidefinite.
Examples
--------
>>> import torch
>>> from nvalchemi.enhanced_sampling import HarmonicUmbrellaBias, pair_distance
>>> idx = torch.tensor([0, 5])
>>> bias = HarmonicUmbrellaBias(
... cv=lambda b: pair_distance(b, idx),
... centers=torch.tensor([[2.0], [2.5], [3.0]]), # 3 windows
... stiffness=10.0, # eV/A^2
... )
>>> bias.centers.shape
torch.Size([3, 1])
"""
def __init__(
self,
cv: Callable[[Batch], Tensor],
centers: Tensor | float,
stiffness: Tensor | float,
*,
name: str = "umbrella",
periods: Tensor | None = None,
compute_stress: bool = True,
) -> None:
super().__init__(name=name, compute_stress=compute_stress)
self.cv = cv
centers_t = torch.as_tensor(centers, dtype=torch.get_default_dtype())
if centers_t.ndim == 0:
centers_t = centers_t.reshape(1, 1)
elif centers_t.ndim == 1:
centers_t = centers_t.unsqueeze(0) # [D] -> [1, D]
elif centers_t.ndim != 2:
raise ValueError(
f"HarmonicUmbrellaBias: centers must be [D] or [S, D], got "
f"shape {tuple(centers_t.shape)}."
)
n_states, dim = centers_t.shape
stiffness_t = self._expand_stiffness(stiffness, n_states, dim)
self._validate_stiffness(stiffness_t)
# A multi-window bias reads thermodynamic_state_id, so its energy
# depends on the assignment. Replica exchange needs to know: combining
# it with a temperature ladder would need cross-state bias terms that
# the temperature acceptance rule does not compute.
self.state_dependent_for_exchange = n_states > 1
# Buffers, not plain attributes: nn.Module then moves them with .to()
# and round-trips them through state_dict.
self.register_buffer("centers", centers_t)
self.register_buffer("stiffness", stiffness_t)
if periods is None:
self.periods: Tensor | None = None
else:
periods_t = torch.as_tensor(
periods, dtype=torch.get_default_dtype()
).reshape(-1)
if periods_t.numel() != dim:
raise ValueError(
f"HarmonicUmbrellaBias: periods must have {dim} entries to "
f"match the CV dimension, got {periods_t.numel()}."
)
self.register_buffer("periods", periods_t)
@staticmethod
def _expand_stiffness(stiffness: Tensor | float, n_states: int, dim: int) -> Tensor:
"""Broadcast any accepted stiffness form to ``[S, D, D]``.
Parameters
----------
stiffness:
Scalar, ``[D]``, ``[D, D]``, or ``[S, D, D]``.
n_states:
Number of thermodynamic states ``S``.
dim:
CV dimension ``D``.
Returns
-------
Tensor
Shape ``[S, D, D]``.
Raises
------
ValueError
If the shape is none of the accepted forms.
"""
k = torch.as_tensor(stiffness, dtype=torch.get_default_dtype())
eye = torch.eye(dim, dtype=k.dtype)
if k.ndim == 0:
full = k * eye
elif k.ndim == 1:
if k.numel() != dim:
raise ValueError(
f"HarmonicUmbrellaBias: diagonal stiffness must have {dim} "
f"entries to match the CV dimension, got {k.numel()}."
)
full = torch.diag(k)
elif k.ndim == 2:
if k.shape != (dim, dim):
raise ValueError(
f"HarmonicUmbrellaBias: matrix stiffness must be "
f"[{dim}, {dim}], got {tuple(k.shape)}."
)
full = k
elif k.ndim == 3:
if k.shape != (n_states, dim, dim):
raise ValueError(
f"HarmonicUmbrellaBias: per-state stiffness must be "
f"[{n_states}, {dim}, {dim}] to match centers, got "
f"{tuple(k.shape)}."
)
return k.clone()
else:
raise ValueError(
f"HarmonicUmbrellaBias: stiffness must be scalar, [D], [D, D], "
f"or [S, D, D]; got shape {tuple(k.shape)}."
)
return full.unsqueeze(0).expand(n_states, dim, dim).clone()
@staticmethod
def _validate_stiffness(stiffness: Tensor) -> None:
"""Reject a stiffness that is not symmetric positive-semidefinite.
An asymmetric ``K`` makes the quadratic form ambiguous, and a
negative eigenvalue turns the restraint into a repulsion that drives
the CV away without bound — a runaway that is far cheaper to catch
here than to diagnose from a diverging trajectory.
Parameters
----------
stiffness:
Shape ``[S, D, D]``.
Raises
------
ValueError
If any state's matrix is asymmetric or has a negative eigenvalue.
"""
if not torch.allclose(stiffness, stiffness.mT, atol=1e-8):
raise ValueError(
"HarmonicUmbrellaBias: stiffness must be symmetric; got a "
"matrix that differs from its transpose."
)
eigenvalues = torch.linalg.eigvalsh(stiffness.double())
if bool((eigenvalues < -1e-8).any()):
worst = float(eigenvalues.min())
raise ValueError(
f"HarmonicUmbrellaBias: stiffness must be positive-semidefinite; "
f"smallest eigenvalue is {worst:.6g}. A negative eigenvalue makes "
"the restraint repulsive along that direction."
)
def _validate_state_ids(self, current: Batch) -> None:
"""Raise if any ``thermodynamic_state_id`` is out of range.
Called from :meth:`forward`, never from :meth:`energy`. That
placement is deliberate: ``energy()`` is the path
``EnhancedSampling(compile_biases=True)`` hands to ``torch.compile``,
and ``bool(tensor.any())`` there is a data-dependent Python branch
that breaks ``fullgraph=True`` outright. ``forward()`` is eager by
construction, so hoisting the check keeps it running in **every**
mode, rather than skipping it under compile the way the eager-only
guards in ``pair_distance`` must.
Parameters
----------
current:
The batch; read for ``thermodynamic_state_id`` if present.
Raises
------
IndexError
If a state id is negative or beyond the configured windows.
"""
state_ids = getattr(current, "thermodynamic_state_id", None)
if state_ids is None or self.centers.shape[0] == 1:
# A single-window bias selects nothing, so the field is not an
# index into it. This is the legitimate combination of one shared
# restraint with a multi-rung temperature ladder, where the ids
# address the ladder rather than the windows.
return
index = state_ids.reshape(-1).to(torch.long)
n_states = self.centers.shape[0]
out_of_range = (index < 0) | (index >= n_states)
if bool(out_of_range.any()):
bad = out_of_range.nonzero(as_tuple=False).squeeze(-1).tolist()
raise IndexError(
f"HarmonicUmbrellaBias: thermodynamic_state_id out of range for "
f"{n_states} configured window(s). Graph(s) {bad} have "
f"{index[out_of_range].tolist()}; valid ids are 0..{n_states - 1}."
)
[docs]
def forward(self, data: Batch, **kwargs: Any) -> ModelOutputs:
"""Validate the state ids, then derive energy, forces, and stress.
Parameters
----------
data:
The live batch.
**kwargs:
Forwarded to :meth:`ConservativeBias.forward`.
Returns
-------
ModelOutputs
As :meth:`ConservativeBias.forward`.
Raises
------
IndexError
If a ``thermodynamic_state_id`` is out of range.
"""
self._validate_state_ids(data)
return super().forward(data, **kwargs)
def _select_per_graph(
self, current: Batch, values: Tensor
) -> tuple[Tensor, Tensor]:
"""Return ``(centers, stiffness)`` broadcast to this batch.
Contains no data-dependent Python branch, so it compiles with
``fullgraph=True``. Bounds checking lives in
:meth:`_validate_state_ids`, which :meth:`forward` runs first.
Parameters
----------
current:
The batch; read for ``thermodynamic_state_id`` if present.
values:
CV values ``[B, D]``, used for shape and device.
Returns
-------
tuple[Tensor, Tensor]
``centers`` ``[B, D]`` and ``stiffness`` ``[B, D, D]``.
"""
state_ids = getattr(current, "thermodynamic_state_id", None)
if state_ids is None or self.centers.shape[0] == 1:
index = torch.zeros(values.shape[0], dtype=torch.long, device=values.device)
else:
index = state_ids.reshape(-1).to(torch.long)
return self.centers[index], self.stiffness[index]
[docs]
def energy(self, current: Batch) -> Tensor:
"""Return the harmonic restraint energy ``[B, 1]`` in eV.
Parameters
----------
current:
Batch with strained positions supplied by
:func:`~nvalchemi.models._utils.isolated_energy_derivatives`.
Returns
-------
Tensor
Shape ``[B, 1]``.
"""
values = self.cv(current) # [B, D]
centers, stiffness = self._select_per_graph(current, values)
delta = periodic_difference(values, centers, self.periods) # [B, D]
quadratic = torch.einsum("bi,bij,bj->b", delta, stiffness, delta)
return 0.5 * quadratic.unsqueeze(-1) # [B, 1]