docs: Dütsch protocol — consolidate verified source facts and close protocol choices

Source facts with page provenance (motion, quarter-cycle start, stations,
Morison c_d/added-mass c_i definition, Table 1 as computed reference, no
recovered uncertainty); lab-frame kinematics with base at the right turning
point, interval-average wall velocity and force attribution, explicit cycle
indexing; T multiple of 360 steps; native-channel domain sensitivity order;
fluid-only interpolation; periodic gate with fixed-scale waveform/profile
settling, N=3, cap 30, common window; engineering criteria labelled as such.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/validation/duetsch_re100_kc5_protocol.md

@@ -1,119 +1,156 @@
-# Prescribed in-line oscillation: Dütsch Re 100 / KC 5 — PROTOCOL DRAFT (not frozen)
+# Prescribed in-line oscillation: Dütsch Re 100 / KC 5 — PROTOCOL (review draft)
 
 Production under test: `claude/moving-bodies-s3a` at `653fd997` (unchanged).
 Primary source: Dütsch, Durst, Becker & Lienhart, J. Fluid Mech. 360, 249–271
-(1998), doi:10.1017/S002211209800860X. Items marked ⟨verify⟩ must be taken from
-the paper itself before freezing; nothing here is read from plots. All numbers
-marked PROVISIONAL (ladder, window, domain, boundaries) are my choices and stay
-non-normative until the primary-spec packet and Astra's feasibility check land.
+(1998), doi:10.1017/S002211209800860X. Source facts below were verified from
+the paper (Slack C0C78UFKGRM/1793335557.460509, TRON 1793356317–1793356724,
+page numbers given). Everything marked ENGINEERING is our a-priori choice,
+fixed before any benchmark result; it is not a paper uncertainty.
 
-## Criteria (kept separate)
+## 0. Source facts (with provenance)
 
-- Same-grid frame consistency (G4, frozen 2%): already evaluated; not reused here.
-- Cross-resolution criterion: every reported observable's error against the
-  reference, and the fine-pair difference, must decrease monotonically over the
-  resolution ladder. No numeric grid threshold and no order label is added.
-- Reference agreement: only against values with provenance (section 6), with an
-  observable-specific error/uncertainty criterion declared per observable
-  before runs (OPEN). Monotone decrease alone is not a literature pass.
-- Duration/periodicity gate (section 1a) must pass before any statistic is
-  collected.
+- Motion (p.251): `x_c = -A sin(2 pi f t)`; paper phase phi = 0 is the mean
+  position moving left at `-U_max`. KC = 5 gives `A/D = 5/(2 pi) = .7957747`.
+- Start (p.254): the computation starts a quarter cycle before phi = 0, at
+  `x = +A` with zero velocity (phi = -90°).
+- Experiment (pp.252, 254–256): D = 10 mm, L = .65 m, tank 1.2 × .7 × .7 m,
+  rho = 998.2 kg/m³, mu = 1.00818 mPa·s, Re = 100, KC = 5; LDA with 1° phase
+  bins and 200 samples per node and degree; no quantified experimental error
+  recovered.
+- Profiles (Fig. 8, p.260): LAB-FIXED stations x1 = -6, 0, 6, 12 mm, i.e.
+  x/D = -.6, 0, .6, 1.2, at phi = 180°, 210°, 330°; u1 and u2 versus x2.
+- Original numerics (§2): cylinder-fixed accelerated frame (`x_i = x~_i +
+  x_i,s`, outer velocity `-u_c`, inertial source `-rho du_c/dt`), O-grid outer
+  diameter 120 D, illustrated 192 circumferential nodes, 720 steps/cycle; tank
+  influence neglected.
+- Force fit (verified): force ON THE BODY per unit span
+  `F1 = -0.5 rho D c_d xdot|xdot| - (pi/4) rho D² c_i xddot` with `x = -A sin phi`;
+  normalized by `0.5 rho D U_max²`: `c_d cos phi |cos phi| - (pi² c_i / KC) sin phi`.
+  `c_i` is the ADDED-MASS coefficient; total inertia `c_m = c_i + 1` is a
+  different convention and is not used.
+- Table 1 computed Morison coefficients (c_d, c_i) for 96 / 192 / 384 perimeter
+  nodes at dt/T = 1/720: (2.15, 1.42), (2.10, 1.45), (2.09, 1.45). These are
+  fitted computed coefficients, not a measured force and not an error bar. The
+  paper states the coarse direct force is closer to the finest direct force
+  than the Morison fit, but gives no waveform-error norm.
 
-## 1. Kinematics
+## 1. Kinematics, time levels and phase bookkeeping
 
-- In-line only: `x(t) = -A sin(2 pi t / T)`, `u(t) = -U_max cos(2 pi t / T)`
-  ⟨verify sign and phase origin⟩; `KC = U_max T / D = 2 pi A / D = 5`,
-  `Re = U_max D / nu = 100`, so `A = 5 D / (2 pi)`.
-- Prescribed per step through `set_body(offset, vx)` + `run(1)`, offset and
-  velocity evaluated analytically at step n (no differencing).
-- Start: the paper's motion from rest ⟨verify Dütsch start⟩. A one-cycle smooth
-  ramp is a separately named variant that only checks start independence.
-- Phase convention: the motion uses the analytic offset/velocity at the step's
-  time level n; the per-step force (`run(1)`, `read_force(normalize=True)`) is
-  attributed to the same n. Whether the paper's phases refer to endpoint
-  values or interval averages is ⟨verify⟩; comparisons state which.
+- Our run is in the LAB frame: the circle moves, the fluid is initially at rest
+  (rho = 1, u = 0); no fictitious inertial source is added. Lab-fixed profile
+  stations are compared directly (no frame transform needed).
+- Geometry reference: the circle's base centre is the INITIAL position, the
+  right turning point `x_mean + A`; the declared offset box is x in [-2A, 0],
+  y = 0. The body is never teleported: offset 0 at s = 0.
+- Elapsed time s = n dt from the start. Analytic position relative to the mean
+  `x(s) = A cos(2 pi s / T)`, velocity `u(s) = -U_max sin(2 pi s / T)`; paper
+  phase `phi = (360 s / T - 90) mod 360`.
+- Step n moves from s_n to s_{n+1}: target offset `x(s_{n+1}) - A`; wall
+  velocity = the single-step interval average `(x(s_{n+1}) - x(s_n)) / dt`
+  (analytic, supplied, not differenced from stored offsets). The per-step
+  force of `run(1)` / `read_force(normalize=True)` is attributed to that same
+  interval.
+- Paper cycle k = 1, 2, ... spans `s in [T/4 + (k-1) T, T/4 + k T)`; the
+  initial quarter cycle (s < T/4) is cycle 0 and never scored. Every logged
+  sample carries (k, phi). Example: phi = 330° of cycle 1 is at s = 7T/6.
+- T is chosen as a multiple of 360 native steps, so phi = 180°, 210°, 330° fall
+  exactly on step boundaries and 1° bins hold whole steps.
 
-## 1a. Duration and periodic-state gate (auditable, every case)
+## 2. Resolution ladder (uniform grid, fixed Mach), ENGINEERING
 
-- Recorded per case: dx, dt, D, U_max, nu (lattice and nondimensional), steps
-  per period, total steps, total nondimensional duration t U_max / D and in
-  periods, number of discarded cycles, accepted cycle window.
-- Every case in a comparison uses the SAME accepted window in periods (finer
-  grids run proportionately more native steps for the same physical time).
-- Periodic-state adequacy is demonstrated, not assumed: per-cycle mean and RMS
-  of Fx and the Morison fit per cycle must change by less than a predeclared
-  cycle-to-cycle tolerance (OPEN) over the last cycles before the window;
-  otherwise the run is extended and the window moved by whole periods, and the
-  failure is recorded. Cycles 4–6 is PROVISIONAL only.
-- The G4 timing check (100 coarse vs 400 diffusive-fine steps) is a matched
-  short transient, not evidence of periodic convergence.
-
-Mandatory ⟨gate⟩ ledger rows, same schema for every case (values ⟨verify⟩ /
-PROVISIONAL until the primary-spec packet and measurements exist):
-
-| field | content |
-|---|---|
-| dx, dt | lattice spacing and step in physical/nondimensional units |
-| U_max, nu, Re, KC | lattice and nondimensional values |
-| T | period in native steps and in nondimensional time |
-| duration | total native steps, nondimensional time, periods |
-| discard | discarded cycles / transient cutoff |
-| window | accepted window, declared as the SAME cycle indices (or the same nondimensional interval after discard) for the whole ladder |
-| cycle ledger | per cycle: mean, RMS, peak Fx (and Morison coefficients if scored); relative change k → k+1 below a predeclared tol for ≥ N consecutive cycles before the window (tol, N OPEN) |
-| verdict | PASS, or FAIL-CLOSED if a finer grid covers less physical time, the window differs, or the cycle ledger is missing or unconverged |
-
-No literature comparison, cross-resolution statement or VIV statistic is made
-for a case without a PASS ledger.
-
-## 2. Resolution ladder (uniform only, fixed Mach)
-
-| D (cells) | U_max | nu_lat | tau | steps / period |
+| D (cells) | T (steps) | U_max = 5 D / T | nu_lat = U_max D / 100 | tau (3 nu + .5) |
 |---|---|---|---|---|
-| 20 | .04 | .008 | .524 | 2,500 |
-| 40 | .04 | .016 | .548 | 5,000 |
-| 80 | .04 | .032 | .596 | 10,000 |
+| 20 | 2,520 | .039683 | .0079365 | .5238 |
+| 40 | 5,040 | .039683 | .015873 | .5476 |
+| 80 | 10,080 | .039683 | .031746 | .5952 |
 
-- MRT collision (SRT at tau ≈ .524 is the recorded unstable regime).
-- Mach check: U_max .02 vs .04 at D = 40 (separate, labelled).
+- MRT collision. Mach fixed (Ma ≈ .0687); a separate Mach check at D = 40
+  with T = 10,080 (U_max halved, tau .5238) is labelled MACH and not part of the
+  ladder.
+- Per-step displacement ≤ U_max ≈ .04 cells (bound .5).
 
-## 3. Domain and boundaries
+## 3. Domain and boundaries (finite-domain reproduction), ENGINEERING
 
-- Square still-fluid box; size PROVISIONAL (e.g. 20 D vs 40 D check at D = 40)
-  ⟨verify Dütsch domain extent⟩; no generic size is normative.
-- Boundary family declared by the runner owner before running (x-periodic /
-  y free-slip or closed walls, whatever the dense runner supports without
-  production change); swept band ±A + R + 2 clear of any seam.
-- Per-step displacement ≤ .04 cells (bound .5).
+- Boundary family (runner owner confirms the zero-velocity inlet is supported
+  as configured before any run): the native dense channel only — zero-velocity inlet,
+  pressure-NEQ outlet, y walls (bounce-back). This is a finite-domain
+  approximation of the paper's 120 D O-grid, NOT infinite still fluid. The G4
+  periodic/slip overrides are a different family and are not substituted.
+- Sensitivity order (each step at D = 40 before the ladder is run):
+  1. box 24 D × 24 D vs 48 D × 48 D (cylinder mean position at the centre);
+  2. the larger box is accepted if section 6 domain criteria pass between the
+     two; otherwise 96 D is tried once (memory/runtime measured first); if that
+     still fails, the domain verdict is FAIL and is reported.
+- The ladder (D = 20 / 80) uses the accepted box size in units of D.
+- Memory/runtime: measured by a smoke run before each new size; measurements
+  inform scheduling only, never tolerances.
 
 ## 4. Observables (raw, per step, preserved)
 
-- `obs` Fx, Fy (CME) and the diagnostics columns (`MovingTables.DIAG`):
-  CME, CME + Wen, CME + cover − uncover reported separately; crossings,
-  eq_only, no_donor.
-- Velocity u, v on lines at the paper's x-stations relative to the mean
-  cylinder position and at its phase angles ⟨verify stations and phases⟩;
-  cell-centred values, documented bilinear interpolation in physical units.
+- `obs` Fx, Fy (CME) and all `MovingTables.DIAG` columns per step: CME,
+  CME + Wen and CME + cover − uncover reported separately; crossings, eq_only,
+  no_donor (no_donor must stay 0).
+- Velocity u1, u2 on lab-fixed lines x/D = -.6, 0, .6, 1.2 (relative to the
+  mean cylinder position) versus x2, at every step of the scored phases.
+- Interpolation: bilinear on cell centres using only cells that are fluid at
+  that step (flags read back via `get_flags()`); weights renormalized over the
+  fluid corners; a sample with no fluid corner, or inside the circle at that
+  step, is MISSING and logged, never set to zero. One-degree bins carry only
+  valid samples.
 
-## 5. Metrics
+## 5. Periodic-regime gate (every case, before any statistic)
 
-- Morison C_D, C_M by least squares over the measured cycles with the paper's
-  force definition and sign ⟨verify formula⟩; per-cycle RMS force; force
-  phase history; phase-resolved velocity profiles.
-- Unit map for each candidate stated with `k = rho dx^3 / dt^2` per span.
+Ledger rows, same schema for every case:
 
-## 6. Reference data provenance
+| field | content |
+|---|---|
+| dx, dt | in D and in T units |
+| U_max, nu, Re, KC | lattice and nondimensional |
+| T | native steps and nondimensional time |
+| duration | native steps, s/T, number of paper cycles |
+| discard | cycle 0 plus all cycles before the accepted window |
+| window | the common accepted window (below) |
+| cycle ledger | per cycle k: phase-aligned waveform change and profile change (below) |
+| verdict | PASS or FAIL-CLOSED |
 
-- Reference types kept separate: (a) phase-averaged LDA velocity measurements;
-  (b) the paper's computed results, including forces and Morison fits — a
-  computed reference, not a measured force. The paper itself reports the
-  Morison-fit error as larger than its coarse grid/time numerical error, so
-  C_D, C_M agreement is judged against that stated fit uncertainty.
-- Accepted: values from the paper's tables, or digitized figure curves with
-  figure number, tool and uncertainty recorded. Curves without provenance are
-  qualitative only. Values quoted by later papers are secondary until checked.
-- No cost estimate is normative; Astra's smoke run measures it.
+- Settling metric, ENGINEERING, fixed scales (no near-zero denominators):
+  - force: `max over phase of |F_k(phi) - F_{k-1}(phi)| / (0.5 rho U_max² D)`
+    on the per-step CME waveform aligned by step index within the cycle;
+  - profiles: `max over scored stations/phases/points of |u_k - u_{k-1}| / U_max`.
+- Rule: K_case = the smallest cycle k ≥ 4 for which both metrics are ≤ .005
+  for the N = 3 consecutive pairs (k-3→k-2), (k-2→k-1), (k-1→k).
+- Cap: 30 paper cycles per case; not settled by the cap → FAIL-CLOSED.
+- Common window: K = max over all compared cases of K_case; every case is run
+  to cycle K + 2 and scored on cycles K, K + 1, K + 2 (same indices).
+- FAIL-CLOSED also if any case covers fewer paper cycles than K + 2, if windows
+  differ, or if the ledger is missing.
+- The earlier G4 timing check (100 coarse vs 400 diffusive-fine steps) was a
+  matched short transient, not periodic evidence.
 
-## 7. Order
+## 6. Metrics and per-observable criteria (ENGINEERING, not paper uncertainty)
 
-Protocol review → test driver (no production change) → runs → physical
-validation verdict → only then single-cylinder VIV. No AMR, no pinball.
+- Morison fit: least squares of the normalized per-step force over the
+  accepted window against the two basis functions above, each averaged over
+  its single step interval, fixed paper phase, no free phase shift; outputs
+  c_d and added-mass c_i per force candidate.
+- Criteria:
+  - cross-resolution: for each observable, the D20→D40→D80 differences to
+    D80 must decrease; force waveform: normalized RMS difference D40 vs D80
+    ≤ .02 (scale `0.5 rho U_max² D`); profiles: RMS D40 vs D80 ≤ .02 U_max;
+  - domain (section 3): same two norms ≤ .01 between the two box sizes;
+  - against Table 1 (computed reference): |c_d - 2.09| ≤ .06 and
+    |c_i - 1.45| ≤ .04 at D = 80 (our engineering bands; the table's own
+    96→384 change is reported alongside, not used as an error bar);
+  - against Fig. 8 LDA: only after digitization with figure, tool and
+    digitization uncertainty recorded; RMS over all points of
+    `|u - u_LDA| / U_max` ≤ .05; experimental uncertainty is NOT quantified in
+    the recovered source and this is stated with every comparison.
+- No force candidate is selected for an RHS by these results; each is
+  reported.
+
+## 7. Order and scope
+
+Protocol review → lean test driver (no production change; reuses the
+existing Simulation API) → smoke (memory/runtime) → domain sensitivity →
+ladder → physical-validation verdict → only then single-cylinder VIV. No AMR,
+no pinball, no manuscript work.