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:
141
plans/06_complete_base_solver_and_dimensions.md
Normal file
141
plans/06_complete_base_solver_and_dimensions.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Macrostep 06 — Complete base solver and dimensional rendering
|
||||
|
||||
## Objective
|
||||
|
||||
Complete CPU/GPU parity for the main SmoothLife family and provide intentional visualizations for 1-D, 2-D, and 3-D. This macrostep finishes the base model before special variants are added.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Macrosteps 00–05 complete.
|
||||
|
||||
## Phase 6.1 — GPU rule and integration pipeline
|
||||
|
||||
### Substep 6.1.1 — Shared GLSL rule
|
||||
|
||||
Port all typed curves, windows, mixers, and four constructions. Keep formula structure parallel to Rust and use integer/enum specialization rather than float-equality selectors. Add a GPU rule-surface test over all valid combinations.
|
||||
|
||||
### Substep 6.1.2 — Dynamics
|
||||
|
||||
Implement distinct outputs:
|
||||
|
||||
- target `S`;
|
||||
- growth derivative `2S-1`;
|
||||
- relaxation derivative `S-A`.
|
||||
|
||||
Do not conflate target and increment. Preserve channels for inspection.
|
||||
|
||||
### Substep 6.1.3 — Integrators
|
||||
|
||||
- Discrete: target-to-next pass.
|
||||
- Euler: ping-pong update.
|
||||
- AB3: initialized derivative textures plus explicit startup generation.
|
||||
- RK4: full FFT/neighborhood/rule evaluation at each clamped stage, with selectable `StageState` or retained historical `StepOrigin` relaxation reference.
|
||||
|
||||
Reset histories on the same events as CPU. Never sample a write target. Compare both RK4 references to CPU fixtures.
|
||||
|
||||
## Phase 6.2 — Logical atlas for all dimensions
|
||||
|
||||
### Substep 6.2.1 — Layout
|
||||
|
||||
Use the established 2-D texture abstraction:
|
||||
|
||||
- 1-D: `N×1` logical field;
|
||||
- 2-D: `Nx×Ny`;
|
||||
- 3-D: z-slices tiled in a near-square atlas with explicit padding.
|
||||
|
||||
Create one CPU/GPU-tested mapper from `(x,y,z)` to atlas texel. Padding is initialized, ignored by transforms, and excluded from metrics.
|
||||
|
||||
### Substep 6.2.2 — 1-D and 3-D FFT stages
|
||||
|
||||
- Standard 1-D runs x stages only; standard 3-D runs x/y within slices and z across mapped slices.
|
||||
- Extend `LegacyPackedUnitary` from its 2-D proof to historical 1-D and 3-D packing, plans, stage order, unitary scaling, and `sqrt(sample_count)` convolution correction.
|
||||
- Verify DC/Nyquist, conjugate reconstruction, packing, and wrap addressing with asymmetric impulses for both algorithms.
|
||||
- Reuse algorithm-specific plans and buffers; include full-complex versus packed/atlas overhead in memory estimates.
|
||||
|
||||
### Substep 6.2.3 — Transactional backend switching
|
||||
|
||||
Allow CPU↔GPU and standard↔legacy-FFT switches through explicit state transfer. Preserve generation and state; rebuild algorithm-specific kernels/plans and reset integrator history unless an exact transferable history format is implemented. `LegacyPackedUnitary` remains GPU-only and rejects unsupported transitions. Show the consequence before applying.
|
||||
|
||||
## Phase 6.3 — 1-D visualization
|
||||
|
||||
Implement two views:
|
||||
|
||||
1. current scalar profile;
|
||||
2. explicit space-time history raster.
|
||||
|
||||
The history raster is a CPU/GPU ring buffer whose rows advance only on committed simulation steps. It does not depend on uncleared window backbuffers. Support history length, scroll direction, pause, resize, palette, and generation labels.
|
||||
|
||||
## Phase 6.4 — 2-D production view
|
||||
|
||||
Complete:
|
||||
|
||||
- periodic pan and fit/zoom behavior;
|
||||
- state and all inspection channels;
|
||||
- native-resolution capture;
|
||||
- optional interpolation only as a display choice;
|
||||
- pixel probe showing `A,M,N,S,k,next` for the same coordinate/generation.
|
||||
|
||||
The production 2-D target is the first performance profile: 512² Euler should remain interactive on the designated machine, with simulation and rendering times reported separately.
|
||||
|
||||
## Phase 6.5 — 3-D visualization
|
||||
|
||||
### Substep 6.5.1 — Slice inspection first
|
||||
|
||||
Provide axial/coronal/sagittal slices, slice index controls, montage, and numeric probes. This is the correctness view and fallback if volume shaders fail.
|
||||
|
||||
### Substep 6.5.2 — Orbit camera and volume box
|
||||
|
||||
Use an orbit/arcball camera with dolly, pan, reset, and optional time-based autorotation. Keep periodic volume offset separate from camera transform.
|
||||
|
||||
### Substep 6.5.3 — Progressive ray marcher
|
||||
|
||||
Implement, test, and expose quality controls for:
|
||||
|
||||
1. density accumulation (legacy style 2 equivalent);
|
||||
2. simple integral and fog;
|
||||
3. threshold/depth fog;
|
||||
4. depth darkening;
|
||||
5. gradient coloring;
|
||||
6. jittered Laplacian coloring.
|
||||
|
||||
Use atlas-aware manual sampling, early opacity termination, and configurable step size/density/brightness/threshold. Start from legacy values (`0.5`, `0.25`, `4`, `0.99`) but do not hard-code them. Clamp/sanitize palette inputs.
|
||||
|
||||
## Phase 6.6 — Parity and performance gates
|
||||
|
||||
### Stage parity
|
||||
|
||||
Compare standard CPU, standard GPU, and legacy packed GPU against their appropriate stage oracles:
|
||||
|
||||
- kernels, packing, plans, and spectra;
|
||||
- `M`, `N`, `S`, derivative;
|
||||
- every integrator stage, including both RK4 relaxation references;
|
||||
- final one-step state in each dimension.
|
||||
|
||||
Initial final-state target: max difference `≤5e-4` on agreed fixtures. Use aggregate statistics and spectrum bands, not exact hashes, for longer chaotic runs.
|
||||
|
||||
### Performance profiles
|
||||
|
||||
Record designated reference targets without making CI hardware-dependent:
|
||||
|
||||
- 512² Euler: goal ≥60 updates/s;
|
||||
- 64³ Euler: goal ≥10 updates/s with responsive rendering;
|
||||
- 3-D renderer: goal ≥30 render FPS at default quality.
|
||||
|
||||
If targets fail, preserve correctness, lower recommended defaults, and file measured optimization work rather than silently skipping simulation steps.
|
||||
|
||||
## Deliverables
|
||||
|
||||
- Complete standard GPU base pipeline with CPU fallback and selectable legacy packed-unitary GPU pipeline.
|
||||
- 1-D profile/history, 2-D production field, 3-D slices and volume renderer.
|
||||
- CPU/GPU state transfer and all base inspection channels.
|
||||
- Imported and validated base preset catalogue.
|
||||
|
||||
## Exit gate
|
||||
|
||||
- Every supported base preset can be selected and run with compatible dimension/dynamics/integrator settings.
|
||||
- Standard CPU/GPU parity and legacy packed-unitary stage/final tolerances pass in 1-D/2-D/3-D.
|
||||
- Both RK4 relaxation references pass one-step CPU/GPU fixtures.
|
||||
- 1-D history advances exactly once per committed generation.
|
||||
- 3-D slices and ray marcher agree on sampled values.
|
||||
- Unsupported allocations fail transactionally and preserve the prior simulation.
|
||||
- No application behavior depends on legacy shader files or executables.
|
||||
Reference in New Issue
Block a user