Federico Pasqua
51cff7b0f3
- 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.
142 lines
6.1 KiB
Markdown
142 lines
6.1 KiB
Markdown
# 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.
|