Microbenchmarks

DEPRECATION NOTICE (Docs): Benchmark documentation is developer-focused and not part of the centralized user documentation. For canonical docs, start with docs/README.md and AGENTS.md.

This directory hosts targeted microbenchmarks for hot paths in the TNFR engine. Each script isolates a specific optimisation and contrasts it with a reference implementation. Use them to validate performance regressions after refactoring core operators.

Usage

PYTHONPATH=src python benchmarks/<script>.py

• Set PYTHONPATH=src so the interpreter can import the in-repo tnfr package without installing it.
• Scripts emit warnings for optional dependencies (NumPy, YAML, orjson). Those warnings are harmless during ad-hoc benchmarks.

Reproducibility

For deterministic benchmark execution with checksum verification:

# Run all reproducible benchmarks with default seed (42)
make reproduce

# Run specific benchmarks with custom seed
python scripts/run_reproducible_benchmarks.py \
  --benchmarks comprehensive_cache_profiler full_pipeline_profile \
  --seed 123 \
  --output-dir artifacts

# Verify checksums against manifest
make reproduce-verify
# Or manually:
python scripts/run_reproducible_benchmarks.py --verify artifacts/manifest.json

The reproducibility script ensures:

• Global seeds are set consistently across all benchmarks
• Output artifacts are generated with SHA256 checksums
• A manifest file tracks all benchmark runs for verification
• CI can detect when benchmark outputs change unexpectedly

Maintained benchmarks

Evolution backend speed-ups

Use the evolution benchmark to compare how the mathematics backends handle the unitary and contractive engines. The script honours the new CLI selector (--backends) and the TNFR_MATH_BACKEND environment variable, automatically skipping adapters when the corresponding dependencies (JAX, PyTorch) are missing. Results are reproducible thanks to the explicit RNG seed and optional JSON export:

PYTHONPATH=src python benchmarks/evolution_backend_speedup.py \
  --sizes 2 4 8 --steps 16 --repeats 3 --dt 0.05 \
  --output results/evolution_backends.json

Sample output on Python 3.11 with NumPy 2.3.4 (JAX/PyTorch unavailable) illustrates the reported tables:

Unitary mean time (milliseconds per run)

Contractive mean time (milliseconds per run)

Unitary speed-up vs. NumPy baseline

Contractive speed-up vs. NumPy baseline

When additional backends are available, their columns appear automatically in all four tables (unitary timing, contractive timing, and their respective speed-up ratios).

Broadcast accumulator regression check

The performance test suite now covers the vectorised accumulator that relies on numpy.bincount to collapse neighbour contributions. Run the slow-marked test to validate both speed and numerical parity against the pure-Python path:

PYTHONPATH=src pytest tests/performance/test_dynamics_performance.py \
  -k broadcast_neighbor_accumulator_stays_faster_and_correct -m slow

The command prints per-test timings; the assertion requires the NumPy path to complete at least 10 % faster while matching the fallback values within 1e-9 relative/absolute tolerance. Use it to capture before/after measurements when iterating on _accumulate_neighbors_broadcasted or related kernels.

Structural-emergence research benchmarks

These scripts are not performance microbenchmarks. They are falsifiable research harnesses that probe a single question of the TNFR programme: which numbers and arithmetic operations emerge from nodal/structural dynamics (∂EPI/∂t = νf · ΔNFR(t), whose canonical discrete ΔNFR / phase-curvature operator is the emergent random-walk Laplacian L_rw = I − D⁻¹W; the combinatorial L = D − A some harnesses use is its imposed cousin, sharing its eigenspaces on vertex-transitive graphs and giving the additive product spectra) rather than being injected by hand? Each harness pins its claim to an independent, classical ground-truth theorem (graph-product spectra, the representation theory of Aut(G), the field-of-fractions theorem, Schur's lemma) so the TNFR reading can be checked against mathematics that does does not depend on TNFR. The last meta-harnesses flip the question around: they ask whether the obstruction that the others run into is a single generic fact (equivariance_wall.py), whether the two ways out of it are one missing piece or two (missing_piece_bridge.py), and whether that one recipe extends from two Millennium programmes to a third — 3D Navier–Stokes (navier_stokes_recipe_bridge.py). A further harness returns to the emergence-of-numbers thread and completes the odd primes: it adds the ≡ 3 (mod 4) Paley-tournament complement (directed_paley_bridge.py) to Camino 9's ≡ 1 (mod 4) Paley-graph gap, and shows the mod-4 prime split is exactly the real-vs-phase boundary of the wall. The latest harness supplies the dynamical half of that thread: where Camino 9/14 read the primes off the static spectrum of a fixed graph, kuramoto_farey_bridge.py reads the rationals (and φ) off the time evolution of the nodal phase — the sine circle map as the single-node Kuramoto reduction of ∂EPI/∂t = νf · ΔNFR(t) — where mode-locked rotation numbers ρ = p/q are the rationals-OUT, the Farey/Stern-Brocot tree organises the Arnold tongues, φ emerges as the most-irrational (last-to-lock) Fibonacci limit, and the lock/no-lock split mirrors the same wall. The final harness ties that dynamical thread back to the ONE canonical proven object of the frozen Riemann programme: where kuramoto_farey_bridge.py only noted as a soft analogy that φ plays the residue role, golden_residue_remesh_bridge.py feeds its orbits through the N15 REMESH-∞ orthogonal projector R∞ (tnfr.riemann.split_residue_by_remesh_infinity) and checks where they land — the golden orbit in ker(R∞) (the dynamical twin of P50's prime-ladder S_TNFR ∈ ker), REMESH-commensurate lockings in range(R∞) — and exposes the analogy's honest limit (the projector lattice is coarser than the Farey set, so a locked ρ = 1/3 lands in the kernel too). The nineteenth and latest harness closes the methodological gap left by P31: where the canonical oscillatory_correction.py read the oscillatory observable S_TNFR off the classical Riemann–Siegel template and plugged in the prime-ladder spectrum, nodal_propagator_residue_bridge.py instead generates it from the canonical structural propagator e^{−s H_P14} itself — the nodal time-evolution operator — via the weighted spectral trace Z(s) = Tr(W e^{−s H_freq}) = Σ log(p) e^{−s k log p}, and diagnoses it with the two strongest post-N15 results jointly: the propagator oscillation Im Z(½+iT) lands in ker(R∞) (T2), and its kernel residue is S_n-degenerate to machine precision (T3, CCET made dynamical — shuffling the prime labels leaves the residue invariant), so the observable sits in ker(R∞) ∩ Fix(S_n) while the true S(T) needs the Fix(S_n)^⊥ half; the global amplitude scale matches S(T) (T4), confirming the obstruction is the missing phase/correlation structure, not magnitude (the structural reason P31's local correction needed a damping d ∼ 3–5). The twentieth harness turns from probing the wall sideways to studying coherence itself head-on, and folds in TNFR's own coherence metric. Where every prior harness asked can the catalog reach the residue, coherence_projector_sense_index.py asks what is the residue, exactly — and answers with the one proven N15 object: the REMESH-∞ operator R∞ is a bounded self-adjoint orthogonal projection (T1: ‖P²−P‖≈8e-18, ‖P−Pᴴ‖≈2e-18, rank = trace(P) = L = 8, Parseval exact, ⟨range,ker⟩≈0), so the "closed room" is literally the residue of coherence: ker(R∞) = range(I−P), the orthogonal complement of the coherent/resonant subspace. That room is vast (T2: dim(range) = L = 8 constant while dim(ker) = N−8 → ∞, coherent fraction L/N → 0) — the coherent subspace is finite-dimensional, the residue fills everything else. The harness then locates TNFR's Sense Index Si relative to the room: Si is a node-level coherence-capacity functional (T3: mean Si falls monotonically 0.70 → 0.40 as phase dispersion rises, peaking at full synchrony), and it is S_n-degenerate on the complete prime graph (T4: sorted Si invariant under prime relabelling to ≈2e-16), so — like C(t) and the weighted spectral trace — Si ∈ Fix(S_n) and is blind to the room's antisymmetric floor ker(R∞) ∩ Fix(S_n)^⊥ where S(T) lives. Unifies Si with the other symmetric diagnostics and characterises the closed room directly; closes nothing.

All twenty are dependency-light (NetworkX + NumPy), deterministic, and lint-clean. phase_wall.py, paley_bridge.py, boundary_vibration.py, directed_paley_bridge.py and nodal_propagator_residue_bridge.py additionally use mpmath (only to draw the Riemann target ζ(½+iT) / γₙ / S(T), never to derive it). Following the adelic discipline of src/tnfr/dynamics/adelic.py, every harness that touches the Riemann programme cross-checks the canonical tnfr engine when present (with NumPy-only fallbacks): equivariance_wall.py, commutant_bridge.py, missing_piece_bridge.py and navier_stokes_recipe_bridge.py ground their S_n-breaking per-node diagonal in the canonical adelic carrier νf = log p; chiral_involution.py uses tnfr.physics.emergent_particles; commutant_bridge.py, missing_piece_bridge.py and navier_stokes_recipe_bridge.py also use tnfr.yang_mills; navier_stokes_recipe_bridge.py additionally cross-checks the canonical 3D engine tnfr.navier_stokes (the vortex-stretching production); phase_wall.py, paley_bridge.py, boundary_vibration.py, primes_as_consequence.py and directed_paley_bridge.py use tnfr.dynamics.adelic (the last reuses paley_bridge.py's is_prime/paley_gap/quadratic_residues/riemann_s_phase and cross-checks the ≡ 3 (mod 4) prime support against the canonical carrier), and primes_as_consequence.py additionally cross-checks tnfr_primality.core (the canonical ΔNFR(n) pressure) and tnfr.riemann.paley_gap_coercivity (the canonical P25 scope), and kuramoto_farey_bridge.py cross-checks the canonical order parameter tnfr.gamma.kuramoto_R_psi (the Adler 2-oscillator lock) and the emergent golden-ratio limit (1+√5)/2 (the last-to-lock rotation number), and golden_residue_remesh_bridge.py projects its circle-map orbits with the canonical N15 projector tnfr.riemann.split_residue_by_remesh_infinity and reconciles against the P50 prime-ladder certificate tnfr.riemann.compute_residue_split_certificate (both with a NumPy DFT-bin-mask fallback); and nodal_propagator_residue_bridge.py generates its oscillatory observable from the canonical structural propagator tnfr.riemann.weighted_spectral_trace over the canonical prime-ladder Hamiltonian and spectrum (tnfr.riemann.build_prime_ladder_hamiltonian, tnfr.riemann.build_prime_ladder_spectrum), projects it with the same N15 projector, and reconciles against the P50 certificate tnfr.riemann.compute_residue_split_certificate; and coherence_projector_sense_index.py builds the R∞ projector matrix from the canonical N15 resonant-bin mask tnfr.riemann.build_resonant_bin_mask, computes the canonical Sense Index tnfr.metrics.sense_index.compute_Si, and draws its primes from the canonical tnfr.riemann.build_prime_ladder_spectrum. Run any of them directly:

PYTHONPATH=src python benchmarks/<script>.py

The harnesses build on one another: composition_arithmetic.py exports the shared spectral helpers (lap_spectrum, adj_spectrum, outer_sum, outer_prod, character_norm, eigenspaces, automorphism_matrices) reused by operational_irreducibility.py, bridge_primes_riemann.py, emergent_rationals.py, equivariance_wall.py (which also cross-checks the canonical tnfr.dynamics.adelic carrier νf = log p as its S_n-breaking per-node diagonal), chiral_involution.py (which also reuses integer_spectrum, is_pm_symmetric from emergent_rationals.py and winding_ring, winding_number, classify_particle from tnfr.physics.emergent_particles), and commutant_bridge.py (which reuses automorphism_matrices, cross-checks its YM side against the canonical tnfr.yang_mills.audit_nonabelian_derivability, and its RH side against the canonical tnfr.dynamics.adelic carrier νf = log p as its S_n-breaking escape diagonal), and phase_wall.py (which reuses adj_spectrum and cross-checks its phase carrier against the canonical tnfr.dynamics.adelic engine — νf = log p — mpmath's ζ(½+iT), and the same tnfr.yang_mills.audit_nonabelian_derivability U(1) verdict), and paley_bridge.py (which reuses adj_spectrum to cross-check the residue-circulant adjacency spectrum against the closed-form Paley eigenvalues (−1±√n)/2, and cross-references tnfr.dynamics.adelic for the νf prime support, tnfr.riemann.paley_gap_coercivity for the canonical P25 “does not close G4” scope, and mpmath's ζ(½+iT) for the continuous phase S(T)). boundary_vibration.py is self-contained on the algebra side (a NetworkX path graph and its ℤ₂ reflection) but cross-checks the canonical TNFR–Riemann stack end-to-end: tnfr.riemann.von_mangoldt (the −ζ'/ζ convergence barrier), tnfr.riemann.prime_ladder_hamiltonian (the self-adjoint {k log p} source, P14), tnfr.riemann.hilbert_polya (the imported γₙ target and the W₁ gap, P27), tnfr.dynamics.adelic (the νf = log p geometric-trace carrier), and mpmath's ζ(½+iT) to confirm the target ordinates are genuine zeros. missing_piece_bridge.py builds directly on commutant_bridge.py: it imports its adjacency_laplacian, canonical_per_node_diagonal, su2_generators, commutator_norm and symmetric_projector, reuses composition_arithmetic.py's automorphism_matrices, and cross-checks the canonical tnfr.yang_mills.audit_nonabelian_derivability (YM side) together with the adelic carrier νf = log p (RH side). navier_stokes_recipe_bridge.py extends that bridge to a third programme: it reuses commutant_bridge.py's adjacency_laplacian, canonical_per_node_diagonal, catalog_operators, commutator_norm and su2_generators, builds the strain / rotation split of a canonical Taylor–Green velocity field, and cross-checks the 3D vortex-stretching field of tnfr.navier_stokes.operator (exactly zero on a 2D-embedded field, nonzero in 3D) together with the same tnfr.yang_mills.audit_nonabelian_derivability U(1) verdict. directed_paley_bridge.py extends paley_bridge.py to the second odd prime class: it reuses that harness's is_prime, quadratic_residues, paley_gap and riemann_s_phase, builds the directed (non-symmetrised) residue circulant whose tournament spectrum (−1±i√q)/2 exposes the ≡ 3 (mod 4) primes through the imaginary Gauss-sum signature √q/2, and cross-checks the union of both odd prime classes against the canonical tnfr.dynamics.adelic carrier's prime support. kuramoto_farey_bridge.py is self-contained on the dynamics side (it iterates the sine circle map and harvests the devil's-staircase plateaus with NumPy and fractions.Fraction only), but cross-checks the canonical engine end-to-end: the emergent golden-ratio limit (1+√5)/2 (the Fibonacci-Farey limit) and the canonical Kuramoto order parameter tnfr.gamma.kuramoto_R_psi (the Adler 2-oscillator lock that confirms a commensurate detuning coheres while the golden detuning winds), turning Camino 9/14's static-spectrum emergence of the primes into the time-evolution emergence of the rationals and φ. golden_residue_remesh_bridge.py builds directly on kuramoto_farey_bridge.py: it reuses that harness's circle_map_rho, invert_rho, sweep_rho, PHI_INV and K_SUB to generate the circle-map orbits, then projects each demeaned cos(2πθ_n) signal with the canonical N15 projector tnfr.riemann.split_residue_by_remesh_infinity (NumPy DFT-bin-mask fallback) and reconciles the golden orbit's kernel membership against the canonical P50 prime-ladder certificate tnfr.riemann.compute_residue_split_certificate (RESIDUE_IN_KER_ONLY), turning Camino 15's soft φ-residue analogy into a precise statement about the kernel of an actual proven orthogonal projection. or physical realisation in coupled TNFR systems rather than being postulated. They do not derive the multiplicative prime fine structure of ℤ from pure dynamics — that residue coincides with the S_n-unreachable oscillatory term S(T) = (1/π) arg ζ(½ + iT) of the (frozen) TNFR-Riemann programme and is RH-equivalent. equivariance_wall.py makes this last point generic: the same Fix(G)^⊥ obstruction (prime individuation for S_n, degeneracy-lifting for D_n, the chiral sign for ℤ₂) is one group-theoretic shape shared by the Riemann, Navier–Stokes and Yang–Mills walls — it unifies the obstruction, it does not remove it. chiral_involution.py does the complementary, constructive move: the additive inverse −n of ℤ and the antiparticle are one chiral ℤ₂ (the anticommuting Γ A Γ = −A, distinct from the commuting Camino-5 automorphism wall), with n+(−n)=0 and the |W|=0 vacuum as the same neutral element — a precise structural analogy, not a derivation of CPT, antimatter, or the Standard Model. The real continuum ℝ is the assumed continuum substrate, and π is the one assumed structural scale; everything else emerges from the nodal dynamics. Nothing here advances or closes G4 = RH, Navier–Stokes regularity, or the Yang–Mills mass gap.

commutant_bridge.py is the deepest path and its thesis verdict is, by design, OPEN. Its structural checks pass at machine precision: in both the Riemann and the Yang–Mills programmes the reachable set is the commutant of a group acting on the (colour-lifted) graph, and each open target lives in the orthogonal complement that the commutant cannot reach — Fix(S_n)^⊥ (the RH residue S(T)) for the S_n permutation rep, and the traceless su(d) part of the non-Abelian curvature [A_μ,A_ν] for the U(d) gauge action (ℂ^{d×d}=ℂI_d⊕su(d), since {I_V⊗U}'=End(V)⊗ℂI_d by the double-commutant theorem). The catalog only ever builds f(A,L), which is colour-blind (f(A,L)⊗I_d) and therefore trapped in that commutant. This unifies the two Millennium obstructions as one shape; it does not close either. The escape in each programme is exactly the ingredient that is not nodal-equation-derivable: the per-node diagonal P2 for RH, and non-commuting su(d) generators for YM — the latter confirmed by the canonical tnfr.yang_mills.audit_nonabelian_derivability returning OPEN_DERIVABILITY_GAP (canonical_gauge_group = U(1), has_noncommuting_generators = False). Finite toy-graph plus su(2) linear algebra: it proves the obstructions coincide in shape, never that TNFR proves Yang–Mills, RH, or a mass gap.

phase_wall.py is the e–π companion to that deepest path and its thesis verdict is likewise, by design, OPEN. It asks why the open target is a phase. The four fields of the tetrad are the four orders of the derivative tower over the graph (only π is a genuine structural scale — the phase-wrap bound; the other field scales are heuristic or set by the spectral gap, ξ_C ∝ 1/√λ₂), and the catalog is built from the symmetric coupling A = Aᵀ and the self-adjoint L = D − A. Its structural checks pass at machine precision: every f(A,L) is self-adjoint, so its spectrum is real and its eigen-phases are locked to arg ∈ {0, π} (a sign), while the Riemann residue S(T) = (1/π) arg ζ(½ + iT) is a continuous phase on the e–π circle S¹ — the two sets are disjoint. The only map from the real axis to a continuous phase is the complexification z ↦ exp(i z) (Euler: exp(iπ) = −1); the canonical engine owns exactly one such carrier — the adelic unitary U(t) = diag(exp(i·t·νf)) with νf = log p (tnfr.dynamics.adelic) — and it does reach the circle, but its per-node arithmetic content νf = log p is imposed (a prime sieve), not produced by ∂EPI/∂t = νf·ΔNFR, which reads νf as input. Promoting νf to a circle-valued / Pontryagin-dual object is the non-derivable step (FORWARD_INDEPENDENT_OF_BACKWARD). This is the exact e–π mirror of the Yang–Mills U(1) gap of commutant_bridge.py: the canonical gauge is the same U(1) circle (a scalar phase exp(i φ)), and the missing ingredient — non-commuting generators (YM) / derived prime frequencies (RH) — is not nodal-derivable. The harness locates the residue as a real-vs-phase wall; reaching S(T) is RH-equivalent and remains OPEN.

paley_bridge.py answers a direct objection to phase_wall.py: the zeros do come from somewhere — the Paley gap. The objection is correct, and the harness concedes it with running code. The residue-circulant Laplacian λ₂ (computed by FFT) and the Paley gap g(n) = |λ₂ − (n−√n)/2| vanish exactly at the primes n ≡ 1 (mod 4) (reproduced to n ≤ 200 here; ≤ 2601 in the source note, Zenodo 10.5281/zenodo.17665853) — so the prime support of the carrier frequency νf = log p is not sieved, it emerges from a spectral identity that realises primality as a ΔNFR = 0 structural equilibrium. The adelic engine's ≡ 1 (mod 4) primes match the Paley-derived set exactly (21 = 21 up to 200). But this does not breach the Camino-8 wall — it sharpens it. Two facts pin the limit: (i) the Paley mechanism is real / self-adjoint (the residue circulant is symmetric ⇒ real λ₂ ⇒ real g(n), eigen-phases in {0,π}, adjacency spectrum matching the closed form (−1±√n)/2 to 5e-15), so it lives entirely in the real/scale sector; (ii) there are two different “zeros” — the Paley-gap zeros are real integers (primes ≡ 1 mod 4) and are disjoint from the Riemann ordinates γₙ (min distance 0.59), while S(T) = (1/π) arg ζ(½+iT) is a continuous phase that no real g(n) can produce. The source note states “reproducible; not a primality proof”; the canonical P25 module (tnfr.riemann.paley_gap_coercivity) states it “does not close G4”. So the Paley gap grounds the prime support (the real “where”), not the phase residue (the continuous “argument”): it demonstrates the real sector reaches even prime individuation, while the oscillatory S(T) stays in the orthogonal phase sector. Reaching S(T) remains RH-equivalent and OPEN. (Honest limit: the gap covers the ≡ 1 (mod 4) class only; ≡ 3 (mod 4) primes and 2 need a complementary construction.)

boundary_vibration.py follows the directive that every harness should derive whatever it can from TNFR structure and dynamics, exactly as src/tnfr/dynamics/adelic.py does (νf = log p, the nodal equation ∂EPI/∂t = νf·ΔNFR, the zeros held only as Ground-Truth target). It asks the sharpest form of the Hilbert–Pólya question — why can't the engine derive the zeros' location canonically, without mpmath? — and answers it with running code. Its structural checks pass at machine precision: (1) the TNFR-native von Mangoldt carrier Z_vM(s) = Σ w e^{−sμ} stabilises for Re(s) > 1 (matches the classical −ζ'/ζ(2) = 0.567 to 5e-3) but diverges as the truncation grows at Re(s) = ½ (drift 0.01 vs 13.3), so the object that sees the primes literally cannot be evaluated where the zeros live — the abscissa Re = 1 is the barrier; (2) the canonical self-adjoint Hamiltonian P14 reproduces the source spectrum {k log p} exactly with no mpmath; (3) the adelic geometric-trace carrier is built purely from νf = log p, while the nodal pressure ΔNFR = −∇V that lands the flow on the zeros is defined from the imported known_zeros — making visible that {γₙ} enter only as the resonance target; (4) self-adjoint + the ℤ₂ reflection R ⇒ real spectrum on the fixed axis (eigen-parities [+,−,+,−,…]), the rigorous core of the Hilbert–Pólya intuition: “self-adjoint ⇒ real ⇒ on the line” is TRUE as algebra. The honest residual (5): {k log p} grows like log n while γₙ grows like 2πn/log n (W₁(P14,T_HP) = 115, growth ratio 26), so no smooth structural map carries the source to the target. This locates G4 = RH precisely as the canonical analytic continuation of Z_vM across Re = 1 / the map {k log p} → {γₙ}; mpmath (P13/P27) only marks that barrier — it draws the target, it never derives it. Exhibiting the self-adjoint operator whose spectrum is {γₙ} from TNFR structure alone is the open piece. ℝ is the assumed continuum and π the one assumed structural scale; nothing here closes G4.

primes_as_consequence.py is the thirteenth harness and returns to the very first question of the map — do the primes themselves emerge, or are they fed in? — now that Caminos 5–10 have located the wall. Its thesis verdict is, by design, OPEN, and its structural checks pass at machine precision. It reuses composition_arithmetic.py's automorphism_matrices/character_norm/eigenspaces and paley_bridge.py's is_prime/paley_gap, and cross-checks the canonical tnfr_primality.core pressure, tnfr.dynamics.adelic, and tnfr.riemann.paley_gap_coercivity. It separates two readings of the canonical theorem “n prime ⟺ ΔNFR(n) = 0” (theory/TNFR_NUMBER_THEORY.md §4): Reading A evaluates ΔNFR(n) = ζ(Ω−1) + η(τ−2) + θ(σ/n − (1+1/n)) (the structural-pressure coefficients are canonical units; the prime ⟺ ΔNFR = 0 criterion is coefficient-independent, theory §4.2) and reproduces the primes n ≤ 200 exactly, but it consumes the factorization — Ω, τ, σ are obtained by n % d, so as a derivation it is circular (3026 trial divisions consumed; primes go IN and come back re-labelled ΔNFR = 0). Reading B is a genuine non-circular emergence: the Paley gap g(n) = 0 reads the primes ≡ 1 (mod 4) out of a self-adjoint residue spectrum built only from squares x·x mod n — it never computes n % k (21 = 21 primes-out up to 200). The frontier confirms the limit of pure emergence: the dim-4 mode of K₅ is irreducible (⟨χ,χ⟩ = 1.00) yet 4 = 2 × 2 arithmetically, so irreducibility ≠ primality — representation theory alone cannot reproduce unique factorisation. The bridge then pins the residual: the adelic carrier reads every prime IN (νf = log p), Reading B reads only the ≡ 1 (mod 4) class OUT, leaving 2, the ≡ 3 (mod 4) primes, and the continuous phase S(T) = (1/π) arg ζ(½+iT) as the same real-vs-phase wall as Caminos 8–10. So the optic-shift is real and clarifying — a TNFR prime is a zero-pressure structural equilibrium, partially spectrally emergent — but it locates the residual; it does not close G4 = RH. ℝ is the assumed continuum and π the one assumed structural scale.

missing_piece_bridge.py is the fourteenth harness and closes the conceptual arc of Caminos 5–11 by asking the sharpest cross-program question directly: are the two ways out of the wall — the RH S_n-breaking diagonal and the Yang–Mills non-commuting generators — one missing canonical piece, or two? Its thesis verdict is, by design, OPEN, and its four structural checks pass at machine precision. The strong unifying conjecture (recorded in repo memory: one absent canonical piece; closing one gives the other) is REFUTED: the two escapes act on different tensor factors — the base V = ℂⁿ for RH, the fibre ℂ^d for YM — D is Abelian-on-base (diagonal/Cartan) while su(d) is non-Abelian-on-fibre, and D ⊗ I commutes with I ⊗ T_a, so the base ingredient cannot manufacture the fibre's generators. What survives is a precise weaker unification: both gaps are the same recipe (break a commutant by adjoining a non-commuting, traceless operator — so(n) on the base, su(d) on the fibre) sharing one non-derivability root (no per-node / per-fibre slot in ∂EPI/∂t = νf · ΔNFR). It reduces two mysteries to one recipe with two independent realisations, not to one piece; it sharpens the conjecture and closes nothing. ℝ is the assumed continuum and π the one assumed structural scale; nothing here proves RH or the Yang–Mills mass gap.

navier_stokes_recipe_bridge.py is the fifteenth harness and asks whether the weaker unification that missing_piece_bridge.py left standing — one recipe, two realisations — reaches a third Millennium programme, the global-regularity problem for the 3D incompressible Navier–Stokes equations. Its thesis verdict is, by design, OPEN, and its four structural checks pass at machine precision. The reachable / smooth half is the linear viscous flow — the heat semigroup exp(−ν t L), self-adjoint, equivariant, scale-translation commuting — exactly the NS analogue of Riemann's range(R∞) and Yang–Mills' colour-scalar part. The obstruction is the non-linear vortex-stretching term (ω·∇)u, and the canonical engine's own vortex_stretching_field() docstring states the gating verbatim: “in 2D it is identically zero … so 2D NS is globally regular; in 3D it can in principle amplify enstrophy without bound … the Clay Millennium Problem NS-G5.” Structurally the stretching is carried by the velocity-gradient split ∂_i u_j = S_ij + Ω_ij into the strain S (symmetric, traceless because tr S = ∇·u = 0 by incompressibility) and the rotation Ω (antisymmetric, ∈ so(3) ≅ su(2)). This is the same recipe as RH ([A,D] ∈ so(n), traceless by anti-symmetry) and YM (su(d), traceless by definition) — adjoin a non-commuting traceless generator — now on a third tensor factor: the velocity-component fibre ℂ³, distinct from RH's prime base and YM's colour fibre. The wall is gated by non-Abelianity exactly as before: ‖(ω·∇)u‖ = 0 to machine precision for a 2D-embedded field (rotation lives in the Abelian so(2), one generator, no wall — reproduced against the canonical operator), and ≠ 0 for the genuine 3D Taylor–Green field (non-Abelian so(3), wall present) — the same threshold as RH needing n ≥ 2 primes and YM needing d ≥ 2 colours. The non-derivability roots are one family on distinct slots: RH's νf = log p is imposed, YM's non-Abelian multiplet is an audited derivability gap, and NS's residue is the Cascade Development Condition, which CHANGELOG N17-A records as “not derivable from U3, U5, or the nodal equation … the structural analogue of S(T) = (1/π) arg ζ(½+iT) in the Riemann programme.” The harness therefore extends the weaker unification from two Millennium programmes to three — one recipe, three realisations (so(n) prime base / su(d) colour fibre / so(3) velocity fibre) — and closes nothing: NS-G5, the Clay 3D Navier–Stokes problem, RH (G4), and the Yang–Mills mass gap all remain OPEN. The recipe unifies the obstructions; it does not remove them. ℝ is the assumed continuum and π the one assumed structural scale.

directed_paley_bridge.py is the sixteenth harness and returns to the emergence-of-numbers thread (Caminos 1–9) to settle Camino 9's one explicit open gap: do the ≡ 3 (mod 4) primes emerge too, or only the ≡ 1 (mod 4) class? Its thesis verdict is, by design, OPEN, and its four structural checks pass at machine precision. Camino 9 grounded the ≡ 1 (mod 4) primes in a REAL/self-adjoint Paley graph gap (−1 is a quadratic residue there, so the residue circulant is symmetric — the scale sector). This harness grounds the ≡ 3 (mod 4) primes in the IMAGINARY Gauss-sum signature of the Paley tournament (−1 is a non-residue, so A + Aᵀ = J − I and the secondary eigenvalues are (−1 ± i√q)/2, real part −½, imaginary part ±√q/2 — the phase sector). The new detector h(n) = 0 reads the ≡ 3 (mod 4) primes out of squares alone (24/24 up to 200, never n % k), so Camino 9's real gap g(n) and this imaginary gap h(n) together make every odd prime emerge (21 + 24 = 45 odd primes ≤ 200, cross-checked against the canonical adelic carrier), split exactly by whether −1 is a quadratic residue — which is precisely the real-vs-phase boundary of the Equivariance Wall. But both sectors are NORMAL operators with DISCRETE point spectra: "i times self-adjoint" is still not the continuous phase S(T) = (1/π) arg ζ(½ + iT), which remains RH-equivalent and unreachable, and the even prime 2 (≡ 2 mod 4) sits outside both classes. So the harness extends the emergence-of-numbers line to all odd primes and connects the mod-4 prime split to the wall — but it closes nothing: 2, the continuous phase S(T), and G4 = RH all remain OPEN. ℝ is the assumed continuum and π the one assumed structural scale.

kuramoto_farey_bridge.py is the seventeenth harness and supplies the dynamical half of the emergence-of-numbers thread (Caminos 1–9, 14): where Camino 9/14 read the primes off the static spectrum of a fixed graph, this harness reads the rationals (and φ) off the time evolution of the nodal phase. Its thesis verdict is, by design, OPEN, and its four structural checks pass. The carrier is the sine circle map θ_{n+1} = θ_n + Ω − (K/2π) sin(2π θ_n), which is exactly the single-node Kuramoto reduction of ∂EPI/∂t = νf · ΔNFR(t) (Ω = νf the bare structural frequency, −(K/2π) sin(2π θ) = ΔNFR the coupling pressure), and the emergent quantity is the rotation number ρ = lim (θ_N − θ_0)/N. (1) The rationals emerge blind as the mode-locked plateaus of the devil's staircase: harvesting the flat runs at criticality recovers 41 distinct rationals via limit_denominator alone — the dynamical twin of Camino 9/14's primes-OUT spectral emergence. (2) The Farey/Stern-Brocot tree organises the Arnold tongues: between Farey neighbours the widest plateau is the mediant, and tongue width strictly shrinks along the Fibonacci path 1/2, 2/3, 3/5, 5/8 → 0. (3) φ emerges as the canonical, most-irrational number: the Fibonacci ratios F_n/F_{n+1} → 1/φ = [0; 1, 1, 1, …] saturate the Hurwitz bound (√5·q²·err → 0.9999) and the limit is the golden ratio (1+√5)/2, recovered numerically to 6e-13. (4) At sub-critical coupling φ does not lock (the staircase is incomplete, locked measure 0.184 < 1): the locked rationals are the reachable half (range R∞), while the un-locked irrationals — φ foremost, the LAST to lock — play the residue role (ker R∞ = Fix(G)^⊥), the dynamical analogue of the oscillatory S(T) = (1/π) arg ζ(½ + iT) (the canonical tnfr.gamma.kuramoto_R_psi confirms the Adler-locked commensurate pair coheres at R = 0.95 while the golden detuning winds). But the analogy is honest and soft: φ is only the un-lockable limit of reachable rationals (an accumulation boundary), not the hard orthogonal residue S(T); the dynamics yields a discrete set of rationals plus one distinguished φ, never the continuum. So the harness extends the emergence-of-numbers line from the spectral to the dynamical side and connects the lock/no-lock split to the wall — but it closes nothing: G4 = RH remains OPEN, and ℝ is the assumed continuum and π the one assumed structural scale.

golden_residue_remesh_bridge.py is the eighteenth harness and is the capstone of the dynamical thread: it ties Camino 15 to the ONE canonical proven object of the (frozen) TNFR-Riemann programme — the N15 REMESH-∞ orthogonal projector R∞ (theory/REMESH_INFINITY_DERIVATION.md, Branch A). Its thesis verdict is, by design, OPEN, and its four structural checks pass at machine precision using the canonical projector tnfr.riemann.split_residue_by_remesh_infinity. Camino 15 only noted, as a soft analogy, that φ (the last to lock) plays the residue role; this harness makes it precise. (1) The golden quasi-periodic orbit ρ = 1/φ lands in ker(R∞) (range fraction 0.15%): its incommensurate frequency 2π/φ misses the resonant lattice {2πm/L}, L = lcm(4,8) = 8 — the dynamical twin of P50's prime-ladder S_TNFR ∈ ker(R∞) (whose carrier log p is incommensurate by Baker's theorem). (2) REMESH-commensurate lockings ρ = 1/2, 1/4 (periods 2, 4 | 8) land in range(R∞) (100%): every harmonic sits on the resonant lattice. (3) The honest limit: a genuinely locked ρ = 1/3 (period 3 ∤ 8) also lands in ker(R∞) (100%), so Camino 15's lock/no-lock dichotomy does not map one-to-one onto N15's range/ker split — R∞'s lattice is coarser than the full Farey set of lockings, and range(R∞) is the period-divides-L sub-lattice only. (4) The engine's own controls reproduce (sin(2πT/8) → range, sin(γT) → ker 99.99%), and the canonical P50 certificate confirms the prime-ladder S_TNFR ∈ ker — the same kernel holds both the arithmetic residue carrier (log p, Baker) and the golden orbit, two incommensurate carriers of one large residue subspace (its complement, the resonant lattice, is measure-zero among all frequencies). Membership in ker(R∞) LOCATES the residue; it is not a route to RH. The harness sharpens the Camino-15 analogy (golden ∈ ker, now precise) and limits it (not all lockings reach range) at once — and closes nothing: G4 = RH remains OPEN, and ℝ is the assumed continuum and π the one assumed structural scale.

Structural-emergence benchmarks — chemistry, geometry & dimension

A second structural-emergence arc applies the same let-it-emerge discipline to shell structure, symmetry cardinals and spatial dimension, under one canonical gate: everything must emerge from TNFR structure and dynamics — no imported quantum mechanics, no Coulomb law, no postulated geometry. Each harness models a system as a pure structural manifold (or reads the substrate's own emergent symplectic geometry), lets the structure/dynamics produce what it produces, and only then identifies the emergent ontology against observed phenomena. As with the numbers thread, the comparison framework (Laplace–Beltrami (2l+1) degeneracies, the representation theory of the dynamical-symmetry groups SO(3)/SO(4)/U(3), the K_m-simplex Laplacian spectra, the spectral dimension estimator) is standard external mathematics; the TNFR contribution is the emergent reading and the honest boundary where a pure single-coherence manifold stops and a two-body / imported-geometry ingredient would be required. All seven are dependency-light (NetworkX + NumPy), deterministic (no RNG — the sphere/ball graphs are Fibonacci-deterministic), and lint-clean. Several reuse the canonical tnfr.physics.emergent_chemistry primitives (fibonacci_sphere_graph, structural_eigenmodes), the canonical nodal-topology read-out tnfr.physics.fields.classify_nodal_topology (the radial/annular/multinodal emergent geometry), the substrate certificate tnfr.physics.symplectic_substrate.verify_polarization_symmetry (the U(2) polarization symmetry), and the shared fixed-point kernel tnfr.metrics.common.is_structural_equilibrium (closed shell = prime = relaxed node = one ΔNFR = 0 predicate). Run any of them directly:

PYTHONPATH=src python benchmarks/<script>.py

The rigorous emergent facts are pinned as engine tests in tests/physics/test_emergent_chemistry.py (14 tests: the (2l+1) angular degeneracy, the emergent radial nucleus, the 2,8,18 spherical-well closures, the ΔNFR = 0 closed-shell predicate, and the non-spectral boundary of the aufbau (n+l) postulate).

Honest synthesis. Pure single-manifold TNFR structure reproduces the independent-particle (mean-field) skeleton that atoms and nuclei share — the (2l+1) multiplets, the central-field shells, the independent-particle magic 2, 8, 20 — and the substrate's own emergent symmetry is U(2) (2D quantum-dot cardinals), structurally locked. The domain-specific corrections are the known two-body physics that a single coherence manifold cannot carry: screening (→ atomic 2,10,18,…) and spin-orbit (→ nuclear 28,50,82). So spatial dimensionality and 3D rotational symmetry are inputs, not predictions — TNFR's emergent geometric substrate is intrinsically a 2D resonant theory (the U(2) fibre). The deeper resolution of the dimension question is that the dimension which truly emerges from a form is its simplex grade (= the cardinal it carries): the coherent coupled-NFR cluster (EPI) is an n-simplex of dimension n, the dynamics builds it by resonant coherent accretion gated by U3, and that form-grade dimension is unbounded and dynamically generated — a notion distinct from the locked U(2) fibre symmetry. Closed shell = prime = relaxed node is one ΔNFR = 0 fixed point across all three domains. Honest scope: these are emergent-ontology falsifiers, not derivations of the periodic table, the nuclear shell model, or 3D space; the standard representation theory and spectral geometry are the comparison framework, and ℝ is the assumed continuum and π the one assumed structural scale.

Retired scripts

Older benchmarks covering glyph history trimming, usage counters, or glyph timing updates have been removed because the optimised paths now mirror the reference implementations. Keeping them would create maintenance noise without providing actionable performance signals.

Profiling workflows

ΔNFR default pipeline

Run the benchmark with profiling enabled to capture cumulative timings for the entire ΔNFR pipeline. Choose the output format that best fits your tooling:

PYTHONPATH=src python benchmarks/default_compute_delta_nfr.py \
  --nodes 320 --edge-probability 0.22 --repeats 3 \
  --profile profiles/dnfr_default.pstats

• Use --profile-format json to export an ordered JSON array with the totaltime and inlinetime for each function.
• Inspect .pstats files via python -m pstats profiles/dnfr_default.pstats and sort on cumtime (cumulative time) or tottime (self time) to spot hotspots.

Sense Index vectorised vs. fallback paths

The profiling script mirrors the setup from tests/performance/test_sense_performance.py to compare vectorised and pure-Python Si computations:

PYTHONPATH=src python benchmarks/compute_si_profile.py \
  --nodes 512 --loops 8 --format json --output-dir profiles

The command writes two files:

• compute_Si_numpy.* – profile captured when NumPy is available.
• compute_Si_python.* – profile captured with NumPy disabled, exercising the fallback path.

Inspect the top entries sorted by cumtime (cumulative time per function) to spot the phases consuming most wall-clock time. Compare both outputs to confirm that vectorisation shifts time into array primitives rather than Python loops.

Full pipeline profiling (Si + ΔNFR)

PYTHONPATH=src python benchmarks/full_pipeline_profile.py \
  --nodes 384 --edge-probability 0.28 --loops 6 --output-dir profiles \
  --si-chunk-sizes auto 2048 --dnfr-chunk-sizes auto 4096

The profiler iterates over the Cartesian product of the requested Si and ΔNFR chunk sizes (and, when provided, worker counts via --si-workers and --dnfr-workers). Each combination is tagged as cfgXX and encoded in the artefact name, for example full_pipeline_vectorized_cfg01_si_auto_dn_auto_siw_auto_dnw_auto.json.

For every configuration + execution-mode pair the script writes matching .pstats and .json files. The JSON schema now includes:

• configuration – the label, ordinal, textual description, and raw knob values (SI_CHUNK_SIZE, DNFR_CHUNK_SIZE, SI_N_JOBS, DNFR_N_JOBS).
• metadata – runtime context covering vectorisation, graph size, and the requested/resolved chunk sizes and worker counts applied to the seeded graph.
• operator_totals – raw wall-clock totals for each explicit operator call in the benchmark loop.
• operator_timings – totals and per-loop averages per operator (mirrored under manual_timings for backwards compatibility).
• compute_Si_breakdown – wall-clock totals, per-loop averages, and execution path counts for the Sense Index sub-stages (cache rebuilds, vectorised neighbour aggregation, normalisation/clamp, and in-place writes). Use the path_counts entry to verify whether the NumPy kernels or the pure-Python fallback handled the run.
• target_functions – cumulative profiler statistics (cumtime, totaltime) for the four canonical operators. Use this section to compare how much time each function spends (including callees) in vectorised vs. fallback modes.
• rows – the complete, sorted profiler table, matching the .pstats export. Inspect it when a hotspot needs deeper call-tree analysis.

Contrast the vectorised and fallback JSON summaries to confirm that NumPy shifts most cumulative time from _compute_dnfr_common into array-based kernels and that compute_Si benefits from the same optimisation. The console output now prints the same Sense Index breakdown, making it easier to spot whether cache reconstruction or neighbour aggregation dominates the runtime. Cross-check the path_counts field—vectorised runs should report NumPy activity while fallback profiles stay in the Python bucket. Significant regressions should surface as higher cumtime values or inflated per-loop wall-clock figures across both the top-level operator timings and the Si sub-stages.

_compute_dnfr vectorisation checks

Use the microbenchmark to compare the NumPy and pure-Python branches directly across multiple graph sizes and densities:

PYTHONPATH=src python benchmarks/compute_dnfr_benchmark.py \
  --nodes 192 384 768 --edge-probabilities 0.05 0.12 0.3 --repeats 8

The output prints a compact table per configuration with:

• Vectorised best/median/mean/worst – summary timings in seconds when NumPy is available.
• Fallback best/median/mean/worst – the pure-Python execution statistics.
• Ratio (fallback ÷ vectorized) – the average slow-down when vectorisation is disabled. Ratios significantly above 1.00× confirm that dense kernels are exercised and provide a guardrail for regressions.

Pass --force-dense to ensure the dense accumulator path is exercised when the automatic heuristics might prefer sparse accumulation. The script gracefully degrades to reporting only the fallback timings whenever NumPy is unavailable.

Chunked execution switches

Both benchmarks honour the new batching knobs exposed by the engine:

• Set graph.graph["SI_CHUNK_SIZE"] = 2048 (or pass chunk_size=2048 when calling compute_Si) inside compute_si_profile.py to process nodes in deterministic batches. This is helpful when profiling large (>10k nodes) graphs on memory-constrained machines.
• Set graph.graph["DNFR_CHUNK_SIZE"] = 4096 before invoking default_compute_delta_nfr to bound the accumulator size in the ΔNFR benchmark. Larger chunks favour throughput, while smaller ones keep the temporary buffers inside stricter memory budgets.

Leave both settings unset for medium-sized runs; the automatic heuristics use CPU availability and a conservative memory estimate to choose a balanced chunk size.

Cache Profiling

Comprehensive Cache Analysis

The comprehensive_cache_profiler.py tool tracks buffer allocation effectiveness across all TNFR hot paths:

PYTHONPATH=src python benchmarks/comprehensive_cache_profiler.py \
  --nodes 200 --steps 50 --buffer-cache-size 256 \
  --output cache_report.json

Key Metrics Reported:

• Buffer Reuse Rate: Should remain near 100% (indicates effective buffer caching)
• Edge Cache Hit Rate: Per-hot-path buffer allocation cache effectiveness
• TNFR Cache Hit Rate: DNFR preparation state and structural cache hits
• Cache Entry Count: Memory usage tracking

Sample Results (100 nodes, 20 steps):

• coherence_matrix: 97.5% hit rate, 100% buffer reuse ⭐
• default_compute_delta_nfr: 96.7% hit rate, 100% buffer reuse ⭐
• sense_index: 0.7% hit rate, 100% buffer reuse (expected - creates new structural arrays)
• dnfr_laplacian: 0.0% hit rate, 100% buffer reuse (by design - stateless gradients)

For detailed analysis see ARCHITECTURE.md.

Usage Examples:

# Basic profiling
python benchmarks/comprehensive_cache_profiler.py --nodes 100 --steps 20

# Detailed per-step metrics
python benchmarks/comprehensive_cache_profiler.py --nodes 200 --steps 50 --verbose

# Export JSON report
python benchmarks/comprehensive_cache_profiler.py \
  --nodes 150 --steps 30 --buffer-cache-size 256 \
  --output cache_analysis.json

# Test different cache sizes
python benchmarks/comprehensive_cache_profiler.py \
  --nodes 500 --steps 100 --buffer-cache-size 512

Interpreting Results:

1. Buffer Reuse Rate = 100% ✅ Optimal - buffers are being reused perfectly
2. Buffer Reuse Rate < 95% ⚠️ Investigation needed - possible cache thrashing
3. High Edge Cache Misses + 100% Buffer Reuse ✅ Normal for Si/Laplacian (creates new entries but reuses buffers)
4. High Eviction Rate ⚠️ Consider increasing --buffer-cache-size

The comprehensive profiler supersedes the basic cache_hot_path_profiler.py by tracking all cache layers.