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
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,17 @@ All notable changes to CableDyn are recorded in this file. The format follows

## [Unreleased]

### Added

- In-process stepping in moving water (ABI 1.4). On decks with finite-EI lines, bodies or rods
the C API and Python march a steady deck current (`current`, WaterKin `CurrentMod 1`, MoorDyn-C
`Currents 1`), in the static start and in every step. A host can instead supply the fluid at
every line node: `CableDyn_SetHostFluid`, `CableDyn_NFluidNodes`,
`CableDyn_GetFluidNodePositions` and `CableDyn_UpdateFluidFields`, in Python `set_host_fluid`,
`n_fluid_nodes`, `fluid_node_positions` and `update_fluid_fields`. The field is sampled and held
as in the standalone march and in OpenFAST; in current and waves a stepped cable matches the
standalone driver to the digits of its output.

### Fixed

- The C API messages of `CableDyn_UpdatePointFluidFields` and `CableDyn_CalcOutputDerivatives` on
Expand Down
46 changes: 45 additions & 1 deletion doc/api_python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -710,6 +710,49 @@ library is located. Array ordering, frames, and units at the coupling boundary f
:rtype: numpy.ndarray
:raises CableDynError: if the call fails.

.. py:method:: set_host_fluid(enable=True)

Choose, before a deck initialization, whether the host supplies the ambient fluid.
With ``enable``, the following :meth:`init_deck`, :meth:`init_deck_at` and
:meth:`init_deck_rotating` take the field of :meth:`update_fluid_fields`: deck waves
are refused and a steady deck current sets the static start only.

:param enable: Whether the host supplies the fluid.
:type enable: bool
:raises CableDynError: if the call fails.

.. py:attribute:: n_fluid_nodes

Nodes of the host fluid field; zero without one.

.. py:method:: fluid_node_positions()

Committed positions of the fluid nodes, where the host evaluates the field of the
coming step.

:returns: Global positions (m), shaped ``(3, n_fluid_nodes)``.
:rtype: numpy.ndarray
:raises CableDynError: on a model built without a host fluid field.

.. py:method:: update_fluid_fields(fluid_velocity, fluid_acceleration, waterline_z, dynamic_pressure=None)

Prescribe the ambient fluid at every fluid node, held until the next call. Call it
once with the field at ``t = 0`` before the first step, then before each step from
``t`` to ``t + dt`` with the field at ``t + dt`` at the positions of
:meth:`fluid_node_positions`. The density is the deck's.

:param fluid_velocity: Whole ambient velocity (m/s), global axes, shaped
``(3, n_fluid_nodes)`` or flat.
:type fluid_velocity: array_like
:param fluid_acceleration: Fluid acceleration (m/s\ :sup:`2`), with the same shape.
:type fluid_acceleration: array_like
:param waterline_z: Free-surface elevation above each node (m), ``(n_fluid_nodes,)``.
:type waterline_z: array_like
:param dynamic_pressure: Wave dynamic pressure (Pa) for the end caps of rods.
:type dynamic_pressure: array_like, optional
:raises CableDynError: on a model built without a host fluid field, or if the call
fails.

.. py:method:: update_point_fluid_fields(fluid_velocity, fluid_acceleration, waterline_z, fluid_density)

Prescribe external fluid kinematics at every system point.
Expand Down Expand Up @@ -828,7 +871,8 @@ imports without the shared library.

.. py:function:: abi_minor()

Return the extension level of ABI 1 of the loaded library: 3 when it also has the
Return the extension level of ABI 1 of the loaded library: 4 when it also has the host
fluid calls behind :meth:`CableDyn.update_fluid_fields`, 3 when it has the
host-rotation calls behind :meth:`CableDyn.init_deck_rotating`,
:meth:`CableDyn.update_rotations` and :meth:`CableDyn.coupled_moments`, 2 when it has the
host-coupling calls behind :meth:`CableDyn.init_deck_at`, :meth:`CableDyn.save_state` and
Expand Down
3 changes: 2 additions & 1 deletion doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -221,7 +221,8 @@ node that takes the platform position only and returns a force with zero moment,
rods turn about a fixed End A. A coupled deck (OpenFAST, the C API and Python) carries bodies or
rods, not both, a rod fixed to a body counting as a rod; the standalone driver's multibody march
takes both, as does MoorDyn (``CompMooring = 3``). The C API and Python
run free, fixed and pinned rods and free bodies in still water. The coupled body/rod routes carry
run free, fixed and pinned rods and free bodies in still water or in a field the host supplies
at the nodes (:doc:`capi`). The coupled body/rod routes carry
checkpoint state and SeaState drag, Froude–Krylov, and added mass.
``Rigid6`` also carries the documented hydrostatic restoring terms. Consult :doc:`driver_format`
before using an imported object because unsupported fields fail closed.
Expand Down
72 changes: 66 additions & 6 deletions doc/capi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,12 @@ A model lives behind an opaque handle. The lifecycle is:
.. code-block:: text

CableDyn_Create
-> [CableDyn_SetHostFluid] (host fluid field)
-> CableDyn_InitDeck | CableDyn_InitDeckAt | CableDyn_InitDeckRotating
| CableDyn_InitLine | CableDyn_InitLines (initialize; may repeat)
-> CableDyn_GetCoupledMotion (read the initial state)
-> loop: [CableDyn_SaveState | CableDyn_RestoreState] (host outer correctors)
[CableDyn_UpdatePointFluidFields]
[CableDyn_UpdatePointFluidFields | CableDyn_UpdateFluidFields]
[CableDyn_UpdateRotations] (a host that turns)
CableDyn_Step(dt, motion at t+dt)
CableDyn_CalcOutput [, CableDyn_GetCoupledMoments] (loads at t+dt)
Expand Down Expand Up @@ -61,6 +62,9 @@ MoorDyn's C API.
- set the coupled-point motion without advancing time
* - ``CableDyn_UpdatePointFluidFields``
- set fluid kinematics at the deck points (point hydrodynamics)
* - ``CableDyn_SetHostFluid``, ``CableDyn_NFluidNodes``, ``CableDyn_GetFluidNodePositions``,
``CableDyn_UpdateFluidFields``
- supply the ambient fluid at the nodes of every line (`Step 9: moving water`_)
* - ``CableDyn_Step``
- advance one implicit step to :math:`t+\Delta t`
* - ``CableDyn_CalcOutput``
Expand Down Expand Up @@ -685,6 +689,58 @@ The rotations are inputs, like the motion: an end frame turned by more than a qu
about its line since the last committed step is refused, and ``CableDyn_SaveState``/``CableDyn_RestoreState`` carry the
last rotations with the model.

Step 9: moving water
~~~~~~~~~~~~~~~~~~~~

A deck's steady current is marched as in the standalone driver: a ``current`` option, a WaterKin
``CurrentMod 1`` depth table or a MoorDyn-C ``Currents 1`` profile acts in the static start and in
every step, on lines between ``Fixed``, ``Coupled`` and ``Vessel`` points. Nothing else is needed.

A host that evaluates the water itself, such as a wave field not known in advance, supplies it at
the nodes:

.. code-block:: c

CableDyn_SetHostFluid(h, 1, &err); /* before the initialization */
CableDyn_InitDeckRotating(h, deck, len, q0, n_q0, &err);
n = CableDyn_NFluidNodes(h, &err);

CableDyn_GetFluidNodePositions(h, xyz, n, &err); /* the field at t = 0 */
CableDyn_UpdateFluidFields(h, vel, acc, eta, NULL, n, &err);
for (;;) { /* a step from t to t + dt */
CableDyn_GetFluidNodePositions(h, xyz, n, &err); /* the step-start positions */
/* evaluate vel, acc, eta at xyz at time t + dt */
CableDyn_UpdateFluidFields(h, vel, acc, eta, NULL, n, &err);
CableDyn_Step(h, dt, q, v, a, n_dof, &converged, &stalled, &n_iter, &err);
}

The convention is that of the standalone march and of the OpenFAST module:

* the field of a step from ``t`` to ``t + dt`` is sampled at ``t + dt`` at the step-start node
positions, and it is held unchanged over the step;
* ``vel`` is the whole ambient velocity, current and waves together, ``acc`` the fluid
acceleration, both as ``x, y, z`` triples in global axes, and ``eta`` the free-surface elevation
above each node, which decides the wetting of its drag, added mass and buoyancy;
* the first call, before the first step, is the field at ``t = 0`` and sets the start acceleration;
a step without any field is refused, because the march would otherwise run in still water;
* ``dynamic_pressure`` may be ``NULL``; rods use it for their end caps;
* the density is the deck's ``rhoW``;
* the nodes are every node of every line, then the deck's bodies, rods and hydrodynamic points.
The field depends on position alone, so the host needs no node numbering;
* ``CableDyn_SaveState`` and ``CableDyn_RestoreState`` carry the held field.

With the host field, a deck runs on the coupled aggregate whatever its lines, needs ``dtM``, and
needs a seabed if it has ``EI = 0`` lines. Deck waves are refused. A steady deck current sets the
static start only, so the start is the equilibrium in that current, and the host's field is then
the whole water of the march; a deck current that varies in time is refused.

Seabed friction, ``staticsFriction asLaid`` and ``STIFFENERS`` work on this route.

With a host field the deck is read by the coupled rules, as in OpenFAST: it needs no ``TMax``, and a
``SEASTATE`` or ``WaveKinMod 2`` water policy takes the host's field. A deck current marched without
one follows the standalone rules and declares ``TMax``. Neither limits the host, which owns the clock
and may step past it.

Call sequence
~~~~~~~~~~~~~

Expand Down Expand Up @@ -908,8 +964,10 @@ coupled aggregate as the OpenFAST module, with these differences from the point-
the order of `Coupled DOF layout`_ (anchors are not part of the vector); the bodies and
rods are integrated internally;
* the deck must declare ``dtM``, and every ``CableDyn_Step`` must use that ``dt``;
* the run is in still water: deck waves or currents are rejected, and
``CableDyn_UpdatePointFluidFields`` and ``CableDyn_CalcOutputDerivatives`` return
* a deck current is marched on lines between ``Fixed``, ``Coupled`` and ``Vessel`` points,
deck waves are rejected, and other moving water comes from the host (`Step 9: moving
water`_);
* ``CableDyn_UpdatePointFluidFields`` and ``CableDyn_CalcOutputDerivatives`` return
``CD_C_BAD_INPUT``;
* ``CableDyn_NPoints`` and ``CableDyn_NLines`` report the deck's point and line counts.

Expand Down Expand Up @@ -940,13 +998,15 @@ The deck is validated under the standalone-deck rules:
* - a ``CONTROL`` section (active line control)
- the OpenFAST module
* - ``WaveKinMod 2`` / ``SEASTATE`` wave kinematics
- the OpenFAST module
- the OpenFAST module; a host that calls ``CableDyn_SetHostFluid``
* - a ``waves`` option (regular or JONSWAP deck waves)
- the standalone driver; supply time-varying fluid kinematics through
``CableDyn_UpdatePointFluidFields``
``CableDyn_UpdateFluidFields`` (`Step 9: moving water`_), or at the points of a point
deck through ``CableDyn_UpdatePointFluidFields``
* - a MoorDyn-C ``Currents 2``/``5`` table that varies in time
- the standalone driver; supply time-varying fluid kinematics through
``CableDyn_UpdatePointFluidFields``
``CableDyn_UpdateFluidFields`` (`Step 9: moving water`_), or at the points of a point
deck through ``CableDyn_UpdatePointFluidFields``
* - FAST.Farm ``Turbine<J>`` points
- the OpenFAST module in FAST.Farm
* - ``frictionMu`` in a deck that has ``Free`` or ``Connect`` points
Expand Down
9 changes: 6 additions & 3 deletions doc/coupling_boundary.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,12 @@ acceleration enters the dynamic residual through the consistent mass.

**Fluid fields in.**

- Line nodes take their fluid kinematics from the deck environment (waves and current) in
standalone and C API use, and from the host field in OpenFAST, where SeaState is sampled at the
structural nodes and held over the step.
- Line nodes take their fluid kinematics from the deck environment in standalone use (waves and
current) and in C API use (current), and from a host field in OpenFAST, where SeaState is sampled
at the structural nodes, and in C API use after `CableDyn_SetHostFluid`, where the host passes
velocity, acceleration and surface elevation at every node through
`CableDyn_UpdateFluidFields`. All routes sample the field of a step at `t + dt` at the
step-start node positions and hold it over the step.
- Dynamic `Free`/`Connect` points with hydrodynamic properties accept an external point-level
field through `CableDyn_UpdatePointFluidFields`: velocity and acceleration (3 × `n_point`),
local surface elevation (`n_point`), and one fluid density. A point above its surface
Expand Down
2 changes: 1 addition & 1 deletion doc/options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -741,7 +741,7 @@ Ambient fluid and prescribed motion
filename; ``SEASTATE`` selects the host field. The other MoorDyn-C modes fail closed by
name. Mode rules are in :ref:`moordyn-c-wavekin` and :ref:`waterkin-file-modes`
- ``3``/``7`` and file ``WaveKinMod 1``: standalone decks only; ``SEASTATE``,
``WaveKinMod 2``, and ``CurrentMod 2``: OpenFAST only
``WaveKinMod 2``, and ``CurrentMod 2``: OpenFAST and C API hosts with a host fluid field
- ``waterkin.dat WaterKin``
* - ``dtWave``
- positive number [s]
Expand Down
31 changes: 28 additions & 3 deletions doc/python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -769,9 +769,34 @@ through the C API (:doc:`capi`).

A deck with finite-EI lines, ``BODIES`` or ``RODS`` runs on the coupled aggregate and needs
``dtM``; other decks run on the point route. Decks with deck waves, a ``motionFile`` or vessel
motion are rejected in-process (they run in the standalone driver): time-varying fluid
kinematics enter through :meth:`~cabledyn.CableDyn.update_point_fluid_fields`, and motion through
the coupled kinematics of every step.
motion are rejected in-process (they run in the standalone driver): motion enters through the
coupled kinematics of every step. A steady deck current is marched in-process, in the static
start and in every step. Other moving water comes from the host, at the nodes of every line:

.. code-block:: python

model = cabledyn.CableDyn()
model.set_host_fluid() # before the initialization
model.init_deck_rotating(deck)

def field(t):
xyz = model.fluid_node_positions() # (3, n), the committed positions
velocity, acceleration, elevation = my_sea(xyz, t)
model.update_fluid_fields(velocity, acceleration, elevation)

field(0.0) # the start acceleration
for i in range(1, steps + 1):
t = i * dt
field(t) # held over the step
model.step(dt, q(t), v(t), a(t))

``examples/python/step_in_moving_water.py`` is a complete script of this loop.

``velocity`` is the whole ambient velocity, current and waves together. The field of a step to
``t + dt`` is evaluated at ``t + dt`` at the step-start positions and held over the step, as in
the standalone march and in OpenFAST; :meth:`~cabledyn.CableDyn.save_state` carries it. A steady
deck current then sets the static start only; the rules are in :doc:`capi`. On a deck of the
point route, :meth:`~cabledyn.CableDyn.update_point_fluid_fields` sets the field at the points.

A host that moves the ``Coupled`` points from its own body solver starts the model at its
positions and rewinds it between the passes of an iterated time step. The save is keyed on the
Expand Down
119 changes: 119 additions & 0 deletions examples/python/step_in_moving_water.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
# SPDX-License-Identifier: Apache-2.0
# Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University
"""Step a cable in-process while the host supplies the water and moves the top end.

The host owns the time loop. Before each step it reads the node positions, evaluates its own
current and wave at them, hands the field over, and passes the motion of the top end. Replace
``sea`` and ``top_end`` with your own models. Run it with::

python step_in_moving_water.py
"""

from __future__ import annotations

import math
import tempfile
from pathlib import Path

import numpy as np

import cabledyn

DT = 0.05
DEPTH, GRAVITY = 60.0, 9.80665
AMPLITUDE, PERIOD, CURRENT = 1.0, 8.0, 0.4
TOP = np.array([0.0, 0.0, -10.0])

DECK = """--------------------- CableDyn Input File ------------------------------------
A cable from a moving top end to an anchor. The steady current of the deck sets the static start.
--------------------- LINE TYPES ---------------------------------------------
TypeName Diam MassDenInAir EA BA EI Cd_n Cd_t Ca_n Ca_t
(-) (m) (kg/m) (N) (-) (N-m2) (-) (-) (-) (-)
cable 0.16 36.7 4.69e8 -1.0 1.99e4 1.2 0.1 1.0 0.0
--------------------- POINTS ------------------------------------------------
ID Type X Y Z
(-) (-) (m) (m) (m)
1 Coupled 0.0 0.0 -10.0
2 Fixed 70.0 0.0 -60.0
--------------------- LINES -------------------------------------------------
ID NodeA NodeB Outputs
(-) (-) (-) (-)
1 1 2 -
--------------------- SECTIONS ----------------------------------------------
LineID LineType Length NumSegs
(-) (-) (m) (-)
1 cable 100.0 50
--------------------- OPTIONS -----------------------------------------------
9.80665 g
1025.0 rhoW
60.0 WtrDpth
0.05 dtM
uniform 0.4 0 0 current
--------------------- OUTPUTS -----------------------------------------------
"FairTen1"
--------------------- need this line ----------------------------------------
"""


def wave_number(omega: float) -> float:
k = omega * omega / GRAVITY
for _ in range(50):
k = omega * omega / (GRAVITY * math.tanh(k * DEPTH))
return k


OMEGA = 2.0 * math.pi / PERIOD
K = wave_number(OMEGA)


def sea(xyz: np.ndarray, t: float) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
"""Whole ambient velocity, fluid acceleration and surface elevation at the nodes ``(3, n)``."""
theta = K * xyz[0] - OMEGA * t
decay = np.exp(K * np.minimum(xyz[2], 0.0)) # deep-water profile, for brevity
velocity = np.zeros_like(xyz)
acceleration = np.zeros_like(xyz)
velocity[0] = CURRENT + AMPLITUDE * OMEGA * decay * np.cos(theta)
velocity[2] = AMPLITUDE * OMEGA * decay * np.sin(theta)
acceleration[0] = AMPLITUDE * OMEGA**2 * decay * np.sin(theta)
acceleration[2] = -AMPLITUDE * OMEGA**2 * decay * np.cos(theta)
return velocity, acceleration, AMPLITUDE * np.cos(theta)


def top_end(t: float) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
"""Position, velocity and acceleration of the coupled point: a slow surge, from rest."""
rate = 2.0 * math.pi / 10.0
s, c = math.sin(rate * t), math.cos(rate * t)
q = TOP + np.array([0.5 * s**3, 0.0, 0.0])
v = np.array([1.5 * rate * s * s * c, 0.0, 0.0])
a = np.array([1.5 * rate**2 * (2.0 * s * c * c - s**3), 0.0, 0.0])
return q, v, a


def main(duration: float = 20.0) -> list[float]:
"""March for ``duration`` seconds and return the top tension of every step."""
tensions = []
with tempfile.TemporaryDirectory() as folder:
deck = Path(folder) / "cable.dat"
deck.write_text(DECK, encoding="utf-8")
with cabledyn.CableDyn() as model:
model.set_host_fluid() # before the initialization
model.init_deck(deck)

def give_field(t: float) -> None:
# the field of a step: at its end time, at the step-start positions
model.update_fluid_fields(*sea(model.fluid_node_positions(), t))

give_field(0.0) # the start acceleration
for i in range(1, round(duration / DT) + 1):
t = i * DT
give_field(t)
model.step(DT, *top_end(t))
model.calc_output()
tensions.append(float(model.channel("FairTen1")))
if i % round(1.0 / DT) == 0:
print(f"t = {t:5.1f} s top tension {tensions[-1]:10.1f} N")
return tensions


if __name__ == "__main__":
main()
Loading
Loading