nvalchemi.enhanced_sampling.HarmonicUmbrellaBias#

class nvalchemi.enhanced_sampling.HarmonicUmbrellaBias(cv, centers, stiffness, *, name='umbrella', periods=None, compute_stress=True)[source]#

Multi-dimensional harmonic restraint on one or more collective variables.

\[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 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.

param cv:

Any differentiable cv(batch) -> Tensor[B, D]. A plain callable; no base class, no registration.

param centers:

Window centers. Shape [D] (shared) or [S, D] (per state).

param 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

param name:

Unique bias identifier.

param periods:

Period per CV component, shape [D]; 0 marks a non-periodic component. See periodic_difference().

param compute_stress:

Passed through to 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])
energy(current)[source]#

Return the harmonic restraint energy [B, 1] in eV.

Parameters:

current (Batch) – Batch with strained positions supplied by isolated_energy_derivatives().

Returns:

Shape [B, 1].

Return type:

Tensor

extra_repr()#

Format the model config for nn.Module.__repr__.

Parameters:

self (Any)

Return type:

str

forward(data, **kwargs)[source]#

Validate the state ids, then derive energy, forces, and stress.

Parameters:
Returns:

As ConservativeBias.forward().

Return type:

ModelOutputs

Raises:

IndexError – If a thermodynamic_state_id is out of range.

Parameters:
  • cv (Callable[[Batch], Tensor])

  • centers (Tensor | float)

  • stiffness (Tensor | float)

  • name (str)

  • periods (Tensor | None)

  • compute_stress (bool)