docs: Leontini VIV predeclaration draft (not frozen)

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

docs/validation/leontini_viv_predeclare.md

@@ -0,0 +1,57 @@
+# Single-cylinder free transverse VIV — PREDECLARATION DRAFT (not frozen)
+
+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.
+
+## Reference (primary, provenance required)
+
+- 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).
+- OPEN: c_crit convention (in-fluid vs vacuum); the chosen figure panel; the
+  digitized A*/D and f/f_N at the chosen U* with tool and digitization
+  uncertainty. No target number is used before these are recorded.
+
+## Case (one locked point; a sweep is a separate decision)
+
+- One U* inside the primary lock-in band, chosen from the paper's own figure
+  before any run (OPEN, with its digitized A*, f/f_N).
+- 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).
+
+## Structure and coupling
+
+- 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.
+
+## Window and 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.
+- Driver reads force and the small diagnostics per step only; field reads
+  only at a few predeclared snapshots.
+
+## Not in this stage
+
+D80, literature claims, pinball, AMR, BC redesign, threshold changes.