smoothlife/plans/README.md

# SmoothLife Rust/raylib reimplementation plan

## Mission

Reimplement the legacy SmoothLife collection as one modern Rust 2024 application using raylib for the window, input, and presentation. The result is a configurable simulation laboratory, not a line-by-line port. It must expose the internal logic of every simulator through inspectable fields while preserving the documented mathematics and making legacy defects explicit rather than accidental.

This plan is implementation-oriented: execute the macrosteps in order and use each exit gate as the prerequisite for the next step. Later work should rely on the in-repository contract and tests produced by Macrostep 00, not repeatedly reopen the legacy tree.

The original source position is ~/Nextcloud/VecchiProgetti/SmoothLifeAll/

## Required release scope

| Legacy component | New application responsibility |
| --- | --- |
| `SmoothLife/` | Periodic 1-D, 2-D, and 3-D model; discrete/growth/relaxation dynamics; Euler, AB3, and RK4; both RK4 relaxation references; standard and legacy packed-unitary FFTs; inspection and 3-D rendering. |
| `SmoothLifeSDL/` | Subsumed by the portable raylib shell. Its one-pass Euler behavior is covered by the base Euler path, not a separate simulator. |
| `SmoothLifeMultiscale/` | Corrected three-scale 2-D growth/relaxation model, two neighborhood interpretations, three composition policies, and either GPU FFT algorithm. |
| `SmoothLifeSphere/` | Corrected sphere default plus one coherent retained legacy sphere model; both use safe deterministic resources. |
| `SmoothLifeDT/` | Periodic 2-D field with initialized 16-frame circular history and one causal radius-dependent delay policy. |
| FreeBasic/Matlab | Independent CPU oracles, FFT/integrator validation, and a numerical comparison tool. |
| `GliderConstructor.bas` | Optional post-v1 inverse-design tool; it is not a general simulation backend and does not block the main release. |

## Product principles

1. **Pure core, graphical shell.** The model must run headlessly without raylib. Rendering consumes snapshots and inspection channels; it does not own simulation truth.
2. **CPU oracle before GPU optimization.** Every GPU pass is checked against a deterministic CPU implementation.
3. **One shared rule implementation.** All variants use the same typed rule configuration and equivalent Rust/GLSL formulas.
4. **Inspectable by design.** `A`, `M`, `N`, target `S`, derivative/increment, kernels, scale outputs, history layers, and topology diagnostics are first-class channels.
5. **Historical simulation behavior is exceptional and local.** There is no general legacy engine or compatibility profile. Only the explicitly retained RK4 relaxation reference, packed-unitary FFT, and sphere model are selectable; all other simulation behavior follows the new deterministic design.
6. **Deterministic replay and continuation.** A run is identified by schema version, preset ID, seed, shape, backend, only the localized historical options relevant to that run, and step count. Restart-state files reset numerical history; exact checkpoints additionally store AB history, DT history/head, generation, and deterministic RNG state.
7. **No runtime dependency on the old project.** Bundled product presets are newly authored in the new schema; legacy sources remain provenance for the model contract, not preset input.
8. **No steady-state allocation or readback.** Buffers and plans are reused; GPU readback is only for tests and explicit exports.

## Intended repository shape

```text
smoothlife/
├── Cargo.toml
├── src/
│   ├── lib.rs                    # raylib-free public core
│   ├── main.rs                   # application entry point
│   ├── config/                   # schema, validation, preset library
│   ├── field/                    # shapes, storage, indexing, inspection data
│   ├── math/                     # curves, rules, kernels
│   ├── integration/              # discrete, Euler, AB3, RK4
│   ├── convolution/              # direct oracle and FFT implementations
│   ├── simulation/               # common commands and backend facade
│   ├── variants/                 # planar, multiscale, sphere, delayed time
│   ├── gpu/                      # isolated rlgl/OpenGL resources and passes
│   ├── app/                      # scheduler, actions, lifecycle
│   ├── render/                   # palettes, 1-D/2-D/3-D/sphere rendering
│   └── ui/                       # panels, HUD, help, notifications
├── assets/
│   ├── presets/
│   └── shaders/
├── tests/
├── benches/
└── plans/
```

Start as one Cargo package. Make raylib and GPU code optional behind features so `cargo test --no-default-features` exercises the mathematical core without a graphics context. Create a workspace only if later standalone tools justify it.

## Core data flow

```text
validated preset + deterministic initializer
                     │
                     ▼
                 state A
                     │
         topology-specific neighborhood
                     │
              M (disk), N (ring)
                     │
             common target S(N,M)
                     │
        dynamics → derivative/increment
                     │
             selected integration
                     │
             clamp and commit A'
                     │
      inspection snapshot → raylib renderer/UI
```

The special variants replace only the neighborhood/topology and update policy layers:

- **Multiscale:** several `(M,N,S)` pipelines plus a composition policy.
- **Sphere:** direct geodesic, area-weighted neighborhoods on a cube-sphere.
- **Delayed time:** each radial offset selects a spatially shifted history layer.

## Configuration model

Use strict, versioned TOML with string enums and a tagged variant:

```text
Preset
├── identity/provenance
├── VariantConfig
│   ├── Planar
│   ├── Multiscale
│   ├── Sphere
│   └── DelayedTime
├── RuleConfig (one or one per scale)
├── DynamicsConfig
├── InitializerConfig
└── recommended presentation
```

Keep model presets distinct from user preferences (window, palette, camera, key bindings). Bundled presets are immutable; user presets and captures live in platform-specific user directories.

## Historical options policy

The new deterministic implementation is always the baseline: complete kernel support, initialized state, Euler → AB2 → AB3 startup, explicit ping-pong writes, corrected multiscale evaluation, causal delayed history, fixed simulation scheduling, and strict configuration validation.

Exactly three historical choices remain:

```text
Rk4RelaxationReference
  StageState       # default: S(stage)-stage
  StepOrigin       # historical: S(stage)-state_at_step_start

FftAlgorithm
  Standard         # default: conventional normalized FFT
  LegacyPackedUnitary

SphereModel
  Corrected        # default: complete seams and sampled normalization
  Legacy           # original atlas/seam and analytic-cap model
```

These are independent, local settings—not a general compatibility profile. `LegacyPackedUnitary` retains packed real/complex storage, half-width x spectra, historical butterfly/plan stages, unitary scaling, and the matching `sqrt(N)/kernel_sum` correction. `SphereModel::Legacy` retains the original cube-atlas geometry, side-gutter/corner masking, analytic normalization, radius conversion, direct stencil, and fixed smooth update.

Even these options use safe deterministic infrastructure. The project never preserves undefined AB buffers, uninitialized textures, texture feedback loops, unclamped `acos`, platform `rand()` streams, stale multiscale fields, additive-discrete multiscale behavior, or the delayed-time head anomaly.

## Delivery milestones

| Milestone | Macrosteps | User-visible result |
| --- | --- | --- |
| R0: frozen contract | 00 | All required behavior and source provenance live in this repository. |
| R1: first useful simulator | 01–04 | Deterministic CPU SmoothLife with a professional raylib 2-D workbench and inspectors. |
| R2: accelerated base model | 05–06 | CPU/GPU base parity, 1-D history, 2-D field, 3-D slices/volume, complete base presets. |
| R3: all historical models | 07–09 | Multiscale, sphere, and delayed-time backends selectable in one application. |
| R4: release candidate | 10–11 | Reference tooling, benchmarks, packaging, portability, and complete documentation. |

## Macrostep index

1. [Macrostep 00 — Model contract and retained historical options](00_model_contract_and_historical_options.md)
2. [Macrostep 01 — Project foundation and configuration](01_project_foundation_and_configuration.md)
3. [Macrostep 02 — Mathematical core and deterministic oracles](02_mathematical_core_and_oracles.md)
4. [Macrostep 03 — CPU planar simulation engine](03_cpu_planar_simulation_engine.md)
5. [Macrostep 04 — Raylib visualization workbench](04_raylib_visualization_workbench.md)
6. [Macrostep 05 — GPU resources and 2-D FFT proof](05_gpu_resources_and_fft_proof.md)
7. [Macrostep 06 — Complete base solver and dimensional rendering](06_complete_base_solver_and_dimensions.md)
8. [Macrostep 07 — Multiscale backend](07_multiscale_backend.md)
9. [Macrostep 08 — Spherical backend](08_spherical_backend.md)
10. [Macrostep 09 — Delayed-time backend](09_delayed_time_backend.md)
11. [Macrostep 10 — Reference and analysis tools](10_reference_and_analysis_tools.md)
12. [Macrostep 11 — Performance, portability, and release](11_performance_portability_and_release.md)

## Definition of “macrostep complete”

A macrostep is complete only when:

- every required phase is implemented;
- its tests and diagnostics pass in debug and release where relevant;
- its deliverables are committed;
- its exit gate is demonstrated, not merely asserted;
- documentation and schema examples are updated in the same change;
- unresolved deviations are recorded as explicit issues with an owner and blocking status.

Do not begin optimization before the corresponding oracle and stage-level comparisons exist.