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:
2026-07-14 16:50:54 +02:00
parent 7a414db1d3
commit 51cff7b0f3
13 changed files with 2122 additions and 0 deletions

View File

@@ -0,0 +1,163 @@
# Macrostep 07 — Multiscale backend
## Objective
Implement the three-scale concept as a first-class corrected 2-D backend with explicit neighborhood and composition semantics, per-scale inspection, and standard/legacy-FFT GPU support.
## Dependencies
Macrosteps 0006 complete.
## Scope decisions
- Mandatory scope is three scales on a periodic 2-D domain.
- The historical 1-D/3-D infrastructure was nonfunctional because integration existed only in 2-D; do not claim support there.
- Generalizing to `n` scales is acceptable internally, but imported fixtures remain exactly three.
## Phase 7.1 — Typed semantic model
Define independent enums:
```text
KernelInterpretation
IndependentDiskRing
ChainedBands
Composition
Sequential
OrderedClampedSum
MeanIncrement
```
Each `ScaleConfig` owns radius/ratios, `dt`, dynamics, and rule. Dimension/shape belongs to the common domain, not each scale.
Validate positive geometry, valid rules, exactly three scales for imported presets, growth/relaxation dynamics only, and descending/nested scales for chained bands. Nonnested bands are defined but produce a warning explaining their meaning.
## Phase 7.2 — Neighborhood evaluation
### Substep 7.2.1 — Independent kernels
For each scale from one requested state snapshot:
```text
N_i = ring_i(A)
M_i = disk_i(A)
S_i = rule_i(N_i,M_i)
```
Cache six kernel spectra. In shared-snapshot compositions, perform one state forward FFT and six inverse products.
### Substep 7.2.2 — Chained bands
Compute only:
```text
R0 = ring_0(A)
R1 = ring_1(A)
R2 = ring_2(A)
D2 = disk_2(A)
inputs = [(R0,R1), (R1,R2), (R2,D2)]
```
Explain in UI that this represents adjacent radial bands cleanly when `inner_0≈outer_1` and `inner_1≈outer_2`. Do not calculate unused `disk_0/disk_1` in this mode.
### Substep 7.2.3 — Response encoding
Keep three concepts separate:
```text
target F_i
growth increment dt_i*(2F_i-1)
relaxation increment dt_i*(F_i-A_reference)
```
Multiscale accepts only growth and corrected relaxation. It rejects discrete dynamics because these three composition names do not uniquely define how several targets replace one state. A future discrete mode requires a new explicit target-aggregation enum and fixtures; additive target-as-increment behavior is discarded.
## Phase 7.3 — Composition policies
### Substep 7.3.1 — Sequential
For independent kernels:
```text
state = A
for scale i:
evaluate scale i from state
state = clamp(state + increment_i)
```
Recompute every required neighborhood from the current state after each update. This is order-dependent. Chained sequential never reuses stale rings from an earlier state.
### Substep 7.3.2 — Ordered clamped sum
Evaluate all increments from original `A`, then:
```text
state = clamp(A+r0)
state = clamp(state+r1)
state = clamp(state+r2)
```
Do not replace this with one final clamp; mixed-sign increments make them different.
### Substep 7.3.3 — Mean increment
Evaluate from original `A`, then:
```text
A' = clamp(A + (r0+r1+r2)/3)
```
Average increments after each scale's own `dt`, not targets.
## Phase 7.4 — CPU implementation and tests
Build on the CPU planar convolution cache. Add mocked-neighborhood unit tests before full FFT tests:
- chained input mapping;
- response encoding (`A=.4,F=.75,dt=.1` gives growth `.05`, relaxation `.035`);
- ordered clamps (`A=.9`, responses `[.3,-.8,.3]` gives `.5`);
- mean gives approximately `.8333333` for the same responses;
- scale-order dependence and full chained recomputation;
- discrete-dynamics validation rejection.
Then run all six kernel/composition combinations against committed one-step fixtures.
## Phase 7.5 — GPU implementation
- Reuse the selected base FFT (`Standard` or `LegacyPackedUnitary`) and rule passes.
- Share one forward FFT in both shared-snapshot compositions.
- Sequential modes recompute only what their semantics require.
- Ping-pong state and integration targets; no read/write feedback.
- Cache spectra by scale and invalidate only geometry-dependent entries.
- Assert expected pass counts in instrumentation tests.
Initial standard CPU/GPU one-step target is max error `≤7e-4`; the legacy packed GPU path must also pass its algorithm-specific stage and final tolerances.
## Phase 7.6 — Workbench integration
Provide:
- three simultaneously visible scale tabs/cards;
- active-scale edits and explicit linked edits;
- kernel interpretation and composition selectors with formula help;
- per-scale `M/N/S/increment` channels;
- combined increment and clamp-stage views;
- scale-color overlay and radial-band diagram;
- clear validation for unsupported discrete dynamics and warnings for nonnested chained radii;
- imported triplet preset browser preserving group identity.
## Deliverables
- CPU and GPU multiscale 2-D backend.
- All six kernel/composition combinations for growth/relaxation, using either selectable GPU FFT algorithm.
- Per-scale inspectors and imported four legacy triplet groups.
## Exit gate
- All mocked and end-to-end composition fixtures pass.
- Tests prove sequential recomputation/order dependence and original-snapshot behavior.
- Chained mode requests only three rings plus the smallest disk.
- Shared-snapshot GPU modes use one state forward FFT.
- Standard CPU/GPU and legacy-packed GPU one-step tolerances pass.
- Additive discrete, stale chained inputs, undefined relaxation sources, and texture feedback are absent.