nvalchemi.dynamics.hooks.PairSwapHook#

class nvalchemi.dynamics.hooks.PairSwapHook(accept_fn, params_fn=None, *, slot_field, n_slots, pairing='even_odd', frequency=100, on_swap=None, record_fn=None)[source]#

Propose and accept pairwise swaps of per-system state.

The cadence is 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 (Callable[[Batch, torch.Tensor, torch.Tensor], torch.Tensor]) – 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 (Callable[[torch.Tensor], Mapping[str, torch.Tensor]] | None) – 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 (str) – 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 (int) – Number of slots on the ladder.

  • pairing (Literal['even_odd'] | Callable[[int, int], list[tuple[int, int]]]) – Pair schedule. "even_odd" is the only built-in; pass a callable (segment, n_slots) -> list[tuple[int, int]] for another.

  • frequency (int) – Dynamics steps per segment.

  • on_swap (Callable[[Batch], None] | None) – 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 (Callable[[list[tuple[int, int]], torch.Tensor], None] | None) – 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 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.

attempt_segment(batch, segment)[source]#

Attempt segment’s pairs, at most once.

Parameters:
  • batch (Batch) – The live batch.

  • segment (int) – The completed segment. Negative, or already attempted, is a no-op.

Return type:

None

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.

load_state_dict(state)[source]#

Restore the segment cursor.

Parameters:

state (Mapping[str, Any]) – A mapping produced by state_dict().

Return type:

None

on_register(workflow)[source]#

Remember the engine whose per-system parameters a swap rebinds.

Parameters:

workflow (Any) – The BaseDynamics doing the registering.

Return type:

None

state_dict()[source]#

Return the segment cursor that must survive a restart.

Returns:

The last segment attempted. A resumed run that lost it would re-decide a segment that was already decided.

Return type:

Mapping[str, Any]