Source code for nvalchemi.dynamics.hooks.swap

# 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.
"""Pairwise swaps of per-system state, without the physics that decides them.

Strip the thermodynamics out of replica exchange and the mechanism is:
propose pairs, evaluate an acceptance rule, and permute per-system parameters
for the pairs that pass, rebinding any integrator state that travels with
them.  That mechanism is also basin hopping with swaps, population or
evolutionary structure search, and any annealing ladder — so it lives here,
and the physics is supplied as ``accept_fn``.

The half that was already reusable is on the integrator:
:meth:`~nvalchemi.dynamics.BaseDynamics.apply_per_system_params` rebinds the
parameters and transforms whatever private state depends on them — thermostat
chain masses, velocity scaling — as one indivisible change.

What a caller supplies
----------------------
``accept_fn(batch, i, j) -> Bool[Tensor, "P"]``
    The rule.  *i* and *j* are the graph rows holding the two slots of each
    proposed pair, so the rule reads whatever it needs off the batch — energy,
    a bias, an order parameter — and returns one decision per pair.  It may
    be asked twice about one segment, so it should change nothing.
``record_fn(pairs, accepted) -> None``
    Optional.  Where a rule keeps its statistics: called once per segment,
    after the outcome is final.
``pairing(segment, n_slots) -> list[tuple[int, int]]``
    Optional.  Which rungs to propose.  Its pairs must be disjoint — they are
    decided simultaneously, so an overlap has no defined meaning and its
    writes would collide — and that is checked rather than assumed.
``params_fn(slots) -> Mapping[str, Tensor]``
    Optional.  Maps the post-swap slot assignment to per-graph parameters for
    ``apply_per_system_params``.  Omit it when a method permutes labels only.
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Any, Literal

import torch

from nvalchemi.dynamics.base import DynamicsStage

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

    from nvalchemi.data import Batch
    from nvalchemi.hooks import HookContext

__all__ = ["PairSwapHook", "apply_pair_swaps", "even_odd_pairs"]


def even_odd_pairs(segment: int, n_slots: int) -> list[tuple[int, int]]:
    """Return the neighbouring slot pairs attempted in *segment*.

    Alternating even and odd offsets means every slot is exchangeable with
    both neighbours over two segments, while no slot appears in two pairs of
    the same segment — which is what lets every pair be decided
    simultaneously rather than in sequence.

    Parameters
    ----------
    segment:
        Segment index.  Even segments pair ``(0,1), (2,3), ...``; odd ones
        pair ``(1,2), (3,4), ...``.
    n_slots:
        Number of slots on the ladder.

    Returns
    -------
    list[tuple[int, int]]
        Neighbouring ``(slot, slot + 1)`` pairs, possibly empty.
    """
    offset = segment % 2
    return [(index, index + 1) for index in range(offset, n_slots - 1, 2)]


_PAIRINGS: dict[str, Callable[[int, int], list[tuple[int, int]]]] = {
    "even_odd": even_odd_pairs,
}


def _require_disjoint(values: torch.Tensor, what: str, detail: str) -> None:
    """Raise if *values* names anything twice.

    A swap writes each member of a pair into the other's place, so two pairs
    sharing a member write over each other: one label is duplicated and the
    other lost, and what comes out is no longer a permutation.

    Parameters
    ----------
    values:
        Every member of every pair, flattened.
    what:
        What the values are, for the error.
    detail:
        What the caller should do about it.

    Raises
    ------
    ValueError
        If any value appears more than once.
    """
    flat = values.reshape(-1).tolist()
    seen: set[int] = set()
    repeated = sorted({int(v) for v in flat if int(v) in seen or seen.add(int(v))})
    if repeated:
        raise ValueError(
            f"{what} appears in more than one pair: {repeated}. Pairs within "
            "a segment have to be disjoint — they are decided simultaneously, "
            f"and overlapping writes duplicate one label and lose another. "
            f"{detail}"
        )


def apply_pair_swaps(
    slots: torch.Tensor,
    rows_i: torch.Tensor,
    rows_j: torch.Tensor,
    accepted: torch.Tensor | None = None,
) -> torch.Tensor:
    """Return *slots* with the accepted row pairs exchanged.

    Labels move, rows do not: a walker keeps its place in the batch and its
    slot assignment changes.  Nothing is copied between rows, which is what
    makes the move viable inside a batched GPU step.

    Keyed by row rather than by slot because rows are what every caller
    already holds — proposing a pair means naming the two rows that hold it —
    and re-deriving them from a slot lookup is the step that can disagree
    with the lookup the acceptance rule used.

    Parameters
    ----------
    slots:
        Current per-graph slot assignment, shape ``[B]``.
    rows_i, rows_j:
        Graph rows holding each pair's two slots, shape ``[P]``.
    accepted:
        One boolean per pair, or ``None`` to swap every pair — which is what
        a rule needs when it has to evaluate the *proposal* before deciding
        on it.

    Returns
    -------
    torch.Tensor
        A new assignment; *slots* is not modified.

    Raises
    ------
    ValueError
        If two accepted pairs share a row, which would make the result
        something other than a permutation.
    """
    if accepted is None:
        accepted = torch.ones(rows_i.numel(), dtype=torch.bool)
    take = accepted.to(dtype=torch.bool, device=slots.device)
    # Only the accepted pairs are written, so only those have to be disjoint:
    # a schedule may propose an overlap that acceptance happens to resolve.
    _require_disjoint(
        torch.cat([rows_i[take], rows_j[take]]),
        "apply_pair_swaps: a graph row",
        "Propose each row at most once per round.",
    )
    new_slots = slots.clone()
    new_slots[rows_i[take]] = slots[rows_j[take]]
    new_slots[rows_j[take]] = slots[rows_i[take]]
    return new_slots


[docs] class PairSwapHook: """Propose and accept pairwise swaps of per-system state. The cadence is :attr:`frequency`, so the hook registry gates the dispatch: fired at step *kN*, the hook acts on segment ``step // N - 1``, the one that has just completed. Attempts stay idempotent by segment index, because a caller may also drain a completed segment from elsewhere — a checkpoint, say — and neither pass may decide the same segment twice. Parameters ---------- accept_fn: ``accept_fn(batch, i, j) -> Bool[Tensor, "P"]``. The physics: given the graph rows holding each proposed pair, return one decision per pair. Not called when the segment proposes no pairs, and called again when a segment that failed before committing is retried — so it should have no side effects. Statistics go in ``record_fn``. params_fn: ``params_fn(slots) -> Mapping[str, Tensor]``, mapping the post-swap assignment to per-graph parameters handed to ``apply_per_system_params``. ``None`` for a method that permutes labels only and rebinds nothing. slot_field: Per-graph batch field holding the assignment. Must be a permutation of ``0..n_slots-1``. Required rather than defaulted: the name is the caller's, and a default borrowed from one method would quietly make this hook that method's. n_slots: Number of slots on the ladder. pairing: Pair schedule. ``"even_odd"`` is the only built-in; pass a callable ``(segment, n_slots) -> list[tuple[int, int]]`` for another. frequency: Dynamics steps per segment. on_swap: Called with the batch after an accepted swap has been applied, for whatever the method has to repair — forces computed under the old parameters, most obviously. record_fn: ``record_fn(pairs, accepted) -> None``, given the segment's slot pairs and the decision on each. Called once per decided segment, when the outcome is final: after an accepted swap commits, or when no pair was accepted. Never for a segment that raised before committing, so a retried segment is counted once. Runs before ``on_swap``, so a failed repair does not lose the record of a swap that happened. If it raises, the record is kept and retried on the next :meth:`attempt_segment` call, before anything else is decided — so it should record all of a call or none of it. Notes ----- Applying is the indivisible half: the slot labels, the rebound parameters, and anything derived from them move together. Leaving any of them behind would sample a state the assignment says the walker is no longer in — which is why the parameter rebinding goes through ``apply_per_system_params`` rather than being open-coded per method. Indivisibility is enforced by ordering rather than by rollback: every step that can refuse — building the parameters, the engine checking it can rebind them — runs before the labels are written, and the label write itself cannot fail. ``on_swap`` runs last because it repairs quantities derived from a swap that has, by then, definitely happened. """ def __init__( self, accept_fn: Callable[[Batch, torch.Tensor, torch.Tensor], torch.Tensor], params_fn: Callable[[torch.Tensor], Mapping[str, torch.Tensor]] | None = None, *, slot_field: str, n_slots: int, pairing: Literal["even_odd"] | Callable[[int, int], list[tuple[int, int]]] = "even_odd", frequency: int = 100, on_swap: Callable[[Batch], None] | None = None, record_fn: Callable[[list[tuple[int, int]], torch.Tensor], None] | None = None, ) -> None: if isinstance(pairing, str) and pairing not in _PAIRINGS: raise ValueError( f"PairSwapHook: unknown pairing {pairing!r}. Built-in " f"schedules are {sorted(_PAIRINGS)}; pass a callable " "(segment, n_slots) -> list[tuple[int, int]] for another." ) if int(frequency) < 1: raise ValueError( f"PairSwapHook: frequency must be at least 1, got {frequency}. " "It is the segment length, and the registry uses it to gate " "the dispatch." ) self.stage: Enum | None = DynamicsStage.BEFORE_STEP self.frequency = int(frequency) self.accept_fn = accept_fn self.params_fn = params_fn self.slot_field = slot_field self.n_slots = int(n_slots) self.pairing = _PAIRINGS[pairing] if isinstance(pairing, str) else pairing self.on_swap = on_swap self.record_fn = record_fn self.attempted_segment = -1 self.dynamics: Any = None self._attempting = False self._unrecorded: tuple[list[tuple[int, int]], torch.Tensor] | None = None
[docs] def on_register(self, workflow: Any) -> None: """Remember the engine whose per-system parameters a swap rebinds. Parameters ---------- workflow: The ``BaseDynamics`` doing the registering. """ self.dynamics = workflow
def __call__(self, ctx: HookContext, stage: Enum) -> None: """Attempt the segment that has just completed. Parameters ---------- ctx: The dynamics hook context. stage: The stage being dispatched. """ step = getattr(ctx, "step_count", 0) self.attempt_segment(ctx.batch, step // self.frequency - 1)
[docs] def state_dict(self) -> Mapping[str, Any]: """Return the segment cursor that must survive a restart. Returns ------- Mapping[str, Any] The last segment attempted. A resumed run that lost it would re-decide a segment that was already decided. """ return {"attempted_segment": int(self.attempted_segment)}
[docs] def load_state_dict(self, state: Mapping[str, Any]) -> None: """Restore the segment cursor. Parameters ---------- state: A mapping produced by :meth:`state_dict`. """ self.attempted_segment = int(state.get("attempted_segment", -1))
[docs] def attempt_segment(self, batch: Batch, segment: int) -> None: """Attempt *segment*'s pairs, at most once. Parameters ---------- batch: The live batch. segment: The completed segment. Negative, or already attempted, is a no-op. Notes ----- A segment that raises **before the swap commits** — a rejected rebinding, a malformed pairing — stays unattempted, so a caller that recovers can try it again. ``record_fn`` has not run for it, so the failed attempt is not counted, and the retry asks ``accept_fn`` again. A rule that draws from a counter it advances only in ``record_fn`` — as ``ReplicaExchange`` does — therefore replays the same decision rather than consuming a second draw. Once the swap commits the cursor advances immediately, even if the post-swap repair then raises. Past that line the batch has already moved, so a retry would not re-attempt the segment: it would decide afresh and swap an already-swapped batch a second time, giving two exchanges where the rule granted one. A failed repair leaves derived quantities — forces evaluated under the old parameters — stale, which the next force evaluation corrects; a double swap is silent and corrects nothing. A ``record_fn`` that raises is the same case: the segment is decided and stays decided, ``on_swap`` still runs, and the unrecorded decision is handed to ``record_fn`` again on the next call — before any later segment is decided, since a rule drawing from a counter its record advances would otherwise decide that segment from a stale draw. """ if self._attempting: return self._attempting = True try: self._record_pending() if segment < 0 or segment <= self.attempted_segment: return self._attempt(batch, segment) finally: self._attempting = False # Reached when the segment proposed no pairs, so there was nothing to # decide. A segment that was decided advanced the cursor itself, # inside _attempt. The in-progress flag keeps a hook driven # re-entrantly from attempting the same segment twice. self.attempted_segment = max(self.attempted_segment, segment)
def _validated_pairs(self, segment: int) -> list[tuple[int, int]]: """Return this segment's pairs, or say why they cannot be used. A pairing is an extension point, so what it returns is input. Two pairs sharing a slot is the failure worth catching here: the writes overlap, one label is duplicated and another lost, and the assignment stops being a permutation — which the *next* segment reports, after a round has already been run at parameters nobody asked for. Parameters ---------- segment: Segment index. Returns ------- list[tuple[int, int]] The proposed pairs, possibly empty. Raises ------ ValueError If a slot is out of range or appears in more than one pair. """ pairs = self.pairing(segment, self.n_slots) if not pairs: return pairs members = [slot for pair in pairs for slot in pair] out_of_range = sorted( {slot for slot in members if not 0 <= slot < self.n_slots} ) if out_of_range: raise ValueError( f"PairSwapHook: the pairing proposed slot(s) {out_of_range} " f"for a ladder of {self.n_slots}. A slot is an index into the " "ladder, so it has to name a rung that exists." ) _require_disjoint( torch.tensor(members, dtype=torch.long), "PairSwapHook: a slot", "Return a schedule whose pairs do not touch — the built-in " "'even_odd' alternates offsets for exactly this reason.", ) return pairs def _validated_slots(self, batch: Batch) -> torch.Tensor: """Return the assignment, or say why it cannot be swapped on. Pairing looks up "which row holds slot *k*", so the assignment has to be a bijection. Checked here rather than left to fail later because the later failure is a bare ``KeyError`` from a dict lookup, naming neither the field nor the ladder. Parameters ---------- batch: The live batch. Returns ------- torch.Tensor The assignment as a ``[B]`` long tensor. Raises ------ ValueError If the field is absent, the wrong length, or not a permutation of ``0..n_slots-1``. """ values = getattr(batch, self.slot_field, None) if values is None: raise ValueError( f"PairSwapHook: the batch has no {self.slot_field!r} field, " "so there is no assignment to swap. Stamp it before the first " "step, or name the field the batch actually carries." ) slots = values.reshape(-1).to(torch.long) if slots.numel() != self.n_slots: raise ValueError( f"PairSwapHook: the ladder has {self.n_slots} slot(s) but " f"{self.slot_field!r} holds {slots.numel()} entr(ies). A swap " "pairs slots with the rows holding them, which needs one row " "per slot." ) if sorted(slots.tolist()) != list(range(self.n_slots)): raise ValueError( f"PairSwapHook: {self.slot_field!r} must be a permutation of " f"0..{self.n_slots - 1}, got {slots.tolist()}. A duplicate " "would let two rows claim the same slot, and the pair lookup " "would silently decide one of them twice." ) return slots def _attempt(self, batch: Batch, segment: int) -> None: """Decide one round of swaps and apply the accepted ones. Parameters ---------- batch: The live batch. segment: Segment index, which selects the pairing. """ pairs = self._validated_pairs(segment) if not pairs: return slots = self._validated_slots(batch) row_of_slot = {int(slot): row for row, slot in enumerate(slots.tolist())} rows_i = torch.tensor( [row_of_slot[i] for i, _ in pairs], device=slots.device, dtype=torch.long ) rows_j = torch.tensor( [row_of_slot[j] for _, j in pairs], device=slots.device, dtype=torch.long ) accepted = self.accept_fn(batch, rows_i, rows_j) if not bool(accepted.any()): # Nothing to apply, so nothing left that can refuse: the outcome # is already final. self._settle(segment, pairs, accepted) return new_slots = apply_pair_swaps(slots, rows_i, rows_j, accepted) # Everything that can refuse the swap runs before anything is written. # The labels are the cheapest half to commit and the most damaging to # commit alone: a batch saying a walker moved rung while the # integrator still targets the old one samples a state the assignment # says it has left, which is exactly the indivisibility this hook # exists to provide. params = None if self.params_fn is not None: if self.dynamics is None: raise RuntimeError( "PairSwapHook: no engine to rebind on. The hook takes it " "from on_register, so register it on the dynamics rather " "than driving attempt_segment() by hand." ) params = self.params_fn(new_slots) if params is not None: # Implementations validate the parameters they were handed before # touching any state, so a rebinding they refuse leaves both the # integrator and the batch as they were. self.dynamics.apply_per_system_params(params, batch) batch[self.slot_field] = new_slots # The swap is now committed: the integrator and the labels both moved. # The cursor advances here rather than after on_swap, because from # this line on a retry would not re-attempt the segment, it would # swap an already-swapped batch a second time — two exchanges where # the acceptance rule granted one. try: self._settle(segment, pairs, accepted) finally: # Last, and deliberately after the labels: this is repair work on # quantities derived from the swap — forces computed under the old # parameters — so it needs the swap to have happened, and it is # owed whether or not the swap was recorded. if self.on_swap is not None: self.on_swap(batch) def _settle( self, segment: int, pairs: list[tuple[int, int]], accepted: torch.Tensor ) -> None: """Mark *segment* decided, then hand the decision to ``record_fn``. The one place a segment's outcome becomes final. Recording anywhere earlier — inside ``accept_fn``, say — counts a segment whose application then fails, and counts it again when it is retried. Parameters ---------- segment: The segment just decided. pairs: Its slot pairs. accepted: One boolean per pair. """ self.attempted_segment = segment self._unrecorded = (pairs, accepted) self._record_pending() def _record_pending(self) -> None: """Hand a decided-but-unrecorded segment to ``record_fn``. Cleared only once ``record_fn`` returns, so a record that raised is still pending on the next call rather than lost with the cursor already past it. """ if self._unrecorded is None: return if self.record_fn is not None: self.record_fn(*self._unrecorded) self._unrecorded = None