Source code for nvalchemi.enhanced_sampling._exchange

# 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.
"""Synchronous replica exchange over a batch of walkers.

Exchange swaps **thermodynamic-state labels, not atomic coordinates**.  A
walker keeps its execution slot, its history, and its integrator arrays; what
changes is the temperature or bias window assigned to it.  That keeps the
move local — no coordinate traffic, no reallocation — which is what makes it
viable inside one batched GPU step.

Every walker holds exactly one state and every state exactly one walker, so
an exchange is a permutation of :attr:`Batch.thermodynamic_state_id`.
"""

from __future__ import annotations

import math
from typing import TYPE_CHECKING, Any, Literal

import torch
from pydantic import BaseModel, ConfigDict, Field

from nvalchemi.dynamics.hooks._utils import KB_EV
from nvalchemi.dynamics.hooks.swap import (
    PairSwapHook,
    apply_pair_swaps,
    even_odd_pairs,
)

if TYPE_CHECKING:
    from collections.abc import Callable, Mapping, Sequence

    from nvalchemi.data import Batch

__all__ = ["ReplicaExchange", "ThermodynamicState"]


[docs] class ThermodynamicState(BaseModel): """One set of conditions a walker can be assigned to. Attributes ---------- state_id: Index into the ladder. Must be dense and start at zero across the set of states, because pairing walks neighbouring indices. temperature: Temperature in Kelvin. Equal across all states means the ladder varies by bias window instead, which selects umbrella acceptance. """ model_config = ConfigDict(extra="forbid", frozen=True) state_id: int = Field(ge=0) temperature: float = Field(gt=0.0)
[docs] class ReplicaExchange: r"""Synchronous replica exchange with an even/odd pair schedule. Parameters ---------- states: The ladder. ``state_id`` values must be exactly ``0..S-1``. initial_state_ids: Assignment of states to walkers, shape ``[B]``. Must be a permutation of ``0..S-1``: replica exchange presumes a bijection between walkers and states, and a duplicate would let two walkers claim the same rung. mode: ``"synchronous"`` only. Asynchronous exchange is not implemented. attempt_interval: Dynamics steps per exchange segment. random_seed: Base seed for acceptance draws. Randomness is derived per attempt as ``random_seed + exchange_id`` rather than from a long-lived generator, so a checkpoint needs two integers instead of an opaque RNG blob — the same counter-based scheme ``NVTLangevin`` uses for its noise. Raises ------ ValueError If the mode is unsupported, ``attempt_interval`` is below 1, the ladder is not dense, or the assignment is not a permutation. Notes ----- Acceptance Which rule applies is inferred from the ladder and validated, rather than being a free parameter that can silently disagree with it. *Temperature exchange* — temperatures differ: .. math:: \log a = \min\bigl(0,\ (\beta_i - \beta_j)(U_i - U_j)\bigr) A cold replica holding anomalously high energy therefore moves up the ladder with probability one, which is the point of the method. *Umbrella exchange* — temperatures are equal and the states differ by bias window: .. math:: \log a = \min\bigl(0,\ u_i(x_i) + u_j(x_j) - u_i(x_j) - u_j(x_i)\bigr) with :math:`u_k` the reduced bias potential of state *k*. The two cross terms need the bias re-evaluated under swapped labels, which costs one extra bias evaluation per attempt. Not supported A ladder that varies temperature *and* bias window at once needs a combined acceptance rule that is not implemented. The temperature rule alone omits the cross-state bias terms, so running it anyway would break detailed balance with no symptom — it is therefore **rejected**, twice over: a bias that declares ``state_dependent_for_exchange`` is refused at construction, and the runner additionally probes empirically at prime time by evaluating every bias under a permuted assignment. Vary one or the other. """ def __init__( self, states: Sequence[ThermodynamicState], initial_state_ids: torch.Tensor, *, mode: Literal["synchronous"] = "synchronous", attempt_interval: int = 100, random_seed: int = 1234, ) -> None: if mode != "synchronous": raise ValueError( f"ReplicaExchange: mode={mode!r} is not supported. Only " "'synchronous' is implemented; asynchronous exchange " "(pair-local rendezvous, non-blocking workers) is future work." ) if len(states) < 2: raise ValueError( f"ReplicaExchange: need at least 2 states to exchange, got " f"{len(states)}." ) ladder = sorted(states, key=lambda s: s.state_id) if [s.state_id for s in ladder] != list(range(len(ladder))): raise ValueError( f"ReplicaExchange: state_id values must be exactly 0..{len(ladder) - 1}, " f"got {sorted(s.state_id for s in states)}. Pairing walks " "neighbouring indices, so a sparse ladder has no defined " "neighbours." ) if int(attempt_interval) < 1: raise ValueError( f"ReplicaExchange: attempt_interval must be at least 1, got " f"{attempt_interval}. A non-positive interval has no meaning " "as a segment length — it would be clamped to every-step " "exchange while the checkpoint recorded the value you passed, " "so the run and its metadata would disagree." ) self.states = tuple(ladder) self.mode = mode self.attempt_interval = int(attempt_interval) self.random_seed = int(random_seed) self._acceptance = self._infer_acceptance() self.initial_state_ids = self.validate_assignment( initial_state_ids, source="initial_state_ids" ) self.exchange_id = 0 self.attempts = 0 self.accepted = 0 # Per neighbouring-state-pair tallies, for the acceptance-rate # diagnostics a REMD run is tuned on. self.pair_attempts = [0] * (len(self.states) - 1) self.pair_accepted = [0] * (len(self.states) - 1) # ------------------------------------------------------------------ # Configuration # ------------------------------------------------------------------
[docs] def validate_assignment( self, state_ids: torch.Tensor, num_graphs: int | None = None, *, source: str = "assignment", ) -> torch.Tensor: """Return *state_ids* as a validated ``[B]`` long tensor. The bijection between walkers and states is the assumption every other piece rests on: pairing looks up "which walker holds state k", and a duplicate or a wrong-length assignment makes that lookup meaningless. Without this the failures surface far from their cause — a length mismatch as ``ValueError: Length mismatch: 4 vs 2`` from inside the batch storage, a duplicate as ``KeyError: 3`` from the pair lookup — neither of which names the ladder or the batch. Used for both the constructor argument and whatever assignment the batch actually carries, so the rule lives in one place. Parameters ---------- state_ids : torch.Tensor Candidate assignment, any shape reshapeable to ``[B]``. num_graphs : int | None Walker count to check the ladder against, when known. source : str Name of the thing being validated, used in the error. Returns ------- torch.Tensor The assignment as a 1-D long tensor. Raises ------ ValueError If the walker count disagrees with the ladder, or the assignment is not a permutation of ``0..S-1``. """ n_states = len(self.states) if num_graphs is not None and num_graphs != n_states: raise ValueError( f"ReplicaExchange: the ladder has {n_states} state(s) but the " f"batch has {num_graphs} walker(s). Replica exchange presumes " "one walker per state — pairing looks up which walker holds " "each rung, which has no answer when the counts differ. Build " "the batch with one graph per ThermodynamicState." ) ids = state_ids.reshape(-1).to(torch.long) if ids.numel() != n_states: raise ValueError( f"ReplicaExchange: {source} has {ids.numel()} entr(ies) but the " f"ladder has {n_states} state(s); they must agree." ) if sorted(ids.tolist()) != list(range(n_states)): raise ValueError( f"ReplicaExchange: {source} must be a permutation of " f"0..{n_states - 1}, got {ids.tolist()}. Replica exchange " "presumes one walker per state; a duplicate would let two " "walkers claim the same rung of the ladder, and leave another " "rung held by none." ) return ids
def _infer_acceptance(self) -> Literal["temperature", "umbrella"]: """Return which acceptance rule this ladder implies. A :class:`ThermodynamicState` carries only a temperature, so the rule is read from the ladder: varying temperatures mean temperature exchange, equal ones mean the states can only differ by which bias window they select. Inferring rather than accepting a parameter is deliberate — a mismatch between a declared rule and the ladder it runs on would be silent, and wrong acceptance breaks detailed balance without any symptom a run would show. Returns ------- Literal["temperature", "umbrella"] The applicable rule. """ temperatures = [s.temperature for s in self.states] varies_temperature = max(temperatures) - min(temperatures) > 1e-12 return "temperature" if varies_temperature else "umbrella" @property def acceptance(self) -> str: """Return the inferred acceptance rule name.""" return self._acceptance @property def temperatures(self) -> torch.Tensor: """Return the ladder temperatures in Kelvin, shape ``[S]``.""" return torch.tensor([s.temperature for s in self.states])
[docs] def validate_for(self, biases: Mapping[str, Any]) -> None: """Reject bias/ladder combinations whose acceptance is undefined. Parameters ---------- biases: The runner's bias mapping. Raises ------ ValueError If umbrella exchange is configured with no bias to exchange over, if any bias cannot supply the energy the acceptance rule needs, or if a state-dependent bias is combined with a temperature ladder. """ if self._acceptance == "umbrella" and not biases: raise ValueError( "ReplicaExchange: every state has the same temperature, so the " "ladder can only differ by bias window — but no biases were " "registered. Either vary the temperatures for temperature " "exchange, or register the bias whose windows the states select." ) for name, bias in biases.items(): energy_less = getattr(bias, "supplies_exchange_energy", None) if energy_less is False: raise ValueError( f"ReplicaExchange: bias {name!r} declares that it supplies " "no exchange energy (a force-only bias such as adaptive " "biasing force). The acceptance rule needs a cross-state " "bias energy, so such a bias cannot participate; run it " "without replica exchange." ) if self._acceptance == "temperature" and ( getattr(bias, "state_dependent_for_exchange", False) is True ): raise ValueError( f"ReplicaExchange: the ladder varies temperature, which " f"selects temperature acceptance, but bias {name!r} has " "per-state parameters. The combined temperature-plus-window " "acceptance rule is not implemented, and the temperature " "rule alone omits the cross-state bias terms — so detailed " "balance would be wrong with nothing to show for it. Use a " "single-window bias with a temperature ladder, or equal " "temperatures with a multi-window bias." )
# ------------------------------------------------------------------ # Scheduling # ------------------------------------------------------------------
[docs] def pair_schedule(self, segment: int) -> list[tuple[int, int]]: """Return the neighbouring state pairs attempted in *segment*. Alternating even/odd offsets means every rung of the ladder is exchangeable with both neighbours over two segments, while no state appears in two pairs of the same segment — which is what lets all pairs be decided simultaneously. Parameters ---------- segment: Exchange segment index. Returns ------- list[tuple[int, int]] Neighbouring ``(state_id, state_id + 1)`` pairs. """ return even_odd_pairs(segment, len(self.states))
def _uniforms(self, count: int, device: torch.device) -> torch.Tensor: """Draw acceptance uniforms for one attempt, reproducibly. Parameters ---------- count: Number of draws. device: Device for the result. Returns ------- torch.Tensor Shape ``[count]`` in ``[0, 1)``. Notes ----- Drawn on the CPU from a generator seeded with ``random_seed + exchange_id``, then moved. Seeding per attempt makes the sequence a pure function of two checkpointed integers, and drawing on the CPU keeps it independent of the device the run happens to use — so a restored run reproduces the same accept/reject decisions. """ generator = torch.Generator() generator.manual_seed(self.random_seed + self.exchange_id) return torch.rand(count, generator=generator).to(device) # ------------------------------------------------------------------ # Acceptance # ------------------------------------------------------------------
[docs] def decide( self, segment: int, state_ids: torch.Tensor, energies: torch.Tensor, bias_current: torch.Tensor | None = None, bias_swapped: torch.Tensor | None = None, ) -> tuple[torch.Tensor, list[tuple[int, int]], torch.Tensor]: """Decide this segment's swaps and return the new assignment. Pure with respect to the batch: it takes energies and returns a permutation, so the caller owns every side effect (rebinding the integrator, rescaling velocities, re-priming forces). That keeps the acceptance rule testable against hand-computed numbers. Parameters ---------- segment: Exchange segment index, which selects the even/odd pairing. state_ids: Current assignment, shape ``[B]``. energies: Per-walker potential energy ``U`` in eV, shape ``[B]``. Used by temperature acceptance. bias_current: Reduced bias potential per walker under its current state, shape ``[B]``. Required for umbrella acceptance. bias_swapped: Reduced bias potential per walker under its proposed state, shape ``[B]``. Required for umbrella acceptance. Returns ------- tuple[torch.Tensor, list[tuple[int, int]], torch.Tensor] The new state assignment ``[B]``, the pairs attempted, and the boolean accept mask over those pairs. Raises ------ ValueError If *state_ids* is not a permutation of the ladder, or if umbrella acceptance is in force but the bias energies were not supplied. """ # Validate before touching any counter. Pairing looks up "which walker # holds state k", which a duplicate or short assignment answers with a # bare KeyError — and by then attempts/pair_attempts have already been # incremented, leaving the tallies corrupted by a call that failed. ids = self.validate_assignment(state_ids, source="state_ids") pairs = self.pair_schedule(segment) if not pairs: empty = torch.zeros(0, dtype=torch.bool, device=ids.device) return ids.clone(), pairs, empty rows_i, rows_j = self._pair_rows(ids, pairs) accepted = self._decide_rows( ids, rows_i, rows_j, energies=energies, bias_current=bias_current, bias_swapped=bias_swapped, ) # Nothing is applied here, so the decision is already final. self._tally(pairs, accepted) new_ids = apply_pair_swaps(ids, rows_i, rows_j, accepted) return new_ids, pairs, accepted
@staticmethod def _pair_rows( state_ids: torch.Tensor, pairs: list[tuple[int, int]] ) -> tuple[torch.Tensor, torch.Tensor]: """Return the graph rows holding each pair's two states. Parameters ---------- state_ids: Assignment, shape ``[B]``. pairs: Neighbouring ``(state_id, state_id)`` pairs. Returns ------- tuple[torch.Tensor, torch.Tensor] Row indices, shape ``[P]`` each. """ row_of_state = {int(state): row for row, state in enumerate(state_ids.tolist())} return ( torch.tensor( [row_of_state[i] for i, _ in pairs], device=state_ids.device, dtype=torch.long, ), torch.tensor( [row_of_state[j] for _, j in pairs], device=state_ids.device, dtype=torch.long, ), ) def _decide_rows( self, slots: torch.Tensor, rows_i: torch.Tensor, rows_j: torch.Tensor, *, energies: torch.Tensor | None = None, bias_current: torch.Tensor | None = None, bias_swapped: torch.Tensor | None = None, ) -> torch.Tensor: """Apply the acceptance rule to one round of proposed pairs. The single implementation of the rule. Both callers reach it — the :class:`~nvalchemi.dynamics.hooks.PairSwapHook` that runs a live ladder, and :meth:`decide`, which exposes the same decision without a batch so the formula can be checked against hand-computed numbers. Two implementations would drift, and a drifted acceptance rule breaks detailed balance with nothing to show for it. Counts nothing and leaves the draw counter where it is: the caller calls :meth:`_tally` once the decision is final. For the hook that is after the swap commits, so a swap that fails to apply and is retried is decided again from the same draw and counted once. Parameters ---------- slots: Current assignment, shape ``[B]``. rows_i, rows_j: Graph rows holding each proposed pair's two slots, shape ``[P]``. energies: Per-walker potential energy ``U``. Temperature acceptance only. bias_current, bias_swapped: Reduced bias potential under the current and proposed assignment. Umbrella acceptance only. Returns ------- torch.Tensor One boolean per pair. Raises ------ ValueError If the inputs the rule in force needs were not supplied. """ if self._acceptance == "temperature": if energies is None: raise ValueError( "ReplicaExchange: temperature acceptance needs the " "per-walker potential energy, but none was supplied." ) energies = energies.reshape(-1) if not bool(energies.isfinite().all()): raise ValueError( f"ReplicaExchange: temperature acceptance read a " f"non-finite potential energy {energies.tolist()}. The " "exponent becomes nan, which compares false, so every " "swap would be rejected and the ladder would look merely " "badly tuned." ) log_alpha = self._log_acceptance_temperature_rows( slots, rows_i, rows_j, energies ) else: if bias_current is None or bias_swapped is None: raise ValueError( "ReplicaExchange: umbrella acceptance needs the bias " "energy under both the current and the proposed state " "assignment, but one was not supplied." ) log_alpha = self._log_acceptance_umbrella_rows( rows_i, rows_j, bias_current.reshape(-1), bias_swapped.reshape(-1) ) uniforms = self._uniforms(rows_i.numel(), log_alpha.device) return log_acceptance_is_accepted(log_alpha, uniforms) def _tally(self, pairs: list[tuple[int, int]], accepted: torch.Tensor) -> None: """Record one round of attempts, and advance the acceptance RNG. Called once per round, when its outcome is final — directly by :meth:`decide`, and as the swap hook's ``record_fn`` otherwise. All or nothing: a ``record_fn`` that raised is called again, so a partial tally would be counted twice. Everything that can fail runs before the first counter moves. Parameters ---------- pairs: The pairs that were decided. accepted: One boolean per pair. """ rounds = list(zip(pairs, accepted.tolist(), strict=True)) pair_attempts = list(self.pair_attempts) pair_accepted = list(self.pair_accepted) for (state_i, _state_j), take in rounds: pair_attempts[state_i] += 1 if take: pair_accepted[state_i] += 1 self.attempts += len(rounds) self.accepted += sum(bool(take) for _, take in rounds) self.pair_attempts = pair_attempts self.pair_accepted = pair_accepted self.exchange_id += 1
[docs] def proposed_assignment( self, segment: int, state_ids: torch.Tensor ) -> torch.Tensor: """Return the assignment that would result if every pair swapped. Umbrella acceptance needs the bias evaluated under the proposed labels *before* the decision is made, so the caller needs the proposal separately from the outcome. Parameters ---------- segment: Exchange segment index. state_ids: Current assignment, shape ``[B]``. Returns ------- torch.Tensor The all-swaps-accepted assignment, shape ``[B]``. Raises ------ ValueError If *state_ids* is not a permutation of the ladder. """ ids = self.validate_assignment(state_ids, source="state_ids") rows_i, rows_j = self._pair_rows(ids, self.pair_schedule(segment)) return apply_pair_swaps(ids, rows_i, rows_j)
# ------------------------------------------------------------------ # The PairSwapHook surface # ------------------------------------------------------------------
[docs] def swap_hook( self, *, bias_energy_fn: Callable[[Batch, torch.Tensor], torch.Tensor] | None = None, on_swap: Callable[[Batch], None] | None = None, slot_field: str = "thermodynamic_state_id", ) -> PairSwapHook: """Return the generic swap hook that runs this ladder. Everything mechanical — the pair schedule, the permutation, the cadence, the parameter rebinding — belongs to :class:`~nvalchemi.dynamics.hooks.PairSwapHook`. This supplies the two pieces that are enhanced-sampling physics: the Sugita-Okamoto acceptance rule and the temperature table it rebinds from. The tallies and the draw counter advance through the hook's ``record_fn``, so only a segment that actually commits counts. Parameters ---------- bias_energy_fn: ``(batch, state_ids) -> Tensor[B]`` giving the reduced bias potential under an assignment. Required for umbrella acceptance, which evaluates the bias under both the current and the proposed labels; unused by temperature acceptance. on_swap: Called with the batch after an accepted swap. Forces computed under the previous labels are what this is for. slot_field: Per-graph batch field holding the assignment. Returns ------- PairSwapHook Configured for this ladder's interval and rung count. """ return PairSwapHook( self._make_accept_fn(bias_energy_fn, slot_field), self.per_system_params, slot_field=slot_field, n_slots=len(self.states), frequency=self.attempt_interval, on_swap=on_swap, record_fn=self._tally, )
[docs] def per_system_params(self, state_ids: torch.Tensor) -> dict[str, torch.Tensor]: """Return the integrator parameters implied by an assignment. The ``params_fn`` half of the swap: a state id is an index into the ladder, and what the integrator needs is the temperature it points at. Parameters ---------- state_ids: Assignment, shape ``[B]``. Returns ------- dict[str, torch.Tensor] ``{"temperature": T}`` in Kelvin per graph, shape ``[B]``. """ table = self.temperatures.to(state_ids.device) return {"temperature": table[state_ids.reshape(-1).to(torch.long)]}
def _make_accept_fn( self, bias_energy_fn: Callable[[Batch, torch.Tensor], torch.Tensor] | None, slot_field: str, ) -> Callable[[Batch, torch.Tensor, torch.Tensor], torch.Tensor]: """Return the ``accept_fn`` a :class:`PairSwapHook` calls. The rule is read off the pairs rather than off a segment index, which is what lets it match the generic ``accept_fn(batch, i, j)`` signature: the proposal is "swap the slots these rows hold", and both acceptance formulas need only that. Parameters ---------- bias_energy_fn: Reduced bias potential under a given assignment, or ``None``. slot_field: Per-graph batch field holding the assignment. Returns ------- Callable ``(batch, rows_i, rows_j) -> Bool[Tensor, "P"]``. """ def accept( batch: Batch, rows_i: torch.Tensor, rows_j: torch.Tensor ) -> torch.Tensor: slots = batch[slot_field].reshape(-1).to(torch.long) if self._acceptance == "temperature": return self._decide_rows( slots, rows_i, rows_j, energies=self._batch_energies(batch) ) if bias_energy_fn is None: raise ValueError( "ReplicaExchange: umbrella acceptance needs the bias " "energy under both the current and the proposed state " "assignment, but no bias_energy_fn was supplied." ) proposed = apply_pair_swaps(slots, rows_i, rows_j) return self._decide_rows( slots, rows_i, rows_j, bias_current=self._reduced_bias_energy(batch, slots, bias_energy_fn), bias_swapped=self._reduced_bias_energy(batch, proposed, bias_energy_fn), ) return accept @staticmethod def _batch_energies(batch: Batch) -> torch.Tensor: """Return the per-walker potential energy the rule needs. Raises rather than substituting zeros, matching :meth:`decide`. Zero is not a neutral stand-in here: temperature acceptance is ``(beta_i - beta_j)(U_i - U_j)``, so equal energies make every exponent zero and **every swap accepted** — a random relabelling with no energetic criterion, and an acceptance rate of 1.00 in the diagnostics a ladder is tuned on, which reads as rungs that are too close together rather than as a missing field. Parameters ---------- batch: The live batch. Returns ------- torch.Tensor Potential energy per walker, shape ``[B]``. Raises ------ ValueError If the batch carries no ``energy``. Finiteness is checked in :meth:`_decide_rows`, where both entry points meet. """ energies = getattr(batch, "energy", None) if energies is None: raise ValueError( "ReplicaExchange: temperature acceptance needs the per-walker " "potential energy, but the batch has no 'energy' field. " "Construct it with energy=torch.zeros(1, 1) so the model can " "write into it — a bias-free ladder needs the buffer just as " "much as a biased one, because the acceptance rule reads it." ) return energies.reshape(-1) def _reduced_bias_energy( self, batch: Batch, state_ids: torch.Tensor, bias_energy_fn: Callable[[Batch, torch.Tensor], torch.Tensor], ) -> torch.Tensor: """Return ``beta * E_bias`` per walker under *state_ids*. The reduction is the ladder's, not the bias's: ``beta`` comes from the temperature a state id points at, and the bias knows nothing about temperatures. Parameters ---------- batch: The live batch. state_ids: Assignment to evaluate under, shape ``[B]``. bias_energy_fn: Total bias energy per walker under a given assignment. Returns ------- torch.Tensor ``beta * E_bias`` per walker, shape ``[B]``. """ total = bias_energy_fn(batch, state_ids).reshape(-1) temperatures = self.temperatures.to(total.device, total.dtype) beta = 1.0 / (KB_EV * temperatures[state_ids.reshape(-1).to(torch.long)]) return beta * total def _log_acceptance_temperature_rows( self, slots: torch.Tensor, rows_i: torch.Tensor, rows_j: torch.Tensor, energies: torch.Tensor, ) -> torch.Tensor: """Return ``log a`` per pair for temperature exchange, by row. Parameters ---------- slots: Current assignment, shape ``[B]``. rows_i, rows_j: Graph rows holding each pair's two slots, shape ``[P]``. energies: Per-walker potential energy ``U``, shape ``[B]``. Returns ------- torch.Tensor ``log a`` per pair, capped at zero. """ beta = 1.0 / (KB_EV * self.temperatures.to(energies.device, energies.dtype)) delta = (beta[slots[rows_i]] - beta[slots[rows_j]]) * ( energies[rows_i] - energies[rows_j] ) return torch.clamp(delta, max=0.0) @staticmethod def _log_acceptance_umbrella_rows( rows_i: torch.Tensor, rows_j: torch.Tensor, bias_current: torch.Tensor, bias_swapped: torch.Tensor, ) -> torch.Tensor: """Return ``log a`` per pair for umbrella exchange, by row. Parameters ---------- rows_i, rows_j: Graph rows holding each pair's two slots, shape ``[P]``. bias_current: Reduced bias potential under the current assignment, shape ``[B]``. bias_swapped: Reduced bias potential under the proposed one, shape ``[B]``. Returns ------- torch.Tensor ``log a`` per pair, capped at zero. """ before = bias_current[rows_i] + bias_current[rows_j] after = bias_swapped[rows_i] + bias_swapped[rows_j] return torch.clamp(before - after, max=0.0) # ------------------------------------------------------------------ # State # ------------------------------------------------------------------
[docs] def config_fingerprint(self) -> dict[str, Any]: """Return the configuration a restored run must match. Exchange semantics live in the ladder, not in the counters: the temperatures set the acceptance exponent, the rule follows from them, and the interval sets the segment cadence. Restoring a run into a different ladder would keep the counters and the walker assignment while silently changing what a swap *means* — the walkers would carry on labelled 0..S-1 against temperatures they were never sampled at. ``initial_state_ids`` is deliberately excluded. It seeds the assignment only when the batch does not already carry one, and a restored batch always does, so it has no effect after step zero and would be a false mismatch. Returns ------- dict[str, Any] JSON-representable configuration. """ return { "mode": self.mode, "acceptance": self._acceptance, "attempt_interval": int(self.attempt_interval), "temperatures": [float(state.temperature) for state in self.states], }
[docs] @staticmethod def describe_config_mismatch( saved: Mapping[str, Any] | None, actual: Mapping[str, Any] | None ) -> list[str]: """Return human-readable differences between two fingerprints. Parameters ---------- saved: The checkpoint's fingerprint, or ``None`` when it had no exchange. actual: The live runner's fingerprint, or ``None`` when it has none. Returns ------- list[str] One line per difference; empty when they agree. """ if saved is None and actual is None: return [] if saved is None: return [ " exchange: the checkpoint was written without replica " "exchange, but this runner has one configured" ] if actual is None: return [ " exchange: the checkpoint was written with replica exchange " f"({saved.get('acceptance')}, " f"{len(saved.get('temperatures', []))} states), but this " "runner has replica_exchange=None" ] problems: list[str] = [ f" exchange {key}: checkpoint has {saved.get(key)!r}, " f"this runner has {actual.get(key)!r}" for key in ("mode", "acceptance", "attempt_interval") if saved.get(key) != actual.get(key) ] saved_temps = [float(t) for t in saved.get("temperatures", [])] actual_temps = [float(t) for t in actual.get("temperatures", [])] if len(saved_temps) != len(actual_temps): problems.append( f" exchange ladder: checkpoint has {len(saved_temps)} state(s), " f"this runner has {len(actual_temps)}" ) elif any( not math.isclose(a, b, rel_tol=1e-9, abs_tol=1e-9) for a, b in zip(saved_temps, actual_temps, strict=True) ): problems.append( f" exchange temperatures: checkpoint has {saved_temps}, " f"this runner has {actual_temps}" ) return problems
[docs] def state_dict(self) -> dict[str, Any]: """Return exchange state for checkpointing. Returns ------- dict[str, Any] Counters and the acceptance-RNG position. The position is two integers rather than a generator blob; see :meth:`_uniforms`. """ return { "exchange_id": int(self.exchange_id), "attempts": int(self.attempts), "accepted": int(self.accepted), "random_seed": int(self.random_seed), "pair_attempts": list(self.pair_attempts), "pair_accepted": list(self.pair_accepted), # Carried so the component is self-describing: loading it into a # different ladder is refused rather than silently accepted. "config": self.config_fingerprint(), }
[docs] def load_state_dict(self, state: Mapping[str, Any]) -> None: """Restore exchange state produced by :meth:`state_dict`. Parameters ---------- state: The mapping previously returned by :meth:`state_dict`. Raises ------ ValueError If the saved configuration disagrees with this instance's. """ saved_config = state.get("config") if saved_config is not None: problems = self.describe_config_mismatch( saved_config, self.config_fingerprint() ) if problems: detail = "\n".join(problems) raise ValueError( "ReplicaExchange.load_state_dict: the saved exchange was " f"configured differently:\n{detail}\n" "Counters and the acceptance-RNG position only mean " "anything against the ladder they were produced on." ) self.exchange_id = int(state.get("exchange_id", 0)) self.attempts = int(state.get("attempts", 0)) self.accepted = int(state.get("accepted", 0)) # random_seed is RNG *position* and is restored; attempt_interval is # configuration and is validated above, never silently overwritten. self.random_seed = int(state.get("random_seed", self.random_seed)) pair_attempts = state.get("pair_attempts") if pair_attempts is not None: self.pair_attempts = [int(v) for v in pair_attempts] pair_accepted = state.get("pair_accepted") if pair_accepted is not None: self.pair_accepted = [int(v) for v in pair_accepted]
@property def acceptance_rate(self) -> float: """Return the fraction of attempted pair swaps that were accepted.""" return self.accepted / self.attempts if self.attempts else 0.0
[docs] def pair_acceptance_rates(self) -> list[float]: """Return the per-neighbouring-pair acceptance rates. A REMD ladder is tuned on these: a pair far below the others is a gap the walkers cannot cross, and the ladder needs another rung there. Returns ------- list[float] One rate per neighbouring pair, ``0.0`` where never attempted. """ return [ (accepted / attempts if attempts else 0.0) for accepted, attempts in zip( self.pair_accepted, self.pair_attempts, strict=True ) ]
def __repr__(self) -> str: """Return a concise description of the exchange.""" return ( f"{type(self).__name__}(states={len(self.states)}, " f"acceptance={self._acceptance!r}, " f"attempt_interval={self.attempt_interval}, " f"accepted={self.accepted}/{self.attempts})" )
def log_acceptance_is_accepted( log_alpha: torch.Tensor, uniforms: torch.Tensor ) -> torch.Tensor: """Return the accept mask for the given log-acceptance values. ``log_alpha`` is capped at zero, so ``log_alpha == 0`` means accept with probability one. Comparing ``log(u) < log_alpha`` rather than ``u < exp(log_alpha)`` keeps a very negative ``log_alpha`` from underflowing to exactly zero and turning a rare-but-possible swap into an impossible one. Parameters ---------- log_alpha : torch.Tensor Log acceptance probability per pair, ``<= 0``. uniforms : torch.Tensor Draws in ``[0, 1)``, same shape. Returns ------- torch.Tensor Boolean accept mask. """ safe = torch.clamp(uniforms, min=torch.finfo(uniforms.dtype).tiny) return torch.log(safe) < log_alpha