smoothlife/plans/11_performance_portability_and_release.md

Macrostep 11 — Performance, portability, and release

Objective

Harden the complete simulator into a measurable, portable, supportable release. Optimize only verified bottlenecks while preserving CPU/GPU stage parity and deterministic replay.

Dependencies

All mandatory behavior in Macrosteps 00–09 complete. Required analysis tooling from Macrostep 10 complete.

Phase 11.1 — Benchmark suite and budgets

Substep 11.1.1 — CPU benchmarks

Benchmark in release mode:

• curve/rule surface evaluation;
• kernel generation;
• direct oracle at small sizes;
• 1-D/2-D/3-D FFT and convolution;
• Euler, AB3, and RK4 base steps, including both RK4 relaxation references;
• all multiscale policies;
• reduced sphere and DT oracle steps;
• state upload/export.

Substep 11.1.2 — GPU timings

Use timer queries where reliable and separate:

• standard and legacy packed-unitary FFT stages;
• algorithm-specific kernel multiplication/inverses;
• rule/integration, including both RK4 relaxation references;
• multiscale passes under each supported FFT algorithm;
• corrected and legacy sphere stencils;
• delayed-time stencil/commit;
• 3-D ray marching;
• UI/render cost.

Avoid glFinish() in normal operation. Record p50/p95 and warm-up methodology.

Substep 11.1.3 — Baseline policy

Commit benchmark metadata for designated hardware/software. Flag median regressions above 10–15% for review, but keep hardware-dependent gates out of ordinary CI. Correctness tolerances remain blocking everywhere.

Phase 11.2 — Measured optimization

CPU

• reuse plans, spectra, and scratch buffers;
• parallelize transform lines and pointwise passes after deterministic tests;
• improve cache locality and avoid unnecessary complex copies;
• vectorize only with readable fallback and measured benefit.

GPU

• reuse state forward transforms;
• fuse only pointwise passes whose separate inspection output can still be produced on demand;
• cache shader specializations and uniform locations;
• precompute sphere/DT stencil metadata;
• adapt raymarch quality independently from simulation quality;
• never introduce per-frame allocation/readback.

Every optimization requires before/after stage parity plus benchmark evidence.

Phase 11.3 — Memory and resource management

• Estimate CPU RAM and GPU VRAM before every cold rebuild.
• Include state, histories, RK/AB buffers, spectra, atlas padding, render targets, and capture staging.
• Enforce configurable soft/hard budgets.
• Fall back to the previous valid configuration on allocation failure.
• Expose a resource report in the diagnostics panel.
• Stress repeated backend/variant/resolution switching and verify stable resource counts.

Recommended interactive profiles should be realistic; do not advertise legacy shortcut sizes such as 512³ when memory/performance makes them unusable.

Phase 11.4 — Portability matrix

Primary tier

• Linux desktop;
• Windows desktop;
• macOS supported raylib/OpenGL path, with limitations documented.

Target OpenGL 3.3 core-compatible behavior and CPU fallback where float-FBO requirements fail. Web/GLES remains secondary until separately implemented and tested.

CI

Run:

• formatting and Clippy with the declared toolchain;
• all headless tests on primary OSes;
• raylib application compilation on primary OSes;
• bundled preset/schema validation;
• shader compilation/static validation;
• hidden-window Mesa/Xvfb GPU smoke tests on Linux when stable;
• packaging smoke tests from directories unrelated to the repository.

Document driver-specific tolerances instead of accepting arbitrary output drift.

Phase 11.5 — Operational hardening

Substep 11.5.1 — File behavior

• user config/data/captures use platform directories;
• atomic settings/preset writes;
• collision-safe captures;
• no writes beside the executable;
• clear migration/backup policy for future schema versions.

Substep 11.5.2 — Failure behavior

Test missing/corrupt config, invalid preset, shader failure, unsupported GPU, OOM/preflight rejection, minimized window, resize storms, and failed state import. Standard auto mode falls back to CPU when possible and displays why; explicit LegacyPackedUnitary fails clearly rather than changing algorithms.

Substep 11.5.3 — Diagnostics

A copyable report includes version, OS, raylib/OpenGL/GLSL, backend, FFT algorithm, relevant RK4 reference or sphere model, capabilities, preset/run descriptor, memory estimate, and recent errors. Logs rotate or remain bounded.

Phase 11.6 — Documentation and packaging

Write:

• project README with screenshots and quick start;
• mathematical model and retained historical-options guide;
• controls/UI reference;
• configuration schema with examples for every variant;
• CPU/GPU backend and tolerance explanation;
• performance and memory tuning guide;
• troubleshooting and driver fallback guide;
• contributor architecture/testing guide;
• release notes listing intentional differences from legacy.

Package binaries, embedded/packaged shaders, preset catalogues, licenses, and example configs. Verify clean-machine installation and launch.

Phase 11.7 — Final acceptance matrix

Functional

• Base 1-D/2-D/3-D: modes 0/1/2 and Euler/AB3/RK4.
• Multiscale 2-D: both neighborhood interpretations and all three compositions.
• Retained options: both RK4 relaxation references and both FFT algorithms where supported.
• Sphere: complete Corrected and Legacy models with discrete/fixed-smooth dynamics.
• DT: one causal 16-layer distance-delay model with both update modes.
• Every backend exposes its required logic channels.

Numerical

• Direct↔standard CPU↔standard GPU tolerances pass, and legacy packed GPU stages/final convolution pass their dedicated CPU-oracle tolerances.
• State remains finite and committed values remain [0,1].
• Deterministic reset/replay works for CPU; GPU is reproducible within documented tolerance.
• Retained historical options use safe deterministic infrastructure; no undefined historical behavior exists in any path.

Performance/resource

• No steady-state allocation or readback.
• Reference profiles meet recorded responsiveness targets or ship with lower documented defaults.
• Memory preflight and transactional failure paths work.

Product

• Presets, controls, captures, state replay, and diagnostics are discoverable.
• Launch never depends on the old repository or current working directory.
• Primary-platform packages pass smoke tests.

Deliverables

• Baselines and optimized implementations with preserved parity.
• Primary-platform CI/build/package pipeline.
• Complete user/contributor documentation.
• Signed-off functional/numerical/performance acceptance matrix.

Exit gate

Release only when every mandatory matrix row is implemented, tested, and documented; all bundled presets validate; CPU fallback can execute every simulation variant using its CPU-supported standard options; explicit LegacyPackedUnitary requests remain GPU-only and fail rather than substitute; GPU acceleration passes reference-profile smoke tests; and no blocking diagnostic, resource leak, undefined feedback path, or runtime dependency on legacy files remains.