Add detailed phase plans for foundational macrosteps
- Macrostep 00: Model contract and retained historical options. - Macrostep 01: Project foundation and configuration, including schema, presets, CLI, and CI setup. - Macrostep 02: Mathematical core implementation and deterministic oracles. - Macrostep 03: CPU-based planar simulation engine, FFT backend, and headless runner. Provides exhaustive objectives, phase breakdowns, validation policies, and deliverables for each macrostep.
This commit is contained in:
172
plans/README.md
Normal file
172
plans/README.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# 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.** Legacy catalogues are imported once and committed in the new schema.
|
||||
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/import
|
||||
│ ├── 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.
|
||||
Reference in New Issue
Block a user