0109 — Freeze never settles on an oscillating rig: it re-arms about 60 times in 300 s

ID	0109
Class	KNOWN-LIMITATION
Severity	1
Status	blocked

Models: —

Found: 2026-10-12, feature wake-casting-trawl: fhsim_marine_elements' TrawlCableWakes fixture (300 s) and fhsim_fishery's SteadyTow with CastWake.

Decision needed: what Freeze should do with an object that never reaches a steady state (oscillating doors, a rig in waves): hold the non-converged freeze, widen the re-arm test, or recommend (or default to) Periodic for such objects.

Evidence

• Observed: in both runs Freeze re-arms about 60 times in 300 s and each round ends with "wake frozen at t = … s after N rebuilds without converging".
• src/environment/WakeSchedule.cpp:230-237 (FreezesAfter): a round freezes when the change measure is below WakeTolerance (0.01) or after 1 + WakeIterations (4) rebuilds, WakeIterInterval (5 s) apart (:294-296); the exhausted case logs :316-317.
• Re-arm triggers, checked at every Due (:125-133): the filtered source velocity u_s or the filtered ambient current at the source drifting by more than WakeRearmTolerance (0.1) of the relative flow speed at the freeze (:143-173), or the mean position moving more than WakeRearmDistance × √(W·H) from the frozen frame (:175-188). Rearm (:222-228) starts a new round at once.
• An oscillating rig changes its loads by more than 1 % between rebuilds 5 s apart, so no round converges, and an oscillation of u_s beyond 10 % of the flow speed re-arms the next. Which trigger fires in the two runs has not been tallied (each re-arm line names it).

Effect

Freeze degenerates into a rebuild roughly every WakeIterInterval, each with a WakeBlendTime blend, with about 60 rebuild, freeze and re-arm lines each in 300 s: the cost and the log of Periodic with a 5 s period, without its predictability. The wakes are as current as a 5 s Periodic schedule would make them, so results are plausible; the log is noise.

Possible fix

1. After a freeze without convergence, do not re-arm for drifts the rounds already saw (keep the band of u_s over the round, re-arm only outside it) or for at least a minimum hold time.
2. Recommend WakeUpdate="Periodic" for oscillating objects in doc/user/wake-parameters.md, or let a consumer such as the trawl rig default to it.
3. Rate-limit the log: one summary line per N re-arms.

Test that would prove it

A TestWakeBody or TestWakeCluster whose velocity oscillates by ±20 % with a 10 s period, WakeUpdate="Freeze", 300 s: the number of rebuilds stays bounded (option 1) and the log holds at most a few re-arm lines.

Risk

Option 1 keeps a stale wake longer for an object that really changes its operating point during an oscillation; option 2 changes the results of consumers that switch.