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:
163
plans/07_multiscale_backend.md
Normal file
163
plans/07_multiscale_backend.md
Normal 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 00–06 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.
|
||||
Reference in New Issue
Block a user