|
FhSim
3.1.0
Marine systems simulation
|
|
|
FhSim
3.1.0
Marine systems simulation
|
Class containing a constrained net structure.
Collaboration diagram for Net structure with constraints:0121 — SimObject.NetStructureWithConstraints_SolverFrequency may be flaky
0321 — NetStructureWithConstraints_CablesThreadIndependent no longer runs anything in parallel
A net made of triangular net panels and cable elements, read from a net file (File), where a set of net nodes is driven by two chains of rigid elements instead of by their own states. The rigid elements are solved by the CoRiBo constraint solver (CoRiBoDynamics::ConstraintSolver with a JointConstraint).
NumConstraintsElements and integer division. Neighbouring elements in a chain are coupled end to end, at offsets \((0, 0, \pm l/2)\) in the element frame.ExternalTopConstraintsPos1/Vel1 (chain 1) and ExternalTopConstraintsPos2/Vel2 (chain 2) input ports.NodesInputPosAndVelFromConstraints. The Pos_/Vel_ states of those nodes are frozen: their derivatives are set to zero.NodesOutputForceToConstraints (the sum of panel and cable forces) is applied to rigid element \(i\) as a force. No moment is applied.The element length is \(l\) = ConstraintsCableDepth \(/ (N/2 - 1)\). Rigid element \(i\) takes the translational inertia \(m\) of the net node it drives, and the rotational inertia \(m(3d^2/4 + l^2)/12\) about its two transverse axes and \(m d^2/8\) about its axis. Here \(d\) is the twine diameter (BarD) of the first net panel. The coupling stiffness uses YoungsModulus, a shear modulus of YoungsModulus/2.6 and a cross-section of \(n_u/2\) twines of diameter \(d\), where \(n_u\) is the span of the first net panel in the u mesh coordinate, with second area moment \((n_u/2)\pi d^4/64\). The solver frequency is SolverFrequencyCoefficient. The constraint parameters \(\beta_N = \alpha_N = 90\) are hard-coded (meaning not determined from source: they are CoRiBo addRigidCoupling arguments).
The free nodes follow \(m \ddot{\vec x} = \vec F\), where \(\vec F\) is the sum of:
Rho. The panels apply no twine tension and no damping; before MARE-0095 NetElement3NWithConstraints computed both and discarded them.AddStructuralForces is commented out in NetCableElementWithConstraints::AddEndForces.The water velocity at each panel centroid and at each cable mid-point is the waked current there (GetWakedCurrent with the net's wake query; see Wake casting) plus the wave particle velocity averaged over the element's nodes (owner ruling R62), from the Environment shared resource through NetFlowInteraction, as for Net/NetStructure. The wave field is not linear in position, so this differs from the value at the centroid where a panel spans a noticeable part of a wave length. The SeafloorForces shared resource must exist, but it is not used: bottom forces and external node forces are disabled in OdeFcn.
The constructor reports an error unless NumConstraintsElements is even and \(\ge 4\), ConstraintsCableDepth > 0, NodesInputPosAndVelFromConstraints lists exactly NumConstraintsElements tags, NodesOutputForceToConstraints at least that many, and the net file contains at least one net panel. The defaults of NumConstraintsElements and ConstraintsCableDepth fail this check, so both must be set.
The panels take their hydrodynamic load as Net/NetStructure's panels do (MARE-0095): one evaluation of the panel load law chosen by HydroModel (fhsim_environment/hydrodynamics/PanelLoadLaw.h), by the shared panel core (src/net/NetElement3NForces.h), shared equally between the panel's three nodes. The law sees the panel's deformed area and normal, its twine diameter, its solidity by SolidityModel (fhsim_environment/hydrodynamics/NetSolidity.h), its bar directions and bar and knot data, and the water velocity relative to the panel, the mean of its node velocities, always as the free stream. The parameters are read, checked and warned about exactly as NetStructure does (src/net/NetPanelSetup.h); see the Net/NetStructure page and doc/user/net_hydrodynamics_methods.md.
For flow in the panel plane the screen laws (LocalThroughFlow, ScreenKF2012, ScreenMF2022) carry only TwineCrossFlow's twine friction (MARE-0111); only TwineCrossFlow also gives the bars' cross-flow drag. The MeshOpening solidity is computed from the unstretched bar length BarL, while the screen laws load the deformed panel area. The panels here carry no tension, so nothing holds their bars near BarL: at a given mesh opening angle, a panel whose bars are stretched by a factor s gets s² times the screen-law load it has at BarL, a slack panel (s < 1) less, whereas the twine area grows only with s (MARE-0095).
With CastWake the net casts its wake into the environment as Net/NetStructure does (MARE-0114; src/net/NetFlowInteraction.h, plan §B1, §B4, §B6, ADR 0002); the Net/NetStructure page describes the build, the schedules and the blending, and the parameters below are the same, with the same defaults. In FinalSetup the net registers its lumped field under its SimObject name and keeps its per-panel private field unregistered (ADR 0006); rebuilds run in PreOdeFcn only, so OdeFcn stays const and every stage of a step sees the same fields. Each source's momentum deficit comes from the panel load law, fluid and solidity that OdeFcn uses (NetElement3NWithConstraints::EvaluatePanelLoad). The node positions and velocities of the nodes driven by the rigid elements are the rigid elements' position and velocity states, as in OdeFcn; their own frozen Pos_/Vel_ states are never read. The source velocity u_s, the area-weighted mean of the filtered panel velocities, therefore follows the rigid elements. The cable elements cast no wake.
A panel's own inflow, and a cable element's, is GetWakedCurrent with the net's wake query plus the node-averaged waves (R62): the other objects' lumped wakes and the net's private field, which includes the wake of the panels upstream and never the panel's own; the net's own lumped field is skipped. Other SimObjects that query the flow see the lumped wake only.
No example uses this SimObject. The excerpt below is assembled from the parameters the constructor reads. A run version is tests/in/NetStructureWithConstraints/NetStructureWithConstraints_Smoke_in.xml.
| Name | Width | Description |
|---|---|---|
| ExternalTopConstraintsPos1 | 3 | Position of the top attachment point of rigid-element chain 1 in NED [m]. |
| ExternalTopConstraintsPos2 | 3 | Position of the top attachment point of rigid-element chain 2 in NED [m]. |
| ExternalTopConstraintsVel1 | 3 | Velocity of the top attachment point of chain 1 in NED [m/s]. |
| ExternalTopConstraintsVel2 | 3 | Velocity of the top attachment point of chain 2 in NED [m/s]. |
This SimObject registers no output ports. The member functions NodePos, NodeVel, NodeForce, BottomContact and outExternalNodeForce exist, but none of them is registered as a port.
| Name | Width | Description |
|---|---|---|
| File | 1 | Name of the XML net file (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 binary net file; relative to the directory of the main input file, or absolute (fhsim_marine_elements_issue_0360). The binary reader does not read any net panels, so a binary file is always reported as an error. |
| NetSpec | 1 | Name of an XML net specification instead of a net file. As for Net/NetStructure. |
| NodesInputPosAndVelFromConstraints | n | Tags from the net file's ExternalNodeMap. Entry \(i\) names the net node whose position and velocity are taken from rigid element \(i\). It also gives that element its translational inertia. |
| NodesOutputForceToConstraints | n | Tags from ExternalNodeMap. The net force on the node named by entry \(i\) is applied to rigid element \(i\). |
| NodesInputForce | n | Tags from ExternalNodeMap. Checked against the map but otherwise without effect: no input port is registered and the inertia added per node is 0 (Default: empty; with NetSpec the specification's Connect nodes). |
| NodesOutputPosAndVel | n | Tags from ExternalNodeMap. Checked against the map but otherwise without effect: no output port is registered (Default: empty; with NetSpec the specification's Connect and Output nodes). |
| NumConstraintsElements | 1 | Total number \(N\) of rigid elements in the two chains. Must be even and at least 4 (Default: 3, which is reported as an error). |
| ConstraintsCableDepth | 1 | Length of each rigid-element chain from its top attachment to the centre of its last element [m]. Must be > 0 (Default: 0, which is reported as an error). |
| YoungsModulus | 1 | Young's modulus used for the stiffness of the rigid-element couplings [Pa] (Default: 2e11). |
| SolverFrequencyCoefficient | 1 | Frequency coefficient of the constraint solver that joins the rigid elements [1/s], the RegulatorFrequencyCoefficient of TrawlCable. The couplings' own β and α stay fixed at 90. Must be > 0 (Default: 100). @addoption{NumCpuCore, 1, Number of threads in the constraint solver's core-bound thread pool\, one per CPU core, as NumCpuCore of TrawlCable. A value below 1 is a setup error\, a value above the number of hardware threads is reduced to it\, and 1 runs the solver on the calling thread. With more than one thread the results are not reproducible from run to run (MARE-0075). Before 3.0 the solver ran on a pool of hardware_concurrency() threads whatever was set\, which cost a small run seconds of system time (MARE-0317) (Default: 1). } |
| StartCpuCore | 1 | Index of the CPU core the first pool thread is bound to, the others take the next cores. A negative value is a setup error, and a pool that reaches past the last hardware thread logs a warning (Default: 0). |
| NumThreads | 1 | Threads of the net's panel and cable loops in OdeFcn (owner ruling R63, MARE-0310), as NumThreads of Net/NetStructure: 1 is the serial loop\; N > 1 splits the panels and the cables into N chunks summed into their own node-force buffers, 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. The constraint solver keeps its own threads (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 load, the panels' weight in water and their node inertia, and for the cable elements' weight in water, node inertia and drag (Default: 1025). |
| Nu | 1 | Kinematic viscosity of water [m²/s], for the panel load (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, CnKnots_nominal | 1 | TwineCrossFlow: its coefficients, as on the Net/NetStructure page (Defaults: 0.01, 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). |
| NetDampingRatio | 1 | Not read since MARE-0095. Before that it set a panel damping coefficient whose force was computed but not applied. |
| AddedDragPerMPS | 1 | Read but without effect: the value is overwritten by the net file reader, which sets it to 0. Meant as an added linear drag per unit speed, shared over the panels [N s/m] (Default: 0). |
| CastWake | 1 | Cast the net's wake into the environment; see Wake casting above. 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. The same reader (NetStructureSpec) is used by Net/NetStructure. 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.
| Name | Width | Description |
|---|---|---|
| MaxNumPanels | 1 | Limit on the panel count. Refinement continues while all three counts (panels, cable elements and nodes) are below their limits, or while the length factor of MaxElementLengthFactor is exceeded (Default: 100). |
| MaxNumCables | 1 | Limit on the cable-element count, as MaxNumPanels (Default: 100). |
| MaxNumNodes | 1 | Limit on the node count, as MaxNumPanels (Default: 100). |
| MinElementLength | 1 | Refinement stops when the edge chosen for division is shorter than twice this value. The value is in mesh-coordinate units (twine lengths) for panel edges and in m for cable elements (Default: 1). |
| MaxElementLengthFactor | 1 | Refinement continues even beyond the count limits while the largest edge length times RefineFactor exceeds this value (Default: 100). |
| MaxStepLength | 1 | Default for each cable element's MaxStep [s] (Default: 0.01). |
| MaxTension | 1 | Default for each cable element's MaxTension [N] (Default: 1e6). |
| MeanTension | 1 | Default for each cable element's MeanTension [N] (Default: 0). |
| MinLength | 1 | Default for each cable element's MinLength [m] (Default: 0.001). |
| StepSafetyFactor | 1 | Default for each cable element's StepSafetyFactor (Default: 50). |
| AdaptationPeriod | 1 | Default for each cable element's AdaptationPeriod [s] (Default: 0). |
| MassFactor | 1 | If greater than 1, every free node's acceleration is divided by this factor. This is the same as scaling its inertia up by the factor (Default: 1). |
| MaxVelocity | 1 | If positive, bounds each component of every node's position derivative to ±this value [m/s]. The velocity states themselves are not bounded (Default: 0). |
| Scale | 1 | Factor applied to the panel mesh coordinates and to each cable element's D and L (Default: 1). |
| FoldingPointRefinement | 1 | 1 selects folding-point refinement: each cable element is split by its NoOfFoldingPoints instead of the length-based refinement. This mode throws if any cable element has folding points while net panels exist, so it cannot be combined with folding points in this class (Default: 0). |
| TwineColour | 4 | Visualisation only. Default RGBA twine colour of the panels (Default: 1,1,1,1). |
The section is required. Each attribute maps a tag to a node number, for example PWing1 = "8". The Nodes... configuration parameters above select nodes by these tags. An unknown tag is an error.
The panel sections must be named El1, El2, ... in order.
| Name | Width | Description |
|---|---|---|
| Name | 1 | Panel name (Default: the section name). |
| Conn | 3 or 4 | Node numbers of the panel corners A, B, C (and D for a quadrilateral, which is split into two triangles). Required. |
| PosAMesh | 2 | Mesh coordinates (u, v) of corner A, in twine lengths (bars). The number of bars in a triangle is the determinant \(\lvert \Delta u_{AC}\Delta v_{AB} - \Delta u_{AB}\Delta v_{AC} \rvert\). Multiplied by Scale. Required. |
| PosBMesh | 2 | Mesh coordinates of corner B (as PosAMesh). Required. |
| PosCMesh | 2 | Mesh coordinates of corner C (as PosAMesh). Required. |
| PosDMesh | 2 | Mesh coordinates of corner D. Read only when Conn has 4 nodes. |
| BarD | 1 | Twine diameter [m]. The knot diameter is knotDiameterRatio × BarD (2 × BarD by default). Required, must be non-zero. |
| BarL | 1 | Unstretched bar (twine) length [m]. Required, must be non-zero. |
| BarE | 1 | Young's modulus of the twine [Pa]. The twine axial stiffness is BarE × πBarD²/4. Required, must be non-zero. |
| BarRho | 1 | Twine material density [kg/m³]. The node inertia uses (BarRho + Rho) and the vertical load uses (BarRho − Rho). Required, must be non-zero. |
| RefineFactor | 1 | Weight on this panel's longest edge when the refinement chooses the next edge to divide (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 only. RGBA twine colour of this panel (Default: the General TwineColour). |
The cable sections must be named El1, El2, ... in order. The CableElements section is required.
| Name | Width | Description |
|---|---|---|
| Conn | 2 | Node numbers of the two ends A and B. Required. |
| Name | 1 | Cable name (Default: Net_<id>_Cable_El<n>). |
| D | 1 | Cable diameter [m]. Multiplied by Scale. Required, must be > 0. |
| L | 1 | Unstretched length [m]. Multiplied by Scale. Also sets the element's mass and weight. Required, must be > 0. |
| E | 1 | Young's modulus [Pa]. Required and must be > 0, but it has no effect on the forces because the axial forces are disabled in this class. |
| Rho | 1 | Material density [kg/m³]. Mass is πD²/4 · L · (Rho + ρ_fluid). Weight in water is 9.81 · πD²/4 · L · (Rho − ρ_fluid). Required, must be > 0. |
| RefineFactor | 1 | Weight on this element's length when the refinement chooses the next edge to divide (Default: 1). |
| MaxTension | 1 | Tension limit of the dynamic-stiffness cable model [N]. No effect here: the axial forces are disabled (Default: General MaxTension). |
| MaxStep | 1 | Integration step the dynamic stiffness is tuned for [s]. No effect here: the axial forces are disabled (Default: General MaxStepLength). |
| MeanTension | 1 | Mean tension of the dynamic-stiffness model [N]. No effect here: the axial forces are disabled (Default: General MeanTension). |
| MinLength | 1 | Minimum element length [m]. Must be > 0. No effect here: the axial forces are disabled (Default: General MinLength). |
| StepSafetyFactor | 1 | Safety factor of the dynamic-stiffness model. Must be > 0. No effect here: the axial forces are disabled (Default: General StepSafetyFactor). |
| AdaptationPeriod | 1 | Non-zero enables the mean-tension update of the dynamic-stiffness model [s]. No effect here: the axial forces are disabled (Default: General AdaptationPeriod). |
| NoOfFoldingPoints | 1 | Number of extra nodes this element is split into when FoldingPointRefinement is 1. Ignored otherwise (Default: 0). |
| TangentialFrictionCoeff | 1 | Read but ignored: NetCableElementWithConstraints overwrites it with 0.03 (Default: 0.03). |
| NormalDragCoeff | 1 | Read but ignored: NetCableElementWithConstraints overwrites it with 1.2 (Default: 1.2). |
| Material | 1 | Visualisation only. Material name (Default: Trawl/Wire2). |
| DrawScale | 1 | Visualisation only. Scale on the drawn diameter (Default: 1). |
| NumFaces | 1 | Visualisation only. Number of faces of the drawn cable (Default: 5). |
| NumSpheres | 1 | Number of spheres attached to the element (Default: 0). |
| SphereD | NumSpheres | Sphere diameters [m]. They set the drag (coefficient 0.3) and the buoyancy. |
| SphereMass | NumSpheres | Sphere masses [kg]. Must be > 0. |
| SpherePos | NumSpheres | Sphere positions along the element, 0 to 1. Measured from end A: a sphere's mass, weight and drag go to end A with weight 1 − SpherePos and to end B with weight SpherePos, and the visualisation draws the sphere at A + SpherePos·(B − A). |
| SphereMesh | NumSpheres | Visualisation only. Mesh or material names of the spheres (optional). |
| NumDisks | 1 | Number of disks attached to the element. Required. |
| DiskD | NumDisks | Disk diameters [m]. They set the drag, the mass and the buoyancy. |
| DiskThickness | NumDisks | Disk thicknesses [m], 0 to 10. |
| DiskMass | NumDisks | Disk masses [kg]. Must be > 0. |
| DiskPos | NumDisks | Disk positions along the element, 0 to 1, measured from end A, with the same end-weighting as SpherePos. |
| DiskMesh | NumDisks | Visualisation only. Mesh or material names of the disks (optional). |
| AddedWeightInWater | 1 | Extra weight in water on the element, shared equally between its ends [N]. Required. |
The fluid density passed to each cable element is Rho when both ends are deeper than 1 m and 1 kg/m³ when both are shallower. It is interpolated linearly by depth for an element that crosses 1 m. The cable element then scales it by the fraction of the element below z = 0, and recomputes its weight from the result. The node inertia contributed by a cable element is computed once, at construction, with ρ_fluid = Rho.
| Name | Width | Description |
|---|---|---|
| Pos_1 ... Pos_<n> | 3 | Position of each net node after refinement in NED [m]. |
| Vel_1 ... Vel_<n> | 3 | Velocity of each net node in NED [m/s]. |
| position1 ... position<N> | 3 | Position of each rigid element in NED [m]. |
| orientation1 ... orientation<N> | 4 | Orientation quaternion of each rigid element (w, x, y, z order as passed to Ogre). |
| velocity1 ... velocity<N> | 3 | Velocity of each rigid element [m/s]. |
| angularvel1 ... angularvel<N> | 3 | Angular velocity of each rigid element [rad/s]. The frame is defined by the CoRiBo solver (not determined from source). |
The Pos_/Vel_ states of nodes driven by the rigid elements stay at their initial values. Their positions and velocities are taken from the rigid elements instead.
The Pos_ and Vel_ states default to 0,0,0 when the input file gives no value. This class suggests no initial value for the rigid-element states position, orientation, velocity and angularvel, so the input file must give them.
The test fixture tests/in/NetStructureWithConstraints/NetStructureWithConstraints_Smoke_in.xml, with the net definition file tests/in/NetStructure/SimplePanelNet.xml.
This SimObject is referred to as Net/NetStructureWithConstraints
1.9.8