CelerisLab/research/viv_re150

Research VIV driver — coupling contract (not production)

run.py couples a 1-DOF undamped spring–mass (viv.py) to the production moving-circle API. Everything specific to fluid–structure coupling lives here, not in src/.

• Per step: known (y_n, v_n) and the last completed force F_last → exact harmonic candidate (y_{n+1}, v_{n+1}) → set_body(offset=(0, y_{n+1}), vy=y_{n+1} − y_n) (interval wall velocity, lattice dt = 1) → run(1) → commit y, v and F_last only after the step succeeded. One step of explicit force lag (weak coupling); no sub-iteration.
• Structural RHS = CME + Wen (y), read from moving_diagnostics() by the names in MovingTables.DIAG; raw CME, the obs force and node terms are logged as diagnostics. This is a stage choice, not a validated force law.
• Production guarantees used: fail-closed target commit (synchronized step, no_donor == 0), input rejection before mutation, a failed device step marks the Simulation failed.
• Not provided, by design: device-resident structure state or batched (multi-step) coupling, strong/sub-iterated coupling (would need state rollback), more than one DOF. These are future work and would be a separate execution path, not an abstraction over this driver.
• Recorded result and limits: docs/validation/moving_bodies_stage1.md; predeclaration: docs/validation/viv_re150_predeclare.md.