# 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.