docs: VIV predeclare — Kolahdouz/Qin Re150 primary case, CME+Wen RHS, explicit lag

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

docs/validation/leontini_viv_predeclare.md

@@ -3,64 +3,70 @@
 Stage goal (Yanqi via TRON): prescribed Dütsch case + one VIV case both
 "reasonably close" to a predeclared reference = development-stage success, then
 cleanup. The frozen Dütsch settling failure (0/28 pairs at 31.25 T) stays on
-record; nothing here re-scores it. No code until this page is agreed.
+record. Practical closeness is not a formal validation claim. No code until
+this page is jointly agreed.
 
-## Reference (primary, provenance required)
+## Primary case (one case)
 
-- Leontini, Thompson & Hourigan, J. Fluids Struct. 22 (2006) 857–864,
-  doi:10.1016/j.jfluidstructs.2006.04.003. 2-D, one transverse DOF,
-  Re = 200, m* = m/m_f = 10, zeta = 0.01; U* = U/(f_N D), f_N natural frequency
-  in fluid with inviscid added mass (as read by Grok from the full text).
-- Verified (Grok, primary text, JFS §3.1): U* uses f_N in fluid "assuming an
-  inviscid added-mass term applies" (C_A = 1); the paper also plots f/f_N,vac.
-  Companion: ANZIAM J. 46(E) C365–C378 (2005), doi:10.21914/anziamj.v46i0.965.
-- c_crit: both papers write zeta = c/c_crit without defining c_crit. OPEN for
-  the owners: (a) structural 2 sqrt(k m) or (b) effective 2 sqrt(k (m + m_A)).
-  The difference in c is sqrt(11/10) ≈ 5 % at m* = 10; the choice is declared
-  before any run and the other is not substituted afterwards.
-- Target: digitized A*/D and f/f_N at U* = 5.0 from Fig. 1 (tool and
-  digitization uncertainty recorded). OPEN until that digitization exists; no
-  target number is used before it.
+- Reference: Kolahdouz et al., arXiv:2003.12046, §4.1.1 (setup) and Qin et
+  al., arXiv:2003.12186, §4.5 (maximum amplitudes at U_red = 3…8: .075, .551,
+  .520, .459, .370, .084 D, as quoted by Grok/Astra from the text).
+- Re = 150, U* = U/(f_n D) = 5, m/(rho D²) = 2 (m* = rho_s/rho_f = 8/pi),
+  zeta = 0, f_n = sqrt(K/M)/(2 pi) in vacuum. Transverse DOF only.
+- Target: A_max = .520 D (peak amplitude, Qin §4.5). Multi-code reference
+  (Kolahdouz ILE-NS, Qin II-LBM). Reference uncertainty: not stated; the
+  spread between codes is not quantified here.
 
-## Case (one locked point; a sweep is a separate decision)
+## Our reproduction (declared differences)
 
-- U* = 5.0: the paper's own example of a periodic, constant-amplitude,
-  stable-phase response (Fig. 3); avoids the intermittent upper-type range
-  U* in (4.2, 4.7) (Fig. 2 at U* = 4.6, transition near 4.7). Chosen from the
-  paper's prose before any run.
-- D = 40 (matches the prescribed stage), MRT, dense double buffer, native
-  channel: uniform inlet U_lat = .04, NEQ outlet, slip y walls; box 40 D × 20 D
-  (blockage .05), cylinder 10 D from the inlet — a reproduction choice.
-- nu = U D / 200 = .008, tau = .524. Allowed y offset ±1.5 D; per-step move
-  ≤ .04 cells (bound .5).
+- D = 40, MRT, dense double buffer; U_lat = .04, nu = U D / 150 = .010667,
+  tau = .532.
+- Box 75 D × 60 D (3000 × 2400, Kolahdouz class); cylinder position as in
+  Kolahdouz (OPEN: confirm; default 20 D from the inlet, centred in y).
+- Boundaries: uniform Zou–He inlet, NEQ outlet (rho = 1, backflow clamp),
+  free-slip y walls. Kolahdouz uses a traction outlet: declared mismatch.
+- Qin's own VIV box (40 D × 20 D) is not used; a smaller box would be a
+  declared cost cut with more blockage, not "the same case".
+- Allowed y offset ±1.5 D; peak transverse speed ≈ .026 cells/step (bound .5).
 
-## Structure and coupling
+## Structure, coupling and time levels
 
-- m = m* rho pi D²/4, m_A = rho pi D²/4, k = (m + m_A)(2 pi f_N)², c from zeta
-  under the c_crit convention (OPEN).
-- Weak staggered update per step (host driver, `set_body` + `run(1)`, no
-  production change): v_{n+1} = v_n + (F_y^n − c v_n − k y_n)/m,
-  y_{n+1} = y_n + v_{n+1}. Newmark is the declared alternative only.
-- Force RHS: a coupled run uses exactly one RHS; other candidates are
-  diagnostics of that run, not alternative outcomes. Proposal (to agree):
-  primary RHS = raw obs/CME (the documented body force); one labelled
-  sensitivity run with RHS = CME + Wen. CME + cover − uncover is not used as RHS
-  (it failed the G4 same-grid frame target). This is a stage choice, not a
-  validated RHS.
+- M = 2 rho D² (lattice rho = 1), f_n = U/(5 D) = 2e-4 per step, K = M (2 pi f_n)²,
+  zeta = 0. Equation of motion uses the structural mass only.
+- Time levels (binding): the target y^{n+1} must be set before step n runs
+  (`set_body`, then `run(1)`), so step n moves the body with (y^n, v^n) that
+  were advanced using F^{n-1} from the previous fluid step; step n measures
+  F^n. One step of explicit lag, declared.
+- Structural update over one step with constant force F = F^{n-1} (exact
+  harmonic solution, zeta = 0): y_e = F/K, w = 2 pi f_n,
+  y^{n+1} = y_e + (y^n − y_e) cos w + (v^n / w) sin w,
+  v^{n+1} = −(y^n − y_e) w sin w + v^n cos w.
+- Primary RHS (single coupled run): CME + Wen (theory-motivated stage choice:
+  Galilean-invariant link correction; G4 could not separate it from CME).
+  Raw CME and the node terms are logged as diagnostics of that trajectory;
+  the node impulse is not added. A run with CME-only as RHS is a separate,
+  labelled sensitivity case, decided separately. Neither RHS is claimed proven.
 
-## Window and acceptance (engineering, development stage)
+## Window, failure semantics, acceptance (engineering, development stage)
 
-- Discard the start-up; the response is settled when A_rms changes ≤ 2 %
-  between consecutive 10-cycle windows and the last 5 cycle amplitudes agree
-  within 1 %; cap 150 oscillation cycles; unsettled → FAIL-CLOSED, reported.
-- Score on the 20 cycles after settling: A*/D and f/f_N (in-fluid f_N;
-  vacuum normalisation secondary).
-- Acceptance: |A* − A*_ref| ≤ .15 A*_ref and |f* − f*_ref| ≤ .05 f*_ref,
-  each reported together with the digitization uncertainty and the fact that
-  the reference is computed (2-D), not experimental.
+- Settled when the per-cycle peak |y| changes ≤ 2 % between consecutive
+  10-cycle windows and the last 5 cycle peaks agree within 1 %; cap 150
+  oscillation cycles.
+- FAIL-CLOSED and reported (no sub-iteration, no RHS or parameter retune):
+  unsettled at the cap, |y| beyond the declared offset box, no_donor > 0, or a
+  growing/diverging amplitude (coupling instability at m* ≈ 2.55).
+- Score over the 20 cycles after settling: A_max/D (mean of cycle peaks) and
+  f/f_n (reported; no target).
+- Acceptance: |A_max − .520 D| ≤ .052 D (±10 %), stated together with the
+  boundary mismatch and the absence of a quoted reference uncertainty. A pass
+  is "reasonably close" for the stage: not grid convergence, not force-RHS
+  validation, and it does not touch the Dütsch settling record.
 - Driver reads force and the small diagnostics per step only; field reads
-  only at a few predeclared snapshots.
+  only at a few predeclared snapshots. Cost from Astra's no-dump timing on
+  this grid.
 
-## Not in this stage
+## Queued, not in this stage
 
-D80, literature claims, pinball, AMR, BC redesign, threshold changes.
+Leontini et al. JFS 22 (2006) Re = 200, m* = 10, zeta = 0.01, U* = 5.0 (needs
+the owners' c_crit convention and a Fig. 1 digitization). D80, literature
+claims, pinball, AMR, BC redesign, threshold changes.