Reproduction code — A circulation bound on the frenetic component of branch selection
Description
Reproduction code for the manuscript “A circulation bound on the frenetic component of branch selection” by Shigeo Kaneko. The deposited scripts reproduce the manuscript’s numerical and computational results, regenerate all fourteen figures, and provide consistency checks for the central circulation bound. The analytical proof is contained in the manuscript. The paper establishes |ΔC| ≤ ½ Σ_cyc, where ΔC is the reversal-even frenetic or traffic asymmetry between the dominant forward and backward escape tubes, and Σ_cyc ≥ 0 is the entropy production around the transition cycle closed by those tubes. The proof uses tube minimality, reversal parity, and closure of the comparison class under time reversal. The dimensionless frenetic polarization index η = 2ΔC / Σ_cyc ∈ [−1,1] quantifies the imbalance between the two reciprocal optimality gaps. It approaches saturation along nondegenerate branchwise approaches to the route-handover locus where the forward tube and the time-reversed backward tube become co-optimal. Detailed balance forces ΔC = 0, so circulation around the selected transition cycle is necessary, though not sufficient, for frenetic branch selection. The bound is a structural consistency relation of the minimum-action description, not a thermodynamic variational principle or conversion-efficiency law. The code examines the bound in finite-state networks, Schnakenberg and Hill matrix-tree constructions, chemical-reaction-network count lattices, continuous Langevin systems, and spatial field models. It also shows that the pairwise tube bound does not extend directly to arbitrary arborescence comparisons, confirming that reversal closure is essential. The sfef/ directory contains the Freidlin–Wentzell diffusion benchmarks, including the two-channel route-handover example reaching η ≈ 0.97, the single-channel envelope remaining at |η| ≲ 0.37, and the window-closing trajectory experiment. Further scripts reproduce the contact-weight correction, rotational Maier–Stein example, coarse-graining results, Schüttler–Jack–Cates instanton, spatial-field instanton, and trajectory-level mechanism diagnostic. Every numerical entry in Tables I–IV is associated with a deposited verification script. The aggregate runner checks reported numerical values rather than relying on exit codes alone. See README.md for the claim-to-script map and expected_outputs.txt for reference outputs. V5 changes: 1. Replaced “efficiency |η|” with “frenetic polarization |η|” in the terminology and in Figs. 1 and 9. 2. Added calibration_locus.py to test calibration dependence of the route-handover locus and distinguish symmetry-pinned η = 0 from accidental cancellation. 3. Updated the aggregate runner, documentation, and deposited figures. 4. No numerical result reported in V4 was changed. Licences: source code (*.py, *.sh), MIT; generated data, figures, and documentation, CC BY 4.0. The Mendeley Data record-level licence is CC BY 4.0.
Files
Steps to reproduce
1. Install Python 3.11 or later. For the exact reference environment, run: pip install -r requirements-lock.txt Alternatively, install the currently compatible dependency versions with: pip install -r requirements.txt 2. Unzip circulation-bound-reproduction_v5.zip and change into the repository root directory: cd circulation-bound-reproduction Run all commands from this repository root. Bundled data files and shared modules are resolved reliably from this location. All randomized tests are seeded, so their outputs are deterministic to the precision reported in expected_outputs.txt. 3. Run the numerical verification suite: python run_core_checks.py --smoke runs a short subset of checks. python run_core_checks.py --fast runs the main numerical checks while skipping the heaviest stochastic and gMAM calculations. python run_core_checks.py runs the full suite, including the canonical single-channel gMAM convergence sweep. The aggregate runner checks the printed numerical values and PASS/FAIL conditions rather than relying on exit codes alone. Compare the results with expected_outputs.txt. 4. Regenerate the figures: python make_figures.py regenerates all fourteen figures and collects them in figures/ under the manuscript filenames fig1_bound.pdf through fig14_eta_map.pdf. python make_figures.py --fast skips the heaviest figure generators, including Figs. 4, 5, and 12. 5. The principal V5 calibration check can also be run separately: python calibration_locus.py This checks that the route-handover locus can depend on the selected action calibration unless the competing routes have matched interior escape rates. It also checks that a symmetry-pinned η = 0 survives both calibrations, whereas an accidental cancellation need not. 6. To reproduce the window-closing experiment underlying Fig. 6 and Table II, run: python sfef/window_suite.py python sfef/window_fig.py The full suite takes several hours of CPU time. The deposited sfef/window_results.csv allows sfef/window_fig.py to regenerate the figure and table without repeating the stochastic simulation. 7. Fig. 13 can be regenerated immediately from the bundled fld/cont_rows.npy: python fld/fig_field.py To regenerate the underlying continuation data, run, in order: python fld/step1.py python fld/step2.py python fld/fig_field.py fld/step3.py is an independent small-drive resolution check and is not part of the Fig. 13 production pipeline. 8. Do not replace the bundled pickle-enabled NumPy files fld/cont_rows.npy or sfef/geom_cache.npz with files from untrusted sources.