
ID	0037
Class	KNOWN-LIMITATION
Severity	2
Status	ready
Models	Auv/UndulateDiveControl, Auv/UndulateMissionControl, Auv/Vehicle
Found	2026-09-22
Decision needed

Evidence

Measured on tests/in/Auv/Auv_Undulate_in.xml, the whole stack at cruise: Auv with the suggested parameter set at AverageDensity = 1025, the three increment F PID instances, and Auv/UndulateDiveControl at DiveAngle = 0.349.

Sampled every 10 s over one descending leg (tests/out/Auv/Auv_Undulate_res.txt):

t, s	depth, m	pitch, rad	PitchRef, rad	RudderDive, rad
139.8	13.878	−0.1562	−0.349	0.0566
159.8	17.579	−0.2450	−0.349	0.1587
179.8	23.359	−0.3111	−0.349	0.1871
199.8	30.189	−0.3357	−0.349	0.1969
209.8	33.772	−0.3412	−0.349	0.1989

Two separate shortfalls.

The settled vertical speed is 0.36 m/s, not 0.51 m/s. Between t = 199.8 and t = 209.8 the depth grows by 3.58 m, that is 0.358 m/s, where u sin(DiveAngle) = 1.5 sin(0.349) = 0.513 m/s. The pitch angle really is −0.341 rad, so this is not a control error: the dive plane carries a standing deflection of 0.199 rad to hold the nose down against the COG righting moment, the upward fin force that comes with it has to be balanced by the hull, and the hull balances it by flying at roughly 0.10 rad of angle of attack. The flight path angle is about 0.24 rad where the pitch angle is 0.34.

The pitch loop needs about 40 s to reach the reference. The proportional part alone settles near −0.23 rad, 66 % of the reference, and the rest is removed by IntegratorGain = -0.05 against ProportionalGain = -0.6, an integrator time constant of 12 s. An undulation leg in this fixture is about 90 s, so a third of every leg is spent still turning over. The triangle wave is visibly rounded.

**MaxIntegratorPart = 0.2 is all but consumed at the default DiveAngle.** The settled RudderDive is 0.1989 rad and the integrator part is what supplies almost all of it. A steeper undulation, a slower cruise or a COG[2] above the suggested 0.020 m would hit the anti-windup limit and the vehicle would simply not reach the commanded angle, with no diagnostic.

Effect

A mission planner that budgets a survey from DiveAngle alone overestimates the vertical coverage rate by about 40 %, which matters directly to increment H and to the battery budget: the same water column costs 1.4 times the track length and 1.4 times the energy.

The slow pitch loop means the shortest sensible undulation amplitude is set by the loop, not by the guidance. Below roughly 15 m of amplitude the vehicle spends most of each leg in the transient and never reaches DiveAngle at all, so the depth trace becomes a sine rather than a triangle and the effective dive angle is smaller again.

Possible fix

Document, and derive the planning number from the flight path angle. The Doxygen of Auv/UndulateDiveControl should say that the vertical speed is u sin(gamma) with gamma < DiveAngle, and increment H should take its vertical rate from a measurement rather than from the parameter. Cheapest, and it is what this increment did.
Raise the pitch loop's IntegratorGain and MaxIntegratorPart. A sweep at Ki = -0.15 and MaxIntegratorPart = 0.3 would cut the 40 s and restore headroom, at the cost of re-tuning against the overshoot that increment F measured on the heading step. The gains are XML, not code.
Feed-forward the standing deflection. The deflection needed is m g |COG_z| sin(theta_ref) / (q_dyn A_fin |x_fin|), which the dive control could compute and PidController could accept as an InitOutput-like bias port. That removes both the 40 s and the anti-windup exposure, but it means a new port on Trawl/PIDController, which every trawl model shares.

Test that would prove it

Auv_UndulateACommandedDiveActuallyDescends in tests/AuvUndulateDiveControl_Test.cpp already asserts the settled descent rate lies in [0.25, 0.55] m/s and that RudderDive exceeds 0.19 rad, so a fix under option 2 or 3 will fail it and force the numbers to be revisited deliberately. A direct test of the claim would fix the pitch reference at −0.349 rad in an open-loop fixture, measure Vel_2 / |Vel|, and assert that asin of it is 0.24 rad and not 0.349.

Risk

Option 2 re-opens increment F's tuning, which was swept and measured; option 3 touches a class every trawl model in the library uses. Option 1 changes nothing and leaves a 40 % planning error available to anyone who reads DiveAngle and multiplies.