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:
173
plans/11_performance_portability_and_release.md
Normal file
173
plans/11_performance_portability_and_release.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user