substrate-universe

Multi-physics tick orchestrator — composes four anchored mechanisms in one deterministic loop with a SHA-256-chained evidence ledger.

from substrate_universe import SubstrateUniverse

u = SubstrateUniverse()
for _ in range(200):
    state = u.tick()
print(state.metrics.R, state.head_digest[:16])

---

Honest scope

This package is not "the digital substrate of reality" and does not claim to be. It is a small, well-tested core (~700 LoC, 47 tests, mypy strict) that lets you wire together physics primitives without re-implementing them every project:

Mechanism	What it is	Anchor
GrayScottField	2-D periodic reaction-diffusion (Turing patterns)	Pearson 1993, Science 261:189
KuramotoRicciEnsemble	Phase oscillators on a non-negative weighted graph	Kuramoto 1984; Restrepo-Ott-Hunt 2005
AdExPopulation	Vectorised adaptive exponential integrate-and-fire neurons	Brette & Gerstner 2005, J. Neurophysiol. 94:3637
EvidenceLedger	SHA-256 chained snapshots — tamper-evident audit trail	NIST FIPS 180-4

Each subsystem has its own falsification battery; the universe orchestrator pins determinism, ledger consistency, and a single optional cross-coupling channel (R → spike rate).

Install

pip install -e .[dev]

Requires Python ≥ 3.11 and NumPy ≥ 1.26. No JAX, no Torch — pure NumPy by design.

Quickstart

from substrate_universe import SubstrateUniverse, UniverseConfig

u = SubstrateUniverse(UniverseConfig(
    grid_shape=(64, 64),
    n_oscillators=32,
    n_neurons=16,
    coupling_K=2.0,
    seed=42,
))

for _ in range(500):
    state = u.tick()

m = state.metrics
print(f"R={m.R:.3f}  V={m.coupling_potential:.3f}  H_field={m.field_entropy:.3f}  rate={m.spike_rate_hz:.1f} Hz")
print(f"ledger head: {state.head_digest}")
assert u.ledger.verify_chain()

Or browse examples/:

examples/01_minimal_run.py            # 200-tick run, prints metrics + ledger
examples/02_sync_phase_transition.py  # K-sweep across the Restrepo-Ott-Hunt boundary
examples/03_oscillators_drive_neurons.py  # cross-coupling: R modulates spike rate

Constitutional invariants

The package enforces these by test (47/47 green):

INV	Class	Module	What it pins
INV-RD1	universal	fields	U, V finite ∀t; rejects bad shape / dt / D
INV-RD2	conservation	fields	Pure-diffusion mass conservation to 1e-10
INV-OSC1	universal	oscillators	R ∈ [0, 1]; rejects bad n / K / γ; rejects signed adjacency
INV-OSC2	algebraic	oscillators	K=ω=0 ⇒ no drift
INV-OSC3	conservation	oscillators	ω=0 ⇒ V non-increasing under midpoint flow (Lyapunov)
INV-AdEx1	universal	spikes	V finite under any drive; no NaN/Inf
INV-AdEx2	universal	spikes	spike-rate monotone in input current
INV-LED1	universal	ledger	digest = sha256(prev ‖ canonical_payload); 64-char hex
INV-LED2	universal	ledger	tampering with any past entry breaks verify_chain()
INV-MET1	universal	metrics	finite for any finite input
INV-MET2	algebraic	metrics	Kuramoto R ∈ [0, 1]
INV-UNI1	universal	universe	tick is bit-identical for the same (config, seed)
INV-UNI3	universal	universe	ledger chain verifies after any number of ticks

Run them yourself:

pytest -q             # 47 tests, ~0.6 s on a laptop
ruff check .          # clean
black --check .       # clean
mypy --strict substrate_universe   # clean

What it does NOT do

• No JAX/CUDA/distributed in v0.1. Pure NumPy. The interfaces are deliberately small enough that swapping in a JAX backend is a contained refactor for v0.2 — but it isn't done yet, and pretending otherwise would be dishonest.
• No "morphogenetic mesh", "fractal memory", "active inference" in this release. Those are research directions, not load-bearing claims here.
• No hidden global state. Every subsystem is constructed with explicit seed; every step is pure-functional in spirit (subsystems mutate their own internal arrays — see tick() for the full mutation surface).
• No claim to ground-truth physical realism beyond what the four anchored references provide. Gray-Scott is a toy reaction-diffusion model. Kuramoto is a mean-field phase oscillator. AdEx is a minimal spiking neuron. The whole point is that each individually is well-understood; composing them gives you a deterministic playground, not a "model of reality".

Roadmap (v0.2)

• runtime.metrics.compute_lambda1_proxy → swap to a full Benettin-QR Lyapunov spectrum (port from GeoSync core/physics/lyapunov_spectrum.py).
• JAX backend for KuramotoRicciEnsemble.step and GrayScottField.step under a thin protocol; CPU fallback retained.
• Pinning-control hook on the oscillator subsystem (port from runtime/pinning_control.py).
• Replay verification: serialise (config, seed, ledger); re-run; assert byte-equality of the head digest.

License

MIT. See LICENSE.

Citation

Treat this as alpha software. If you use it for anything you want to defend later, cite the underlying papers (Pearson 1993, Kuramoto 1984, Restrepo-Ott-Hunt 2005, Brette & Gerstner 2005, FIPS 180-4) — not this package.