Source code for nvalchemi.enhanced_sampling.hooks

# 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 hooks an enhanced-sampling run installs on a ``BaseDynamics``.

``BaseDynamics`` owns the stepping loop and ``Hook`` already carries
``frequency`` and ``stage``, so the work an enhanced-sampling run adds is
expressed as hooks on that loop rather than as a second runner around it:

==============================  ======================  =====================
Concern                         Hook                    Cadence
==============================  ======================  =====================
Walker identity and counters    ``WalkerIdentityHook``  every step
Bias forces and updates         ``BiasHook``            every step
Shared-history synchronisation  ``EpochCommitHook``     ``steps_per_epoch``
Replica-exchange attempts       ``PairSwapHook``        ``attempt_interval``
==============================  ======================  =====================

The last of those is not defined here: proposing pairs, accepting them and
permuting per-system parameters is the mechanism behind basin hopping with
swaps and population search too, so it lives in
:class:`~nvalchemi.dynamics.hooks.PairSwapHook` and
:meth:`ReplicaExchange.swap_hook` supplies the physics.

The last two carry their cadence as ``Hook.frequency``, so the registry gates
them and nothing here re-implements "has the boundary been crossed".  A hook
at ``frequency=N`` is dispatched at step *kN*, where ``step // N - 1`` is the
index of the boundary that has just completed — the same index the lazy
"did the epoch change" test used to produce.

Where both are due on the same step, the exchange goes first:
:meth:`EnhancedSampling.build_hooks` registers it ahead of the commit, and
``checkpoint()`` drains them in the same order.  A commit publishes shared
history, and publishing it before the swap would file it under labels that are
about to change.

Why the biases share one hook
-----------------------------
:class:`BiasHook` takes *all* the biases rather than each bias being
registered separately.  Registering them independently would make each apply
its contribution in turn, so the second bias evaluates against a batch that
already carries the first one's forces — measured, on two biases contributing
along ``x``: the second saw ``|forces| = 3.0`` instead of ``0.0``.  That is the
sequential in-place mutation
:class:`~nvalchemi.hooks.BiasedPotentialHook` was deprecated for, and hook
registration order is user-owned, so the total would also depend on it.  One
hook evaluates every bias against the same unmodified model output and sums
once.
"""

from __future__ import annotations

from collections import OrderedDict
from typing import TYPE_CHECKING, Any

import torch

from nvalchemi.dynamics.base import DynamicsStage
from nvalchemi.hooks._context import BiasContext
from nvalchemi.models._utils import (
    DIAGNOSTIC_PREFIX,
    aggregate_contributions,
    validate_contribution,
)

if TYPE_CHECKING:
    from collections.abc import Mapping
    from enum import Enum

    from nvalchemi._typing import ModelOutputs
    from nvalchemi.data import Batch
    from nvalchemi.enhanced_sampling._exchange import ReplicaExchange
    from nvalchemi.hooks import HookContext, StatefulHook
    from nvalchemi.models.base import BaseModelMixin

__all__ = [
    "BiasHook",
    "EpochCommitHook",
    "WalkerIdentityHook",
]

_ALLOCATION_HINT = {
    "energy": "energy=torch.zeros(1, 1)",
    "forces": "forces=torch.zeros(n_atoms, 3)",
    "stress": "stress=torch.zeros(1, 3, 3)",
}


[docs] class WalkerIdentityHook: """Stamp walker identity and step counters onto the live batch. ``walker_id`` and ``thermodynamic_state_id`` are assigned once and then preserved; the counters are refreshed every step. All five fields are also registered as ``BaseDynamics`` bookkeeping keys, so they survive refill and graduation rather than depending on this hook alone. Parameters ---------- steps_per_epoch: Divisor for ``sampling_epoch``. exchange: Ladder, when replica exchange is configured. Read for the initial assignment and the segment divisor only; attempts are the swap hook's job. Attributes ---------- next_walker_id: The identifier the next unstamped graph will receive. Carried in a checkpoint so a resumed run does not reissue identifiers. current_batch: The batch last stamped, which is what ``checkpoint()`` saves when the caller does not name one. """ def __init__( self, *, steps_per_epoch: int, exchange: ReplicaExchange | None = None, ) -> None: self.stage: Enum | None = DynamicsStage.BEFORE_STEP self.frequency = 1 self.steps_per_epoch = int(steps_per_epoch) self.exchange = exchange self.next_walker_id = 0 self.current_batch: Batch | None = None # One-shot: the walker/state bijection is checked on the first stamp. self._validated_assignment = False # The engine whose per-system parameters follow the assignment, set # by on_register, and whether it has been told the current one. self.dynamics: Any | None = None self._states_bound = False
[docs] def on_register(self, workflow: Any) -> None: """Remember the engine the thermodynamic assignment has to drive. Parameters ---------- workflow: The ``BaseDynamics`` doing the registering. """ self.dynamics = workflow
def __call__(self, ctx: HookContext, stage: Enum) -> None: """Stamp the live batch. Parameters ---------- ctx: The dynamics hook context. stage: The stage being dispatched. """ self.stamp(ctx.batch, getattr(ctx, "step_count", 0))
[docs] def state_dict(self) -> Mapping[str, Any]: """Return the identifier allocation that must survive a restart. Returns ------- Mapping[str, Any] The next identifier to issue. A resumed run that restarted the counter would reissue ids already attached to saved history. """ return {"next_walker_id": int(self.next_walker_id)}
[docs] def load_state_dict(self, state: Mapping[str, Any]) -> None: """Restore the identifier allocation. Parameters ---------- state: A mapping produced by :meth:`state_dict`. """ self.next_walker_id = int(state.get("next_walker_id", 0))
def _assign_walker_ids( self, batch: Batch, n_graphs: int, device: torch.device ) -> None: """Give an identity to every graph that does not have one yet. Three cases, and the third is the one that is easy to miss: * The field is absent — a fresh batch. Every row is allocated. * Every row holds an identity. Nothing is touched; that is what "immutable identity that follows a physical configuration" means. * Some rows hold the ``-1`` sentinel. That is a refill: graduated graphs were dropped and replacements appended, and the bookkeeping registry rebuilt the column with the sentinel for rows it has no value for. Those rows are **new walkers** and are allocated fresh identities — reusing the id of the walker that just left the slot would hand the replacement that walker's per-walker bias history. Parameters ---------- batch: The live batch. n_graphs: Number of graphs in it. device: Device for a newly allocated column. """ existing = getattr(batch, "walker_id", None) if existing is None: batch["walker_id"] = self._next_ids(n_graphs, device) return ids = existing.reshape(-1).to(torch.long) unassigned = ids < 0 if not bool(unassigned.any()): # Never hand out an id a caller already used: a batch may arrive # carrying its own identities, and the counter has to clear them # or the first refill would collide with one. self.next_walker_id = max(self.next_walker_id, int(ids.max()) + 1) return assigned = ids[~unassigned] if assigned.numel(): self.next_walker_id = max(self.next_walker_id, int(assigned.max()) + 1) ids = ids.clone() ids[unassigned] = self._next_ids(int(unassigned.sum()), device, shape=(-1,)).to( ids.dtype ) batch["walker_id"] = ids def _assign_state_ids( self, batch: Batch, n_graphs: int, device: torch.device ) -> None: """Give a thermodynamic state to every graph that does not have one. Mirrors :meth:`_assign_walker_ids`, but the value is not free: under a ladder the assignment must stay a bijection, so a sentinel row takes a **vacant** rung rather than a default one. Those are exactly the rungs the graduated walkers left behind, so the replacement entering a slot inherits the rung that slot was holding and the ladder stays fully occupied. Parameters ---------- batch: The live batch. n_graphs: Number of graphs in it. device: Device for a newly allocated column. """ existing = getattr(batch, "thermodynamic_state_id", None) if existing is None: if self.exchange is not None: # Check before attaching: a ladder-sized tensor on a # differently-sized batch would otherwise fail as an opaque # "Length mismatch" from inside the batch storage. self.exchange.validate_assignment( self.exchange.initial_state_ids, n_graphs, source="initial_state_ids", ) batch["thermodynamic_state_id"] = self.exchange.initial_state_ids.to( device ) else: batch["thermodynamic_state_id"] = torch.zeros( n_graphs, dtype=torch.long, device=device ) self._validated_assignment = True self._bind_states(batch) return ids = existing.reshape(-1).to(torch.long) unassigned = ids < 0 if bool(unassigned.any()): ids = ids.clone() ids[unassigned] = self._vacant_states(ids, unassigned, device) batch["thermodynamic_state_id"] = ids # The replacement took a vacant rung, so the integrator is now # targeting the temperature of whoever held that row before. self._states_bound = False if self.exchange is not None: # Re-checked after a refill, not only on arrival: the batch # membership just changed, which is the one event that can # break a bijection that was valid a step ago. self.exchange.validate_assignment( ids, n_graphs, source="batch.thermodynamic_state_id after refill" ) elif self.exchange is not None and not self._validated_assignment: # A batch may arrive carrying its own assignment, which never went # through the constructor's check. Validate it once — a duplicate # would surface later as a KeyError from the pair lookup. self.exchange.validate_assignment( existing, n_graphs, source="batch.thermodynamic_state_id" ) self._validated_assignment = True self._bind_states(batch) def _bind_states(self, batch: Batch) -> None: """Make the integrator target the temperatures the assignment names. The label and the thermostat target are two halves of one fact, and only one of them was ever written here. An accepted swap rebinds both together, which left the two moments where the assignment changes *without* a swap sampling the wrong ensemble: * **The first stamp.** The engine is built from ``engine_kwargs`` with one temperature — the documented recipe passes a scalar — so every walker started at that temperature while its label claimed a rung. On a four-rung ladder from 300 K, three of the four walkers sampled 300 K until a swap happened to touch them. * **A refill.** A replacement is given a vacant rung by :meth:`_assign_state_ids`, but inherits the integrator row of the walker that graduated, and so its temperature. Both are silent: the trajectory looks healthy and the acceptance rate looks merely badly tuned. Integrator state is allocated lazily, on the first step, and this hook runs before it. Rather than let the first step integrate unbound, the allocation is forced through the idempotent ``_ensure_state_initialized`` the step itself calls; an engine that keeps no per-system state is left alone, having nothing to bind. Parameters ---------- batch: The live batch, carrying the assignment to bind. """ if self._states_bound or self.exchange is None or self.dynamics is None: return ensure = getattr(self.dynamics, "_ensure_state_initialized", None) if callable(ensure): ensure(batch) if getattr(self.dynamics, "_state", None) is None: return ids = batch.thermodynamic_state_id.reshape(-1).to(torch.long) self.dynamics.apply_per_system_params( self.exchange.per_system_params(ids), batch ) self._states_bound = True def _vacant_states( self, ids: torch.Tensor, unassigned: torch.Tensor, device: torch.device ) -> torch.Tensor: """Return the rungs no walker is holding, for the unassigned rows. Parameters ---------- ids: The current assignment, sentinel rows included. unassigned: Mask of the rows needing a state. device: Device for the result. Returns ------- torch.Tensor One state per unassigned row, in ascending rung order. Raises ------ ValueError If there are more rows to fill than rungs left to fill them with. """ count = int(unassigned.sum()) if self.exchange is None: # Without a ladder the field is a label, not a rung; zero is the # same value a fresh batch gets. return torch.zeros(count, dtype=torch.long, device=device) held = {int(value) for value in ids[~unassigned].tolist()} vacant = [ state for state in range(len(self.exchange.states)) if state not in held ] if len(vacant) < count: raise ValueError( f"ReplicaExchange: {count} walker(s) need a thermodynamic " f"state but only {len(vacant)} rung(s) are vacant " f"({vacant}). The batch has outgrown the ladder — replica " "exchange presumes one walker per state, so a refill cannot " "add walkers beyond the number of states." ) return torch.tensor(vacant[:count], dtype=torch.long, device=device) def _next_ids( self, count: int, device: torch.device, shape: tuple[int, ...] = (-1,) ) -> torch.Tensor: """Allocate *count* consecutive identities and advance the counter. Parameters ---------- count: How many to issue. device: Device for the result. shape: Shape to view the result as. Returns ------- torch.Tensor The issued identities. """ ids = torch.arange( self.next_walker_id, self.next_walker_id + count, dtype=torch.long, device=device, ) self.next_walker_id += count return ids.reshape(shape)
[docs] def stamp(self, batch: Batch, step: int) -> None: """Write identity and counter fields for *step* onto *batch*. Exposed separately from :meth:`__call__` because force priming needs the batch stamped without a hook dispatch behind it. Parameters ---------- batch: The live batch. step: The dynamics step the stamp describes. """ n_graphs = batch.num_graphs device = batch.positions.device self._assign_walker_ids(batch, n_graphs, device) self._assign_state_ids(batch, n_graphs, device) self.current_batch = batch full = torch.full((n_graphs,), step, dtype=torch.long, device=device) batch["sampling_step"] = full batch["sampling_epoch"] = full // self.steps_per_epoch interval = ( self.exchange.attempt_interval if self.exchange is not None else self.steps_per_epoch ) batch["exchange_segment"] = torch.full( (n_graphs,), step // interval, dtype=torch.long, device=device )
[docs] class BiasHook: """Evaluate every bias against one unmodified model output, then apply. The single hook the bias family needs. It defines ``_runs_on_stage`` so the registry lets one object serve both ``AFTER_COMPUTE`` (evaluate and apply) and ``AFTER_STEP`` (observe, deliver ``update()``, re-prime), which keeps the ordering guarantees in one place rather than spread across separately-registered hooks whose relative order would then depend on registration sequence. It is also the *orchestrator* for the biases, in the sense :class:`~nvalchemi.training.hooks.update.TrainingUpdateHook` establishes: an adaptive bias carries the :class:`~nvalchemi.hooks.StatefulHook` attributes (``frequency``, ``stage``, ``read_only``, ``commit``) but dispatches through ``update`` rather than ``__call__``, because a bias is also an ``nn.Module`` whose ``__call__`` is its model forward. This object owns protocol compliance on their behalf: it is the thing the registry sees, and it reads those attributes to decide when each bias is due. Parameters ---------- biases: Mapping of unique name to bias. May be empty, which reduces this hook to a no-op — what pure temperature replica exchange needs. prime_after_update: When ``True`` (default), re-evaluate the 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. compile_biases: When ``True``, ``torch.compile`` each conservative bias's ``energy()``. Attributes ---------- last_outputs: Diagnostics from the most recent force evaluation — ``physical/*`` (model only), ``bias/<name>/*`` (one bias's contribution), ``bias_total/*`` (the sum across biases) and ``total/*`` (physical plus bias, read back from the batch). Notes ----- Bias *state* is not part of :meth:`state_dict`. A checkpoint writes each bias into its own ``biases/<name>`` group so the pieces can be inspected and restored individually; what this hook owns is the per-bias delivery bookkeeping that keeps ``update()`` exactly-once across a restart. """ def __init__( self, biases: Mapping[str, BaseModelMixin] | None = None, *, prime_after_update: bool = True, compile_biases: bool = False, ) -> None: # stage=None plus _runs_on_stage: one object, two stages. self.stage: Enum | None = None self.frequency = 1 self.read_only = False self.biases: dict[str, BaseModelMixin] = dict(biases or {}) self.prime_after_update = bool(prime_after_update) self.last_outputs: dict[str, torch.Tensor] = {} # Per-bias observation captured at the bias's stage, consumed by the # next update() call. self._pending: dict[str, BiasContext] = {} # Per-bias contributions from the most recent force evaluation. Held # because an AFTER_STEP capture happens after that evaluation has # returned, and update() is documented to receive the contribution its # bias produced during it. self._last_results: dict[str, ModelOutputs] = {} self._last_update_step: dict[str, int] = {} self._last_seen_version: dict[str, int] = {} self._physical: dict[str, torch.Tensor] = {} self._dynamics: Any = None self.sync_seen_versions() if compile_biases: self._compile_bias_energies() # ------------------------------------------------------------------ # Registry protocol # ------------------------------------------------------------------ def _runs_on_stage(self, stage: Enum) -> bool: """Return whether this hook fires at *stage*. Parameters ---------- stage: The stage being dispatched. Returns ------- bool ``True`` at ``AFTER_COMPUTE`` and ``AFTER_STEP``. """ return stage in (DynamicsStage.AFTER_COMPUTE, DynamicsStage.AFTER_STEP)
[docs] def on_register(self, workflow: Any) -> None: """Remember the engine this hook was registered on. The engine is the authority on the current step, supplies the model a bias's ``update`` context names, and is what :meth:`reprime_from_scratch` drives through a fresh force evaluation. Parameters ---------- workflow: The ``BaseDynamics`` doing the registering. """ self._dynamics = workflow
def __call__(self, ctx: HookContext, stage: Enum) -> None: """Dispatch to the phase for *stage*. Parameters ---------- ctx: The dynamics hook context. stage: The stage being dispatched. """ if stage is DynamicsStage.AFTER_COMPUTE: self.evaluate_and_apply(ctx.batch) elif stage is DynamicsStage.AFTER_STEP: self.observe_and_update(ctx.batch)
[docs] def commit(self) -> None: """Publish every adaptive bias's pending state. The :class:`~nvalchemi.hooks.StatefulHook` synchronisation point, fanned out to the biases. Called by :class:`EpochCommitHook` at a consistency epoch boundary, never on the hot path. """ for bias in self.adaptive_biases().values(): commit = getattr(bias, "commit", None) if callable(commit): commit()
[docs] def state_dict(self) -> Mapping[str, Any]: """Return the delivery bookkeeping that must survive a restart. Returns ------- Mapping[str, Any] The step at which each bias last received ``update()``, which is what keeps delivery exactly-once across the boundary. """ return { "last_update_step": { name: int(step) for name, step in self._last_update_step.items() } }
[docs] def load_state_dict(self, state: Mapping[str, Any]) -> None: """Restore the delivery bookkeeping. Does **not** re-baseline the seen-version cache: the biases' own states are loaded separately, and the cache is only meaningful once they have been. Call :meth:`sync_seen_versions` after that. Parameters ---------- state: A mapping produced by :meth:`state_dict`. """ self._last_update_step = { name: int(step) for name, step in (state.get("last_update_step") or {}).items() }
@property def _step(self) -> int: """Return the engine's current step, or ``0`` before registration.""" return int(getattr(self._dynamics, "step_count", 0)) # ------------------------------------------------------------------ # Setup helpers # ------------------------------------------------------------------ def _compile_bias_energies(self) -> None: """Compile each conservative bias's ``energy()`` in place. Assigning the compiled callable as an instance attribute shadows the bound method, so ``forward()`` picks it up without an indirection the eager path would also pay. """ for bias in self.biases.values(): if hasattr(bias, "energy"): bias.energy = torch.compile(bias.energy) # type: ignore[method-assign]
[docs] def sync_seen_versions(self) -> None: """Re-baseline the cached per-bias state versions from the live biases. The cache answers "has this bias changed since the hook last looked", which is what decides whether forces need re-priming. It must be re-baselined after anything that changes a bias's version without the hook observing it — construction, and a restore, which loads a saved version straight onto the bias. Called from both, rather than inlined, so the two cannot drift: a restore that skipped this would leave the cache at ``0`` against a restored version of ``N``, and the first post-restore ``update()`` would re-prime on a change that never happened. """ self._last_seen_version = { name: int(getattr(bias, "state_version", 0)) for name, bias in self.biases.items() }
[docs] def adaptive_biases(self) -> dict[str, BaseModelMixin]: """Return the biases that implement the stateful-hook ``update``. Detection is structural (``hasattr``), so a bias satisfies the adaptive contract without inheriting ``AdaptivePotentialMixin``. Returns ------- dict[str, BaseModelMixin] Name to bias, for adaptive biases only. """ return { name: bias for name, bias in self.biases.items() if callable(getattr(bias, "update", None)) }
# ------------------------------------------------------------------ # Phase 1 — evaluate and apply (AFTER_COMPUTE) # ------------------------------------------------------------------
[docs] def evaluate_and_apply(self, batch: Batch) -> None: """Evaluate every bias against the unmodified batch, then apply the sum. Implements steps 1-7 of the documented force-step ordering. The ordering is the whole point: every bias sees the same physical outputs, so no bias can observe another's contribution and the result does not depend on registration order. Parameters ---------- batch: The live batch, immediately after the model forward pass. """ if not self.biases: return # 1. Capture the physical outputs before anything is added. self._physical = { key: value.clone() for key in ("energy", "forces", "stress") if (value := getattr(batch, key, None)) is not None } # 2-3. Evaluate each bias against the same unmodified batch. results = self._contributions(batch) # 4. Capture AFTER_COMPUTE observations while batch.forces still # holds unbiased physical forces. ABF depends on this: an # estimator fed its own output diverges. self._capture(batch, results, DynamicsStage.AFTER_COMPUTE) # 5-6. Namespace diagnostics, then sum once. total = aggregate_contributions( [self._namespace(name, r) for name, r in results.items()] ) self._record_diagnostics(results, total) # 7. Apply the total contribution, then record the combined result. self._apply(batch, total, results) self._record_totals(batch)
def _contributions(self, batch: Batch) -> dict[str, ModelOutputs]: """Evaluate every bias against *batch* and check what each returned. Validation lives here rather than in each bias because this is where an unchecked contribution does damage: the next thing that happens to it is being added into a batch buffer, retained in a capture, or written to a checkpoint. One enforcement point also covers biases that never call the checker themselves — a hand-written one, or a non-conservative one such as ABF. Parameters ---------- batch: The live batch, unmodified by any bias. Returns ------- dict[str, ModelOutputs] Name to contribution. Raises ------ ValueError If any contribution violates the ``ModelOutputs`` conventions — an attached grad graph, a wrong shape, a NaN. See :func:`~nvalchemi.models._utils.validate_contribution`. """ results: dict[str, ModelOutputs] = {} for name, bias in self.biases.items(): outputs = bias(batch) # Checked per bias, not on the aggregate: summing absorbs a # broadcastable shape ([4, 3] + [1, 3] is [4, 3]), so by the time # the total reaches the batch it looks right and the bias that # was wrong can no longer be named. validate_contribution( outputs, source=f"{type(bias).__name__} {name!r}", num_atoms=batch.num_nodes, num_graphs=batch.num_graphs, ) results[name] = outputs self._last_results = results return results def _namespace(self, name: str, result: ModelOutputs) -> ModelOutputs: """Return *result* with its diagnostics keyed by contributing bias. ``diagnostics/<key>`` becomes ``diagnostics/bias/<name>/<key>``. Namespacing has to happen before aggregation, because :func:`~nvalchemi.models._utils.aggregate_contributions` rejects duplicate diagnostic keys rather than silently dropping one — two biases of the same type would otherwise collide on identical names. Parameters ---------- name: The bias name. result: The bias's contribution. Returns ------- ModelOutputs A copy with namespaced diagnostics, or *result* unchanged when it has none. """ if not any(key.startswith(DIAGNOSTIC_PREFIX) for key in result): return result renamed: ModelOutputs = OrderedDict() for key, value in result.items(): if key.startswith(DIAGNOSTIC_PREFIX): suffix = key[len(DIAGNOSTIC_PREFIX) :] renamed[f"{DIAGNOSTIC_PREFIX}bias/{name}/{suffix}"] = value else: renamed[key] = value return renamed def _record_diagnostics( self, results: dict[str, ModelOutputs], total: ModelOutputs ) -> None: """Populate :attr:`last_outputs` with the physical and bias views. Writes ``physical/*``, ``bias/<name>/*``, and ``bias_total/*``. ``total/*`` is *not* written here: at this point the bias has not been applied yet, so there is no combined value to record. :meth:`_record_totals` adds it afterwards. Parameters ---------- results: Per-bias results, un-namespaced. total: The aggregated bias result — the sum across biases, **not** physical plus bias. """ outputs: dict[str, torch.Tensor] = {} for key, value in self._physical.items(): outputs[f"physical/{key}"] = value for name, result in results.items(): for key, value in result.items(): if value is None: continue label = ( key[len(DIAGNOSTIC_PREFIX) :] if key.startswith(DIAGNOSTIC_PREFIX) else key ) outputs[f"bias/{name}/{label}"] = value for key in ("energy", "forces", "stress", "virial"): value = total.get(key) if value is not None: outputs[f"bias_total/{key}"] = value self.last_outputs = outputs def _record_totals(self, batch: Batch) -> None: """Record ``total/*`` — physical plus bias — from the live batch. Must run *after* :meth:`_apply`. Reading the batch rather than adding ``physical/*`` and ``bias_total/*`` back together keeps the record faithful to what was actually written, including any reshape :meth:`_apply` performed. Parameters ---------- batch: The live batch, immediately after the bias has been applied. Notes ----- This is the state as this hook leaves it, not necessarily the state the integrator sees. The hook is deliberately ahead of caller-supplied hooks at ``AFTER_COMPUTE`` (so a force clamp acts on the total rather than on the model force alone), which means any later hook at that stage can still modify ``batch.forces`` afterwards. Read the batch directly if you need the value the integrator consumed. """ for key in ("energy", "forces", "stress"): value = getattr(batch, key, None) if value is not None: self.last_outputs[f"total/{key}"] = value.detach().clone() def _apply( self, batch: Batch, total: ModelOutputs, results: dict[str, ModelOutputs] | None = None, ) -> None: """Add the aggregated bias contribution to the batch, in place. Every non-``None`` output must have a destination buffer. Skipping a field whose buffer is absent would discard that contribution in silence — for ``stress`` that is precisely the barostat-invisibility failure this API exists to remove, arrived at from a different direction: the bias is computed correctly, applied nowhere, and the cell evolves as though it did not exist. Parameters ---------- batch: The live batch. total: The aggregated bias result. results: Per-bias results, used only to name the contributors in an error. Raises ------ ValueError If the aggregate carries a virial, or if any non-``None`` output has no destination buffer on the batch. """ if total.get("virial") is not None: raise ValueError( "EnhancedSampling: a bias returned 'virial', but the runner " "applies 'stress' to the batch. Convert W -> sigma = -W/V in " "the bias before returning it; the cell volume is the bias's " "to supply." ) self._check_destinations(batch, total, results or {}) with torch.no_grad(): energy = total.get("energy") if energy is not None: batch.energy.add_(energy.reshape(batch.energy.shape)) forces = total.get("forces") if forces is not None: # reshape, like energy and stress above: it raises on a numel # mismatch, where a bare add_ would broadcast a single row # onto every atom. batch.forces.add_(forces.reshape(batch.forces.shape)) stress = total.get("stress") if stress is not None: batch.stress.add_(stress.reshape(batch.stress.shape)) @staticmethod def _check_destinations( batch: Batch, total: ModelOutputs, results: dict[str, ModelOutputs] ) -> None: """Raise if any produced output has nowhere to go on the batch. Parameters ---------- batch: The live batch. total: The aggregated bias result. results: Per-bias results, used to name which biases produced each field. Raises ------ ValueError Listing every missing destination, the biases responsible, and both ways to resolve it. """ missing = [ key for key in ("energy", "forces", "stress") if total.get(key) is not None and getattr(batch, key, None) is None ] if not missing: return lines = [] for key in missing: contributors = sorted( name for name, result in results.items() if result.get(key) is not None ) who = f" (from {contributors})" if contributors else "" lines.append(f" '{key}'{who}: add {_ALLOCATION_HINT[key]} to AtomicData") detail = "\n".join(lines) extra = "" if "stress" in missing: extra = ( "\nA bias that produces stress with nowhere to put it is " "invisible to an NPT/NPH barostat — the cell would evolve as " "if the bias were absent. If this run genuinely has no use for " "a cell response (NVE/NVT), pass compute_stress=False to those " "biases instead of leaving the output to be discarded." ) raise ValueError( f"EnhancedSampling: bias output has no destination buffer on the " f"batch, so it would be silently discarded:\n{detail}{extra}" ) # ------------------------------------------------------------------ # Phase 2 — observe and update (AFTER_STEP) # ------------------------------------------------------------------ def _capture( self, batch: Batch, results: dict[str, ModelOutputs], stage: DynamicsStage, ) -> None: """Snapshot the batch for adaptive biases whose ``stage`` is *stage*. The stored :class:`~nvalchemi.hooks.BiasContext` is exactly what :meth:`AdaptivePotentialMixin.update` is documented to receive: the frame at the bias's ``stage``, and the contribution that bias returned during the preceding force evaluation. An ``AFTER_STEP`` capture happens after that evaluation has returned, so the contributions are read from the retained results rather than recomputed — a metadynamics bias sizing its next hill from the bias energy it just applied needs the real value, not an empty placeholder. Parameters ---------- batch: The live batch. results: Per-bias contributions from the preceding force evaluation. stage: The stage being captured. """ step = self._step for name, bias in self.adaptive_biases().items(): if getattr(bias, "stage", DynamicsStage.AFTER_STEP) is not stage: continue if step % max(1, getattr(bias, "frequency", 1)) != 0: continue self._pending[name] = self._bias_context( batch.clone(), results.get(name), step ) def _bias_context( self, batch: Batch, contribution: ModelOutputs | None, step: int ) -> BiasContext: """Build the context handed to one bias's ``update``. Parameters ---------- batch: The observed frame. contribution: What the bias returned during the preceding force evaluation, or ``None`` when it has not been evaluated yet. step: The dynamics step the capture belongs to. Returns ------- BiasContext Populated context; ``workflow`` is this hook, so a bias can reach the engine and the full diagnostics dict if it needs to. """ from nvalchemi.training.distributed import get_rank return BiasContext( batch=batch, model=getattr(self._dynamics, "model", None), global_rank=get_rank(None), workflow=self, step_count=step, contribution=contribution if contribution is not None else OrderedDict(), )
[docs] def observe_and_update(self, batch: Batch) -> None: """Capture post-step frames, deliver ``update()``, then re-prime. Implements steps 10-12 of the force-step ordering. Parameters ---------- batch: The live batch, after the integrator has finished. """ adaptive = self.adaptive_biases() if not adaptive: return step = self._step self._capture(batch, self._last_results, DynamicsStage.AFTER_STEP) changed = False for name, bias in adaptive.items(): if step % max(1, getattr(bias, "frequency", 1)) != 0: continue # Exactly once per step, even if this hook is dispatched twice. if self._last_update_step.get(name) == step: continue ctx = self._pending.pop(name, None) if ctx is None: ctx = self._bias_context(batch, self._last_results.get(name), step) bias.update(ctx, getattr(bias, "stage", DynamicsStage.AFTER_STEP)) # type: ignore[attr-defined] self._last_update_step[name] = step version = getattr(bias, "state_version", 0) if version != self._last_seen_version.get(name, 0): self._last_seen_version[name] = version changed = True if changed and self.prime_after_update: self._reprime(batch)
def _reprime(self, batch: Batch) -> None: """Rewrite total forces from cached physical outputs and current biases. A bias that just deposited a hill leaves ``batch.forces`` describing the bias as it was *before* the deposition. Anything reading the batch between steps — a reporter, a convergence check — would see stale values. This restores the cached physical outputs and re-adds a freshly evaluated bias contribution. The physical part is reused rather than recomputed: this is *evaluate-only* priming, so it costs one bias evaluation and no model forward pass. The physical forces are therefore the ones from the start of the step, not from the post-step coordinates. That is exact only if the model forward were repeated, which is precisely the cost this avoids; the next step recomputes them anyway. Parameters ---------- batch: The live batch. """ if not self._physical: return with torch.no_grad(): for key, value in self._physical.items(): target = getattr(batch, key, None) if target is not None: target.copy_(value.reshape(target.shape)) results = self._contributions(batch) total = aggregate_contributions( [self._namespace(name, r) for name, r in results.items()] ) self._record_diagnostics(results, total) self._apply(batch, total, results) self._record_totals(batch)
[docs] def replay(self, frames: Batch) -> None: """Deliver each frame in *frames* to every adaptive bias, in order. The mechanism behind a warm start: it reconstructs bias history from prior frames, one graph at a time, without any dynamics behind it. The per-step exactly-once bookkeeping is deliberately bypassed — these are replayed frames, not steps of this run — and the frame index stands in for the step count. Parameters ---------- frames: Prior frames in chronological order, one graph per frame. """ adaptive = self.adaptive_biases() if not adaptive: return for index in range(frames.num_graphs): frame = frames.index_select( torch.tensor([index], device=frames.positions.device) ) for bias in adaptive.values(): ctx = self._bias_context(frame, None, index) bias.update(ctx, getattr(bias, "stage", DynamicsStage.AFTER_STEP)) # type: ignore[attr-defined]
# ------------------------------------------------------------------ # Services for the replica-exchange hook # ------------------------------------------------------------------
[docs] def bias_energy(self, batch: Batch, state_ids: torch.Tensor) -> torch.Tensor: """Return the total bias energy per walker under *state_ids*. Umbrella acceptance needs the bias evaluated under both the current and the proposed labels, so the assignment is swapped in, the biases re-evaluated, and the original restored in a ``finally``. Raw energy, not reduced: multiplying by ``beta`` is thermodynamics and belongs to whatever ladder is asking, which is also what keeps this hook free of any temperature table. Contributions are checked here as well as on the force path, and for a reason specific to this one: it is the only place a bias is evaluated under an assignment the run is *not* in. A window bias can be perfectly finite with every walker at home and overflow the moment one is scored against another's window — which is precisely what umbrella acceptance asks it to do — so the force path never sees it. An unchecked non-finite energy here does not raise either: it makes the acceptance exponent ``nan``, and ``nan`` compares false, so the swap is silently rejected and the run looks like a ladder with poor overlap. The ``isfinite`` sync this costs is per exchange attempt, not per step. Only the energy is checked, because only the energy is read. The forces and stress computed alongside it are discarded, and a bias can be finite under a foreign window while its derivative is singular there — a square-root restraint scored at its own centre. Refusing that would stop the run over a value nothing applies; the force path checks the derivatives the integrator actually uses. Parameters ---------- batch: The live batch. state_ids: Assignment to evaluate under, shape ``[B]``. Returns ------- torch.Tensor ``E_bias`` per walker in eV, shape ``[B]``. Raises ------ ValueError If any bias returns an energy violating the ``ModelOutputs`` conventions under *state_ids*, naming the bias. """ original = batch.thermodynamic_state_id try: batch["thermodynamic_state_id"] = state_ids total = torch.zeros( batch.num_graphs, dtype=batch.positions.dtype, device=batch.positions.device, ) for name, bias in self.biases.items(): energy = bias(batch).get("energy") validate_contribution( {"energy": energy}, source=f"{type(bias).__name__} {name!r} under the proposed " "assignment", num_graphs=batch.num_graphs, ) if energy is not None: total = total + energy.reshape(-1) finally: batch["thermodynamic_state_id"] = original return total
[docs] def reprime_from_scratch(self, batch: Batch) -> None: """Recompute the model and reapply the bias at fixed coordinates. Unlike :meth:`_reprime`, which reuses the cached physical outputs, this repeats the model forward pass — the caller has changed something the model itself responds to. An accepted replica-exchange swap is that case: the forces in the batch were produced under the previous labels, and the integrator reads them in its next half-step before any model call. Reproduces the prefix of ``BaseDynamics.step`` up to the model call, including the ``BEFORE_COMPUTE`` hooks. Those are not optional: a cutoff model reaches ``adapt_input`` expecting a neighbor list that ``NeighborListHook`` builds at exactly that stage, so calling ``compute()`` bare would fail. Parameters ---------- batch: The live batch. """ dynamics = self._dynamics dynamics._ensure_state_initialized(batch) dynamics._call_hooks(DynamicsStage.BEFORE_COMPUTE, batch) dynamics.compute(batch) self.evaluate_and_apply(batch)
[docs] class EpochCommitHook: """Fire :meth:`StatefulHook.commit` on a consistency-epoch cadence. The cadence is :attr:`frequency`, so the registry gates the dispatch and nothing here re-implements "has the boundary been crossed". Commits stay idempotent by epoch index regardless, because the boundary is also reached eagerly when a checkpoint drains a completed epoch. Parameters ---------- targets: The stateful hooks to commit — for enhanced sampling, the single :class:`BiasHook`, which fans out to its adaptive biases. frequency: Steps per consistency epoch. """ def __init__(self, targets: list[StatefulHook], *, frequency: int) -> None: self.stage: Enum | None = DynamicsStage.BEFORE_STEP self.frequency = int(frequency) self.targets = targets self.committed_epoch = -1 def __call__(self, ctx: HookContext, stage: Enum) -> None: """Commit the epoch that has just completed. Parameters ---------- ctx: The dynamics hook context. stage: The stage being dispatched. """ self.commit_epoch(getattr(ctx, "step_count", 0) // self.frequency - 1)
[docs] def state_dict(self) -> Mapping[str, Any]: """Return the boundary cursor that must survive a restart. Returns ------- Mapping[str, Any] The last epoch committed. Restarting at ``-1`` would re-commit epochs whose shared history was already published, which a bias that merges pending deposits would double-count. """ return {"committed_epoch": int(self.committed_epoch)}
[docs] def load_state_dict(self, state: Mapping[str, Any]) -> None: """Restore the boundary cursor. Parameters ---------- state: A mapping produced by :meth:`state_dict`. """ self.committed_epoch = int(state.get("committed_epoch", -1))
[docs] def commit_epoch(self, epoch: int) -> None: """Commit *epoch*, at most once. Idempotent by design: the boundary is reached from two directions — the cadence, and a checkpoint draining a completed epoch — and a shared-history bias that merged its pending deposits twice would double-count them. Parameters ---------- epoch: Index of the completed epoch. Negative, or already committed, is a no-op. """ if epoch < 0 or epoch <= self.committed_epoch: return for target in self.targets: commit = getattr(target, "commit", None) if callable(commit): commit() self.committed_epoch = epoch