|
FhSim
3.1.0
Marine systems simulation
|
|
|
FhSim
3.1.0
Marine systems simulation
|
This page is the migration note for fhsim_marine_elements 3.0.0, the net-hydrodynamics release. It says what an input or a downstream build written for 2.0.0 (or for the development tags 3.1.0 to 3.2.1, here called 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.
[>=3.0.0 <4]), 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 3.0 and 2.0 changelogs: EnvironmentProvider::GetWakeRatio is now GetWakeDeficit, and WakeField::Sample returns a deficit and a source velocity.TestNetcageWake's MaxWakeFactor and WakeFactorCutoff are now MaxDeficit and DeficitCutoff, and VisualFlowPlane's ComputeFunction="WakeFactor" is now "WakeDeficit".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:
ScreenElement3N, ScreenElementDef and ScreenStructureSpec;NetStructureOCL, NetPanelForcesOcl and netpanelforces.c, which was never compiled;FNetElementFloat;netconstants namespace in FNetElement.h.A downstream build that includes one of these headers no longer compiles. Net/NetStructureWakeEffect and NetElement3NWakeEffect were kept in 3.0 but deprecated, and are removed after 3.0.1 (see Deprecated, then removed).
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;kSaturationVel, and hydroForcesRatio in Net/NetStructure) in Net/NetStructure;TwineCrossFlow: the screen laws include the knots through the solidity;Net/NetStructureWithConstraints computed and discarded.Net/NetStructureWakeEffect and its panel class NetElement3NWakeEffect were deprecated in 3.0 (MARE-0117) and kept for fhsim_aquaculture's Netcage/NetCageWakeEffect. They are removed after 3.0.1 (owner ruling 2026-10-12), with their registration, tests and setup warning. An input that uses Net/NetStructureWakeEffect no longer loads, and a downstream class that derives from either class no longer compiles.
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.
fhsim_aquaculture 2.0.0 pins fhsim_marine_elements ~2.0.0 (and fhsim_environment ~2.0.0, base ~3.0, coribo ~2.8, fhsim_conan/1.2) and does not build on this release without a port (MARE-0163). What the port must change:
net/CNetStructure.h, CNetStructureWakeEffect, CNetElement3NWakeEffect, and Hungarian members such as dMassFactor.MaxAcceleration** (MARE-0133, Parameters). CNetCageWakeEffect, CNetCageScreen, CMembraneStructure, CMembraneCage and CNetCage read m_SAdaptations.dMaxAcceleration, which no longer exists. The limit is not reinstated: a cage input that sets MaxAcceleration runs without it, and its results change wherever the limit acted. Owner ruling 2026-10-13: such an input must warn that the value is ignored, never be ignored silently. A net file read through NetStructureSpec (<General MaxAcceleration=...>) already does, with "Warning: the attribute
MaxAcceleration=... in <file> is ignored; it was removed in 3.0 (MARE-0133)." (MARE-0165, pinned by SimObject.NetStructure_MaxAccelerationRemoved). A file the port reads itself must call removed_attributes::WarnIfPresent (RemovedAttributes.h) on every element that carried the attribute, and a SimObject parameter MaxAcceleration must be checked for and warned about through ISimObjectCreator::LogInfo in the same words.NetCageWakeEffect.** Its bases Net/NetStructureWakeEffect and NetElement3NWakeEffect are removed (Deprecated, then removed). The port replaces it, for example by Net/NetStructure with CastWake, or carries its own copy of the two classes; its OdeFcn used the base's protected members and the panel's wake methods.GetParticleVelocity, GetCurrentVelocity) is already waked by every registered lumped source (Wakes: other objects see lumped sources). The cage's own internal wake polynomials then stack on any environment wake object placed for the same cage: use one or the other.kRhoWater = 1025 is fixed in four aquaculture files (fhsim_base BASE-0054).CNetCage overrides CalcStateDerivatives, AddNetForces, AddCableForces and AddNodeBottomForce without const; the bases are const since 3.0, so those signatures hide the base functions instead of overriding them, silently. Mark every override override. The NetElement3N constructor and AddNodeForces changed (C++ API (installed headers)); CNetCageScreen's Screen bases are removed (Removed).The port is a work package of its own, with its own baselines.
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.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.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).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).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 3.0.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 3.0.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.
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.
Only models with CastWake="true" are affected (ADR 0006; methods manual § 14. The wake a net or a body casts):
VisualFieldPlane (formerly VisualFlowPlane) shows the lumped wakes only.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).Net/Disk and Net/Sphere can cast a lumped wake with CastWake (see Parameters).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.| 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 % |
NetStructure_Regression fixture the default gives about 3 % more drag at the steady drift.Net/NetStructure. The panels still apply the hydrodynamic load and the weight in water only.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).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;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.
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.
These corrections came with the development tag 3.2.1 (2026-09-26), not with the load laws; a model coming from 2.0.0 or 3.2.0 gets them as well. The CHANGELOG's [3.0.0] "Fixed" section lists them, among them:
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);TrawlCable, MooringCable, RundDorg and TrawlBeam corrections.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.
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*. | fhsim_marine_elements_issue_0110 |
Three NetWake diagnostics (removed 2026-10-22; facts in Removed tests) | 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 |
| The three S1 towed-panel twins of the load-law tests (removed 2026-10-22; facts in Validation: towed panel through the SimObject (S1)) | The towed panel fails where its load-law tests fail. | fhsim_marine_elements_issue_0110 |
| The Zhan cylinder S2 drag ratio and W9 for s 0.128 (removed 2026-10-22; facts in Validation: Zhan 2006 cylinder (S2, W9, S6)) | 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), fhsim_marine_elements_issue_0110 |
| The three Lader cage S3 drag tests (removed 2026-10-22; facts in Validation: Lader 2009 cages (S3, S4)) | Cage drag above KF2012 Fig. 14 beyond 20 %. | fhsim_marine_elements_issue_0110 |
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. | fhsim_marine_elements_issue_0122 |
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:
WakeGrid 96 × 48 × 48 and WakeCutoff 1e-3; the phase F re-benchmark is in Net hydrodynamics: benchmark of load laws and wake evaluation § 11; superseded by owner decision R48, MARE-0302: when not given, both are now sized from the panels, and both stay user-settable), QF12 (a casting body's force uses its state velocity, the lumped wake the filtered source velocity; they agree in steady motion: kept and documented), QF13 (W9 measures a net's internal wake at caster level on the private field, MARE-0132) and QF14 (the lumped M is the felt drag, not the panel sum: kept).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 was kept in 3.0 and deprecated, and is removed after 3.0.1 (Deprecated, then removed). 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:
CastWake off at WakePeriod 1 s and 0 at 0.05 s, so use Periodic with a short WakePeriod.<LinearSolver Type="DENSE"/> and <Jacobian Type="dense"/>. 
1.9.8