YAML Metadata Warning:empty or missing yaml metadata in repo card
Check out the documentation for more information.
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.