docs: VIV predeclare — unified step sequence, velocity seed, cycle/peak definitions, caps, failure set

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

docs/validation/leontini_viv_predeclare.md

@@ -41,11 +41,17 @@ this page is jointly agreed.
 
 - 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
+- Per-step sequence (binding): known (y_n, v_n) and the last completed force
-  (`set_body`, then `run(1)`), so step n moves the body with (y^n, v^n) that
+  F_last → candidate (y_{n+1}, v_{n+1}) by the update below → `set_body` with
-  were advanced using F^{n-1} from the previous fluid step; step n measures
+  offset y_{n+1} and wall velocity (y_{n+1} − y_n)/dt (interval average; a
-  F^n. One step of explicit lag, declared.
+  different quantity from the endpoint v_{n+1}) → `run(1)` → only on success:
-- Structural update over one step with constant force F = F^{n-1} (exact
+  commit y_n ← y_{n+1}, v_n ← v_{n+1}, F_last ← force read for that step. Any
+  failure leaves the Simulation failed (existing lifecycle). Whether the
+  measured force represents the interval's start, midpoint or end is not
+  asserted; the one-step lag is declared, not corrected.
+- Initial state: fluid at rest except the uniform inlet; y_0 = v_0 = 0;
+  F_last = 0 for the first step; geometry initialized at the declared centre.
+- Structural update over one step with constant force F = F_last (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.
@@ -61,37 +67,44 @@ this page is jointly agreed.
   rest at the declared centre, y(0) = v(0) = 0.
 - Seed policy (conditional, declared): exact mirror symmetry can suppress
   lift. If max |y| over the last 5 T_n before t = 40 T_n (200,000 steps) is
-  below .01 D, apply one labelled seed at that step: body centre displaced by
+  below .01 D, apply one labelled seed at that step as a structural velocity
-  +.01 D in y (v = 0), `seed_applied=true` and its step logged; the run
+  increment v += 2 pi f_n (.01 D) (amplitude ≈ .01 D), so the geometry then
-  continues under the same cap. Missing shedding is a diagnostic, never an
+  moves continuously through the update (never a jump);
+  `seed_applied=true`, its step and size logged; the run continues under the
+  same caps. Missing shedding is a diagnostic, never an
   "A = 0 pass"; the seed is not changed or repeated after seeing results.
-- Response cycles: delimited by consecutive upward zero crossings of y about
+- Response cycles: delimited by consecutive upward crossings of y through the
-  its running mean; per-cycle peak = max |y − mean| in that cycle.
+  mean of the previous completed cycle (0 for the first). Per cycle: positive
+  peak max(y), negative peak min(y), mean offset, amplitude (max − min)/2.
+  Window value = mean amplitude over 10 cycles; window change =
+  |W_k − W_{k−1}| / W_{k−1}.
 - Settled when the per-cycle peak changes ≤ 2 % between consecutive 10-cycle
   windows and the last 5 cycle peaks agree within 1 %. Budget: 150 response
   cycles from the start of motion, including the 20 scoring cycles, so
   settling must complete by response cycle 130; the score uses the first 20
-  cycles after settling. Cap miss → FAIL-CLOSED.
+  cycles after settling. Hard native cap 1,000,000 steps (= 200 T_n) in case
+  response cycles cannot be detected. Either cap missed → FAIL-CLOSED
+  (timeout).
 - Durations reported: total steps, t U/D, N_resp, measured T_resp (mean
   upward-crossing interval); N_resp / f_n only as a labelled secondary clock,
   never as the settling unit.
-- Growth transient vs instability: an envelope that rises and then saturates
+- Growth is not a failure: initial VIV growth is physical. Checked every step
-  under the settling windows is a physical transient. Instability =
+  (FAIL-CLOSED): non-finite y, v or force; |y| > 1.0 D (about twice the
-  |y| > 1.0 D (about twice the largest reference peak, .551 D), a non-finite
+  largest reference peak, .551 D) or the offset box reached; no_donor > 0;
-  value, the offset box being reached, or an envelope still growing at the
+  a failed upload/step/sync. Timeout = a cap missed (above).
-  cap.
+- All failures are reported as they are (no sub-iteration, no RHS or
-- FAIL-CLOSED and reported (no sub-iteration, no RHS or parameter retune):
+  parameter retune, no automatic second case).
-  unsettled at the cap, instability as defined above (possible weak-coupling
+- Score over the 20 cycles after settling: target metric A_max/D =
-  instability at m* ≈ 2.55), or no_donor > 0.
+  max over those cycles of max(|positive peak|, |negative peak|) about y = 0
-- Score over the 20 cycles after settling: A_max/D (mean of cycle peaks) and
+  (Qin reports "maximum amplitude"); also reported: mean amplitude, positive
-  f/f_n (reported; no target).
+  and negative peaks, mean offset, f/f_n (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. Cost from Astra's no-dump timing on
+  only at a few predeclared snapshots. No runtime claim: there is no measured
-  this grid.
+  timing on this grid yet (the D40/60D receipt is a different, sampled case).
 
 ## Queued, not in this stage