Metadata-Version: 2.4
Name: nwt-substrate
Version: 0.5.0
Summary: Substrate-algebraic computation library for Null Worldtube Theory.
Author-email: Jim Galasyn <jim.galasyn@hotmail.com>
License: MIT License
        
        Copyright (c) 2026 Jim Galasyn and the NWT contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/JimGalasyn/nwt-substrate
Project-URL: Repository, https://github.com/JimGalasyn/nwt-substrate
Project-URL: Bug Tracker, https://github.com/JimGalasyn/nwt-substrate/issues
Project-URL: Paper series, https://zenodo.org/communities/nwt
Keywords: physics,particle-physics,topological-quantum-field-theory,knot-theory,octonions,null-worldtube,substrate-monism
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: sympy>=1.12
Requires-Dist: networkx>=2.8
Provides-Extra: heron
Requires-Dist: qiskit>=1.0; extra == "heron"
Requires-Dist: qiskit-ibm-runtime>=0.20; extra == "heron"
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: qiskit>=1.0; extra == "test"
Requires-Dist: astropy>=6.0; extra == "test"
Provides-Extra: all
Requires-Dist: nwt-substrate[heron,test,torch]; extra == "all"
Dynamic: license-file

# nwt-substrate

[![tests](https://github.com/JimGalasyn/nwt-substrate/actions/workflows/test.yml/badge.svg)](https://github.com/JimGalasyn/nwt-substrate/actions/workflows/test.yml)
[![benchmarks](https://github.com/JimGalasyn/nwt-substrate/actions/workflows/benchmarks.yml/badge.svg)](https://github.com/JimGalasyn/nwt-substrate/actions/workflows/benchmarks.yml)
[![codecov](https://codecov.io/gh/JimGalasyn/nwt-substrate/branch/main/graph/badge.svg)](https://codecov.io/gh/JimGalasyn/nwt-substrate)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20012027.svg)](https://doi.org/10.5281/zenodo.20012027)
[![release](https://img.shields.io/github/v/release/JimGalasyn/nwt-substrate?label=release)](https://github.com/JimGalasyn/nwt-substrate/releases)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://github.com/JimGalasyn/nwt-substrate)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

![One QED amplitude, two views: the Compton process with its substrate amplitude color-mapped term-by-term (left), and the K_7-on-torus / Cl(0,7) substrate its gamma-matrices descend from (right)](docs/assets/readme_hero.png)

<sub>The Compton amplitude *i*𝓜 with each chunk colored to the diagram line it represents, beside the K<sub>7</sub> Heffter embedding (7 vertices, 21 edges = the so(7) generators) it rides on — pick 4 of the 7 Cl(0,7) imaginary directions for the Dirac γ<sup>μ</sup>, the remaining 3 generate the internal SU(2). Generated by the library's `diagrams` submodule: `python3 diagrams/readme_hero.py`.</sub>

A substrate-algebraic computation library for Null Worldtube Theory (NWT).

`nwt-substrate` is the reference implementation of the substrate algebra
described in the NWT paper series: a Cl(0,7) octonion Clifford algebra
with K_7 graph state on the Heegaard torus of the Brieskorn-Poincaré
sphere S^3 / 2I, supporting particle / scattering / decay /
gravitational-coupling / chemistry computations from a single
internally consistent codebase.

This library is an algebraic continuation of the **photon-vortex programme**
(Williamson & van der Mark 1997 and successors): particles as confined
toroidal structures of the electromagnetic / substrate field, with mass and
quantum numbers emerging from topology. NWT supplies the explicit substrate
algebra — K_7 / so(7) / Spin(7) / Cl(0,7) — that turns the topological
intuition into closed-form quantitative predictions. The
[paper series on Zenodo](https://zenodo.org/communities/nwt) is the
derivation record; this library is the executable companion.

**Since v0.2.0** (current release **v0.5.0**, 2026-06-13), the library ships a
**substrate Instruction Set Architecture** (`nwt_substrate.isa`) that
makes the K_7 algebra load-bearing across every shim. ~25
structural constants (`N_EDGES_K7 = 21`, `N_VERTICES_K7 = 7`,
`DIM_OCTONION = 8`, `RANK_SO7 = 3`, `N_GENERATIONS = 3`,
`N_CARRIER_TYPES = 7`, `B_QED_SM = 8`, …) live in one place,
are asserted at import time, and are consumed by seven
view-shims (chemistry, gravity, qed, qcd, particles, electroweak,
heron). The substrate algebra compiles all the way through to the
21 CZ gates that fire on IBM Heron when `k7_graph_state()` runs.

## Headline predictions

All derived from the substrate algebra at zero free parameters
(beyond the four substrate constants m_e, M_Pl, c, ℏ):

- **Electron mass ratio**: m_e / m_Pl ≈ 4.185 × 10⁻²³ via α^(21/2) Wilson
  amplitude on the K_7 graph state — Paper 17, **−5.5 ppm CODATA**.
  Call: `isa.k7_wilson_amplitude(1/137.036, order="NNLO")`.
- **Newton's G**: 6.674228 × 10⁻¹¹ m³ kg⁻¹ s⁻² via Sakharov-induced
  gravity — Paper 17, **−11 ppm CODATA, inside the ±22 ppm experimental
  band**. Call: `gravity.G_substrate_SI()`.
- **Particle mass spectrum**: 24-particle compendium (hadronic + leptonic
  + exotic) at **0.76 % median residual** — Paper 6 topological mass
  formula. Call: `nwt.particle("p").mass_pred → 937.24 MeV`.
- **Molecular bound states via connected-sum**: deuteron mass-prediction
  residual −0.06 % vs PDG, Pc(4312) +0.013 %, all five tested
  near-threshold molecules within ~0.6 %.
  Call: `nwt.compose(p, n, op="#")`.
- **Coronene aromaticity**: K_7-toroidal resonance energy = 200.0 kcal/mol
  exact (+56 kcal/mol stabilization detected via `Tr(M²) ≤ −24` on the
  K_7 W_6-wheel signature). Call: `chem.smiles_resonance_energy(...)`.
- **Heron quantum-hardware structural verification**: 7 H gates + 21 CZ
  gates fired on IBM Heron, runtime-verified against `isa.N_VERTICES_K7`
  and `isa.N_EDGES_K7`. Call: `heron.k7_graph_state()`.
- **Neutrino sector** (Paper 20, K_8 extension): three active masses
  ≈ (14.8, 17.2, 53) meV, three sterile masses ≈ (61.3, 70.8, 218.8)
  MeV, mixing |U_α4|² ≈ 2.4×10⁻¹⁰, PMNS angles + δ_CP = −2π/3 from
  π_1(PSU(3)) winding. Call: `nwt.neutrino.substrate_breakdown()`.
- **38 forward-prediction benchmarks** (`nwt_substrate.benchmarks`) —
  substrate algebra vs traditional-method speed and accuracy across particle
  physics, atomic physics, QED/QCD, electroweak precision, cosmology, gravity,
  black-hole thermodynamics, and chemistry. Full suite in **~100 ms**: α at
  7.6 ppm, G at 11 ppm, v_EW at 28 ppm, **sin²θ_W (on-shell, (2+α)/9) at <0.1 %**
  (it *is* `1 − M_W²/M_Z²`; the effective angle is +3.68 % via radiative running),
  **Ω_b/Ω_c at 0.0067 %** (better than the Planck systematic), Higgs mass via
  λ_H = 18α at 0.9 %, etc. **v0.4.0** added the standard hadronic QCD correction
  to the Z width (Γ_Z 2.93 % → 0.31 %), decomposed the muon lifetime (weak-sector
  closure now 0.007 %), a sensitivity **structural-criticality** layer
  (`--criticality`), and L. Leighton's **O10 derivation-separation** predictor +
  DAG cit-readout (`benchmarks.predict`, `benchmarks.o10 --suite`).
  Anti-numerology argument made empirically concrete:
  `from nwt_substrate.benchmarks import run_all; run_all()`.
  See [`nwt_substrate/benchmarks/README.md`](nwt_substrate/benchmarks/README.md).
- **1436 substrate tests pass in ~2 minutes**, including 92
  substrate-identity enforcement tests across seven K_7 shims plus
  31 K_8 neutrino-sector tests — the substrate algebra is enforced
  by the codebase, not merely described.

## Install

```bash
pip install nwt-substrate          # not yet on PyPI; for now:
pip install git+https://github.com/JimGalasyn/nwt-substrate.git
```

## Quick start

**Try this first** — three substrate predictions in three lines:

```python
import nwt_substrate as nwt
nwt.particle("p").mass_pred                          # → 937.24 MeV (proton, Paper 6)
nwt.gravity.G_substrate_SI()                         # → 6.674228e-11, -11 ppm CODATA (Paper 17)
nwt.isa.k7_wilson_amplitude(1/137.036, order="NNLO") # → 4.185e-23 = m_e / m_Pl, -5.5 ppm
```

Three independent substrate predictions — particle mass, gravitational
coupling, and the underlying K_7 Wilson amplitude — all matching CODATA
to ppm precision in three function calls.

**The K_7 cross-shim demo** — one substrate, seven shims:

```bash
python3 analysis/isa_cross_shim_demo.py
```

This walks the K_7 algebra through chemistry (coronene aromatic
resonance energy), gravity (m_e/M_Pl via α^(21/2) Wilson amplitude),
qed (8×8 Dirac γ matrices via Cl(0,7) → Cl(1,3)), qcd (8 gluons + 3
colors via Spin(7) ⊃ G_2 ⊃ SU(3)), particles (Paper 6 mass formula on
7 carrier-knot types), electroweak (`b_QED^SM = 8 = DIM_OCTONION`
empirically verified from the SM fermion table), and heron (a qiskit
circuit with exactly 7 H + 21 CZ gates, runtime-verified). Ends with
the substrate identity table showing 8 surfaces in four independent
physics computations.

Particle masses from substrate quantum numbers:

```python
>>> import nwt_substrate as nwt
>>> p = nwt.particle("p")
>>> p.mass_pred
937.24...                             # MeV, Paper 6 mass formula
>>> p.J, p.Q, p.B
(0.5, 1, 1)
>>> p.carrier                          # sourced from isa.CARRIER_NAMES
'cinquefoil'
```

Connected-sum composition law for molecular bound states:

```python
>>> p, n = nwt.particle("p"), nwt.particle("n")
>>> d = nwt.compose(p, n, op="#", name="d", m_obs=1875.61)
>>> d.mass_pred                       # ~1874.48 MeV
>>> d.mass_residual                   # ~ -0.06 % vs PDG
```

Gravitational coupling from substrate alone (now via the ISA):

```python
>>> from nwt_substrate.gravity import G_substrate_SI
>>> G_substrate_SI()                  # 6.674228e-11 m^3 kg^-1 s^-2
                                       # -11 ppm of CODATA, inside ±22 ppm
                                       # experimental error bar
>>> import nwt_substrate.isa as isa
>>> isa.k7_wilson_amplitude(1/137.036, order="NNLO")
4.185439e-23                           # m_e/M_Pl, -5.5 ppm from CODATA
```

Chemistry — aromatic resonance energy from SMILES via batched so(7)
trace invariants:

```python
>>> import nwt_substrate.chemistry as chem
>>> chem.smiles_resonance_energy("c1cc2ccc3ccc4ccc5ccc6ccc1c1c2c3c4c5c61")
200.0                                  # coronene: K_7-toroidal +56 kcal/mol
                                       # stabilization detected via Tr(M²) ≤ -24
                                       # (= TR_M2_W6 from isa.constants)
```

ISA kernel — substrate-native batched contraction:

```python
>>> import numpy as np
>>> import nwt_substrate.isa as isa
>>> # Build a K_7 adjacency
>>> A = np.ones((1, 7, 7)) - np.eye(7)[None]
>>> inv = isa.graphs_to_invariants(A)
>>> inv["Tr_M2"][0]                    # -42 = -2 × |E(K_7)| (=2×N_EDGES_K7)
-42.0
>>> isa.available_backends()
['numpy', 'torch_cpu', 'torch_cuda']
```

Heron K_7 quantum circuit, structurally verified:

```python
>>> import nwt_substrate.heron as heron
>>> qc = heron.k7_graph_state()
>>> heron.verify_k7_circuit_substrate(qc)
{'n_qubits': 7,    # == N_VERTICES_K7 ✓
 'n_h': 7,         # == N_VERTICES_K7 ✓
 'n_cz': 21,       # == N_EDGES_K7 ✓
 'n_edges_match': True,
 'n_vertices_match': True}
```

## What's implemented

- **`nwt_substrate.isa`** — Substrate Instruction Set Architecture
  (v0.2 new). Central source of truth for K_7 / Spin(7) / so(7) /
  Cl(0,7) structural constants, with import-time assertions enforcing
  identities like `N_EDGES_K7 = DIM_ADJ_SPIN7 = 21`,
  `4 + 3 = N_VERTICES_K7 = 7`, `B_QED_SM = DIM_OCTONION = 8`. Backends:
  numpy, torch CPU, torch CUDA. Observables: `aromaticity_score`,
  `hopf_pair_count`, `k7_indicator`, `k7_wilson_amplitude`,
  `classify_signature`. **Batched einsum kernel runs at 2 ns/molecule
  on CUDA, 1124× faster than networkx graph traversal.**
- **Particles** — Paper 6 mass formula, charge via extended GMN, the
  full SM hadronic + leptonic + exotic catalog. `Particle` class
  validates `n_q ∈ [0, MAX_CROSSING_NUMBER]` against ISA at construction
  time.
- **Compositions** — knot connected-sum (#) for molecular bound states
  (deuteron, X(3872), Pc family), Hopf-link with Λ_QCD = 313 MeV per
  crossing for nuclear / strongly-bound exotic regimes.
- **Walk-phase scattering** — substrate-algebraic Compton (matches
  Klein-Nishina to 1e-9), Møller / Bhabha, V-A muon decay matching
  Sargent rate, neutron decay with g_A = 1.27.
- **Solitons** (`nwt_substrate.solitons`, v0.5 new) — Faddeev-Skyrme
  (Hopf) soliton primitives: the CP¹ → S² map, the faithful Berg-Lüscher
  area form, the field-theoretic Whitehead Hopf charge
  `Q_H = (1/16π²)∫A·B`, a smooth in-basin rational-map hopfion seed, and
  the forward-difference energy / virial diagnostics — the construct/measure
  half of the L₃ Skyrme-Faddeev sector (Paper 16), and the first stable
  lattice hopfion in the project (Q_H +0.998). The energy-minimising GPU
  relaxers live in the separate `jax-solitons` engine, which validates
  against these numpy primitives as its reference oracle.
- **Classical EM + form factors** (`nwt_substrate.em`,
  `nwt_substrate.amplitudes`, v0.5 new) — FFT-Poisson electric/magnetic
  fields a carrier radiates from its charge / supercurrent density (periodic
  or open BCs), the optional Euler-Heisenberg nonlinear-vacuum correction,
  and the charge-density → form-factor → elastic-scattering chain
  (`form_factor`, `mean_square_radius`, Mott + form-factor cross sections).
- **Vortex profiles** (`condensate.solve_bps_vortex` / `solve_gl_vortex`,
  v0.5 new) — the radial cross-section `f(ρ), a(ρ)` of the abelian-Higgs
  vortex: the exact self-dual BPS profile (shooting) and the full gauged
  Ginzburg-Landau profile at any `κ = λ/ξ` and winding `n` (BVP collocation,
  stable for n ≥ 2), with a supercurrent-sheath helper.
- **Linking invariants** (`topology.linking_invariants`, v0.5 new) — Gauss
  linking number / matrix, Borromean-vs-anti-Borromean deletion test, Milnor
  indeterminacy (the modulus of the triple linking invariant), and A₄ link
  symmetry — the numeric backing for "binding = Hopf linking of carrier
  knots" (Paper 20).
- **Particle portraits** (`nwt_substrate.portraits`, v0.5 new) — renders each
  particle from its actual field content: the BPS vortex profile bent along
  the carrier-knot curve, with the abelian-Higgs phase composited as an
  emission-absorption volume (`portrait(p, q)`, `gallery()`).
- **Chemistry** (v0.2 new) — SMILES → substrate Hopf-pair aromaticity
  RE with K_7-toroidal correction; Clar sextets via maximum-independent-
  set; McKay-admissible coordinations; C_60 vibrational mode decomposition
  (174 = 4 IR + 10 Raman + ...); batched ISA-backed RE for ≥10^5 SMILES.
- **Gauge-theory shims** — `nwt.qed`, `nwt.qcd` (incl. gg→gg),
  `nwt.electroweak` (Z resonance + chiral couplings + `b_QED^SM`
  verification), `nwt.qft` (Lagrangian view), `nwt.string` (string-
  theoretic view), `nwt.gravity` (Sakharov-induced G via
  `isa.k7_wilson_amplitude`). Every shim has a `substrate_breakdown()`
  function printing its substrate-identity table.
- **Heron experiments** — qiskit-runtime interface and an experiment
  registry for IBM Heron processors. Supports Experiments 4 / 5 / 9
  / 10 / 11 from the paper series. K_7-circuit gate counts are
  runtime-verified against `isa.N_VERTICES_K7` / `isa.N_EDGES_K7`.
- **Cross-architecture QPU interface** (`nwt_substrate.qpu`, v0.2.0) — a
  vendor-neutral spec → decode → adapter layer for running the K_7 / Steane
  circuits on real hardware: IBM, AWS Braket, and simulator adapters, a
  capabilities/preflight guardrail, and a canonical-counts decode contract.
  Used by the Paper 21b cross-vendor / cross-architecture experiments.
- **Neutrino sector** (K_8 extension for Paper 20) — closed-form
  active masses (Wilson amplitude on K_8 with `N_v=8, N_e=28`), sterile
  masses (Wilson amplitude with `N_v=8, N_e=19` from the Z_3 ⊂ G_2
  triality seesaw, edge difference 9 = 12 − 3), `|U_α4|² = α^(9/2)`,
  PMNS angles at leading order from Spin(8) triality, and `δ_CP = −2π/3`
  from π_1(PSU(3)) winding. K_8 structural constants
  (`N_VERTICES_K8 = 8`, `N_EDGES_K8 = 28`, `K8_PARTITION = (6,3,12,1,6)`,
  `K8_SEESAW_EDGE_DIFFERENCE = 9`) live in `isa.constants` alongside
  the K_7 family.
- **Cosmology** (`nwt_substrate.cosmology`, v0.2.0) — substrate cosmological
  observables: baryon asymmetry `eta_B`, the Ω_b/Ω_c bridge partition
  (`omega_b_c`), the cosmological constant `lambda_cc`, and CMB-anisotropy
  axes, all importing `isa.constants`.
- **Decay constants + stability ratio** (`particles.decay_constants`,
  `particles.stability_ratio`, `qcd.confinement`) — P7b §7.5/§7.6 substrate
  decay constants (heavy + vector mesons + B_c) and the ρ = m_X/Γ_X
  substrate-applicability ratio.
- **Diagrams** — programmatic figure factories for the canonical
  substrate visualisations (torus knots, K_7 traversals,
  Heegaard-torus unification).
- **Dark sector** (`nwt_substrate.dark_sector`, v0.3 new) — L_NWT
  Higgs-portal calculation for the 98 GeV WIMP from VV's K_8 mass
  tower (N_e = 16 rung). Provides direct-detection σ_SI at substrate
  α + portal coupling g_Hχχ, comparison against LZ-2024 limit, and
  rough LHC off-shell production cross section. The K_7/K_8 portal
  must be at least α⁴ suppressed for the 98 GeV WIMP to be consistent
  with current LZ data — a falsifiable structural constraint. Call:
  `dark_sector.predict_all(dark_sector.WIMP_98GeV())`.
- **Benchmarks** (`nwt_substrate.benchmarks`, v0.3 new) —
  substrate-vs-traditional comparison for 38 physical observables
  spanning every domain the substrate program touches, runnable in
  ~100 ms. Sub-percent accuracy on cosmology (Ω_b/Ω_c at 0.0067 %,
  η_B at 0.38 %), sub-ppm chains (electron Schwinger a_e exact, α
  at 7.6 ppm, G at 11 ppm), and 100 % on chemistry (aromaticity 15/15,
  NICS 14/14, C_60 174-mode vibrational decomposition exact). The
  anti-numerology argument made empirically concrete. **v0.4.0** adds
  L. Leighton's O10 **derivation-separation** layer — `benchmarks.predict`
  (standalone, zero-input, CODATA-2018-witness predictions, `diff`-comparable)
  and `benchmarks.o10 --suite` (the whole 38-benchmark suite as one validated
  DAG cit-readout: one-way proof-order edges, witness sinks, defect edges
  *marked* not repaired) — plus the hadronic QCD layer on the Z width and the
  muon-lifetime decomposition. Call:
  `from nwt_substrate.benchmarks import run_all; run_all()`. See
  [`nwt_substrate/benchmarks/README.md`](nwt_substrate/benchmarks/README.md).

## The active-encoding architecture

The library has three layers:

```
┌─────────────────────────────────────────────────────────────┐
│  SUBSTRATE (passive primitives)                              │
│  isa.constants — 25 K_7/Spin(7)/so(7)/Cl(0,7) structural    │
│                  integers, import-time-asserted             │
│  isa.so7       — 21-generator basis + edge-graph embedding  │
├─────────────────────────────────────────────────────────────┤
│  ISA (active encoding — the substrate ribosome)              │
│  isa.batched     — einsum kernels: numpy / torch CPU / CUDA  │
│  isa.observables — polynomial-of-trace-invariants assembly   │
├─────────────────────────────────────────────────────────────┤
│  SHIMS (translation to domain vocabularies)                  │
│  chemistry, qed, qcd, electroweak, particles, gravity,      │
│  heron — each turns its domain vocabulary into so(7) input  │
│  and consumes ISA constants for cross-shim consistency      │
└─────────────────────────────────────────────────────────────┘
```

Spectacular cross-shim identities the architecture surfaces:

- **`N_EDGES_K7 = 21`** appears in **seven** shims:
  - chemistry: 21 so(7) generators in ISA basis
  - gravity: α^(21/2) Wilson amplitude
  - qed: 21 = dim(so(7) adjoint) holding the γ-matrix algebra
  - qcd: 21 = dim(adjoint Spin(7)) ⊃ SU(3) gluons
  - particles: 21 - 9 = 12 mixed so(7) gens host SM flavors
  - electroweak: `21 = 6 (Lorentz) + 3 (internal) + 12 (flavors)`
  - heron: 21 CZ gates in `k7_graph_state()` on real hardware
- **`8 = DIM_OCTONION`** appears in **four independent physics
  computations**:
  - gravity: numerator of `SPINOR_VECTOR_RATIO = 8/7`
  - qed: shape of Dirac γ^μ = 8×8
  - qcd: number of gluons = N_c² - 1 = 8
  - electroweak: `b_QED^SM = Σ N_c × Q² = 8` empirically verified
- **`7 = N_VERTICES_K7`** appears in **five** shims
  (chemistry, gravity, qed, particles, heron)

If a refactor violates any of these identities in any one shim, the
92 cross-shim tests catch it across all seven shims simultaneously.
The substrate algebra is no longer described by the code — it is
enforced by it.

## Tests + coverage

```bash
pytest nwt_substrate/tests/ -q
# 1436 passed in ~2 min
```

For coverage:

```bash
pytest nwt_substrate/tests/ \
    --cov=nwt_substrate --cov-branch \
    --cov-report=term --cov-report=html
# generates htmlcov/index.html
```

CI runs the full test suite with branch coverage on Python 3.10, 3.11,
and 3.12, uploads the report to Codecov, and saves an HTML coverage
report as a workflow artifact (30-day retention) — see the
[tests workflow](.github/workflows/test.yml) for details. Coverage
configuration lives in `[tool.coverage]` in `pyproject.toml`.

This includes:
- 92 cross-shim tests (`test_isa_cross_shim.py`) enforcing K_7 algebra
  across chemistry, gravity, qed, qcd, particles, electroweak, heron
- 47 ISA-internal tests across 3 backends (numpy / torch_cpu /
  torch_cuda)
- 58 chemistry tests (SMILES parsing, K_7 hub detection on coronene,
  Clar sextets, McKay coordinations, C_60 vibrational)
- All pre-Phase-Q.16 tests preserved (zero numerical regressions in
  particle masses, scattering cross-sections, gravity prediction,
  EW Z-resonance, etc.)

## Citation

If you use this library in a publication, please cite both:

- The relevant NWT paper(s) — typically one of
  [Paper 14–19](https://zenodo.org/communities/nwt) for the result
  you're using.
- The library Zenodo record (concept DOI `10.5281/zenodo.20012027`, auto-archived per release — resolves to the latest version):

```bibtex
@software{nwt_substrate,
  author       = {Galasyn, Jim and others},
  title        = {{nwt-substrate}: a substrate-algebraic computation
                  library for Null Worldtube Theory},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.20012027}
}
```

Each tagged release also mints a version-specific DOI (e.g.\ v0.2.0 =
`10.5281/zenodo.20398451`) for citing an exact snapshot.

A `CITATION.cff` is included in this repo for tools that auto-resolve
software citations.

## Papers

The library implements the computations described in:

- **Paper 6** — topological mass formula (0.76 % median residual on the
  24-particle compendium after the 2026-04-30 nucleon update).
- **Paper 14** — α^(21/2) heptafoil amplitude.
- **Paper 15** — Wilson amplitude on K_7 graph state.
- **Paper 16** — NWT three-field Lagrangian (BPS critical coupling).
- **Paper 17** — m_e / m_Pl closed form: G to -11 ppm CODATA (inside
  the ±22 ppm experimental band).
- **Paper 18** — Sakharov-induced Einstein gravity from substrate
  matter sector. *Includes the canonical "Heegaard torus, two
  sectors" figure rendered by `nwt.diagrams.figure_paper18_unified()`.*
- **Paper 19** — substrate monism via library demonstration.
- **Paper 20** — neutrino sector from Spin(8) triality on K_7 / K_8.
  Three sterile masses {61.3, 70.8, 218.8} MeV in the νMSM window,
  |U_α4|² ≈ α^(9/2) ≈ 2.4×10⁻¹⁰ active-sterile mixing, PMNS angles
  from triality, δ_CP = −2π/3 from π_1(PSU(3)) Z_3 winding. Library
  implementation in `nwt_substrate.neutrino`; K_8 structural
  constants in `isa.constants`. DOI:
  [10.5281/zenodo.20259632](https://doi.org/10.5281/zenodo.20259632).
- **Paper 21a / 21b** — Standard Model particles as closed walks on K_7
  (theory + quantum-hardware experiment): the K_7 = Steane [[7,1,3]]
  identification, the (2,F_n) carrier-knot family, closed-form n_q^q, and
  cross-vendor / cross-architecture stabilizer-syndrome reproduction on IBM
  Heron, IQM Garnet, and AQT Ibex-Q1. *(in preparation)*

The Zenodo community for the full series is at
https://zenodo.org/communities/nwt (collected DOIs).

## Status

**v0.5.0 (2026-06-13)**: the field-theoretic construct/measure layer —
Faddeev-Skyrme hopfions (`solitons.faddeev`), classical EM + form factors
(`em`, `amplitudes`), gauged Ginzburg-Landau vortices at any κ
(`condensate.solve_gl_vortex`), Gauss/Milnor link invariants
(`topology.linking_invariants`), and the particle-portrait renderer
(`portraits`); the energy-minimising relaxers live in the separate
`jax-solitons` engine, for which these numpy primitives are the reference
oracle. v0.4.x delivered the review-driven correction layers, the O10
derivation-separation predictor + DAG cit-readout, and the
route-redundancy/diversity audit (archived on Zenodo; concept DOI
`10.5281/zenodo.20012027`, resolves to latest). The active-encoding
architecture + cross-architecture QPU interface + ISA layer landed in v0.2.0
(the version the Paper 21a/21b bundle cites).

API surface is stable for particles, compositions, walk_phase, gauge
shims, gravity, chemistry, diagrams, and the new ISA layer. Minor
breaking changes may still occur before 1.0; we aim for semver
discipline post-1.0.

The main private development monorepo, where new analyses and paper
drafts live before promotion, is `null-worldtube-private` (not public).
Polished analyses and paper-supporting computations are promoted to
this repo; exploratory work stays private.

## Contributing

Issues and pull requests welcome. See **[`CONTRIBUTING.md`](CONTRIBUTING.md)**
for the full guide: dev setup, testing/coverage workflow, hard rules
(no fitted constants, no magic numbers, no silent constant changes),
soft rules (style, dataclasses, einsum kernels), and how to add a new
observable / benchmark / shim. AI coding agents should read
**[`AGENTS.md`](AGENTS.md)** instead — same rules, agent-targeted phrasing.

Quick version: run `pytest` before submitting, route any substrate-algebra
integer through `nwt_substrate/isa/constants.py`, and add a `CHANGELOG.md`
entry under `[Unreleased]`. Cross-shim tests in
`tests/test_isa_cross_shim.py` will catch identity violations across
all seven shims.

## Changelog and releases

- **[`CHANGELOG.md`](CHANGELOG.md)** — structured changelog
  ([Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
  format). Every user-visible change lands here.
- **[`docs/releases/`](docs/releases/)** — narrative release notes
  per minor version. The latest is
  [`v0.5.0`](docs/releases/v0.5.0.md) — the field-theoretic construct/measure
  layer (solitons, EM, vortices, linking, portraits).

## License

MIT. See [LICENSE](./LICENSE).
