smoothlife/plans/07_multiscale_backend.md

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 mandatory product presets and contract fixtures remain exactly three scales.

Phase 7.1 — Typed semantic model

Define independent enums:

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, 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:

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:

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:

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:

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:

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:

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;
• newly authored three-scale preset browser with stable preset 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 newly authored deterministic multiscale presets.

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.