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. No brand. The container name “infretis”/”∞RETIS” is being retired from PyRETIS. Absorbed methods are named for what they are: the analysis is WHAM, the sampler is infinite swapping (stem infswap). Compatibility spellings remain only where removing them would break an existing input or public API.

  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 old infretisrun command has been removed.

  • The WHAM crossing-probability / rate analysis lives in pyretis/analysis/wham_analysis.py (a faithful implementation of the standard weighted-histogram procedure for TIS; the previous infretis_analysis.py 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.

Working documents (in the repository)

  • MERGE_TODO.md – the completed alignment roadmap and the work explicitly deferred to PyRETIS 5.

  • docs/inf_removal_validation.md – the evidence ledger for the now- complete _inf removal; kept as the historical validation record.

  • docs/debrand_plan.md – de-branding status: nearly all of it landed via the merge effort itself; see the file’s own “Still genuinely open” section for the short real remainder.

  • docs/test_integrity_audit.md – whether the example comparisons are meaningful, and the known gaps.

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.