# 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.
"""``EnhancedSampling``: the ``DynamicsStrategy`` that runs biased dynamics.
A biased run differs from a plain one only in *what it configures*: the same
engine, plus hooks for walker identity, bias forces, shared-history commits
and replica-exchange attempts. That is exactly what a
:class:`~nvalchemi.dynamics.DynamicsStrategy` expresses, so this
module contributes a :meth:`~EnhancedSampling.build_hooks` override and the
restart machinery around it — never a second stepping loop. The hooks
themselves live in :mod:`nvalchemi.enhanced_sampling.hooks`.
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Any
import torch
from pydantic import Field, PrivateAttr, model_validator
from nvalchemi._checkpoint import (
CheckpointManifest,
Stateful,
_qualified_name,
load_checkpoint,
save_checkpoint,
)
from nvalchemi.dynamics.base import BaseDynamics
from nvalchemi.dynamics.hooks.swap import PairSwapHook
from nvalchemi.dynamics.strategy import DynamicsStrategy
from nvalchemi.enhanced_sampling._exchange import ReplicaExchange
from nvalchemi.enhanced_sampling.hooks import (
BiasHook,
EpochCommitHook,
WalkerIdentityHook,
)
from nvalchemi.models.base import BaseModelMixin
if TYPE_CHECKING:
from collections.abc import Mapping, Sequence
from pathlib import Path
from nvalchemi.data import Batch
from nvalchemi.hooks import Hook
__all__ = ["EnhancedSampling"]
# Graph-level fields WalkerIdentityHook stamps that AtomicDataZarrWriter does
# not recognise. Without naming them to save_checkpoint they are dropped
# without complaint, and a "restored" run comes back with fresh ids and default
# state assignments. The counters are not here: they are a function of the
# step count, which the manifest carries.
_IDENTITY_FIELDS = ("walker_id", "thermodynamic_state_id")
def _register_identity_bookkeeping() -> None:
"""Make the walker identity fields survive refill and graduation.
``BaseDynamics._bookkeeping_keys`` is the mechanism ``status`` and
``system_id`` already use: ``refill_check`` rebuilds every registered key
after graduated graphs are dropped and replacements appended, so the field
keeps its per-graph meaning across a change of batch membership.
Without registration the identity fields exist only because
:class:`~nvalchemi.enhanced_sampling.hooks.WalkerIdentityHook` rewrites
them each step, which is not the same guarantee: a refill that drops row 2
and appends a replacement leaves the surviving rows' history attached to a
``walker_id`` the registry never restored. Walker identity is documented
as "immutable identity that follows a physical configuration" (§4), and
that claim needs the registry behind it.
``walker_id`` registers a ``-1`` sentinel rather than a default value, the
way ``system_id`` does. The factory runs for the *whole* batch, including
the replacement rows, and an identity is **allocated** rather than
defaulted: a factory returning ``arange(n)`` hands each replacement the id
of whichever walker just graduated out of that slot, so a per-walker
metadynamics history is inherited by an unrelated configuration — and it
does so on every refill, not occasionally. The sentinel says "no identity
yet" and :meth:`WalkerIdentityHook.stamp` allocates a fresh one.
Idempotent: registration overwrites by key, so importing this module more
than once is harmless.
"""
BaseDynamics.register_bookkeeping_key(
"walker_id",
lambda n, dev: torch.full((n, 1), -1, dtype=torch.long, device=dev),
)
# Also allocated rather than defaulted, for the same reason and a
# different consequence: a walker graduating *vacates* its rung of the
# ladder, and a replacement defaulted to state 0 claims a rung another
# walker already holds while leaving the vacated one empty — which is not
# a ladder replica exchange can pair on.
BaseDynamics.register_bookkeeping_key(
"thermodynamic_state_id",
lambda n, dev: torch.full((n, 1), -1, dtype=torch.long, device=dev),
)
# The counters are a function of the step and are rewritten on every
# stamp, so a zero default is simply overwritten.
for key in ("sampling_step", "sampling_epoch", "exchange_segment"):
BaseDynamics.register_bookkeeping_key(
key, lambda n, dev: torch.zeros(n, 1, dtype=torch.long, device=dev)
)
_register_identity_bookkeeping()
[docs]
class EnhancedSampling(DynamicsStrategy):
"""Declarative recipe for biased dynamics on a ``BaseDynamics`` engine.
A sibling of any other :class:`~nvalchemi.dynamics.DynamicsStrategy`:
construction validates the configuration, :meth:`build_hooks` contributes
the enhanced-sampling hook family, and ``DynamicsStrategy.run`` drives the
engine. The model, the integrator, the thermostat, and every other hook
behave exactly as they would unbiased.
Attributes
----------
biases:
Mapping of unique name to bias. A bias is any
:class:`~nvalchemi.models.base.BaseModelMixin` that maps a ``Batch``
to :data:`~nvalchemi._typing.ModelOutputs` and carries a ``name`` —
there is no separate bias protocol. May be empty, which reduces the
strategy to identity stamping — what pure temperature replica exchange
needs, since the ladder alone drives the sampling.
steps_per_epoch:
Steps per consistency epoch, the
:class:`~nvalchemi.hooks.StatefulHook` synchronisation boundary at
which :meth:`AdaptivePotentialMixin.commit` fires.
compile_biases:
When ``True``, ``torch.compile`` each conservative bias's
``energy()``. Not ``forward()`` — that path calls
``requires_grad_()``, which ``torch.compile`` cannot trace; see the
:class:`~nvalchemi.enhanced_sampling.ConservativeBias` docstring.
prime_after_update:
When ``True`` (default), re-evaluate biases and rewrite the batch's
total forces after an ``update()`` bumps a bias's state version, so
that anything reading ``batch.forces`` between steps sees the current
bias rather than the previous one.
replica_exchange:
Optional ladder. When given, the strategy also contributes the
:class:`~nvalchemi.dynamics.hooks.PairSwapHook` the ladder configures.
A runtime object rather than a declarative knob, so it is excluded
from :meth:`to_spec_dict` the way ``biases`` and ``extra_hooks`` are.
cache_engine:
Always ``True``; see *One strategy, one trajectory* below.
Raises
------
TypeError
If any value in *biases* is not a
:class:`~nvalchemi.models.base.BaseModelMixin`, or if
*replica_exchange* is given for an engine that cannot rebind a
thermodynamic state.
ValueError
If ``steps_per_epoch`` is below 1, a bias's ``name`` disagrees with
its key in *biases*, no ``engine`` is given, or ``cache_engine`` is
``False``.
Examples
--------
>>> sampling = EnhancedSampling( # doctest: +SKIP
... model=model,
... engine=NVTLangevin,
... engine_kwargs={"dt": 0.5, "temperature": 300.0, "friction": 0.01},
... biases={"umbrella": umbrella, "wall": lower_wall},
... )
>>> batch = sampling.run(batch, n_steps=1000) # doctest: +SKIP
Notes
-----
Hook ordering
:meth:`build_hooks` returns the strategy's own hooks before
``extra_hooks``, so at ``AFTER_COMPUTE`` the bias contribution is
applied before any caller-supplied hook runs. A safety hook such as
``MaxForceClampHook`` therefore clamps the *total* force, which is
the physically meaningful quantity, rather than the model force
alone. Bias observations that need unbiased physical forces are
captured inside :class:`~nvalchemi.enhanced_sampling.hooks.BiasHook`
before the contribution is applied, so they are unaffected.
Among the strategy's own hooks the order is identity, bias, exchange,
commit. Exchange precedes commit because the commit publishes shared
history, and doing it before the swap would publish under labels that
are about to change — the same order :meth:`checkpoint` drains in.
One strategy, one trajectory
The hook family is built once, at construction, because it holds the
run's bookkeeping: the walker counter, the committed epoch, the
attempted segment, and each bias's delivery record. That is also
what a checkpoint saves and :meth:`restore` writes back. So the
engine is cached — ``cache_engine`` defaults to ``True`` and ``False``
is refused — and :meth:`dynamics` returns it. Calling
``build_engine()`` again would hand a second engine the first one's
bookkeeping; construct a second strategy instead.
"""
biases: dict[str, Any] = Field(
default_factory=dict,
exclude=True,
description="Unique name to bias; each a BaseModelMixin whose name matches.",
)
cache_engine: bool = Field(
default=True,
description="Always True: the hook family belongs to one engine.",
)
steps_per_epoch: int = Field(
default=10_000, description="Steps per consistency epoch."
)
compile_biases: bool = Field(
default=False, description="torch.compile each conservative bias's energy()."
)
prime_after_update: bool = Field(
default=True, description="Re-prime forces when an update() changes a bias."
)
replica_exchange: ReplicaExchange | None = Field(
default=None,
exclude=True,
description="Optional ladder; a runtime object, not serialised.",
)
_bias_hook: BiasHook = PrivateAttr()
_identity_hook: WalkerIdentityHook = PrivateAttr()
_epoch_hook: EpochCommitHook = PrivateAttr()
_exchange_hook: PairSwapHook | None = PrivateAttr(default=None)
# One-shot: the empirical state-dependence probe runs at prime time.
_probed_state_dependence: bool = PrivateAttr(default=False)
_restored: bool = PrivateAttr(default=False)
@model_validator(mode="after")
def _validate_and_build_hooks(self) -> EnhancedSampling:
"""Check the configuration, then construct the hook family.
Returns
-------
EnhancedSampling
This strategy, with its hooks built.
Raises
------
TypeError
If a bias is not a ``BaseModelMixin``, or the engine cannot
rebind a thermodynamic state under a configured ladder.
ValueError
If ``steps_per_epoch`` is below 1, a bias's ``name`` disagrees
with its key, no ``engine`` is given, or ``cache_engine`` is
``False``.
"""
if self.engine is None:
raise ValueError(
"EnhancedSampling: engine= is required. The strategy contributes "
"hooks to one engine it builds itself, and checks that engine "
"can rebind a thermodynamic state when a ladder is configured."
)
if not self.cache_engine:
raise ValueError(
"EnhancedSampling: cache_engine=False is not supported. The "
"hook family is built once and holds the run's bookkeeping — "
"walker ids, the committed epoch, the attempted segment — so a "
"fresh engine per run() would inherit the previous one's. "
"Construct a second strategy for an independent run."
)
if self.steps_per_epoch < 1:
raise ValueError(
f"EnhancedSampling: steps_per_epoch must be at least 1, got "
f"{self.steps_per_epoch}. It is a divisor — the epoch index is "
"step // steps_per_epoch and the checkpoint boundary is "
"step % steps_per_epoch — so zero raises deep in a run and a "
"negative value makes both meaningless."
)
for key, bias in self.biases.items():
if not isinstance(bias, BaseModelMixin):
raise TypeError(
f"EnhancedSampling: biases[{key!r}] is a "
f"{type(bias).__name__}, which is not a BaseModelMixin. A "
"bias is an additive potential like any other: subclass "
"ConservativeBias to get forces and stress from an "
"energy(), or mix in BaseModelMixin directly and return "
"ModelOutputs from forward()."
)
if getattr(bias, "name", None) != key:
raise ValueError(
f"EnhancedSampling: biases[{key!r}] has name="
f"{getattr(bias, 'name', None)!r}. The key and the bias "
"name must agree — both are used as identifiers, in the "
"output dict and in checkpoint group names respectively."
)
if self.replica_exchange is not None:
self.replica_exchange.validate_for(self.biases)
self._validate_exchange_capability()
self._bias_hook = BiasHook(
self.biases,
prime_after_update=self.prime_after_update,
compile_biases=self.compile_biases,
)
self._identity_hook = WalkerIdentityHook(
steps_per_epoch=self.steps_per_epoch, exchange=self.replica_exchange
)
self._epoch_hook = EpochCommitHook(
[self._bias_hook], frequency=self.steps_per_epoch
)
# The swap itself is generic — propose pairs, accept, permute
# per-system parameters — so it is a PairSwapHook that the ladder
# configures with the acceptance rule and the temperature table.
self._exchange_hook = (
self.replica_exchange.swap_hook(
bias_energy_fn=self._bias_hook.bias_energy,
on_swap=self._bias_hook.reprime_from_scratch,
)
if self.replica_exchange is not None
else None
)
return self
def _validate_exchange_capability(self) -> None:
"""Reject an engine that cannot rebind a thermodynamic state.
An accepted swap must change the target temperature, rescale
velocities, and transform any thermostat memory as one indivisible
move. An integrator that only accepts the new label would keep
sampling the old temperature, which breaks detailed balance with no
symptom the run would show — so this fails at construction rather
than producing a plausible-looking wrong trajectory.
Checked against the engine *class*, since a strategy holds a recipe
rather than a live engine. ``BaseDynamics`` defines
``apply_per_system_params`` only to raise, so presence is not enough
and the subclass must override it.
Raises
------
TypeError
If the engine does not implement the rebinding adapter.
"""
if self.engine.apply_per_system_params is BaseDynamics.apply_per_system_params:
raise TypeError(
f"EnhancedSampling: replica exchange needs "
f"{self.engine.__name__} to implement "
"apply_per_system_params(), so an accepted swap can rebind "
"temperature, velocities, and thermostat state together. "
"NVTLangevin and NVTNoseHoover implement this; other "
"integrators can run biased dynamics without exchange."
)
[docs]
def build_hooks(self) -> list[Hook]:
"""Return the enhanced-sampling hooks, then ``extra_hooks``.
Returns
-------
list[Hook]
Identity, bias, exchange (when configured) and epoch-commit
hooks, followed by whatever the base contributes.
"""
return [
self._identity_hook,
self._bias_hook,
*([self._exchange_hook] if self._exchange_hook is not None else []),
self._epoch_hook,
*super().build_hooks(),
]
@property
def last_outputs(self) -> dict[str, torch.Tensor]:
"""Diagnostics from the most recent force evaluation.
``physical/<field>`` is the model alone, ``bias/<name>/<field>`` one
bias's contribution, ``bias_total/<field>`` the sum across biases, and
``total/<field>`` physical plus bias as read back from the batch.
"""
return self._bias_hook.last_outputs
def _adaptive_biases(self) -> dict[str, BaseModelMixin]:
"""Return the biases that implement the stateful-hook ``update``.
Returns
-------
dict[str, BaseModelMixin]
Name to bias, for adaptive biases only.
"""
return self._bias_hook.adaptive_biases()
[docs]
def dynamics(self) -> BaseDynamics:
"""Return the engine this strategy drives, building it on first use.
The same slot ``DynamicsStrategy.run`` caches into, so this, ``run()``,
:meth:`prime_forces` and :meth:`restore` all reach one engine.
Returns
-------
BaseDynamics
The cached engine. Stable across calls, so step counters and
thermostat state persist.
"""
if self._engine is None:
self._engine = self.build_engine()
return self._engine
def _require_engine(self) -> BaseDynamics:
"""Return the built engine, or explain that there is not one yet.
Returns
-------
BaseDynamics
The engine this strategy has been driving.
Raises
------
RuntimeError
If no engine has been built, meaning nothing has been run,
primed, or restored.
"""
if self._engine is None:
raise RuntimeError(
"EnhancedSampling: no engine has been built yet. Call run(), "
"prime_forces() or restore() before asking for state that "
"only a live engine has."
)
return self._engine
def _probe_state_dependence(self, batch: Batch) -> None:
"""Reject a state-dependent bias under a temperature ladder.
The declaration checked at construction only covers biases that know
to declare — ``HarmonicUmbrellaBias`` does, an arbitrary user bias
does not. This probes instead of asking: evaluate every bias under
the current assignment and under a rotated one, at identical
coordinates. A bias whose energy is independent of the assignment
returns the same number twice; one that reads
``thermodynamic_state_id`` does not.
Temperature acceptance uses only ``U``, so a bias whose energy varies
with the assignment contributes cross-state terms that the rule never
computes — detailed balance would be wrong with no symptom. Runs
once, at prime time, before any exchange has been attempted.
Parameters
----------
batch:
The live batch, already carrying a state assignment.
Raises
------
ValueError
If any bias's energy changes when the assignment is permuted.
"""
exchange = self.replica_exchange
if (
exchange is None
or exchange.acceptance != "temperature"
or not self.biases
or self._probed_state_dependence
):
return
self._probed_state_dependence = True
current = batch.thermodynamic_state_id.reshape(-1).to(torch.long)
if current.numel() < 2:
return
# Rotate by one: every walker sees a different state, and the result
# is still a permutation, so a per-state lookup stays in range.
rotated = torch.roll(current, shifts=1)
original = batch.thermodynamic_state_id
try:
offenders: list[str] = []
for name, bias in self.biases.items():
batch["thermodynamic_state_id"] = current
before = bias(batch).get("energy")
batch["thermodynamic_state_id"] = rotated
after = bias(batch).get("energy")
if before is None or after is None:
continue
if not torch.allclose(before, after, rtol=1e-9, atol=1e-12):
offenders.append(name)
finally:
batch["thermodynamic_state_id"] = original
if offenders:
raise ValueError(
f"EnhancedSampling: bias(es) {sorted(offenders)} produce a "
"different energy when the thermodynamic-state assignment is "
"permuted, so they depend on the state — but the ladder varies "
"temperature, which selects temperature acceptance. That rule "
"uses only the total energy and omits the cross-state bias "
"terms, so detailed balance would be wrong with nothing to "
"show for it. The combined acceptance rule is not implemented: "
"use a state-independent bias with a temperature ladder, or "
"equal temperatures with a multi-window bias."
)
# ------------------------------------------------------------------
# Public API
# ------------------------------------------------------------------
[docs]
def prime_forces(self, batch: Batch) -> Batch:
"""Run one force evaluation without advancing dynamics.
Populates ``batch.energy`` / ``forces`` / ``stress`` with the total
(physical plus bias) values at the current coordinates. Needed
before the first step of a warm-started run, where a consumer may
read forces before any step has happened.
Parameters
----------
batch:
The batch to prime.
Returns
-------
Batch
The same batch, primed in place.
Raises
------
ValueError
If the batch has no ``forces`` field to write into.
Notes
-----
Does not advance sampling state. Identity is stamped directly rather
than by dispatching ``BEFORE_STEP``, so no exchange is attempted and
no epoch is committed from here — priming after a restore leaves the
run exactly where the checkpoint left it.
``compute()`` writes its outputs back with ``copy_`` into fields that
must already exist — a model output whose batch field is absent is
silently discarded rather than created. That is the toolkit's
contract (``AtomicData(..., forces=torch.zeros(n, 3))``), so the
check below turns a silent no-op into a named error.
"""
if getattr(batch, "forces", None) is None:
raise ValueError(
"EnhancedSampling.prime_forces: batch has no 'forces' field. "
"Model outputs are written back in place, so the buffer must "
"exist first — construct AtomicData with "
"forces=torch.zeros(n_atoms, 3) and energy=torch.zeros(1, 1), "
"plus stress=torch.zeros(1, 3, 3) whenever a bias produces "
"stress (any periodic batch, unless the bias was built with "
"compute_stress=False)."
)
engine = self.dynamics()
self._identity_hook.stamp(batch, engine.step_count)
self._bias_hook.reprime_from_scratch(batch)
self._probe_state_dependence(batch)
return batch
[docs]
def warm_start(self, frames: Batch) -> None:
"""Replay prior frames into every adaptive bias, in order.
Approximate by construction: it reconstructs bias history but not
velocities, RNG, or integrator state. Use
:meth:`restore` when exact reproducibility matters.
Parameters
----------
frames:
Prior frames in chronological order, one graph per frame.
Raises
------
RuntimeError
If called after :meth:`restore`; the two are mutually exclusive
and applying a warm start over a restored state would silently
corrupt it.
"""
if self._restored:
raise RuntimeError(
"EnhancedSampling: warm_start() and restore() are mutually "
"exclusive. This strategy has already been restored from a "
"checkpoint; warm-starting over it would replay history the "
"restored state already contains."
)
self.dynamics()
self._bias_hook.replay(frames)
[docs]
def run(
self,
batch: Batch,
n_steps: int | None = None,
*,
prime: bool = True,
) -> Batch:
"""Run biased dynamics.
Primes forces first by default. A velocity-Verlet-style integrator
reads ``batch.forces`` in its *first* half-step, before any model
call — so without priming, step 0 integrates against whatever the
buffer happened to hold (zeros, for a freshly built batch), making it
the one step in the run that ignores the bias.
Parameters
----------
batch:
The initial batch.
n_steps:
Number of steps; falls back to :attr:`n_steps`.
prime:
Set ``False`` to skip priming when the caller has already
evaluated forces at these coordinates.
Returns
-------
Batch
The batch after all steps.
"""
if prime:
self.prime_forces(batch)
return super().run(batch, n_steps=n_steps)
def _components(self, engine: BaseDynamics | None = None) -> dict[str, Stateful]:
"""Name every object whose state a checkpoint must carry.
Each is a :class:`~nvalchemi._checkpoint.Stateful`, so the checkpoint
layer reads it directly rather than being handed a pre-collected
schema: the hooks own their own cursors, the biases own their history,
and the ladder owns its acceptance RNG position.
Parameters
----------
engine:
The live engine, included as ``"dynamics"`` when given. Omitted
on restore, where the integrator's state has to be applied after
its per-system arrays are allocated against the restored batch.
Returns
-------
dict[str, Stateful]
Component name to the object that owns that state.
"""
components: dict[str, Stateful] = {}
if engine is not None:
components["dynamics"] = engine
components["hooks/identity"] = self._identity_hook
components["hooks/bias"] = self._bias_hook
components["hooks/epoch"] = self._epoch_hook
if self._exchange_hook is not None:
components["hooks/exchange"] = self._exchange_hook
for name, bias in self.biases.items():
if isinstance(bias, Stateful):
components[f"biases/{name}"] = bias
if self.replica_exchange is not None:
components["exchange"] = self.replica_exchange
return components
def _compatibility(self, engine: BaseDynamics) -> dict[str, Any]:
"""Describe the configuration a restore has to match.
Parameters
----------
engine:
The live engine.
Returns
-------
dict[str, Any]
Fingerprint stored in the manifest and checked by
:meth:`_validate_compatibility`.
"""
return {
"model_class": _qualified_name(engine.model),
"dynamics_class": _qualified_name(engine),
"bias_classes": {
name: _qualified_name(bias) for name, bias in self.biases.items()
},
"exchange_config": (
self.replica_exchange.config_fingerprint()
if self.replica_exchange is not None
else None
),
}
[docs]
def checkpoint(self, path: str | Path, batch: Batch | None = None) -> None:
"""Write a transactional checkpoint at a consistency-epoch boundary.
The boundary is not a convention — it is the only point where there
are no pending ``update()`` calls and no in-flight epoch commit, so a
checkpoint taken anywhere else could capture a bias mid-mutation.
Parameters
----------
path:
Destination Zarr store.
batch:
The batch to save. Defaults to the one last seen by the identity
hook.
Raises
------
RuntimeError
If no engine has been built or no batch is available, meaning
nothing has been run or primed.
ValueError
If the current step is not an epoch boundary; the message names
the next valid step.
"""
engine = self._require_engine()
target = batch if batch is not None else self._identity_hook.current_batch
if target is None:
raise RuntimeError(
"EnhancedSampling.checkpoint: no batch to save. Run or prime "
"the sampler first, or pass batch= explicitly."
)
step = engine.step_count
if step % self.steps_per_epoch != 0:
next_step = ((step // self.steps_per_epoch) + 1) * self.steps_per_epoch
raise ValueError(
f"EnhancedSampling.checkpoint: step {step} is not a consistency "
f"epoch boundary (steps_per_epoch={self.steps_per_epoch}). The "
f"next valid checkpoint step is {next_step}. Only at a boundary "
"are there no pending update() calls or in-flight epoch commits "
"to capture mid-mutation."
)
# Boundary-aligned is not the same as quiescent. Both hooks fire on
# their own cadence at the *start* of the step that crosses the
# boundary — so at step N neither has run for the epoch that just
# ended, and a checkpoint taken here would record pre-exchange labels
# and a shared-history bias with its deposits still pending rather
# than merged. Drain both, in the same order build_hooks() registers
# them: exchange first, because the commit publishes shared history
# and doing it before the swap would publish under labels that are
# about to change.
if self._exchange_hook is not None:
interval = self._exchange_hook.frequency
self._exchange_hook.attempt_segment(target, step // interval - 1)
self._epoch_hook.commit_epoch(step // self.steps_per_epoch - 1)
save_checkpoint(
path,
self._components(engine),
batch=target,
batch_fields=_IDENTITY_FIELDS,
compatibility=self._compatibility(engine),
metadata={
"sampling_step": step,
"sampling_epoch": step // self.steps_per_epoch,
"steps_per_epoch": self.steps_per_epoch,
},
)
[docs]
def restore(
self,
path: str | Path,
device: torch.device | str | None = None,
) -> Batch:
"""Restore a checkpoint exactly, and prime forces before returning.
The caller must have reconstructed the same model, engine and biases
first; this validates that they match what was saved. **Model
weights are not restored** — load them through the model's own API
before calling here. The compatibility metadata proves the
architecture agrees, not that the weights do.
Parameters
----------
path:
Source Zarr store.
device:
Device for the restored batch. Defaults to the model's own.
Returns
-------
Batch
The restored batch, force-primed and ready to run.
Raises
------
ValueError
If the checkpoint is uncommitted, fails a checksum, or was
written by a different model, engine, or bias set.
"""
engine = self.dynamics()
target_device = device if device is not None else self._model_device(engine)
# "dynamics" is deliberately not in the mapping: its per-system arrays
# have to be allocated against the restored batch before they can be
# written into, and the batch only exists once the store is read. It is
# applied by hand below, from the decoded state every component gets
# back whether or not it was restored automatically.
contents = load_checkpoint(
path,
self._components(),
device=target_device,
validate=lambda manifest: self._validate_compatibility(manifest, engine),
)
batch = contents.batch
self.steps_per_epoch = int(contents.manifest.metadata["steps_per_epoch"])
# The divisor lives on the hooks that use it, so a checkpoint written
# with a different epoch length re-cadences them rather than leaving
# the strategy's copy and the hooks' copies disagreeing.
self._identity_hook.steps_per_epoch = self.steps_per_epoch
self._epoch_hook.frequency = self.steps_per_epoch
# Loading wrote each bias's saved state_version straight onto it, which
# the bias hook never observed as a change; re-baseline so the first
# post-restore update() does not read it as one.
self._bias_hook.sync_seen_versions()
engine._ensure_state_initialized(batch)
engine.load_state_dict(contents.states["dynamics"])
self._restored = True
self.prime_forces(batch)
return batch
@staticmethod
def _model_device(engine: BaseDynamics) -> torch.device:
"""Return the device the model's own tensors live on.
``BaseDynamics.device`` reports the process's compute device, which
is CUDA whenever a GPU is visible — even for a model that was never
moved off the CPU. Restoring a batch there would put the batch and
the model on different devices. The model's own parameters are the
authority.
Parameters
----------
engine:
The live engine, which holds the model.
Returns
-------
torch.device
The model's device, falling back to the engine's device when the
model holds no tensors (a pure-physics wrapper such as LJ).
"""
model = engine.model
for tensor in list(model.parameters()) + list(model.buffers()):
return tensor.device
return engine.device
def _validate_compatibility(
self, manifest: CheckpointManifest, engine: BaseDynamics
) -> None:
"""Reject a checkpoint written by a different configuration.
Parameters
----------
manifest:
The committed manifest.
engine:
The live engine, which names the model and dynamics classes.
Raises
------
ValueError
If the model class, dynamics class, or bias set disagrees.
"""
saved = manifest.compatibility
actual = self._compatibility(engine)
problems: list[str] = []
for key, label in (("model_class", "model"), ("dynamics_class", "dynamics")):
recorded = saved.get(key)
# An unrecorded class is tolerated; a recorded one that disagrees
# is not.
if recorded and recorded != actual[key]:
problems.append(
f" {label}: checkpoint has {recorded}, "
f"this strategy has {actual[key]}"
)
# Unconditional, unlike the two above: an empty bias set is a real
# configuration, so "checkpoint had none, this strategy has three" is a
# mismatch rather than a missing record.
if saved.get("bias_classes", {}) != actual["bias_classes"]:
problems.append(
f" biases: checkpoint has {saved.get('bias_classes', {})}, "
f"this strategy has {actual['bias_classes']}"
)
# The ladder decides what a swap means, so a mismatch — including
# exchange-versus-none in either direction — changes the semantics of
# every future swap while the counters and assignment carry on looking
# valid.
problems.extend(
ReplicaExchange.describe_config_mismatch(
saved.get("exchange_config"), actual["exchange_config"]
)
)
if problems:
detail = "\n".join(problems)
raise ValueError(
"EnhancedSampling.restore: the checkpoint was written by a "
f"different configuration:\n{detail}\n"
"Reconstruct the same model, dynamics, and biases before "
"restoring. Note that model *weights* are never restored from "
"a checkpoint — load them through the model's own API."
)
def __repr__(self) -> str:
"""Return a concise description of the strategy."""
names = ", ".join(self.biases) or "none"
exchange = (
f", exchange={self.replica_exchange!r}"
if self.replica_exchange is not None
else ""
)
return (
f"{type(self).__name__}(engine={self.engine.__name__}, "
f"biases=[{names}], steps_per_epoch={self.steps_per_epoch}"
f"{exchange})"
)
[docs]
def state_dict(self) -> Mapping[str, Any]:
"""Return sampling counters plus each adaptive bias's state.
Returns
-------
Mapping[str, Any]
Nested mapping; bias state lives under ``biases/<name>``.
"""
state: dict[str, Any] = {
"steps_per_epoch": self.steps_per_epoch,
"next_walker_id": self._identity_hook.next_walker_id,
"committed_epoch": self._epoch_hook.committed_epoch,
"biases": {},
}
for name, bias in self.biases.items():
getter = getattr(bias, "state_dict", None)
if callable(getter):
state["biases"][name] = getter()
return state
[docs]
@classmethod
def from_spec_dict(
cls,
spec: Mapping[str, Any],
*,
model: BaseModelMixin,
biases: Mapping[str, BaseModelMixin] | None = None,
replica_exchange: ReplicaExchange | None = None,
extra_hooks: Sequence[Hook] | None = None,
) -> EnhancedSampling:
"""Rebuild a strategy from :meth:`to_spec_dict` output.
``biases`` and ``replica_exchange`` are excluded from the spec — they
are live objects with state, like ``model`` — so they are supplied
here the same way. Without this override the base would rebuild a
strategy with neither, and the restored run would be unbiased with
nothing to say so.
Parameters
----------
spec:
JSON-decoded strategy configuration.
model:
The potential the engine calls.
biases:
Name to bias, as passed at construction.
replica_exchange:
The ladder, as passed at construction.
extra_hooks:
Runtime hooks appended after hooks rebuilt from the spec.
Returns
-------
EnhancedSampling
A freshly validated strategy.
Raises
------
ValueError
If *spec* already carries ``biases`` or ``replica_exchange``.
"""
runtime = {"biases", "replica_exchange"} & set(spec)
if runtime:
raise ValueError(
f"spec cannot contain runtime-only fields: {', '.join(sorted(runtime))}"
)
data = {
**spec,
"biases": dict(biases or {}),
"replica_exchange": replica_exchange,
}
return super().from_spec_dict(data, model=model, extra_hooks=extra_hooks)