Net structure with constraints

Class containing a constrained net structure.

Collaboration diagram for Net structure with constraints:

Author

Karl-Johan Reite

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).

• Chain 1 is rigid elements 0 to \(N/2-1\) and chain 2 is elements \(N/2\) to \(N-1\), with \(N\) = 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.
• The first element of each chain is coupled to an external point with a fixed identity orientation and zero angular velocity, whose position and velocity come from the ExternalTopConstraintsPos1/Vel1 (chain 1) and ExternalTopConstraintsPos2/Vel2 (chain 2) input ports.
• Rigid element \(i\) sets the position and velocity of the net node named by entry \(i\) of NodesInputPosAndVelFromConstraints. The Pos_/Vel_ states of those nodes are frozen: their derivatives are set to zero.
• The net force on the node named by entry \(i\) of 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:

• Net panel forces (NetElement3N, as in Net/NetStructure): the hydrodynamic load of the panel load law (see Panel hydrodynamics below), and a vertical term weight in water \(9.81 (\rho_{bar} - \rho) A_{bar} L_{bar} n_{bars}/3\) per node along NED z, with \(\rho\) = Rho. The panels apply no twine tension and no damping (NetPanelOptions::twineStructure is false, an adapter choice, owner ruling Q3d, 2026-10-14: the constraint solver holds the lengths).
• Cable element forces (NetCableElement, as in Net/NetStructure): weight and buoyancy, normal and tangential drag, and drag on attached spheres and disks (the disk drag formula is given on the Net/NetStructure page). The cable elements add no axial (tension and damping) force: NetCableOptions::structuralForce is false, an adapter choice (owner ruling Q3d, 2026-10-14), since the constraint solver holds the lengths.

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 net has no bottom contact (owner ruling Q3a, 2026-10-14): the nodes driven by the rigid elements are held by the chains, and the free nodes are not stopped by the seabed. Unlike Net/NetStructure it needs no SeafloorForces shared resource and has no BottomContact port. It takes no external node forces either.

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.

Panel hydrodynamics

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).

Wake casting

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 (NetElement3N::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.

Example configuration excerpt

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.

<Lib
   LibName                            = "marine_elements"
   SimObject                          = "Net/NetStructureWithConstraints"
   Name                               = "NET"
   File                               = "NetFile.xml"
   NodesInputPosAndVelFromConstraints = "C1,C2,C3,C4"
   NodesOutputForceToConstraints      = "C1,C2,C3,C4"
   NumConstraintsElements             = "4"
   ConstraintsCableDepth              = "5"
   YoungsModulus                      = "2e11"
   SolverFrequencyCoefficient         = "100"
/>

Input Ports

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].

Output Ports

This SimObject registers no output ports.

Configuration parameters

The parameters both nets share (the net file, the panel load law and solidity, the threads of the panel and cable loops, the wake), and the format of the net definition file, are on the page Net core: shared parameters and net file format, which also says where this net differs. The parameters below are this SimObject's own.

Name	Width	Description
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).
NetDampingRatio	1	Not read since MARE-0095. Before that it set a panel damping coefficient whose force was computed but not applied.

States

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.

Initial conditions

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.

Full example file

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