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_0the window center, andKthe stiffness matrix. Forces and stress come fromConservativeBias, so they are guaranteed consistent with this energy.Per-state parameters#
centersandstiffnessmay carry a leading state dimensionS. Each graph then selects its row bybatch.thermodynamic_state_id, which is what makes a batch of umbrella windows a single batched run rather thanSseparate simulations. Without that field every graph uses state0.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];0marks a non-periodic component. Seeperiodic_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:
data (Batch) – The live batch.
**kwargs (Any) – Forwarded to
ConservativeBias.forward().
- Returns:
- Return type:
ModelOutputs
- Raises:
IndexError – If a
thermodynamic_state_idis out of range.
- Parameters:
cv (Callable[[Batch], Tensor])
centers (Tensor | float)
stiffness (Tensor | float)
name (str)
periods (Tensor | None)
compute_stress (bool)