smoothlife/plans/06_complete_base_solver_and_dimensions.md

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.
• Newly authored and validated deterministic 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.