FhSim  3.1.0
Marine systems simulation
Loading...
Searching...
No Matches
Migrating to 4.0.0

Table of Contents

This page is the migration note for fhsim_marine_elements 4.0.0, the net-hydrodynamics release. It says what an input or a downstream build written for 3.x has to change, and how much the results move. The detailed entries, with every figure quoted here, are in CHANGELOG.md. How to set the new parameters is in the user guide (Net hydrodynamics: user guide), and the theory in Net hydrodynamics: methods manual.

Dependencies

  • fhsim_marine_elements 4.0.0 requires fhsim_environment 4.x ([>=4.0.0 <5]), which requires marenv 2.x. marenv 2.0 replaces the wake factor with a velocity deficit defined relative to the source velocity. A downstream library that calls the marenv or fhsim_environment wake API directly must follow their 4.0 and 2.0 changelogs: EnvironmentProvider::GetWakeRatio is now GetWakeDeficit, and WakeField::Sample returns a deficit and a source velocity.
  • Two fhsim_environment input changes can affect a combined model: TestNetcageWake's MaxWakeFactor and WakeFactorCutoff are now MaxDeficit and DeficitCutoff, and VisualFlowPlane's ComputeFunction="WakeFactor" is now "WakeDeficit".

Removed

No registered SimObject was removed, and no XML input needs to change for a removal. One parameter was removed, MaxAcceleration; an input that sets it still runs (Parameters).

Removed from the library and from the installed headers (MARE-0097, MARE-0018); none had a 3.x user:

  • the screen-model group ScreenElement3N, ScreenElementDef and ScreenStructureSpec;
  • the OpenCL group NetStructureOCL, NetPanelForcesOcl and netpanelforces.c, which was never compiled;
  • the single-precision FNetElementFloat;
  • the netconstants namespace in FNetElement.h.

A downstream build that includes one of these headers no longer compiles. Net/NetStructureWakeEffect and NetElement3NWakeEffect are kept, but deprecated (see Deprecated).

Removed from the panel force code, with their behaviour:

  • CalcSolidity and CalcVelocities (the speed-up of the whole velocity vector), replaced by the load laws and the structure's solidity rule;
  • the 500 m/s velocity saturation (kSaturationVel, and hydroForcesRatio in Net/NetStructure) in Net/NetStructure;
  • the separate knot drag outside TwineCrossFlow: the screen laws include the knots through the solidity;
  • the twine tension and damping that Net/NetStructureWithConstraints computed and discarded.

Deprecated

Net/NetStructureWakeEffect and its panel class NetElement3NWakeEffect are deprecated (MARE-0117). They are kept, building and unchanged in 4.x because fhsim_aquaculture derives Netcage/NetCageWakeEffect from them, and will be removed in fhsim_marine_elements 5.0. Setup now logs 

<Name>: Warning: this SimObject derives from Net/NetStructureWakeEffect, which is deprecated (MARE-0117) ...

once per object, also for a derived SimObject (the message names the base class it derives from, not the registered type, so it reads correctly whichever name the object is registered under, MARE-0156); nothing else changes. The classes carry no C++ [[deprecated]] attribute, so a downstream build that derives from them gets no compiler warning.

Known limitation, left as it is (MARE-0157): FinalSetup of these classes samples the waked current at the panel centroids to build the wake-effect polynomials, which the environment advises against (fhsim_environment wakes.md, "The FinalSetup rule"). A porous-disc source or TestNetcageWake that sets its field in its own FinalSetup is seen only if its object is set up before the net, so the polynomials depend on the object order in the input file. Put such sources before the net, or use Net/NetStructure with CastWake.

The replacement is Net/NetStructure with the net-hydrodynamics load laws (HydroModel, Load law and fluid) and its wake casting into the environment wake (CastWake, Wake casting). The wake options of Net/NetStructureWakeEffect have no one-to-one counterpart there, so results differ.

C++ API (installed headers)

Every header under src/ is installed, so a downstream library that calls the panel code directly must follow these changes (against 3.2.1):

  • NetElement3N::AddNodeForces takes the panel load law and the fluid as its first two arguments (const hydrodynamics::PanelLoadLaw&, const hydrodynamics::Fluid&), is a const template on the scalar type, and has no hydroForcesRatio argument. The solidity comes from the element's rule, which the constructor now takes (const net_solidity::PanelSolidity&, with knotDiameter in place of dNy_water, knotDiameterRatio and the twine drag coefficients). The free function net_element_forces::AddNodeForces (NetElement3NForces.h) takes a PanelFrame from ComputePanelFrame, the law, the fluid and the solidity.
  • NetElement3N::PanelForceParams() is removed.
  • With MaxAcceleration (MARE-0133): SAdaptationSpec_t::maxAcceleration (NetStructureSpec.h), SCableSpec::maxAcceleration (InternalCable.h), the protected CableBranched::m_maxAcceleration and the header net/NetAccelerationLimit.h (LimitAccelerationMagnitude) are removed. A class derived from CableBranched that reads m_maxAcceleration (fhsim_fishery's CableBranchedAttractor did) no longer compiles.
  • NetElement3NWithConstraints is reworked the same way: its constructor takes knotDiameter and a net_solidity::PanelSolidity in place of the viscosity, knot and drag-coefficient arguments; AddNodeForces takes the law and the fluid and has no hydroForcesRatio or addedLinearDrag, and is const; HasBarDirections and Solidity are added.
  • New: EvaluatePanelLoad on NetElement3N, on NetElement3NWithConstraints and in net_element_forces, which evaluates the law on a panel without adding node forces (used by the wake caster).
  • New headers: net/NetPanelSetup.h (namespace net_panel_setup, the panel setup shared by Net/NetStructure and Net/NetStructureWithConstraints) and net/NetSolidity.h (namespace net_solidity, the solidity rules), besides net/NetWakeCaster.h, net/DiskDrag.h and the hydrodynamics/ laws.

Parameters

Renamed: none in this library. The TwineCrossFlow coefficients take the names of the 3.x NetStructure constant Ct_nominal and of its parameter CnKnots_nominal, so inputs that set CnKnots_nominal keep working. The 3.x Ersdal-Faltinsen constants (CnLinearLimitAngle, CnLinear, CnTurb, CnLam, TurbLimit, LamLimit) are not parameters: TwineCrossFlow holds the cylinder polynomial outside 32 ≤ Re ≤ 10⁴ instead (owner ruling R58, MARE-0200).

No longer read: NetDampingRatio in Net/NetStructureWithConstraints. It only set the damping that was discarded. It is still read by Net/NetStructure.

Removed: MaxAcceleration (MARE-0133, owner ruling R40), the acceleration limit of the net and cable objects: the <General> attribute of the net file of Net/NetStructure, Net/NetStructureWithConstraints and Net/NetStructureWakeEffect (and of the removed Net/NetStructureArray, where it was on by default at 1000 m/s²), the <General> and <CableElements> attributes of the Cable/Branched file, and the Cable/LumpedMass parameter. It was an adaptation to older integrators. It scaled a node's acceleration down but not the forces that node's elements put on their other nodes, so a net whose nodes reached it drove itself (the morenot520 trawl of fhsim_fishery reached its warps' 1 MN MaxTension from every start). An input that still sets it runs unchanged otherwise: the attribute in a net or cable file is ignored, with a warning in the log naming the file (MARE-0165), and the Cable/LumpedMass parameter is listed under "Parameters not queried" in the log (Info level). Results change wherever the limit acted, typically in a start transient. Net/NetStructure now keeps its analytical Jacobian (for implicit integrators) unless MassFactor is above 1, MaxVelocity above 0 or a cable carries a sphere or a disk; before, a net file that left out MaxAcceleration got its default of 1e20 and so the numerical Jacobian. Cable/Branched now always offers its analytical Jacobian.

New, in Net/NetStructure and Net/NetStructureWithConstraints (defaults and units in Load law and fluid and Solidity):

Parameter Default Replaces
HydroModel LocalThroughFlow the hard-coded twine model
HydroA3, HydroB4, HydroInduction law defaults –
SolidityModel MeshOpening the hard-coded 1.1·t/(L₀ sin φ cos φ)
KnotFactor 1 the hard-coded 1.1
Solidity, per-element Sn in the net file none –
Rho, Nu 1025 kg/m³, 1.19e-6 m²/s the same values, hard-coded; now read by both. The cable elements follow Rho too (their 1025 was hard-coded as well)
TwineCrossFlow coefficients the 3.x values of Net/NetStructure the 3.x constants; CnKnots_nominal was already read by NetStructure
knotDiameterRatio 2 now also read by Net/NetStructureWithConstraints

New, in Net/NetStructure and Net/NetStructureWithConstraints: CastWake (default false, so existing inputs are unchanged) and the Wake* parameters (Wake casting). Without CastWake the Wake* parameters are ignored, and the log names each one given. Under Freeze a net converges on the larger of its private max|ΔR| and its lumped |ΔM|/M (owner ruling R121), so an N-row farm needs WakeIterations ≥ N; the default WakeIterations is 4 (owner ruling R130; 2 earlier in 4.0 development), which covers up to four rows.

New, in Net/Disk and Net/Sphere: CastWake (default false; without it the results are byte-identical to those without the parameter) and the common Wake* parameters (WakeUpdate, WakeBuildTime, WakeIterations, WakeIterInterval, WakeTolerance, WakePeriod, WakeRelaxation, WakeBlendTime, WakeRearmTolerance, WakeFilterTime, WakeExpansion, WakeCutoff), read with fhsim_environment's ReadWakeSettings (MARE-0127).

**WakeLength changed meaning during 4.0 development** (phase F, contract C3 amendment). It is now the reach of a net's private grid beyond its rear panel, 0 meaning the largest panel diameter; it no longer sets how far downstream other objects see the net's wake (before phase F 0 meant five times the structure's size). An input that set WakeLength to make a wake reach a downstream structure no longer needs it: other objects see the lumped source at any distance.

New setup errors: an unknown HydroModel or SolidityModel; SolidityModel="Fixed" with neither Solidity nor Sn; TwineCrossFlow on a panel with collinear mesh coordinates; WakeBlendTime above WakePeriod (Periodic) or WakeIterInterval (Freeze); HydroA3 above 0.25 or |HydroB4| above 0.5 (MARE-0137); HydroA3 below −0.125, or a harmonic that is not finite (MARE-0208). New setup warning: ScreenMF2022 at a solidity outside 0.18–0.36.

Changed physics

Every model with a net structure or a Net/Disk gets different loads. The figures below are the CHANGELOG's, measured on single panels and on the test fixtures.

Wakes: other objects see lumped sources

Only models with CastWake="true" are affected (ADR 0006; methods manual § 14. The wake a net or a body casts):

  • A casting net registers one lumped source (its total panel drag along the flow, the frontal rectangle of its nodes, starting at its rear face); its per-panel field is private to its own panels and cable elements. Every other object, a second cage, a probe, a Disk or Sphere, a separate rope or tube, sees only lumped sources. A separate SimObject inside a net's volume therefore sees no internal wake of that net, and VisualFlowPlane shows the lumped wakes only.
  • The net's panel sources carry their cylinder solidity S_c (without the knot factor, less the bar overlap; the given Sₙ with SolidityModel Fixed; owner ruling R56), so the wake behind each panel follows MF2022 Eq. 11 in the near wake (marenv). The net's own drag changes little (Lader cages S3 by at most 0.6 %, MARE-0129).
  • A second cage behind a first is shaded somewhat less than by the per-panel field: 3.7 % in the benchmark farm (cage-2/cage-1 drag 0.760 against 0.733), because the lumped source carries the drag the first cage feels, not the sum of its panels' unshaded momentum deficits (owner question QF14).
  • Net/Disk and Net/Sphere can cast a lumped wake with CastWake (see Parameters).

Net/NetStructure

  • Each panel's load is one evaluation of the chosen law, shared equally between its three nodes. The water velocity is the waked current at the panel centroid (GetWakedCurrent, with the net's wake query) plus the wave particle velocity averaged over the panel's nodes (owner ruling R62), instead of the particle velocity.
  • The default solidity is 1/1.1 of the old one (−9.1 %): K = 1 instead of the implicit 1.1.
  • One panel at rest (t = 4 mm, L₀ = 50 mm, φ = 45°, old Sₙ 0.176, new 0.160), against the old model:
U, inflow angle old LocalThroughFlow K=1 TwineCrossFlow K=1 TwineCrossFlow K=1.1 ScreenMF2022 K=1
0.5 m/s, 0° 11.65 N +0.6 % −3.0 % +0.00 % −11.1 %
0.5 m/s, 45° 8.41 N −9.4 % −10.2 % −8.2 % −23.7 %
0.5 m/s, 80° 6.38 N −72.5 % −24.7 % −24.6 % −76.9 %
0.14 m/s, 0° 1.072 N +2.8 % −2.6 % +0.00 % −24.2 %
  • On the NetStructure_Regression fixture the default gives about 3 % more drag at the steady drift.
  • The large drops at 80° come from the screen laws' small load in the panel plane: they carry TwineCrossFlow's twine friction there (MARE-0111, resolved; −72.5 % at 80° with it), not the bars' cross-flow drag. The default law applies to trawl models as well (owner answer to Q17).

Net/NetStructureWithConstraints

  • The same law, solidity and water-velocity changes as Net/NetStructure. The panels still apply the hydrodynamic load and the weight in water only.
  • One panel at rest (20 × 20 meshes, t = 4 mm, L₀ = 50 mm, φ = 45°, 0.5 m/s), LocalThroughFlow (K = 1) against the old model: +0.6 % at 0°, −9.4 % at 45°, −72.5 % at 80°. A slack panel with bars at 0.8 L₀ gets −36 % at 0°, because the mesh-opening solidity uses the unstretched bar length while the load uses the deformed area (owner decision: MARE-0113, won't fix).

Removed: Net/NetStructureArray

Net/NetStructureArray is removed (owner decision 2026-09-30, MARE-0080). It was a variant of Net/NetStructure with its panel data in flat arrays and no seafloor contact, no binary net file and no wake casting, and it gave its cable elements no inertia (MARE-0080): a node that only cables touched had zero mass. Use Net/NetStructure, which reads the same net definition file:

  • SimObject="Net/NetStructureArray" becomes SimObject="Net/NetStructure";
  • NodeInputs and NodeOutputs become NodesInputForce and NodesOutputPosAndVel, and the ports follow the names on the Net structure object page;
  • the Array's fixed damping ratio of 10, its 20 kg of extra inertia on every node with a force input and its cable elements without inertia have no counterpart: the results change;
  • Net/NetStructure adds seafloor contact, CastWake and the other parameters of its page.

The C++ classes NetStructureArray and array_panel (NetStructureArray.h, FNetElement.h) are removed with it.

Net/Disk

The drag uses the normal and tangential projections of the relative velocity, each with its own speed (owner answer to Q2, MARE-0098). A face-on disk in a 1 m/s current along its axis now gets 481 N (it got 0); for an axis at 45° to a 1 m/s flow the force goes from (−99.67, 0, 0) N to (−170.32, −170.14, 0) N. Seabed friction uses |v|. The disks inside Net/NetStructure (DiskBase) are unchanged.

Result changes already in 3.2.1

These corrections shipped in 3.2.1 (2026-09-26), not in 4.0.0; a model coming from 3.2.0 gets them as well. The CHANGELOG's [3.2.1] "Fixed" section lists them, among them:

  • the solidity speed-up now scales the flow relative to the net, not the current (MARE-0083);
  • the twine Reynolds number is taken from the flow through the meshes (MARE-0085);
  • Net/Sphere gets added mass and uses the relative velocity (MARE-0086, MARE-0084);
  • Cable/LumpedMass and Cable/Branched no longer apply twice their weight in water (MARE-0082);
  • several TrawlCable, MooringCable, RundDorg and TrawlBeam corrections.

Keeping close to 3.x

HydroModel="TwineCrossFlow" with KnotFactor="1.1" reproduces the old panel force of Net/NetStructure and Net/NetStructureWithConstraints at normal incidence. It does not undo the other changes above: the water velocity at the centroid, the removed saturation, and the defect fixes.

Disabled tests and open owner items

SimObject.NetStructure_Regression and SimObject.Disk run again with baselines regenerated after the physics changes (Regression baselines: review of the 2026-09-27 regeneration (MARE-0099, WP-A12), owner review of branch review/A12-baselines, fhsim_marine_elements_issue_0099).

Tests committed DISABLED_ in this release:

Test Why Item
11 PanelLoadLaw_* data tests (L1, L2 and L4 against MF2022, L5 Rudi, L6 Løland, L8 Zhan, L9 consistency) The default law misses lift at high solidity and the angle dependence at 60–80°; nothing is tuned to pass them. Run with --gtest_also_run_disabled_tests --gtest_filter=PanelLoadLaw*. 0110 — Default load law misses lift at high solidity and the angle dependence of Rudi, Løland and Zhan (A6 disabled tests)
NetWakeCaster.DISABLED_GridAgreesWithDirectOnTheDefaultGrid, DISABLED_GridAgainstDirectRefinement, DISABLED_Timing Diagnostics: the default grid does not reach 0.01 agreement on a small net (Q12, MENV-0008); timing. MENV-0008 (resolved, Q12/R39), Net hydrodynamics: benchmark of load laws and wake evaluation
NetValidation_TowedPanel_VALIDATION.DISABLED_S1_L2_TextLiftAt1p75, DISABLED_S1_L8_AngleRatios, DISABLED_S1_L8_SpeedTrendAt30And60Deg The towed panel fails where its load-law tests fail. 0110 — Default load law misses lift at high solidity and the angle dependence of Rudi, Løland and Zhan (A6 disabled tests)
NetValidation_ZhanCylinder_VALIDATION.DISABLED_S2_DragRatioWithAndWithoutTheWake, DISABLED_W9_RearHalfFlowRatioInTheBand_s0128 The pinned wake kernel's near-wake deficit (Q8); S2 also the small in-plane load (twine friction only) and the default law's angle form. MENV-0007, MARE-0111 (resolved), 0110 — Default load law misses lift at high solidity and the angle dependence of Rudi, Løland and Zhan (A6 disabled tests)
NetValidation_LaderCage_VALIDATION.DISABLED_S3_DragSn019, DISABLED_S3_DragSn035, DISABLED_S3_DragSn043 Cage drag above KF2012 Fig. 14 beyond 20 %. 0110 — Default load law misses lift at high solidity and the angle dependence of Rudi, Løland and Zhan (A6 disabled tests)
NetValidation_ZhanCylinder_VALIDATION.DISABLED_S6_SundialsBdfDefaultLinearSolverStepsDoNotCollapseAtARebuild Sundials BDF with FhSim's default linear solver collapses its step at a rebuild; the S6 test itself runs on DENSE and is enabled. 0122 — Sundials BDF with the default linear solver collapses the step in any transient (wake blend, load ramp)

In marenv, the wake tests W2 and W10 (near wake against KF2012 Eq. 15, per-panel mesh dependence; owner questions Q8, Q9 and QF11) and W5 (grid truncation, Q12) are disabled. W1 (against MF2022 Eq. 11) is enabled since phase F as an implementation test: the panel sources' near wake is Eq. 11 itself (QF11).

Open owner items that affect results:

Closed by the owner: MARE-0113, the mesh-opening solidity keeps the unstretched bar length and twine diameter (won't fix); MARE-0109, the velocity ratio r of MF2022 Eq. 11 is clamped to 1 below Sₙ ≈ 0.0825 (flag bit 3); MARE-0130, ScreenMF2022 clamps Sₙ at 0.1005001, where the a3 fitted to Eq. 10 reaches ¼ so that C_D(θ) ≥ 0 at every θ (Q5, QG1), and says so in its setup warning; MARE-0117, Net/NetStructureWakeEffect is kept for 4.x and deprecated (Deprecated). Q1: MF2022 is the anchor dataset (ADR 0005, Accepted).

Fixed: fhsim_marine_elements_issue_0120 — a net file named by File is now looked up in the directory of the main input file (net_input::ResolveNetInputPath), as documented, for Net/NetStructure, Net/NetStructureWithConstraints, Net/NetStructureArray and Net/NetStructureWakeEffect; before, it was found only relative to the working directory. An input that worked around this with a path relative to playpen/bin must name the file relative to the input file. An absolute File path still fails, a bug in FhSim's InputReader outside this library.

Known limitations with a workaround: