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

### Added

- C API host rotations (ABI 1.3): `CableDyn_InitDeckRotating` initialises a handle whose host
passes each coupled point's rotation (`CableDyn_UpdateRotations`: the global-to-body DCM and
the angular velocity and acceleration) with every update and step, so a line restrained in
torsion and a `Rigid` end connection turn with the host, as on the coupled OpenFAST route; a
torsion deck, refused by `CableDyn_InitDeck`/`InitDeckAt`, runs there.
`CableDyn_GetCoupledMoments` returns the moments the lines apply to the host. On a straight
line rolled at 60 deg/s the coupled torque is the quasi-static `GJ phi / L` to 3e-6 N m, and
`SaveState`/`RestoreState` carry the rotations. Python: `CableDyn.init_deck_rotating`,
`update_rotations`, `coupled_moments`.
- OpenFAST linearisation with the line dynamics, as MoorDyn-F's: the continuous states are the
interior-node positions of every `EI = 0` line (MoorDyn's names and order) and the free
degrees of freedom of every finite-EI cable (node positions and tangents), then their
Expand Down
11 changes: 11 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1240,6 +1240,17 @@ add_test(NAME c_api_host_coupling
${CMAKE_CURRENT_SOURCE_DIR}/examples/clump_weight_free_point.dat)
set_tests_properties(c_api_host_coupling PROPERTIES LABELS "c;unit;capi;shared;dynamic")

add_executable(test_c_api_host_rotation tests/test_c_api_host_rotation.c)
target_include_directories(test_c_api_host_rotation PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src")
target_link_libraries(test_c_api_host_rotation PRIVATE cabledyn_shared)
if(NOT WIN32)
target_link_libraries(test_c_api_host_rotation PRIVATE m)
endif()
add_test(NAME c_api_host_rotation
COMMAND test_c_api_host_rotation ${CMAKE_CURRENT_SOURCE_DIR}/tests/data/foam_esflowc_box_points.dat
WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(c_api_host_rotation PROPERTIES LABELS "c;unit;capi;shared;dynamic;torsion")

find_package(Threads QUIET)
if(Threads_FOUND AND CMAKE_USE_PTHREADS_INIT)
add_executable(test_c_api_concurrency tests/test_c_api_concurrency.c)
Expand Down
55 changes: 54 additions & 1 deletion doc/api_python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -540,6 +540,57 @@ library is located. Array ordering, frames, and units at the coupling boundary f
multiple of 3; or if ``q0`` is not finite.
:raises RuntimeError: if the loaded library predates ABI 1 minor extension 2.

.. py:method:: init_deck_rotating(deck, q0=None)

Initialise from a deck for a host that turns the bodies its coupled points are fixed to
(``CableDyn_InitDeckRotating``): :meth:`init_deck_at`, or :meth:`init_deck` with
``q0=None``, whose model takes each coupled block's rotation from
:meth:`update_rotations` and passes it with every :meth:`update_states` and :meth:`step`.
A line restrained in torsion (``END CONNECTIONS`` ``TorsStiffness``) and a ``Rigid`` bending
end connection then turn with the host at their host-driven end, as on the coupled
OpenFAST route; the other initialisations refuse a deck with a line restrained in torsion.
The rotations start at identity (the deck's axes at the static start) and rest.

:param deck: Path of the ``.dat`` deck, as for :meth:`init_deck`.
:type deck: str | os.PathLike
:param q0: The host positions of :meth:`init_deck_at`, or ``None`` for the deck positions.
:type q0: array_like | None
:raises CableDynError: as :meth:`init_deck_at`.
:raises ValueError: as :meth:`init_deck_at`.
:raises RuntimeError: if the loaded library predates ABI 1 minor extension 3.

.. py:method:: update_rotations(dcm, omega, alpha)

Set the host's rotation of every coupled block for the following :meth:`update_states`
and :meth:`step` calls (``CableDyn_UpdateRotations``); it is kept until the next call and
saved and restored with :meth:`save_state` and :meth:`restore_state`. Only a finite-EI
line's host-driven end uses its block.

:param dcm: ``(n_block, 3, 3)``: block ``k``'s global-to-body direction cosine matrix, its
rows the body axes in global axes (the OpenFAST mesh orientation); identity is the body
at its static-start attitude.
:type dcm: array_like
:param omega: ``(n_block, 3)``: the body's angular velocity in global axes (rad/s).
:type omega: array_like
:param alpha: ``(n_block, 3)``: the body's angular acceleration in global axes (rad/s²).
:type alpha: array_like
:raises ValueError: if an array has the wrong shape.
:raises CableDynError: on a model not initialised by :meth:`init_deck_rotating`, or a
matrix that is not proper orthogonal to 1e-8 or a non-finite value (the rotations are
then unchanged).
:raises RuntimeError: if the loaded library predates ABI 1 minor extension 3.

.. py:method:: coupled_moments()

Return the moments the lines apply to the host at the coupled points
(``CableDyn_GetCoupledMoments``), at the state :meth:`calc_output` reports: block ``k``
(entries ``3k .. 3k+2``, N m, global axes) is a finite-EI line's torsional and bending
reaction about the coupled point at its host-driven end, zero for the other blocks and for
``EI = 0`` lines.

:rtype: numpy.ndarray
:raises RuntimeError: if the loaded library predates ABI 1 minor extension 3.

.. py:method:: save_state()
restore_state()

Expand Down Expand Up @@ -776,7 +827,9 @@ imports without the shared library.

.. py:function:: abi_minor()

Return the extension level of ABI 1 of the loaded library: 2 when it also has the
Return the extension level of ABI 1 of the loaded library: 3 when it also 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
:meth:`CableDyn.coupled_layout`, 1 when it has the object queries behind
:attr:`CableDyn.lines` and :meth:`CableDyn.channel`, 0 for an older library.
Expand Down
8 changes: 5 additions & 3 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -91,9 +91,11 @@ Line and constitutive capability
with turning Rigid6 bodies, ``vesselMotion``/``vesselRAO`` and the ``motionFile`` roll
column standalone, and with the platform orientation in coupled OpenFAST and FAST.Farm
runs (torque returned to the platform, ``PtfmInit``, checkpoints; see
:doc:`openfast`); ``Torq``/``Twist`` channels and standalone range graphs. Stopped by
name: the standalone mixed ``EI = 0`` + finite-EI aggregate and the C API (which move the
line ends by translation only), OpenFAST linearisation of a line restrained in torsion,
:doc:`openfast`) and through the C API with the host's rotations
(``CableDyn_InitDeckRotating``, :doc:`capi`); ``Torq``/``Twist`` channels and standalone
range graphs. Stopped by name: the standalone mixed ``EI = 0`` + finite-EI aggregate and
``CableDyn_InitDeck``/``InitDeckAt`` (which move the line ends by translation only),
OpenFAST linearisation of a line restrained in torsion,
rod ends, bodies other than Rigid6, lines with ``ATTACHMENTS``, modal analysis, and
``False alpha_force_blend``. Not modelled: seabed friction against twist, anisotropic
sections, self-contact of a loop (see :ref:`theory-torsion`)
Expand Down
132 changes: 125 additions & 7 deletions doc/capi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,14 @@ A model lives behind an opaque handle. The lifecycle is:
.. code-block:: text

CableDyn_Create
-> CableDyn_InitDeck | CableDyn_InitDeckAt (initialize; may repeat)
| CableDyn_InitLine | CableDyn_InitLines
-> 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_UpdateRotations] (a host that turns)
CableDyn_Step(dt, motion at t+dt)
CableDyn_CalcOutput (loads at t+dt)
CableDyn_CalcOutput [, CableDyn_GetCoupledMoments] (loads at t+dt)
-> CableDyn_Close

A host solver that drives the ``Coupled`` points of a deck, a CFD code in particular, should
Expand Down Expand Up @@ -83,6 +84,11 @@ MoorDyn's C API.
- host coupling (ABI 1.2): initialization with the statics at the host's positions, a
one-slot state save and restore for outer correctors, and the owner of each block of
the coupled vector (`Host coupling calls`_)
* - ``CableDyn_InitDeckRotating``, ``CableDyn_UpdateRotations``,
``CableDyn_GetCoupledMoments``
- host rotations (ABI 1.3): a host that turns the bodies its coupled points are fixed to,
for lines restrained in torsion and Rigid end connections, and the moments the lines
apply (`Host rotation calls`_)

Building and linking
--------------------
Expand Down Expand Up @@ -237,9 +243,9 @@ ABI and versioning
- 1
- the C ABI revision the header describes
* - ``CABLEDYN_CAPI_ABI_MINOR`` / ``CableDyn_GetAbiMinor()``
- 2
- 3
- additive extensions of ABI 1: 1 adds the `Object queries`_, 2 the
`Host coupling calls`_
`Host coupling calls`_, 3 the `Host rotation calls`_
* - ``CableDyn_GetVersion(&major, &minor, &patch, &abi)``
- runtime
- the same four numbers, reported by the loaded library
Expand Down Expand Up @@ -270,8 +276,9 @@ The Python package does this check at import and rejects a library that speaks a

A minor extension only adds functions: every ABI 1 prototype and its semantics are unchanged,
so a caller built against an older header keeps working. A caller that uses the additions checks
``CableDyn_GetAbiMinor() >= 1`` before calling the object queries, and
``CableDyn_GetAbiMinor() >= 2`` before calling the host-coupling functions.
``CableDyn_GetAbiMinor() >= 1`` before calling the object queries,
``CableDyn_GetAbiMinor() >= 2`` before calling the host-coupling functions, and
``CableDyn_GetAbiMinor() >= 3`` before calling the host-rotation functions.

Calling conventions
-------------------
Expand Down Expand Up @@ -650,6 +657,33 @@ SI units in the global right-handed frame with z up and still water at :math:`z
(:doc:`conventions`), as in MoorDyn. A host in another frame or unit system converts the
motion it passes and the loads it receives.

Step 8: a host that turns: torsion and rigid end connections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The coupled vector carries translations only, which is all an ``EI = 0`` line or a pinned
finite-EI end takes. A finite-EI line restrained in torsion (``END CONNECTIONS``
``TorsStiffness``) twists with the body's roll about the line, and a ``Rigid`` bending end
connection holds the line's end tangent on a direction fixed to the body: both need the body's
rotation. ``CableDyn_InitDeck`` and ``CableDyn_InitDeckAt`` move the ends by translation only and
refuse a deck with a line restrained in torsion; a ``Rigid`` end connection there keeps its deck
direction.

*CableDyn.* Initialise with ``CableDyn_InitDeckRotating`` (``CableDyn_InitDeckAt`` that takes
rotations; ``n_q0 = 0`` for the deck positions) and, before every ``CableDyn_UpdateStates`` and
``CableDyn_Step``, pass the body's rotation at the same instant with
``CableDyn_UpdateRotations``: for each block of the coupled vector, the global-to-body
direction cosine matrix (row-major: its rows are the body axes in global axes, the OpenFAST
mesh orientation) and the body's angular velocity and acceleration in global axes. The body's
axes are the deck's at the static start, so the rotation starts at identity; a host whose body
starts rotated passes its rotation relative to that start. ``CableDyn_GetCoupledMoments`` then
returns the moment each line applies to the body about its fairlead, in global axes, beside the
force of ``CableDyn_CalcOutput``; add :math:`\sum_k m_k` to the moment of Step 5. *MoorDyn* has
no line torsion; its coupled bodies and rods take 6 values per object.

The rotations are inputs, like the motion: an end frame turned by more than a quarter turn
about its line since the last committed step is refused, and ``CableDyn_SaveState``/``CableDyn_RestoreState`` carry the
last rotations with the model.

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

Expand Down Expand Up @@ -684,9 +718,12 @@ the deck's ``POINTS`` order of the ``Coupled`` points) the host computes from th
}
++j;
}
/* a host that turns (CableDyn_InitDeckRotating): the body's rotation at t first */
/* CableDyn_UpdateRotations(h, dcm, omega, alpha, n / 3, &err); */
CableDyn_Step(h, dt, q, v, a, n, &converged, &stalled, &n_iter, &err);
CableDyn_CalcOutput(h, f, n, &err);
/* F = sum of f over the host blocks; M = sum of (x - r) x f over the same blocks */
/* (+ the moments of CableDyn_GetCoupledMoments over the same blocks, Step 8) */

/* End of the run. */
CableDyn_Close(&h, &err);
Expand Down Expand Up @@ -1953,6 +1990,87 @@ line-bound points of every type in ``POINTS`` order; on the aggregate route they
has no deck points, and the call returns ``CD_C_BAD_INPUT``: its coupled vector is the caller's
own ``fixed_dofs`` list. A wrong ``n_block`` returns ``CD_C_BAD_INPUT``.

Host rotation calls
~~~~~~~~~~~~~~~~~~~

ABI 1 minor extension 3: check ``CableDyn_GetAbiMinor() >= 3`` before calling these.
`Step 8: a host that turns: torsion and rigid end connections`_ shows how they fit together.

.. code-block:: c

void CableDyn_InitDeckRotating(void *handle, const char *deck_path,
int deck_path_len, const double *q0, int n_q0,
int *err_stat);
void CableDyn_UpdateRotations(void *handle, const double *dcm,
const double *omega, const double *alpha,
int n_block, int *err_stat);
void CableDyn_GetCoupledMoments(void *handle, double *coupled_moments,
int n_coupled_dof, int *err_stat);

**CableDyn_InitDeckRotating.** ``CableDyn_InitDeckAt`` for a host that turns its coupled points:
the arguments, routes, rejections, serialisation and transactions are those of
``CableDyn_InitDeckAt``, and ``n_q0 = 0`` (``q0`` may be ``NULL``) solves the statics at the deck
positions, as ``CableDyn_InitDeck``. The handle takes each coupled block's rotation from
``CableDyn_UpdateRotations`` and passes it with every ``CableDyn_UpdateStates`` and
``CableDyn_Step``, so a line restrained in torsion and a ``Rigid`` bending end connection turn
with the host at their host-driven end, as on the coupled OpenFAST route. It accepts a deck
with a line restrained in torsion, which the other ``Init*`` calls refuse. The rotations start
at identity and rest. Another ``Init*`` call makes the handle one that takes no rotations.

**CableDyn_UpdateRotations.** The rotation of each 3-DOF block of the coupled vector for the
following ``CableDyn_UpdateStates`` and ``CableDyn_Step`` calls; it is kept until the next call.

.. list-table::
:header-rows: 1
:widths: 18 8 12 12 12 38

* - Argument
- Dir
- C type
- Length
- NULL
- Meaning
* - ``dcm``
- in
- ``const double *``
- ``9 * n_block``
- only if ``n_block == 0``
- ``dcm[9k + 3i + j]`` is :math:`R_{ij}` of block ``k``'s global-to-body direction cosine
matrix, row-major: row ``i`` is body axis ``i`` in global axes (the OpenFAST mesh
orientation). Identity is the body at its static-start attitude.
* - ``omega``, ``alpha``
- in
- ``const double *``
- ``3 * n_block`` each
- only if ``n_block == 0``
- the body's angular velocity [rad/s] and acceleration [rad/s²] in global axes
* - ``n_block``
- in
- ``int``
- --
- --
- must equal ``CableDyn_NCoupledDOF / 3``

Only a finite-EI line's host-driven end uses its block; the other blocks (``EI = 0`` lines,
the point route, bodies and rods) are checked and not used. The call is all or nothing: a
handle not initialised by ``CableDyn_InitDeckRotating``, a wrong ``n_block``, a ``NULL``
pointer, a non-finite entry, and a matrix that is not proper orthogonal to :math:`10^{-8}`
(:math:`\max |R R^T - I|` and :math:`|\det R - 1|`) return ``CD_C_BAD_INPUT`` and leave the
rotations unchanged. The rotations are checked against the lines at the next update or step:
an end frame turned by more than a quarter turn about its line since the last committed state is
refused there.
``CableDyn_SaveState`` saves the rotations with the model and ``CableDyn_RestoreState`` restores
them.

**CableDyn_GetCoupledMoments.** The moment [N m] each block of the coupled vector applies to the
host, about the coupled point in global axes, at the state ``CableDyn_CalcOutput`` reports
(after an update without a step, against the frozen interior as there). It is a finite-EI
line's torsional and bending reaction at its host-driven end, and zero for the other blocks and
on the point route. ``coupled_moments`` holds ``n_coupled_dof`` values (``NULL`` only if
``n_coupled_dof == 0``), which must equal ``CableDyn_NCoupledDOF``; it is set to zero before the
evaluation and stays zero if the call fails. It is available on any initialised handle, so a
host without rotations can read the moment of a ``Rigid`` end connection at its deck direction.

Examples
--------

Expand Down
7 changes: 4 additions & 3 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -865,9 +865,10 @@ Scope. A torsionally restrained line needs a finite-EI line with a `Fixed` End B
torsion on an `EI = 0` line, on a rod end or on a `Point3` body, a line with `ATTACHMENTS`,
modal analysis (`nModes`), a dynamic or coupled run with `False alpha_force_blend`, any
restrained end (one end included) in a standalone deck mixing `EI = 0` and finite-EI lines
without a body or through the C API, which move the line ends by translation only (`a line
restrained in torsion needs a host that turns its fairlead frame ...`; with a body such a deck
runs on the multibody route, which supports torsion), OpenFAST linearisation of a line
without a body or through the C API's `CableDyn_InitDeck`/`InitDeckAt`, which move the line
ends by translation only (`a line restrained in torsion needs a host that turns its fairlead
frame ...`; with a body such a deck runs on the multibody route, which supports torsion, and a C
API host passes its rotations after `CableDyn_InitDeckRotating`), OpenFAST linearisation of a line
restrained in torsion, and a `Torq`/`Twist` channel on a line that is not restrained at both
ends. Seabed friction does not resist twist (the laid part of a line twists freely), and there
is no torque–tension coupling.
Expand Down
7 changes: 4 additions & 3 deletions doc/openfast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -345,9 +345,10 @@ substeps; an output probe moves the frame without a step, is limited to 90° fro
committed twist, and stops by name beyond it (a restart first restores the checkpoint's twist,
so it is not limited this way). Formal
linearisation of a line restrained in torsion fails during initialisation: the torque's
rotational stiffness has no column in the translation-only quasi-static reduction. The C API
and the standalone deck that mixes ``EI = 0`` and finite-EI lines without a body move the line
ends by translation only and refuse torsion columns.
rotational stiffness has no column in the translation-only quasi-static reduction. The C API's
``CableDyn_InitDeck``/``InitDeckAt`` and the standalone deck that mixes ``EI = 0`` and finite-EI
lines without a body move the line ends by translation only and refuse torsion columns; a C API
host that initialises with ``CableDyn_InitDeckRotating`` passes its rotations (:doc:`capi`).

Lifecycle features
------------------
Expand Down
Loading
Loading