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 segmentstep // 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 inrecord_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 toapply_per_system_params.Nonefor 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 beforeon_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 nextattempt_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_paramsrather 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_swapruns 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_fnhas not run for it, so the failed attempt is not counted, and the retry asksaccept_fnagain. A rule that draws from a counter it advances only inrecord_fn— asReplicaExchangedoes — 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_fnthat raises is the same case: the segment is decided and stays decided,on_swapstill runs, and the unrecorded decision is handed torecord_fnagain 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