|
FhSim
3.1.0
Marine systems simulation
|
|
|
FhSim
3.1.0
Marine systems simulation
|
Net/NetStructure and Net/NetStructureWithConstraints share one net core (src/net/NetCore.h): the panels, the cable elements, their loads, the wakes and the net file. The parameters and the net file format on this page apply to both. Where a net differs, the row says so; the two differences that come from the constraint solver are owner rulings of 2026-10-14 (Q3): in Net/NetStructureWithConstraints the panels have no twine tension and no damping, the cable elements have no axial (tension and damping) force, and there is no seabed contact. Each SimObject's page lists the parameters and ports that are its own.
| Name | Width | Description |
|---|---|---|
| File | 1 | Name of the net definition file (XML, format below), looked up relative to the directory of the main input file, with the working directory as fallback. An absolute path is used as given with fhsim 3.3.2 or later (FHSIM-0038); older fhsim fails it. Exactly one of File, BinaryFile and NetSpec is required. |
| BinaryFile | 1 | Name of a protobuf net definition file (src/net/protobuf/net.proto), looked up relative to the directory of the main input file; an absolute path is used as given (fhsim_marine_elements_issue_0360). Needs a library built with _USE_PROTOBUF. The binary reader does not read net panels, so Net/NetStructureWithConstraints, which needs one, always reports an error; and it defaults a cable's TangentialFrictionCoeff to 0.01 where the XML reader uses 0.03. |
| NetSpec | 1 | Name of an XML net specification (doc/user/net-specification.md), the format fhsim_trawlwriter reads, instead of a net file: the net is meshed in process into the <Net> text fhsim_trawlwriter writes to a net file (%.4G rounding included) and read from it, so the run is the one with that file as File. Looked up as BinaryFile: an absolute path as given, a relative one in the directory of the main input file. The node lists default to the specification's Connect and Output; no file is written. Exactly one of File, BinaryFile and NetSpec is required (fhsim_marine_elements 5.0.0). |
| NumThreads | 1 | Threads of the net's panel and cable loops in OdeFcn (owner ruling R63, MARE-0212, MARE-0310). 1 is the serial loop. N > 1: the panels and the cables are split into N chunks by index, each summed into its own node-force buffer, and the buffers are added in chunk order, so a run is deterministic for a fixed N and differs from the serial one by rounding. 0 takes OpenMP's default (OMP_NUM_THREADS, else the number of cores). FhSim's NumCores spreads different SimObjects over threads, so keep NumThreads times the busy NumCores threads within the free cores: with more threads than free cores OpenMP's spin-waiting makes the run slower. Measured 2026-09-28 (WSL2, 32 cores shared with other jobs at a load of 10-17, RK45 1 ms): 1000 panels, 0.2 s: 0.65 s serial, 0.41 s on 2 threads, 0.37 s on 4, 0.64 s on 8; 10 000 panels, 0.4 s: about 8 s serial, 3-4 s on 2 and 4 threads, 9 s on 8. Net/NetStructureWithConstraints' constraint solver keeps its own threads (NumCpuCore, MARE-0317). Negative is a setup error (Default: 1). |
| HydroModel | 1 | Panel load law: LocalThroughFlow, ScreenKF2012, ScreenMF2022 or TwineCrossFlow. An unknown name is a setup error, and so is any law on a panel whose mesh coordinates are collinear, which has no bar directions (MARE-0139). ScreenMF2022 warns at setup for a solidity outside its fit range 0.18 to 0.36: each distinct Fixed value, or the smallest and largest MeshOpening value at the initial state (Default: LocalThroughFlow). |
| HydroA3 | 1 | LocalThroughFlow and ScreenKF2012: third drag harmonic a3 of KF2012 Eq. 14 (Default: 0.07 for LocalThroughFlow, 0 for ScreenKF2012). Above 0.25 is a setup error: the drag would turn negative at grazing angles, as on cage side panels at 75-90 deg or trawl panels along the tow (MARE-0137); so is below -0.125, where C_D is no longer largest at normal incidence, or a value that is not finite (MARE-0208). |
| HydroB4 | 1 | LocalThroughFlow and ScreenKF2012: fourth lift harmonic b4 of KF2012 Eq. 14 (Default: 0.10 for LocalThroughFlow, 0 for ScreenKF2012). b4 outside -0.5 to 0.5, or not finite, is a setup error: the lift would change sign near 0 or 90 deg (MARE-0137, MARE-0208). |
| HydroInduction | 1 | ScreenKF2012: apply the MF2022 induction factor (Default: false). |
| Rho | 1 | Water density [kg/m³], for the panel loads and the panels' weight in water and added mass (node inertia), and for the cable elements' weight in water, added mass and drag (Default: 1025). |
| Nu | 1 | Kinematic viscosity of water [m²/s], for the panel Reynolds number (Default: 1.19e-6). |
| SolidityModel | 1 | How the panel solidity is defined: MeshOpening, \(S_n = K t / (L_0 \sin\varphi \cos\varphi)\) with \(\varphi\) the mesh half opening angle of the deformed panel, so it follows the deformation; or Fixed, the net file's per-element Sn, else Solidity. An unknown name is a setup error (Default: MeshOpening). |
| Solidity | 1 | SolidityModel Fixed: the solidity of every panel without an Sn attribute [-]. A panel with neither, or a value outside (0, 1), is a setup error. A solidity above the load law's upper limit (0.5 for the screen laws) is clamped, and the clamp is logged once per run (Default: none). |
| KnotFactor | 1 | SolidityModel MeshOpening: the knot factor K, the ratio of the true solidity to the twine-only 2t/s. A K from MF2022 Table 2 converts as K = K_MF2022 (1 − t/(2s)). Must be positive (a non-positive K is a setup error) (Default: 1.0). |
| Ct_nominal | 1 | TwineCrossFlow: tangential drag coefficient of the bars, multiplied by π [-] (Default: 0.01). |
| CnKnots_nominal | 1 | TwineCrossFlow: drag coefficient of the knots [-]. Multiplied by the knot cross-section area \(\pi d_k^2/4\) (Default: 0.4). |
| knotDiameterRatio | 1 | Knot diameter as a multiple of the twine diameter BarD [-]. For TwineCrossFlow the knot diameter enters the knot drag and shortens the twine length that takes normal drag. For every law, on a panel with bar data, it also shortens the twine length of the in-plane twine friction (MARE-0111) (Default: 2). |
| CastWake | 1 | Cast the net's wake into the environment; see Wake casting on the Net/NetStructure page. The other wake parameters of a source set (Wake* with WakeEvaluation, WakeLength, WakeGrid and WakeXStartFactor, ExternalWakeUpdate) are listed in fhsim_environment's doc/user/wake-parameters.md. (Default: false) |
File names an XML file with a root element Net and the sections below (NetStructureSpec). The panels are split into triangles and the mesh is refined before the simulation starts. Node numbers are zero-based. The node count before refinement is the largest node number used plus one.
The refinement splits the element edge with the largest length factor (the edge length multiplied by the element's RefineFactor) in two, and repeats. It goes on while all of the node, panel and cable counts are below MaxNumNodes, MaxNumPanels and MaxNumCables, or while the largest length factor exceeds MaxElementLengthFactor. It always stops when the edge to split is shorter than 2 MinElementLength. Quadrangular panels are first split into two triangles. The cable parameters here are defaults for every cable element.
| Name | Width | Description |
|---|---|---|
| MaxNumPanels | 1 | Panel count limit for the refinement (Default: 100). |
| MaxNumCables | 1 | Cable element count limit for the refinement (Default: 100). |
| MaxNumNodes | 1 | Node count limit for the refinement (Default: 100). |
| MinElementLength | 1 | Refinement stops when the edge to split is shorter than twice this length: in mesh-coordinate units (twine lengths) for panel edges and in m for cable elements (Default: 1). |
| MaxElementLengthFactor | 1 | Refinement goes on past the count limits while an edge length times its RefineFactor exceeds this value (Default: 100). |
| MaxStepLength | 1 | Default MaxStep of the cable elements [s] (Default: 0.01). |
| MaxTension | 1 | Default MaxTension of the cable elements [N] (Default: 1e6). |
| MeanTension | 1 | Default MeanTension of the cable elements [N] (Default: 0). |
| MinLength | 1 | Default MinLength of the cable elements [m] (Default: 0.001). |
| StepSafetyFactor | 1 | Default StepSafetyFactor of the cable elements (Default: 50). |
| AdaptationPeriod | 1 | Default AdaptationPeriod of the cable elements [s] (Default: 0). |
| MassFactor | 1 | When above 1, the node accelerations are divided by this factor, to allow longer time steps (in Net/NetStructureWithConstraints those of the free nodes). Values of 1 or less have no effect (Default: 1). |
| MaxVelocity | 1 | When above 0, each component of each node's position derivative is limited to this value [m/s]; the velocity states themselves are not bounded. Net/NetStructure uses its analytical Jacobian only when MaxVelocity is 0, MassFactor is 1 or less, no cable element has spheres or disks and no node is in seafloor contact (NetStructure::HasJacobians) (Default: 0). |
| Scale | 1 | Scales the net: multiplies the panel mesh coordinates (PosAMesh...PosDMesh) and each cable element's D and L. BarD and BarL are not scaled (Default: 1). |
| FoldingPointRefinement | 1 | When nonzero, replaces the refinement above with folding-point refinement: each cable element is split into NoOfFoldingPoints + 1 equal parts and panels are not refined. The net fails at start-up if it has panels and a cable with folding points. When exactly 1, Net/NetStructure interpolates unset initial conditions of the new nodes along the original cable; Net/NetStructureWithConstraints sets them to 0 (Default: 0). |
| TwineColour | 4 | Visualisation builds only. Default RGBA colour of the panel twines (Default: "1,1,1,1"). |
The tag is required, and every attribute in it is read.
| Name | Width | Description |
|---|---|---|
| <tag> | 1 | Zero-based global node number that the tag names, for example PWing1 = "8". Several tags may name the same node. The node lists of the main input file (NodesInputForce, NodesOutputPosAndVel and Net/NetStructureWithConstraints' constraint lists) select nodes by these tags; an unknown tag is an error (Default: none). |
A panel is a triangle or a quadrangle in the net's mesh coordinates \((u\,v)\): the position of a corner counted in mesh bars along the two twine directions (Priour). The number of mesh bars in a triangle equals the mesh-coordinate determinant of its corners, \(\lvert \Delta u_{AC}\Delta v_{AB} - \Delta u_{AB}\Delta v_{AC} \rvert\). The sections are named El1, El2, ... in order.
| Name | Width | Description |
|---|---|---|
| Name | 1 | Name of the panel. Only checked to be non-empty (Default: "El\<n\>"). |
| Conn | 3 or 4 | Zero-based global node numbers of the corners A, B, C (and D, for a quadrangle, which is split into two triangles). Required. |
| PosAMesh | 2 | Mesh coordinates \((u,v)\) of corner A [mesh bars]. Multiplied by Scale. Required. |
| PosBMesh | 2 | Mesh coordinates of corner B [mesh bars]. Required. |
| PosCMesh | 2 | Mesh coordinates of corner C [mesh bars]. Required. |
| PosDMesh | 2 | Mesh coordinates of corner D [mesh bars]. Required when Conn has 4 nodes. |
| BarD | 1 | Twine diameter [m]. Sets the twine cross-section, the twine drag and the knot diameter (knotDiameterRatio × BarD). Required. |
| BarL | 1 | Unstretched mesh bar length [m]. Required. |
| BarE | 1 | Young's modulus of the twine [Pa]. The twine axial stiffness is BarE times the twine cross-section area. Net/NetStructureWithConstraints applies no twine tension, so it has no effect there. Required. |
| BarRho | 1 | Density of the twine material [kg/m³], for the panel mass (with Rho, the node inertia) and its weight in water. Required. |
| RefineFactor | 1 | Multiplies the panel's edge lengths in the refinement criterion. Larger values refine the panel more (Default: 1). |
| Sn | 1 | SolidityModel Fixed: the panel's solidity [-], overriding the Solidity parameter; the panels refined from it inherit it. Ignored by MeshOpening (Default: none). |
| TwineColour | 4 | Visualisation builds only. RGBA colour of the panel's twines (Default: the General tag's TwineColour). |
The cable elements use reduced ("dynamic") axial stiffness: the stiffness is scaled by \(\min(1\,\ 2\pi^2 L_0^2 (\rho + \rho_w) / (\Delta t_{max}^2 E))\)\, where \(\Delta t_{max}\) is MaxStep\, so that the element can be integrated with steps up to MaxStep. In Net/NetStructureWithConstraints the cable elements have no axial force (NetCableOptions::structuralForce), so E, MaxTension, MaxStep, MeanTension, MinLength, StepSafetyFactor and AdaptationPeriod are read and checked there but have no effect. The CableElements section is required; its sections are named El1, El2, ... in order.
| Name | Width | Description |
|---|---|---|
| Conn | 2 | Zero-based global node numbers of end A and end B. Required. |
| Name | 1 | Name of the cable element, used to name its visual objects. Must be non-empty (Default: "Net_\<id\>_Cable_El\<n\>"). |
| D | 1 | Diameter of the cable [m]. Multiplied by Scale. Required. |
| L | 1 | Unstretched length of the cable element [m]. Multiplied by Scale. Required. |
| E | 1 | Young's modulus of the cable [Pa]. Required. |
| Rho | 1 | Density of the cable material [kg/m³]. Required. |
| RefineFactor | 1 | Multiplies L in the refinement criterion (Default: 1). |
| MaxTension | 1 | Upper limit of the cable tension [N] (Default: the General tag's MaxTension). |
| MaxStep | 1 | Longest time step the reduced cable stiffness is chosen for [s]. Must be above 0 (Default: the General tag's MaxStepLength). |
| MeanTension | 1 | Tension [N] added in proportion to the stiffness reduction, as (1 - stiffness factor) * MeanTension; the start value of the filter when AdaptationPeriod is nonzero. Must be 0 or more (Default: the General tag's MeanTension). |
| MinLength | 1 | Lower limit of the unstretched length [m] when the element length is updated. Must be above 0 (Default: the General tag's MinLength). |
| StepSafetyFactor | 1 | Read and checked to be above 0, but not used by the stiffness calculation (Default: the General tag's StepSafetyFactor). |
| AdaptationPeriod | 1 | When nonzero, the mean tension starts at MeanTension and follows the element's tension with the time constant AdaptationPeriod [s], so that under a constant load it reaches the load and the strain that of the full stiffness; advanced once per integrator step, in PreOdeFcn from the step's start state, and held for every evaluation of the step (owner rulings R64, MARE-0358). The difference it follows is bounded at a tenth of MaxTension. Must be 0 or more (Default: the General tag's AdaptationPeriod). |
| NoOfFoldingPoints | 1 | Number of folding points. With FoldingPointRefinement the element is split into this many plus one equal parts; otherwise not used (Default: 0). |
| TangentialFrictionCoeff | 1 | Tangential (skin friction) drag coefficient of the cable [-] (Default: 0.03). |
| NormalDragCoeff | 1 | Normal drag coefficient of the cable [-] (Default: 1.2). |
| Material | 1 | Visualisation builds only. Material name for drawing the cable (Default: "Trawl/Wire2"). |
| DrawScale | 1 | Visualisation builds only. Drawn diameter as a multiple of D (Default: 1.0). |
| NumFaces | 1 | Visualisation builds only. Number of faces around the drawn cable (Default: 5). |
| NumSpheres | 1 | Number of spheres attached to the element (Default: 0). |
| SphereD | NumSpheres | Diameter of each sphere [m]. Adds drag (coefficient 0.3), mass and buoyancy. Required, empty when NumSpheres is 0. |
| SphereMass | NumSpheres | Mass of each sphere [kg]. Required, empty when NumSpheres is 0. |
| SpherePos | NumSpheres | Position of each sphere along the element, from 0 to 1. It is measured from end A: end A carries the fraction 1 − SpherePos of the sphere's mass, weight and drag and end B the fraction SpherePos, and the sphere is drawn at that point. Required, empty when NumSpheres is 0. |
| SphereMesh | NumSpheres | Visualisation builds only. Net/NetStructure: the material name for drawing each sphere (the mesh is always fhSphere.mesh); a short list repeats its last entry. Net/NetStructureWithConstraints draws its spheres with the default material. Required, may be empty. |
| NumDisks | 1 | Number of disks attached to the element, oriented normal to the cable. Required. |
| DiskD | NumDisks | Diameter of each disk [m]. Required, empty when NumDisks is 0. |
| DiskThickness | NumDisks | Thickness of each disk [m], 0 to 10. Required, empty when NumDisks is 0. |
| DiskMass | NumDisks | Mass of each disk [kg]. Required, empty when NumDisks is 0. |
| DiskPos | NumDisks | Position of each disk along the element, from 0 to 1, measured from end A as for SpherePos. Required, empty when NumDisks is 0. |
| DiskMesh | NumDisks | Visualisation builds only. Material name for drawing each disk (the mesh is always fhDisk.mesh). A short list repeats its last entry; an empty list gives Net/NetStructure the material "fhDisk.mesh" and Net/NetStructureWithConstraints none. Required, may be empty. |
| AddedWeightInWater | 1 | Extra weight in water of the element [N], split equally between the ends. It also adds AddedWeightInWater / 9.81 to the node mass. Required. |
Each disk adds mass\, weight in water and drag\, split between the ends as DiskPos says. With \(v_t\) and \(v_n\) the parts of the element's mean velocity relative to the water along and across the element\, \(D\) and \(T\) the disk diameter and thickness and \(d\) the element diameter\, the drag is form drag on the parts of the disk outside the element: \(-\frac{1}{2}\rho C_n \frac{\pi}{4}(D^2 - d^2) |v_t| v_t\) on the annulus (face-on) plus \(-\frac{1}{2}\rho C_n (D - d) T |v_n| v_n\) on the edge (edge-on)\, both with \(C_n\) = 1.2\, in NetCableElement::AddHydroForcesAppendices.
1.9.8