# 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.
"""The ``StatefulHook`` battery for biases whose state evolves during sampling.
``AdaptivePotentialMixin`` supplies the
:class:`~nvalchemi.hooks.StatefulHook` half of a bias: ``frequency``,
``stage``, ``read_only``, ``commit``, ``state_dict`` and ``load_state_dict``.
It deliberately invents none of those names. "Read-only while forces are
computed, mutate after the step, synchronise occasionally" is not specific to
enhanced sampling — it is equally the shape of NEB's climbing-image promotion,
an adaptive thermostat, and an adaptive neighbour skin — so the vocabulary
lives in :mod:`nvalchemi.hooks` and this module only fills it in.
It carries no energy, no forces, and no model half. A bias that is adaptive
*and* conservative mixes in both this and
:class:`~nvalchemi.enhanced_sampling.ConservativeBias`; a bias that is adaptive
and non-conservative (ABF) mixes in only this one.
"""
from __future__ import annotations
import math
from typing import TYPE_CHECKING, Any
import torch
from torch import nn
from nvalchemi.dynamics.base import DynamicsStage
from nvalchemi.models._utils import STATE_VERSION_KEY
if TYPE_CHECKING:
from collections.abc import Mapping
from nvalchemi._typing import ModelOutputs
from nvalchemi.data import AtomicData, Batch
from nvalchemi.hooks import BiasContext
__all__ = ["AdaptivePotentialMixin"]
def _values_agree(left: Any, right: Any) -> bool:
"""Return whether two fingerprint entries describe the same setting.
Floats are compared with a relative tolerance so that storing a value
through float32 and reading it back does not read as a configuration
change, while a real difference (0.2 against 0.9) still does.
Parameters
----------
left, right:
Fingerprint entries: scalars, strings, ``None``, or flat sequences.
Returns
-------
bool
``True`` when the two agree.
"""
if isinstance(left, (list, tuple)) and isinstance(right, (list, tuple)):
return len(left) == len(right) and all(
_values_agree(a, b) for a, b in zip(left, right, strict=True)
)
if isinstance(left, bool) or isinstance(right, bool):
return left is right
if isinstance(left, (int, float)) and isinstance(right, (int, float)):
return math.isclose(float(left), float(right), rel_tol=1e-6, abs_tol=1e-12)
return bool(left == right)
[docs]
class AdaptivePotentialMixin:
"""Mixin for a bias whose state changes as sampling proceeds.
Mix in alongside whatever else applies, **this mixin first**::
class WellTemperedMetaDynamicsBias(AdaptivePotentialMixin, ConservativeBias):
... # conservative and adaptive
class AdaptiveBiasingForce(AdaptivePotentialMixin, nn.Module, BaseModelMixin):
... # adaptive, but no energy to differentiate
Order matters and is enforced. :class:`ConservativeBias` inherits
``nn.Module``, which already defines ``state_dict`` / ``load_state_dict``
for buffers; putting this mixin second would let those shadow the ones here
and silently drop the bias history from every checkpoint. With the mixin
first, :meth:`state_dict` calls up the MRO and merges both.
``__init_subclass__`` raises ``TypeError`` on the wrong order rather than
letting a checkpoint quietly lose data.
Attributes
----------
frequency:
Dynamics steps between :meth:`update` calls; ``1`` means every step.
The :class:`~nvalchemi.hooks.Hook` attribute, with the meaning it has
everywhere else.
stage:
Which :class:`~nvalchemi.dynamics.base.DynamicsStage` the frame handed
to :meth:`update` is captured at.
* ``AFTER_STEP`` (default) — post-step coordinates. What metadynamics
wants: a hill is deposited at the configuration the system actually
reached.
* ``AFTER_COMPUTE`` — captured while ``batch.forces`` still holds the
**unbiased** physical forces, before any bias contribution is added.
What ABF requires; observing biased forces would feed the estimator
its own output.
read_only:
``False``: :meth:`update` mutates bias state, so the runner delivers it
exactly once per due step and never during force priming or a
speculative re-evaluation.
Notes
-----
Why ``update`` rather than ``__call__``
A ``Hook`` is dispatched through ``__call__(ctx, stage)``, but a bias
is also an ``nn.Module`` whose ``__call__`` is the model forward that
``BaseDynamics`` and ``PipelineModelWrapper`` both invoke. One name
cannot be both. The house resolution is the one
:class:`~nvalchemi.training.hooks.update.TrainingUpdateHook` already
uses: a domain hook family keeps the signature its semantics need, and
an orchestrator owns protocol compliance on its behalf. Here that
orchestrator is the single composite hook ``EnhancedSampling``
installs, which reads :attr:`frequency` and :attr:`stage` and
dispatches :meth:`update` and :meth:`commit`.
State version
:meth:`bump_state_version` records that the bias changed. The runner
reads :attr:`state_version` to decide whether forces in the batch are
stale and need re-priming, and :meth:`stamp_state_version` publishes it
per graph as the ``state_version`` entry of the bias's
:data:`~nvalchemi._typing.ModelOutputs`. It is also checkpointed per
bias, ready for validating that an accepted replica-exchange state
assignment is coherent — which the exchange does not consume yet. A
bias that mutates state inside :meth:`update` must call it.
"""
frequency: int = 1
stage: DynamicsStage = DynamicsStage.AFTER_STEP
read_only: bool = False
# Incremented by bump_state_version(); never reset.
_state_version: int = 0
def __init_subclass__(cls, **kwargs: Any) -> None:
"""Reject an MRO that would let ``nn.Module`` shadow this mixin.
Parameters
----------
**kwargs:
Forwarded cooperatively up the MRO.
Raises
------
TypeError
If ``nn.Module`` precedes this mixin, which would make
:meth:`state_dict` unreachable and drop bias history from
checkpoints without any error.
"""
super().__init_subclass__(**kwargs)
mro = cls.__mro__
if nn.Module in mro and mro.index(AdaptivePotentialMixin) > mro.index(
nn.Module
):
raise TypeError(
f"{cls.__name__}: AdaptivePotentialMixin must come before "
f"nn.Module (and therefore before ConservativeBias) in the "
f"base list, otherwise nn.Module.state_dict shadows the "
f"mixin's and the bias history is silently dropped from "
f"checkpoints. Write "
f"'class {cls.__name__}(AdaptivePotentialMixin, ConservativeBias)'."
)
@property
def state_version(self) -> int:
"""Monotonic counter of state-changing updates applied to this bias."""
return self._state_version
[docs]
def bump_state_version(self) -> None:
"""Record that the bias state changed.
Call from :meth:`update` whenever the change affects the energy the
next forward pass will return. An update that only accumulates
statistics without changing the applied bias (an ABF bin below its
minimum-sample threshold, say) should **not** bump — bumping forces the
runner to re-prime forces for no reason.
"""
self._state_version += 1
[docs]
def stamp_state_version(
self, outputs: ModelOutputs, data: AtomicData | Batch
) -> ModelOutputs:
"""Add this bias's state revision to *outputs*, one entry per graph.
Parameters
----------
outputs:
The contribution to stamp; mutated in place and returned.
data:
The batch the contribution was computed for, read for
``num_graphs`` and device.
Returns
-------
ModelOutputs
*outputs*, with a ``state_version`` entry of shape ``[B]``.
"""
outputs[STATE_VERSION_KEY] = torch.full(
(int(getattr(data, "num_graphs", 1)),),
self._state_version,
dtype=torch.long,
device=data.positions.device,
)
return outputs
[docs]
def forward(self, data: AtomicData | Batch, **kwargs: Any) -> ModelOutputs:
"""Stamp the state version onto the contribution from further up the MRO.
Cooperative: mixed in before :class:`ConservativeBias` this calls that
class's ``forward`` and adds ``state_version`` to what it returned. A
bias with no conservative half defines its own ``forward`` and calls
:meth:`stamp_state_version` directly.
Parameters
----------
data:
The live batch.
**kwargs:
Forwarded to the next ``forward`` in the MRO.
Returns
-------
ModelOutputs
The contribution, with ``state_version`` added.
"""
outputs: ModelOutputs = super().forward(data, **kwargs) # type: ignore[misc]
return self.stamp_state_version(outputs, data)
[docs]
def update(self, ctx: BiasContext, stage: DynamicsStage) -> None:
"""Consume a captured frame, once per due step.
Called by the runner's composite hook when
``step % frequency == 0`` and ``stage is self.stage``. Free to mutate
state, allocate, grow storage, and communicate — none of this is on the
compiled path.
Parameters
----------
ctx:
The capture. ``ctx.batch`` is the observed frame, stamped by the
runner with ``walker_id``, ``thermodynamic_state_id`` and
``sampling_step``; ``ctx.contribution`` is what this bias returned
during the preceding force evaluation.
stage:
The stage being dispatched, always equal to :attr:`stage`.
Raises
------
NotImplementedError
If the subclass does not override.
"""
raise NotImplementedError(
f"{type(self).__name__} mixes in AdaptivePotentialMixin but does "
"not implement update(ctx, stage)."
)
[docs]
def commit(self) -> None:
"""Synchronise pending state at a consistency-epoch boundary.
The :class:`~nvalchemi.hooks.StatefulHook` synchronisation boundary.
Default is a no-op: a bias whose history is local to one walker needs
no synchronisation. Multi-walker shared-history biases override this
to publish and merge. Called only at epoch boundaries, never on the
hot path, and at most once per boundary.
"""
return None
[docs]
def config_fingerprint(self) -> Mapping[str, Any]:
"""Return the constructor configuration the saved state depends on.
Default is empty, which disables the check. A bias whose persisted
state is only meaningful under the settings that produced it should
override this and list them.
The distinction is between *state* and *configuration*. An ABF
histogram is state; the ``cv_range`` that decides what its bins mean is
configuration. Restoring the first without the second silently
reinterprets every bin — bin 5 stops meaning ``r = 1.55`` and starts
meaning ``r = 3.1``, with the same numbers in it.
Include configuration held as a **buffer** too. ``nn.Module`` restores
buffers by overwriting, so without the check a mismatched setting is
not merely unvalidated: the caller's value is silently replaced by the
checkpoint's, which is the opposite of what asking for it meant.
Returns
-------
Mapping[str, Any]
Zarr-representable scalars, strings, ``None``, or flat sequences of
those. Tensors must be converted to lists.
"""
return {}
def _check_config_fingerprint(self, saved: Mapping[str, Any]) -> None:
"""Reject a saved fingerprint that disagrees with this bias.
Parameters
----------
saved:
The fingerprint recorded when the state was written.
Raises
------
ValueError
If any recorded setting differs from the live one.
"""
live = dict(self.config_fingerprint())
differences = []
for key in sorted(set(saved) | set(live)):
was, now = saved.get(key, "<absent>"), live.get(key, "<absent>")
if not _values_agree(was, now):
differences.append(f" {key}: checkpoint {was!r} vs bias {now!r}")
if differences:
raise ValueError(
f"{type(self).__name__} "
f"{getattr(self, 'name', '<unnamed>')!r}: the saved state was "
f"produced under a different configuration:\n"
+ "\n".join(differences)
+ "\nThe stored state is only meaningful under the settings "
"that produced it, so restoring it here would reinterpret it "
"rather than continue it. Rebuild the bias with the "
"checkpoint's configuration, or start a fresh run."
)
[docs]
def state_dict(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
"""Return the bias state for checkpointing, merged up the MRO.
Cooperative: when mixed into an ``nn.Module`` bias this calls
``nn.Module.state_dict`` first, so buffers (umbrella centers, wall
thresholds) and bias history land in one mapping. A bias with real
history (hills, reference frames, ABF bins) overrides this, calls
``super().state_dict()``, and adds its own entries.
Parameters
----------
*args, **kwargs:
Forwarded to the next ``state_dict`` in the MRO, if any.
Returns
-------
dict[str, Any]
Zarr-representable state, always including ``state_version`` and,
when :meth:`config_fingerprint` is overridden, the configuration
that state is only meaningful under.
"""
parent = getattr(super(), "state_dict", None)
state: dict[str, Any] = dict(parent(*args, **kwargs)) if parent else {}
state["state_version"] = self._state_version
fingerprint = dict(self.config_fingerprint())
if fingerprint:
state["config_fingerprint"] = fingerprint
return state
[docs]
def load_state_dict(
self, state: Mapping[str, Any], *args: Any, **kwargs: Any
) -> Any:
"""Restore bias state produced by :meth:`state_dict`.
Strips the mixin's own keys before delegating, so that
``nn.Module.load_state_dict`` does not reject them as unexpected under
its default ``strict=True``. A recorded :meth:`config_fingerprint` is
checked *before* delegating, since the delegate overwrites buffers and
a check afterwards would come too late to stop the caller's
configuration being replaced.
Parameters
----------
state:
The mapping previously returned by :meth:`state_dict`.
*args, **kwargs:
Forwarded to the next ``load_state_dict`` in the MRO, if any.
Returns
-------
Any
Whatever the next ``load_state_dict`` returns, or ``None``.
Raises
------
ValueError
If the state was written under a different
:meth:`config_fingerprint`.
"""
remaining = dict(state)
self._state_version = int(remaining.pop("state_version", 0))
saved = remaining.pop("config_fingerprint", None)
if saved is not None:
# Before delegating: nn.Module.load_state_dict overwrites buffers,
# so a mismatch caught afterwards would already have replaced the
# caller's configuration with the checkpoint's.
self._check_config_fingerprint(saved)
parent = getattr(super(), "load_state_dict", None)
if parent is not None:
return parent(remaining, *args, **kwargs)
return None