Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,12 @@ All notable changes to CableDyn are recorded in this file. The format follows
finite-EI cables alike (within 1 % of each other). Exact Jacobians; the phase is in the
step-recovery, snapshot and checkpoint state; the Python deck reader and builder take the
section.
- Load power channels `VIVPow<L>`, `DragPow<L>` and `DampPow<L>` [W], and `<name><L>N<J>` per
unit length about a node [W/m]: the power the VIV loads, the drag and the structural damping
(`BA`, `Bb`) deliver to a line at the committed state, on `EI = 0` lines and finite-EI cables,
standalone and coupled. Their work closes a cable's energy balance to 0.04 % in free decays
and VIV runs, and on the locked-in line of `examples/viv_taut_cable_inline.dat` their means
balance within 0.5 % of the VIV power.

## [0.4.2] - 2026-11-09

Expand Down
10 changes: 10 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1326,6 +1326,16 @@ target_link_libraries(test_hermite_viv_inline PRIVATE cabledyn_core)
add_test(NAME hermite_viv_inline COMMAND test_hermite_viv_inline)
set_tests_properties(hermite_viv_inline PROPERTIES LABELS "fortran;dynamic;viv")

add_executable(test_hermite_load_power tests/test_hermite_load_power.f90)
target_link_libraries(test_hermite_load_power PRIVATE cabledyn_core)
add_test(NAME hermite_load_power COMMAND test_hermite_load_power)
set_tests_properties(hermite_load_power PROPERTIES LABELS "fortran;dynamic;viv")

add_executable(test_load_power_deck tests/test_load_power_deck.f90)
target_link_libraries(test_load_power_deck PRIVATE cabledyn_core)
add_test(NAME load_power_deck COMMAND test_load_power_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(load_power_deck PROPERTIES LABELS "fortran;integration;dynamic;viv;driver")

add_executable(test_viv_inline_deck tests/test_viv_inline_deck.f90)
target_link_libraries(test_viv_inline_deck PRIVATE cabledyn_core)
add_test(NAME viv_inline_deck COMMAND test_viv_inline_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
Expand Down
5 changes: 5 additions & 0 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,11 @@ Loads and environment
- Standalone only
- a 6-DOF vessel record, or the RAO response to the deck waves, moves every
``Coupled``/``Vessel`` point of a line deck; see :doc:`options`
* - Load power channels (``VIVPow``, ``DragPow``, ``DampPow``)
- Standalone and coupled
- the power of the VIV loads, the drag and the structural damping on a line, in total and per
unit length about a node, at every output time: the energy ledger of a VIV response; see
:doc:`outputs`
* - Range graphs (``r`` line output flag, ``RangeStart``)
- Standalone and OpenFAST
- minimum, maximum, and mean along each line over the run, from the committed steps; a run
Expand Down
4 changes: 4 additions & 0 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -1651,6 +1651,10 @@ bending moment. None of these channels is mandatory.
| `Torq<L>N<J>` | line L torque at node J (uniform along the line in statics); positive for a right-handed twist of End B relative to End A about the End A → End B tangent. Only on a line solved in torsion (restrained at both ends, or at one end with the other free) | N·m |
| `Twist<L>N<J>` | line L material twist accumulated from End A to node J, `M × Σ L/GJ` (less `(K/GJ)(l − L)` under coupling) over the elements in between; 0 at End A, without the end-spring windup. Only on a line solved in torsion | deg |
| `Twist<L>` | line L total twist `Phi − Theta = M C`, end-spring windup included; on a line free at one end the twist of its elements, the free end's turn. Only on a line solved in torsion | deg |
| `VIVPow<L>` | line L power of the VIV loads (cross-flow lift, and the in-line force of a `VIV` section row) at the committed state, positive into the line ([Outputs](outputs.rst)); 0 in static runs | W |
| `DragPow<L>` | line L power of the Morison drag (and, on a finite-EI line, its ATTACHMENTS' drag) | W |
| `DampPow<L>` | line L power of the structural damping (`BA`, and `EI|Bb` on a finite-EI line); never positive | W |
| `VIVPow<L>N<J>`, `DragPow<L>N<J>`, `DampPow<L>N<J>` | the same per unit unstretched length about node J (node J's share: half of each of its elements' power and its own node loads', over half their unstretched length) | W/m |

- `<L>`/`<P>` are deck LINE/POINT **ids**, not array positions. A channel that matches no
supported form, names an unknown id, or carries trailing text (for example `Point2px_raw`) is a
Expand Down
54 changes: 54 additions & 0 deletions doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -864,6 +864,60 @@ lowest value differs from the converged one by 0.6 m. Elements no longer than ab
:math:`\sqrt{EI/T}` at touchdown keep the node tension there within about 1.5 % of the
converged value through the motion, and a tenth within 0.5 %.

Load power channels
~~~~~~~~~~~~~~~~~~~

The power three loads deliver to a line at every output time, for an energy ledger of its
motion: the work the VIV loads put in against what the drag and the structural damping take out,
along the line and over the run. Each is the load times the velocity it acts through at the
committed state, positive when the load puts energy into the line:

.. list-table::
:header-rows: 1
:widths: 24 56 20

* - Channel
- Meaning
- Unit
* - ``VIVPow<L>``
- power of the VIV loads on line ``L``: the cross-flow lift (:ref:`theory-viv`) and, on a
type with a ``VIV`` section row, the in-line force (:ref:`theory-viv-inline`); zero on a
line without VIV
- W
* - ``DragPow<L>``
- power of the Morison drag on the line (current, waves and a host's fluid field) and, on a
finite-EI line, of its ATTACHMENTS' drag; zero without drag
- W
* - ``DampPow<L>``
- power of the structural damping: the axial dashpot ``BA`` and, on a finite-EI line, the
bending dashpot (``EI|Bb``); never positive
- W
* - ``VIVPow<L>N<J>``, ``DragPow<L>N<J>``, ``DampPow<L>N<J>``
- the same per unit unstretched length about node ``J``
- W/m

The power of a load on an element is :math:`\mathbf{f}_e\cdot\dot{\mathbf{q}}_e`, its nodal
(finite-EI: generalised) load on the element's degrees of freedom times their velocities, which
is the exact rate of work of the load the solver applies; a node load (the lift of an
``EI = 0`` line, an attachment's drag) delivers :math:`\mathbf{f}\cdot\mathbf{v}` at its node.
A node takes half the power of each of its elements and the power of its own node loads, so the
line total ``<name><L>`` is the sum over its nodes, and ``<name><L>N<J>`` is node ``J``'s share
over half the unstretched length of its elements (W per metre of unstretched line; on a refined
line, at the deck node's node of the final mesh). An element's damping power is never positive,
so neither is a node's.

The three are the non-conservative loads of a VIV study, not all of them: the work of the end
supports and points, the seabed contact, damping and friction, the added mass and Froude-Krylov
loads, a body's or point's own drag, the torsional damping ``Bt`` and the internal damping of the
viscoelastic and Syrope laws is not in them. Where those do no net work, the energy the line holds
only oscillates in a steady response, so the means balance:
:math:`\overline{P}_\text{VIV} + \overline{P}_\text{drag} + \overline{P}_\text{damp} \approx 0`.
On the locked-in taut line of ``viv_taut_cable_inline.dat`` (pinned ends, steady current) the VIV
loads put in 8.52 W over 60-90 s, the drag takes out 8.56 W and the axial damping 0.002 W: the
three balance within 0.5 % of the VIV power, the line's loss of energy over the window as its
response settles, and as an ``EI = 0`` line the same. Integrating a channel over the output times gives the work of its
load, :math:`W = \int P\,dt`; a static run reports 0.

Point channels
~~~~~~~~~~~~~~

Expand Down
7 changes: 6 additions & 1 deletion examples/viv_taut_cable_inline.dat
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ CableDyn driver deck -- cross-flow and in-line VIV of a taut cable in a uniform
-- about twice the cross-flow one. Over 60-90 s the quarter span (L1N13py) moves in line at A/D
-- 0.19, at twice the 0.29 Hz cross-flow frequency of the mid span (L1N26pz, A/D 0.82); with the
-- cross-flow lift alone (drop the VIV section) they are 0.03 and 0.66. The Outputs flag V writes
-- the VIV force, lift and in-line, at every node to <root>.Line1.V.out.
-- the VIV force, lift and in-line, at every node to <root>.Line1.V.out. VIVPow1, DragPow1 and
-- DampPow1 are the power the VIV loads, the drag and the axial damping deliver to the line: over
-- 60-90 s the VIV loads put in 8.52 W and the drag and damping take out 8.56 W.
--------------------- LINE TYPES ---------------------------------------
TypeName Diam MassDenInAir EA BA/-zeta EI Cd_n Cd_t Ca_n Ca_t Cl dF cF
(-) (m) (kg/m) (N) (N-s/-) (N-m^2) (-) (-) (-) (-) (-) (-) (-)
Expand Down Expand Up @@ -57,4 +59,7 @@ none frictionMu - Seabed friction coefficient {none; value>=0} [defau
"FairTen1"
"L1N26pz"
"L1N13py"
"VIVPow1"
"DragPow1"
"DampPow1"
--------------------- need this line -----------------------------------
1 change: 1 addition & 0 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@
re.compile(r"(ten|curvx|curvy|curv|bendmom|stfmom|torq)([0-9]+)(n[0-9]+)", re.IGNORECASE),
),
("line", re.compile(r"(twist)([0-9]+)(n[0-9]+|)", re.IGNORECASE)),
("line", re.compile(r"(vivpow|dragpow|damppow)([0-9]+)(n[0-9]+|)", re.IGNORECASE)),
("line", re.compile(r"(l)([0-9]+)(n[0-9]+(?:[pva][xyz]|dec|azi))", re.IGNORECASE)),
("point", re.compile(r"(point|con)([0-9]+)(p[xyz])", re.IGNORECASE)),
("point", re.compile(r"(point)([0-9]+)(f[xyzh])", re.IGNORECASE)),
Expand Down
42 changes: 41 additions & 1 deletion python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -740,6 +740,20 @@ def _parse_line_node_channel(lowered: str) -> tuple[int, int, int, int]:
# Twist<L>: the line's total twist (node 1)
line_id = _native_positive_int(lowered, 6, last)
return (line_id, 1, 11, 0) if line_id > 0 else (line_id, 0, 0, 0)
for keyword, code in (("vivpow", 15), ("dragpow", 17), ("damppow", 19)):
if not lowered.startswith(keyword):
continue
# the load power channels: <name><L> the line total (node 1), <name><L>N<J> per length
prefix = len(keyword)
if last > prefix and "n" not in lowered[prefix:]:
line_id = _native_positive_int(lowered, prefix + 1, last)
return (line_id, 1, code, 0) if line_id > 0 else (line_id, 0, 0, 0)
separator = lowered.find("n", prefix)
if last <= prefix or separator < 0:
return 0, 0, 0, 0
line_id = _native_positive_int(lowered, prefix + 1, separator)
node_id = _native_positive_int(lowered, separator + 2, last)
return line_id, node_id, code + 1 if line_id > 0 and node_id > 0 else 0, 0
for keyword, code in (
("torq", 9),
("twist", 10),
Expand Down Expand Up @@ -822,7 +836,9 @@ def _channel_identity_key(channel: str) -> str:
if touchdown is not None and int(touchdown.group(1)) > 0:
component = ("s", "x", "y", "z", "lay", "exc", "grd").index(touchdown.group(2)) + 1
return f"tdp:{int(touchdown.group(1))}:{component}"
if lowered.startswith(("ten", "curv", "bendmom", "stfmom", "l", "torq", "twist")):
if lowered.startswith(
("ten", "curv", "bendmom", "stfmom", "l", "torq", "twist", "vivpow", "dragpow", "damppow")
):
line_id, node_id, kind, component = _parse_line_node_channel(lowered)
if line_id > 0 and node_id > 0 and kind > 0:
return f"node:{line_id}:{node_id}:{kind}:{component}"
Expand Down Expand Up @@ -5407,6 +5423,30 @@ def is_body_kind(kind: str, pinned: bool) -> bool:
"restrained (END CONNECTIONS TorsStiffness), so it carries no torque"
)
continue
if lowered.startswith(("vivpow", "dragpow", "damppow")):
# native: VIVPow/DragPow/DampPow<L> and <L>N<J>, the load power channels
line_number, node_id, kind, _ = _parse_line_node_channel(lowered)
line_id = str(line_number)
if (
node_id == 0
and line_id in line_ids
and re.search(r"[0-9]n0(?![0-9])", lowered) is not None
):
raise DeckFormatError(
f"{self._label}: OUTPUT {channel!r}: node numbers start at 1 = End A "
"(MoorDyn numbers from N0)"
)
if line_id not in line_ids or kind == 0 or node_id < 1:
raise DeckFormatError(
f"{self._label}: OUTPUT {channel!r}: bad load power channel (use "
"VIVPow<L>, DragPow<L>, DampPow<L>, or <name><L>N<J> per unit length, "
"with a known line id)"
)
if node_id > line_nelems[line_id] + 1:
raise DeckFormatError(
f"{self._label}: OUTPUT {channel!r} node exceeds the line node count"
)
continue
if lowered.startswith(("ten", "curv", "bendmom", "stfmom", "l")):
# native parse_line_node_channel: Ten/Curv/BendMom/StfMom<L>N<J>, L<L>N<J>...
line_number, node_id, kind, _ = _parse_line_node_channel(lowered)
Expand Down
13 changes: 12 additions & 1 deletion python/tests/test_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,16 @@ def test_edit_fields_in_place_and_revalidate() -> None:
def test_rename_propagates_to_rows_and_output_channels() -> None:
model = _chain_model()
model.outputs.add(
"Ten1N3", "L1N2px", "TDP1s", "TDP1Grd", "AnchFz1", "AnchFH1", "Point2FH", "Con1py"
"Ten1N3",
"L1N2px",
"TDP1s",
"TDP1Grd",
"AnchFz1",
"AnchFH1",
"Point2FH",
"Con1py",
"VIVPow1",
"DampPow1N3",
)
model.rename(model.lines[1], 7)
model.rename(model.points[1], 11)
Expand All @@ -284,6 +293,8 @@ def test_rename_propagates_to_rows_and_output_channels() -> None:
"AnchFH7",
"Point2FH",
"Con11py",
"VIVPow7",
"DampPow7N3",
]
deck = model.to_deck_file()
assert deck.lines[0].tokens == ("7", "11", "2", "-")
Expand Down
2 changes: 2 additions & 0 deletions python/tests/test_deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -3862,6 +3862,8 @@ def unqueryable(first, second):
("TDP1Grd", "tdp01GRD"),
("AnchFz1", "anchfz01"),
("AnchFH1", "ANCHFH1"),
("VIVPow1", "vivpow01"),
("DragPow1N3", "dragpow01n03"),
],
)
def test_duplicate_output_channels_fail_like_native(first, second):
Expand Down
23 changes: 23 additions & 0 deletions python/tests/test_deck_native_parity.py
Original file line number Diff line number Diff line change
Expand Up @@ -1025,6 +1025,29 @@ def test_inline_viv_acts_on_an_ei0_line(row):
DeckFile.from_text(_section(_example("viv_taut_line_crossflow.dat"), "VIV", row))


@pytest.mark.parametrize(
("channel", "message"),
[
("VIVPow1", None),
("DragPow1", None),
("DampPow1", None),
("vivpow01n26", None),
("DampPow1N51", None),
("VIVPow0", "bad load power channel"),
("DragPow7", "bad load power channel"),
("DampPowx", "bad load power channel"),
("VIVPow1N0", "node numbers start at 1 = End A"),
("DragPow1N52", "node exceeds the line node count"),
],
)
def test_load_power_channels_are_native(channel, message):
text = _example("viv_taut_line_crossflow.dat", ('"FairTen1"', f'"FairTen1"\n"{channel}"'))
if message is None:
DeckFile.from_text(text)
else:
_rejects(text, re.escape(message))


def test_stiffener_needs_a_finite_ei_line():
text = _section(_HELD, "STIFFENERS", "1 A 1.0 0.5 0.5 0.3 5.0e7 1150")
_rejects(text, "STIFFENERS name line 1, which is not a finite-EI line")
Expand Down
Loading
Loading