README.md

# Seeking Compute & Research Collaborators

We are seeking collaborators with access to substantial GPU compute to independently reproduce, scale, and extend Spectral World Models. The V15.1 experimental program is frozen; the next phase focuses on genuine scaling studies, symmetry-aware spectral dynamics, richer benchmarks, and independent validation.

The objective of the next phase is not simply to make the existing benchmark numbers larger. It is to determine, with substantially greater compute and independent scrutiny, whether spectral/operator world models can scale into a useful foundation for learned dynamics—and to identify clearly the regimes in which they cannot.

We are open to academic collaboration, compute sponsorship, joint research, and funded/contract engineering engagements.


# V13: Axis Symmetry & Intervention Equivariance Audit

## V15.1 bug-fix release

V15.1 replaces V15 after correcting the external state-token diagnostic. The original runner called the flat `text_decoder` layer directly; V15.1 uses the canonical `decode_text()` API and validates `[B,L,V]` logits against `[B,L]` discretized Gym-state token targets. No model architecture, checkpoint, dataset, training recipe, or scientific protocol changed. See `V15_1_BUGFIX.md`.


V13 freezes the V9 learning recipe and diagnoses the V12 vertical-action collapse with exact rotations/reflections/x-y swaps plus deliberately constructed collision episodes. See `V13_AXIS_SYMMETRY_EQUIVARIANCE.md`.

Main run: `PYTHONPATH=. python scripts/run_v13_axis_audit.py --seeds 0 1 2 3 4 5 6 7 8 9 --pairs 64 --horizon 30 --device cuda`

---

# V12: Causal Response Decomposition

V12 freezes the V9 learning recipe and decomposes causal-response behavior by action program, horizon, effect size, initial speed, boundary contact, occlusion-zone exposure, and physics regime. It adds paired episode-clustered bootstrap confidence intervals against neural-operator and no-spectral-transition controls. See `V12_CAUSAL_RESPONSE_DECOMPOSITION.md`.

Main run: `PYTHONPATH=. python scripts/run_v12_decomposition.py --seeds 0 1 2 3 4 5 6 7 8 9 --cf-horizon 30 --cf-pairs 64 --bootstrap 2000 --device cuda`

---

---

## V9: causal generalization across physics regimes

V9 freezes the structured spectral transport mechanism and targets the failure exposed by V8: excellent in-distribution counterfactual alignment did not extrapolate to changed physics. V9 trains on a family of dynamics regimes and adds trajectory-level counterfactual supervision, then evaluates interpolation, parameter extrapolation, and structural OOD shifts separately. See `V9_CAUSAL_GENERALIZATION.md`.

Run: `PYTHONPATH=. python scripts/run_v9_benchmark.py --seeds 0 1 2 3 4 --horizons 5 10 20 30 50 100 --cf-horizon 30 --planning-horizon 20 --planning-episodes 64 --device cuda`

license: mit
library_name: pytorch
tags:
- world-models
- spectral-learning
- operator-learning
- multimodal
- wavelets
- pytorch
- research
---

# Spectral World Models — V7

V7 is the counterfactual-action training revision of the runnable Spectral World Models research prototype.

## Why V7

V6 showed that structured transport can preserve long-horizon latent state, but the model substantially under-reacted to interventions. V7 keeps the V6 structured transition and adds a paired counterfactual objective so action response is learned explicitly rather than expected to emerge from reconstruction loss alone.

The new `swm_structured_cf` model uses the same architecture as `swm_structured`; only the training objective changes. For the same starting state it rolls out opposing left/right interventions and optimizes: action-effect direction alignment, action-effect magnitude calibration, and endpoint reconstruction. Defaults are intentionally modest so the auxiliary objective does not overwhelm next-state learning.

## Main experiment

Install with `pip install -e .` and run:

`PYTHONPATH=. python scripts/run_v7_benchmark.py --seeds 0 1 2 3 4 --horizons 5 10 20 30 50 100 --cf-horizon 30 --device cuda`

Results are written to `results/v7_counterfactual_training/metrics_summary.csv` and `metrics_by_seed.csv`.

The primary comparison is `swm_structured_cf` versus unchanged `swm_structured`, `swm_selective`, `no_spectral_transition`, and `neural_operator`. Inspect counterfactual direction cosine and magnitude ratio together with H100 image MSE, text accuracy, and latent cosine. Do not select a model from a single scalar metric.

## Tunable V7 objective

The runner exposes `--cf-train-horizon`, `--cf-pairs`, `--cf-every`, `--lambda-cf-dir`, `--lambda-cf-mag`, and `--lambda-cf-branch`. Defaults are 8, 64, 4, 0.02, 0.005, and 0.10 respectively. Hyperparameters should be selected using training/validation evidence, not the held-out test set.

## Validation

Run `PYTHONPATH=. python -m pytest -q`. The V7 suite includes the earlier architecture/stability tests plus a backward-pass test for the new counterfactual objective.

See `V7_COUNTERFACTUAL_TRAINING.md` for the experiment rationale. Earlier stages are documented in `V4_MULTIMODAL_STABILITY.md`, `V5_HARD_DYNAMICS.md`, and `V6_STRUCTURED_TRANSPORT.md`.

## V8: frozen-architecture generalization and planning

V8 freezes the V7 architectures and evaluates OOD dynamics, unseen intervention conditions, and imagination-based planning. See `V8_GENERALIZATION_AND_PLANNING.md`.

Run: `PYTHONPATH=. python scripts/run_v8_benchmark.py --seeds 0 1 2 3 4 --horizons 5 10 20 30 50 100 --cf-horizon 30 --planning-horizon 20 --planning-episodes 96 --device cuda`

## V10 — counterfactual benchmark integrity

V10 freezes the learned architectures and audits the causal benchmark itself. See `V10_COUNTERFACTUAL_INTEGRITY.md`.

Run: `PYTHONPATH=. python scripts/run_v10_audit.py --seeds 0 1 2 3 4 --cf-horizon 30 --cf-pairs 48 --device cuda`

## V11: causal gain calibration
V11 freezes the V9 structured transport architecture and replaces endpoint-oriented causal magnitude fitting with scale-aware trajectory-effect calibration. It reports direction, gain error, magnitude correlation, and calibration slope/intercept across interpolation, extrapolation, and structural OOD. See `V11_CAUSAL_GAIN_CALIBRATION.md`.

## V14: external control benchmark

V14 freezes the V9 architecture family and moves evaluation outside the project's synthetic simulator. The external suite uses Gymnasium Classic Control (`CartPole-v1`, `MountainCar-v0`, `Acrobot-v1`) with official RGB rendering converted to the model's 32×32 grayscale input. Models are trained from scratch per environment; architecture and comparison logic are frozen. See `V14_EXTERNAL_CONTROL_BENCHMARK.md`.

## V15 — External Dynamics Diagnostic
V15 is intentionally the **final diagnostic milestone**, not another model revision. It reloads the frozen V14 checkpoints and tests whether V14's negative full-frame MSE result reflects genuine dynamics failure or static-background metric confounding. See `V15_EXTERNAL_DYNAMICS_DIAGNOSTIC.md`.

---

## Final reproducibility release (V6–V15.1)

This tree is the frozen final reproducibility artifact for the SWM falsification program. See `docs/REPRODUCIBILITY_RELEASE.md` for the experimental history and interpretation, and `results/` for the measured V12–V15.1 audit CSVs included with this release. The project intentionally stops architecture iteration at V15.1.