Infinite-swapping integration status

The infinite-swapping source-tree merge was completed on 2026-07-06. This page summarises the resulting architecture, the conventions still in force, and where the historical validation records live.

Goal

PyRETIS has one path-sampling execution path: the scheduler in pyretis/simulation/ drives the unified moves, path/system types, and engine classes. Canonical and runner-style TOML remain separate input dialects, but both feed this scheduler and emit the same per-ensemble output.

Two rules continue to govern development:

  1. One terminology. PyRETIS uses method-based names throughout: the analysis is WHAM and the sampler is infinite swapping (stem infswap). User-facing documentation and commands use these names consistently.

  2. Reproducibility first. Results must be deterministic and correct. A reference comparison is only useful if it fails when the physics is wrong (see Test policy (green == correct)).

What works today

  • pyretis run is the single entry point. It runs all path-sampling tasks through the scheduler and enables parallel infinite swapping via [simulation] task = "infinite_swapping" or the [runner] section.

  • The WHAM crossing-probability / rate analysis lives in pyretis/analysis/wham_analysis.py (a faithful implementation of the standard weighted-histogram procedure for TIS; an earlier analysis stub was scientifically wrong).

  • All tasks share pyretis.core.system_core.System and pyretis.core.path.Path; disk loaders live in pyretis.core.path_load. The random-number generator is PCG64.

How to configure the scheduler

# Classical RETIS / TIS, adapted to the scheduler with one worker:
pyretis run -i retis.toml -p

# infinite swapping (multi-worker, infinite-swap + wire fencing):
#   the TOML selects it via task = "infinite_swapping" or [runner]
pyretis run -i infswap.toml

See examples/validation/ for runnable method and engine comparisons.

Test policy (green == correct)

  • Run ./test-easy.sh (unit + integration + style) before every commit.

  • Run ./test-heavy.sh (engine reference suites + tutorials, 40-60 min) before a push – test-easy does not run the example compare.py harnesses, so a reference/default change can pass test-easy and still break test-heavy.

  • A comparison must not pass on degenerate input. The shared primitives in pyretis/testing/simulation_comparison.py reject empty data, shape mismatches, NaNs at mismatched positions, and entirely-NaN columns; a quantity an engine does not report must be declared explicitly by name, never accepted merely because both sides contain NaN.

Resolved issues

  • test-gromacs/test-load/test-initialise previously asserted that a loaded run bit-for-bit reproduces a fresh run – that is restart semantics, not load semantics. It has been reframed to load semantics (commit b619a767): it now runs the loaded scenario twice from the same loaded path and initial GROMACS RNG state and compares the two, which is what a load must guarantee (it works and reproduces previously loaded results). Rigorous load-determinism is covered by the internal engine (test-internal/retis-load-sparse), and exact continuation by the restart tests (test-internal/{retis,tis,md,mdflux}-restart, test-gromacs/test-restart).

  • The merge-readiness review’s findings (H1–H4, M) are fixed: the load-traj energy comparison is data-driven per ensemble (not a blanket skip); pyretis run restores the completed-restart guard and the descriptive missing-input message; the WHAM lamres default uses the smallest interface gap with a commensurability check; and _wham_pq always returns one crossing probability per interface.

Known issues

  • CP2K loaded frames have no computed energy and declare those unavailable terms per ensemble. The reference is the deterministic conda-forge 2026.1 build (single rank, re-blessed 2026-07-19); other builds run execution-smoke only.

  • The former GROMACS 5.1.4 tarballs were re-baselined onto the single current reference build (double-precision 2025.4, re-blessed 2026-07-19), so one executable validates the complete GROMACS reference set.

  • External numeric tolerances remain provisional until repeated pinned-engine runs provide measured error envelopes. OpenMM and LAMMPS use additional byte-exact gates on their recorded reference builds.