
ID	0064
Class	BUG
Severity	1
Status	blocked
Models	Auv/Echosounder
Found	2026-09-25
Decision needed	Whether to pull the last down-beam sample back above the ray hit, or to stop reporting a masked-below-seabed status as a "domain too small" warning

Evidence

Found while resolving FISH-0057. With the Cod profile extended to 200 m, the Cod warnings are gone, but SimObject.AuvSurvey_* now logs, once per run, in tests/out/AuvSurvey/AuvSurvey_log.txt:

[Warning] In SensorEchosounder 'Echo'. The Down beam sampled species field 'Calanus' at depth 139.962878
          m and got status 1 instead of OK, so the field's domain is too small for the beam and the
          echogram carries a clamped value there. This warning is given once per beam.

It was there before FISH-0057 too, hidden: the flag in src/auv/SensorEchosounder.cpp:696-697 is per beam, not per field, and Cod had already set it on the first ping at 20.6 m.

The Calanus profile runs to 400 m (examples/input/auv_ocean_fields.json:56) and has no domain box, so 139.96 m is inside its profile. The only other way ParametricScalarField::GetValue returns OUT_OF_RANGE_INACCURATE is the seabed mask, fhsim_environment/src/environment/ParametricScalarField.cpp:392-394:

if (m_spec.maskBelowSeabed && z > bottomDepth) {
   value = 0.0;
   return marenv::Status::OUT_OF_RANGE_INACCURATE;

So the down beam's last bin sampled a point below the field's seabed. The beam ends at the range that ComputeRayIntersection returns (SensorEchosounder.cpp:640-641), searched with RayStepSize and RayTolerance. The last bin is sampled at the middle of its wet part, (k * BinSize + R) / 2 (SensorEchosounder.cpp:397-401). If R overshoots the true hit by more than half that wet part, the sample lies below the seabed. This cause is inferred and has not been instrumented.

Effect

The number is right: a masked sample is 0, and it falls in the bin that carries the bottom echo. But the warning says the field's domain is too small, which is false, and it is the same false alarm that FISH-0057 set out to remove from the shipped scenario. Because the flag is per beam, one such sample also hides any later genuine domain warning on that beam.

Possible fix

Clamp the last down-beam sample to at most R - RayTolerance, or skip field sampling in the bottom bin. This changes echogram values only in that bin.
Ignore a non-OK status for a sample at or beyond bottomRange - RayTolerance on the down beam. The echogram does not change; the warning is given only for real domain misses.
Make the warning flag per field and per beam, so that one field cannot hide another's warning. This is independent of the two options above.

Test that would prove it

Run SimObject.AuvSurvey_TheEchogramSeparatesTheSpeciesByFrequency and assert that AuvSurvey_log.txt holds no domain is too small warning. For the first option, add a unit test that SampleRangeOf never exceeds the ray hit minus the tolerance.

Risk

The first option moves one bin per ping in every echogram. The second option is not visible in the output.