
ID	0017
Class	DOCUMENTATION
Severity	1
Status	blocked
Models	Seine/Vessel, Seine/Operation, Seine/Buoy, Seine/Cable
Found	2026-09-15 audit (`a7d080d`)
Decision needed	Supply realistic vessel, buoy, warp and net parameter values for a seine scenario, or confirm that plausible placeholders are acceptable as a starting point. Also needs the `Connected` convention from FISH-0002.

Evidence

examples/input/ holds seven files: 6DOFTrawlDoor.xml, CenterWeight.xml, CrowFoot.xml, Example.xml, SimplePIDController.xml, SimpleTrawlVessel.xml, ValuesDisplay.xml. grep -l Seine/ over examples/input/ matches none of them. All four registered seine types — Seine/Operation, Seine/Vessel, Seine/Buoy, Seine/Cable (src/fhsim_fishery.cpp:27-31) — therefore have no runnable example. Correspondingly, none of the four headers carries an @include/@example reference; the six that do are all in src/trawl/.

Seine/Cable compounds it: unlike every other SimObject here it takes its geometry from a second XML file named by its File parameter (src/seine/CableBranchedAttractor.cpp:26-28), with a BranchedCable structure of General and CableElements sections (:28, :56). No such file exists anywhere in the tree, so the format has no worked instance at all.

Effect

Half the library is undocumented by example. A user wanting a Danish-seining model must infer, from headers alone: the shared-attractor coupling between Seine/Vessel, Seine/Operation and Seine/Cable (which never appears in the interconnection section, so it is invisible in an input file); the AttractorNameWarp (singular, on the vessel) versus AttractorNameWarps (plural, on the operation) parameter-name asymmetry (src/seine/VesselDeploy.cpp:17 vs src/seine/SeineOperation.cpp:43) where the values must match and the names deliberately do not; and the whole BranchedCable file format. It also blocks testing: FISH-0002, FISH-0011, FISH-0012 and this item's own coverage all need a seine scenario that does not exist, which is the largest part of the cost of those fixes.

Possible fix

In increasing order of cost:

examples/input/SeineConnector.xml — Seine/Buoy alone, Connected driven by a Src/Step, two constant position/velocity pairs. Pure signal plumbing, no physics, and exactly the scenario FISH-0002 needs. An agent could write this once the owner confirms the Connected convention in FISH-0002.
examples/input/SeineOperation.xml — Seine/Operation alone with its eight inputs tied to constants, demonstrating the phase schedule and the warp-length outputs. This is what FISH-0011 and FISH-0012 need.
examples/input/SeineDeployment.xml plus a companion SeineCable.xml geometry file — the full coupled operation: vessel, operation, buoy and branched cable, with the attractor names wired up. This documents the shared-resource coupling and the BranchedCable format.

Add @include/@example lines to the four seine headers as each example lands, so the generated reference picks them up (doc/CMakeLists.txt:44-45 already has examples on DOXYGEN_EXAMPLE_PATH).

Owner question: the parameter values. Building a Danish-seining scenario that is physically sensible (track geometry, warp and net dimensions, attractor strengths, integrator tolerances) is modelling work, not transcription, and a wrong example is worse than none. Items 1 and 2 need only plausible values; item 3 is work only the owner can do and can trail the rest.

Test that would prove it

Depends on FISH-0001. Each example added becomes a tests/in/ case directly — that is the point of asking for them, and it is why this item gates the seine behavioural fixes rather than being cosmetic. The Examples-Load_Test from FISH-0009 then covers them all.

Risk

None — additive. New files under examples/input/ and four @include lines.

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

Re-confirmed at HEAD: grep -l Seine/ over examples/input/ returns nothing, so no shipped input exercises any Seine SimObject. Writing seine scenarios is modelling work: it needs realistic parameter values for vessel, buoy, warp and net, and the first scenario also needs the Connected convention that FISH-0002 has not settled. Placeholders invented by the fix pass would look like validated examples. Owner supplies the values, or confirms that plausible placeholders are acceptable as a starting point.