Experimental bar-element net structure (Windows only)

Collaboration diagram for Experimental bar-element net structure (Windows only):

An experimental net made only of two-node bar ("cable") elements. Each node has a position and velocity state. Each element adds axial tension, internal damping, hydrodynamic drag and weight in water to its two end nodes. Spheres and disks can be attached to an element.

Author

Karl-Johan Reite

Review issues:

0031 — The Windows-only NetStructureTest family (NetStructureTest, NetStructureABAQUS, NetStructureConstrained) has no test coverage

0081 — NetCableElementTest still puts sphere and disk mass and weight on the wrong end and splits disk drag as −pos and 1 − pos (Windows only)

Warning

Windows builds only. The sources are compiled only when WIN32 is defined (src/net/CMakeLists.txt, TEST_STRUCTURE_SRC), and the type string Net/NetStructureTest is registered only under #ifdef WIN32 (src/fhsim_marine_elements.cpp). A Linux build has no such SimObject.

No automated tests. No test in tests/ builds or runs this class (see MARE-0031). This page was written from the source code. No simulation results were used to check it.

Units are SI: m, s, kg, N, Pa. The z axis points down. The code treats z as depth: a node with z < 0 is in air.

Example configuration excerpt

<Lib
   LibName              = "marine_elements"
   SimObject            = "Net/NetStructureTest"
   Name                 = "NET"
   XmlFile              = "NetStructureTestInput.xml"
   NodesInputForce      = "Top"
   NodesOutputPosAndVel = "Top,Bottom"
   LineVisualization    = "false"
   ColorBy              = "0"
/>

Note

The simulation must include an Environment (for example Environment from fhsim_environment). FinalSetup reports an error if there is none. The current is the environment's particle velocity at the first node (see Behaviour notes).

Input Ports

Name	Width	Description
<tag>Force	3	External force in N on the node mapped to <tag>. There is one port per tag listed in NodesInputForce. The force is added to that node's force sum.
colorLimits	2	Registered but never read. The only read is commented out in RenderUpdate.

Output Ports

Name	Width	Description
<tag>Force	3	Echo in N of the <tag>Force input port. There is one port per tag in NodesInputForce. It has the same name as the input port.
<tag>Pos	3	Position in m of the node mapped to <tag>. There is one port per tag in NodesOutputPosAndVel.
<tag>Vel	3	Velocity in m/s of the node mapped to <tag>. There is one port per tag in NodesOutputPosAndVel.
CurrentVelocity	3	The current in m/s used by the elements: the environment's particle velocity at the first node.
appendixForce	3	Sum in N over all elements of the hydrodynamic force on the attached spheres and disks. The per-end weighting by SpherePos/DiskPos is inconsistent (see the warning under the element table).
cableForce	3	Sum in N over the elements with E >= 1e10 Pa of the hydrodynamic drag on the element (f_drag_a + f_drag_b).
dragForce	3	Sum in N over the elements with E <= 1e10 Pa of the hydrodynamic drag on the element. The x and z components are multiplied by 2 and y is not. The reason for the factor is not given in the source.
meanProjectedVelocity	1	Mean over elements of the magnitude in m/s of the relative flow velocity normal to the element.
projectedArea	1	Sum over elements in m² of the element cross-section area (π D²/4) times the absolute cosine between the element and the current direction.
meanDragDeduction	1	Mean over elements of the drag-reduction factor (dimensionless). The drag on each element is scaled by the square of this factor. See Behaviour notes.

Configuration parameters

The net must be given by exactly one of BinaryFile, XmlFile or ABAQUSFile. The code checks them in that order and uses the first that is non-empty. If all three are empty the constructor reports an error.

Name	Width	Description
BinaryFile	1	Protobuf net file, relative to the input-file directory (Default: ""). Needs a build with USE_PROTOBUF. Otherwise it reports "Binary file support not available". Reading it also writes a test.data CSV to the working directory.
XmlFile	1	XML net file, relative to the input-file directory (Default: ""). See XmlFile format below. Note the name: sibling NetStructure classes use File, but this class does not read File.
ABAQUSFile	1	ABAQUS .inp net file, relative to the input-file directory (Default: ""). See NetStructureABAQUS for the format. This class reads only the geometry and material from it. Boundary conditions, loads and initial positions need NetStructureABAQUS. As written, the parser opens the directory and not the file, so nothing is read. See the warning on NetStructureABAQUS.
ModelMeshLength	1	Read only when ABAQUSFile is used, and required then (no default). Mesh length in m of the physical net. See NetStructureABAQUS.
NodesInputForce	n	Comma-separated tags of ExternalNodeMap entries that get a <tag>Force input port and output port (Default: none). A tag not in the map is an error.
NodesOutputPosAndVel	n	Comma-separated tags of ExternalNodeMap entries that get <tag>Pos and <tag>Vel output ports (Default: none). A tag not in the map is an error.
LineVisualization	1	Visualisation builds only (FH_VISUALIZATION). If true, the net is drawn as coloured lines and not as per-element objects (Default: false).
ColorBy	1	Visualisation builds only, and required there: it is read with no default in RenderInit. Its value is never used, because RenderUpdate overwrites it with int(T/10) % 2. With line visualisation the colouring therefore switches between strain (0) and drag (1) every 10 s.

XmlFile format

<Net>
   <ExternalNodeMap
      Top    = "0"
      Bottom = "5"
   />
   <NetElements/>
   <CableElements>
      <El1
         Conn              = "0,1"
         Name              = "Bar1"
         D                 = "0.002"
         L                 = "0.5"
         E                 = "1e9"
         Rho               = "1140"
         NoOfFoldingPoints = "0"
         NumSpheres        = "0"
         SphereD           = ""
         SphereMass        = ""
         SpherePos         = ""
         SphereMesh        = ""
         NumDisks          = "0"
         DiskD             = ""
         DiskThickness     = ""
         DiskMass          = ""
         DiskPos           = ""
         DiskMesh          = ""
      />
      <El2 ... />
   </CableElements>
</Net>

ExternalNodeMap is required. Each attribute maps a tag name to a 0-based node index.

NetElements is required. Its contents are never read: the variable that lists its child elements is overwritten by the CableElements listing. Twine elements are never created from the XML file.

CableElements is required. Its children must be named El1, El2, and so on, in order. Each child is one bar element with these attributes:

Name	Width	Description
Conn	2	0-based indices of end node A and end node B (required). The node count is the largest index plus 1. The per-end masses are assigned in the given order. The constructor then sorts Conn ascending. With a descending Conn the per-end mass therefore lands on one node and the per-end forces act on the other. This only matters when the ends differ, that is with spheres or disks.
Name	1	Element name. It is used only to name the Ogre scene nodes of attached spheres (Default: Net_<r>_Cable_El<k>, where r is a random integer and k is the element number).
D	1	Structural diameter in m (required). It sets the cross-section area A = π D²/4, so the axial stiffness E·A. It also sets the mass, the weight in water and the damping. The appendix-area correction subtracts it.
L	1	Unstretched element length in m (required).
E	1	Young's modulus in Pa (required). E·A·strain gives the tension. The elastic tension is clamped to [0, 1e12] N, so the elastic part takes no compression. The damping force is added after the clamp. E also sorts the element into the dragForce output (E <= 1e10) or the cableForce output (E >= 1e10).
Rho	1	Material density in kg/m³ (required). The node mass is (Rho + 1025)·A·L/2 per end, which includes added mass. The weight in water is 9.81·(Rho − 1025)·A·L. The damping coefficient is 2·A·sqrt(E·Rho).
NoOfFoldingPoints	1	Number of extra nodes to insert. The element is split into NoOfFoldingPoints + 1 equal parts (Default: 0).
Material	1	Visualisation builds only (Default: "Trawl/Wire2"). Read but never used.
DrawScale	1	Visualisation builds only (Default: 1.0). Read but never used.
NumFaces	1	Visualisation builds only (Default: 5). Read but never used.
NumSpheres	1	Number of spheres attached to the element (Default: 0).
SphereD	NumSpheres	Sphere diameters in m (no default). They must be in (0, 1000). The diameters set the drag and the buoyancy. The sphere drag is split between the ends as SpherePos says.
SphereMass	NumSpheres	Sphere masses in kg (no default). They must be in (0, 100000).
SpherePos	NumSpheres	Sphere positions as a fraction of the element length from end A (0) to end B (1) (no default). They must be in [0, 1].
SphereMesh	NumSpheres	Ogre material names for the spheres (no default). A short list is padded with its last entry. Only the visualisation uses them.
NumDisks	1	Number of disks attached to the element (required, no default).
DiskD	NumDisks	Disk diameters in m (no default). They must be in (0, 1000).
DiskThickness	NumDisks	Disk thicknesses in m (no default). They must be in [0, 10].
DiskMass	NumDisks	Disk masses in kg (no default). They must be in (0, 100000).
DiskPos	NumDisks	Disk positions as a fraction of the element length from end A (0) to end B (1) (no default). They must be in [0, 1].
DiskMesh	NumDisks	Disk material names (no default). Read but never used: disk rendering is commented out.

Warning

SpherePos and DiskPos are consistent only in the rendering and the sphere drag, which put an appendix at the fraction pos from end A towards end B:

• The sphere drag goes to end A with the weight 1 − pos and to end B with pos.
• The mass and the weight in water of an appendix are split with the fraction pos on end A and 1 − pos on end B. That is the opposite of the lever rule for the rendered position.
• Disk drag is weighted with (0 − pos) on end A and (1 − pos) on end B. The two terms have opposite signs.

"No default" means the code gives none: the InputReader reports an error when the attribute is missing. The list attributes must be present even when the count is 0. An empty list is accepted then.

BinaryFile reads the same element fields from the protobuf message fhsim::NetFile. It also reads general.foldingpointrefinement, but nothing uses that value.

Initial conditions

There is one state pair per computational node i = 0 … N−1. N includes the nodes that NoOfFoldingPoints inserts.

Name	Width	Description
Pos_<i>	3	Position of node i in m. For nodes on an element, a NaN entry is replaced by 0.
Vel_<i>	3	Velocity of node i in m/s. For nodes on an element, a NaN entry is replaced by 0.

Behaviour notes

• Uniform current. Every element sees the same current: the environment's particle velocity at the first node, taken once per evaluation by currentVelocity.
• Fixed coefficients. These values are fixed in the code: water density 1025 kg/m³; normal drag coefficient 1.15; tangential friction coefficient 0.01; damping ratio 1.0; disk normal/tangential coefficients 1.2/0.1; sphere drag coefficient 0.3. The element length is clamped to [1e-3, 1e4] m. The compression speed is clamped to [−100, 100] m/s.
• Air or water. The element's fluid density is 1025 kg/m³ when both nodes have z >= 0 and 1.0 kg/m³ when both have z < 0. When the element crosses z = 0 it is interpolated. Only the sphere and disk forces use this density. The element drag always uses 1025.
• Drag reduction. FinalSetup computes S, the largest (2l − d)·d/l² over all elements, where l = 2·L and d is the hydrodynamic diameter. The reduction factor is 1 − 0.5156·S − 0.8621·S². It is set on every element whose initial mid-point has x > 0. Other elements keep 1.
• Integrator. With the integrators Euler_i or Heun_i, the position derivative becomes v + ½·h·a. Here h is the step for Euler_i and half the step for Heun_i.

When the net comes from XmlFile or BinaryFile, the reader leaves the hydrodynamic diameter unset, and the element uses its structural diameter D. Only the ABAQUSFile path sets the hydrodynamic diameter.