0014 — Crowfoot header describes a state-based solution the code does not implement, and Example.xml passes three dead attributes

ID	0014
Class	KNOWN-LIMITATION
Severity	1
Status	blocked
Models	Trawl/Crowfoot
Found	2026-09-15 audit (a7d080d)
Decision needed	Is validating NumLines to the range 1 to 3 wanted, given that it turns an inert configuration into a load error for existing inputs?

Status (2026-09-15)

items 1, 2 and 4 of the possible fix are done — the header prose now describes the FIR-filtered-force direct solution and says the object has no states, the constructor Doxygen no longer mentions "Mass2D" or Velocity/Position states, the ExternalVel row says the port is always zero, and examples/input/Example.xml no longer passes DampingRatio, EigenFrequency, IntegratorGain. Item 3 (NumLines validation) turns a silently inert configuration into a load error and is left for the owner.

Evidence

src/trawl/Crowfoot.h:15-19 describes how the algebraic loop is broken:

This class finds the stable position of the collecting point, based on the forces acting
on the point. This is done based on a direct solution, but to avoid a circular loop between
the output position and the input force, the output position is found based on a state which is
moved at a constant speed towards the instantaneous solution.

There is no such state. The three states are commented out at src/trawl/Crowfoot.cpp:55-57 and their indices at src/trawl/Crowfoot.h:148-150. What the code does instead is filter the force: AcceptedStep (src/trawl/Crowfoot.cpp:106-109) pushes ExternalForce into a three-channel FIR filter, and OdeFcn (:100-103) solves the geometry from the filter's output, writing straight into m_instantPos, which PositionOut (:66-69) returns with no rate limit at all. The delay that breaks the loop is in the force path, not in a moved position.

Second, smaller defect. src/trawl/Crowfoot.cpp:11-17:

creator->GetIntParam("NumLines", &m_numLines);
// creator->GetDoubleParam("DampingRatio", &dampingRatio, 1.0);
// creator->GetDoubleParam("EigenFrequency", &eigenFrequency);
// creator->GetDoubleParam("IntegratorGain", &m_integratorGain, 0);

NumLines is the only parameter read, yet examples/input/Example.xml:71-74 passes three more:

NumLines                  = "2"
DampingRatio              = "1.0"
EigenFrequency            = "5"
IntegratorGain            = "0"

They are the parameters of the abandoned state-based formulation and have no effect.

Third: the header states "A run-time selected number of lines (1, 2 or 3)" (src/trawl/Crowfoot.h:10), and CrowfootMath::Update switches on exactly those three cases (src/trawl/subroutines/CrowfootMath.cpp:105), but NumLines is not validated. A value of 4 constructs four lines and four port pairs and then falls off the end of that switch.

Effect

A reader of the reference page expects a rate-limited collecting point and tunes DampingRatio/EigenFrequency to control it, with no effect and no warning. Someone debugging a stiff crow-foot model looks for the position filter and finds none. And NumLines = "4" produces a silently inert solver rather than a parameter error.

Possible fix

Documentation plus one validation, no behaviour change to the solver:

1. Rewrite src/trawl/Crowfoot.h:15-21 to describe what the code does: a direct solution from a FIR-filtered external force, with the filter (three channels, three taps, src/trawl/Crowfoot.cpp:59) fed once per accepted step and seeded at InitialConditionSetup with the centroid of the line fastening positions (:111-119). Keep the Coope sphere-intersection citation — it is accurate. Say explicitly that the object has no states.
2. Remove DampingRatio, EigenFrequency and IntegratorGain from examples/input/Example.xml:72-74.
3. Add NumLines validation after src/trawl/Crowfoot.cpp:11: report a parameter error unless 1 <= m_numLines <= 3, naming the supported range.
4. Note in the header that ExternalVel is currently always zero, or leave that to 0003 if 0003 lands first — do not describe it as working.

Do not resurrect the commented-out state formulation here; that is 0003's option 2 and the owner's call.

Owner question: item 3 turns a silently-inert configuration into a load error. Such files produce a non-functioning crow foot today, so no working model is affected — but confirm that a new load error is acceptable.

Test that would prove it

Depends on 0001. tests/in/SimObj-Crowfoot/ already needs to exist for 0001's first wave, built from examples/input/CrowFoot.xml; its _ref.csv pins the geometry solver, and its input file omits the three dead attributes, so the corrected example and the test agree. For item 3, a second input file with NumLines = "4" that is expected to fail setup — fhsim::test::RunTest surfaces a parameter error as a setup failure, so EXPECT_FALSE(run.ok) is the assertion.

Risk

Items 1, 2 and 4 are text. Item 3 rejects input files that pass NumLines outside 1–3; such files produce a non-functioning crow foot today, so the only models affected are already wrong.

Why not solved (fix pass 2026-09-15)

Partially solved. Commit 9f7c8ca in fhsim_fishery did items 1, 2 and 4: the header prose now describes the FIR-filtered-force direct solution and states that the object has no states, the constructor Doxygen no longer cites Mass2D or states, the ExternalVel row says the port is always zero, and Example.xml no longer passes the dead DampingRatio, EigenFrequency and IntegratorGain attributes. Verified with FhSim runs of a scratch copy (TEnd 0.05): the edited file's output is byte-identical to the unedited file run under an equally sized process environment. Item 3, validating NumLines to the range 1 to 3, was not done because it turns an inert configuration into a load error, which is a behaviour change for existing inputs. Owner decision: whether that validation is wanted.

---