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
7 changes: 5 additions & 2 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -500,8 +500,11 @@ import only Windows system DLLs.
minor extension 1 (`CableDyn_GetAbiMinor() ≥ 1`) adds in-process object queries
(object counts and ids, line node and segment values, point, body, and rod
states, and any output channel through `CableDyn_EvalChannel`), which return
what the matching output channel reports for the same state (see
[doc/capi.rst](doc/capi.rst)).
what the matching output channel reports for the same state. Minor extension 2
(`≥ 2`) adds the host-coupling calls: `CableDyn_InitDeckAt` (the statics solved
at the host's coupled-point positions), `CableDyn_SaveState` /
`CableDyn_RestoreState` (a one-slot deep copy of the model object for outer
correctors) and `CableDyn_GetCoupledLayout` (see [doc/capi.rst](doc/capi.rst)).
- **Python** (`python/cabledyn`): runs the driver, reads and post-processes
outputs, edits decks, runs studies, and binds the C interface through ctypes
with a pinned ABI version. With its object views and snapshots it is designed
Expand Down
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,23 @@ All notable changes to CableDyn are recorded in this file. The format follows
body, which move the line ends by translation only, still refuse torsion columns by name, and
so does OpenFAST linearisation of a line restrained in torsion. See the manual's OpenFAST page
(Line torsion).
- C ABI 1 minor extension 2 (`CableDyn_GetAbiMinor() == 2`) for hosts that drive the
`Coupled` points of a deck, such as CFD solvers. Every existing function is unchanged.
`CableDyn_InitDeckAt` solves the statics with the `Coupled`/`Vessel` points at the host's
positions, the counterpart of `MoorDyn_Init(X, XD)` (the statics start at rest), so a body
that starts away from the deck coordinates starts without a transient: for foamMooring's
`EsfLOWC` box, whose fairleads start 15 mm below the deck, the fairlead load of
`CableDyn_InitDeck` followed by held fairleads deviates by up to 0.38 N of 0.52 N, and stays
constant to round-off after `CableDyn_InitDeckAt`. `CableDyn_SaveState` and
`CableDyn_RestoreState` keep one in-memory copy of the whole model for outer correctors
(PIMPLE); a restore followed by a step is bit-identical to stepping from the saved state, on
both routes and across any number of steps. `CableDyn_GetCoupledLayout` returns the deck point
id and type of every block of the coupled vector, which on the point route includes the
`Fixed` anchors. The Python `CableDyn` class gains `init_deck_at`, `save_state`,
`restore_state`, `coupled_layout` and `host_dofs`. The manual's C API page has a new section,
Coupling a host (CFD) solver, that compares the call sequence step by step with MoorDyn's C
API: initialisation, vector layout, end-of-step motion, outer correctors, load summation,
the fixed step of the aggregate route, and units.

### Changed

Expand Down
28 changes: 24 additions & 4 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1081,6 +1081,25 @@ add_test(NAME c_api_shared
${CMAKE_CURRENT_SOURCE_DIR}/examples/dynamic_chain_waves.dat)
set_tests_properties(c_api_shared PROPERTIES LABELS "c;unit;capi;shared")

# The host-coupling calls of ABI 1.2 through the public header and the shared library:
# initialization at the host's positions (the foamMooring EsfLOWC box, whose fairleads start
# below their deck coordinates), state save/restore on both routes, on a raw-array handle and
# with viscoelastic, Syrope, seabed-friction and point fluid-field state, the save-slot
# lifetime across failed initializations, and the layout query.
add_executable(test_c_api_host_coupling tests/test_c_api_host_coupling.c)
target_include_directories(test_c_api_host_coupling PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src")
target_link_libraries(test_c_api_host_coupling PRIVATE cabledyn_shared)
if(NOT WIN32)
target_link_libraries(test_c_api_host_coupling PRIVATE m)
endif()
add_test(NAME c_api_host_coupling
COMMAND test_c_api_host_coupling ${CMAKE_CURRENT_SOURCE_DIR}/tests/data/foam_esflowc_box_points.dat
${CMAKE_CURRENT_SOURCE_DIR}/tests/data/host_coupling_chain_cable.dat
${CMAKE_CURRENT_SOURCE_DIR}/examples/ve_polyester_catenary_mooring.dat
${CMAKE_CURRENT_SOURCE_DIR}/examples/syrope_polyester_mooring.dat
${CMAKE_CURRENT_SOURCE_DIR}/examples/clump_weight_free_point.dat)
set_tests_properties(c_api_host_coupling PROPERTIES LABELS "c;unit;capi;shared;dynamic")

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 All @@ -1094,10 +1113,11 @@ else()
endif()

# Portable (Win32 or POSIX threads) stack bound of the shared library: each deck is
# initialised, stepped, and evaluated on a thread with a 1 MiB stack (a host program, not
# CableDyn, chooses the stack of the threads that call the library). The decks are a
# 2048-element finite-EI cable (12294 DOFs), an EI=0 + finite-EI aggregate, and an EI=0
# mooring; a stack need that grew with the model would overflow here.
# initialised, stepped, saved and restored, evaluated, and initialised again at its coupled
# positions (CableDyn_InitDeckAt) on a thread with a 1 MiB stack (a host program, not
# CableDyn, chooses the stack of the threads that call the library). The
# decks are a 2048-element finite-EI cable (12294 DOFs), an EI=0 + finite-EI aggregate, and an
# EI=0 mooring; a stack need that grew with the model would overflow here.
add_executable(test_c_api_stack tests/test_c_api_stack.c)
target_include_directories(test_c_api_stack PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src")
target_link_libraries(test_c_api_stack PRIVATE $<TARGET_LINKER_FILE:cabledyn_shared>)
Expand Down
73 changes: 70 additions & 3 deletions doc/api_python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -513,6 +513,70 @@ library is located. Array ordering, frames, and units at the coupling boundary f
:raises ValueError: if the path contains a NUL character or, on Windows, cannot be
represented in the active ANSI code page.

.. py:method:: init_deck_at(deck, q0)

Initialise from a deck file with the static initial condition solved at the host's
positions of the coupled points (``CableDyn_InitDeckAt``). Every line-bound
``Coupled``/``Vessel`` point starts at its entry of ``q0`` instead of its deck coordinates;
the lines, ``Free``/``Connect`` points, bodies and rods are solved in equilibrium with those
points held there, at rest. A host whose body starts away from the deck coordinates then
starts without a transient (:ref:`capi-host-coupling`).

:param deck: Path of the ``.dat`` deck, as for :meth:`init_deck`.
:type deck: str | os.PathLike
:param q0: Either the full coupled vector of the deck (``n_coupled_dof`` values, the layout
:meth:`step` uses; the ``Fixed``, ``Free`` and ``Connect`` blocks are not read), or the
``Coupled``/``Vessel`` blocks alone, in coupled-vector order (the ``MoorDyn_Init``
layout of a deck whose coupled objects are points that are all attached to lines: a
``Coupled`` point attached to no line has no block here). Flat, or column-per-point
``(3, n)`` with ``n`` ≠ 3; positions in m.
:type q0: array_like
:raises CableDynError: if the deck fails to initialise, or ``q0`` does not match its
coupled points. A failed initialisation keeps any previously initialised model and its
saved state.
:raises ValueError: if the path is rejected as by :meth:`init_deck`; if ``q0`` is a ``(3, 3)``
array, which is ambiguous (column-per-point or row-per-point: pass three points flat);
if ``q0`` has any other shape than flat or ``(3, n)``, or a length that is not a
multiple of 3; or if ``q0`` is not finite.
:raises RuntimeError: if the loaded library predates ABI 1 minor extension 2.

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

Save the whole model, and :attr:`time`, into the instance's single save slot; return to
it (``CableDyn_SaveState``, ``CableDyn_RestoreState``). The slot is a copy of every line,
point, body and rod state with its solver history. A restore keeps the slot, so one save
serves every outer corrector of a host time step, and a restore followed by a step is
bit-identical to taking that step from the saved state directly. Save when a host time
step starts after the previous one was accepted, and restore on every repeated pass from
the same start time, whatever its ``dt`` (:ref:`capi-host-coupling`). A successful
initialisation discards the slot; a failed one keeps it with the model.

:raises CableDynError: on an uninitialised model, or from :meth:`restore_state` when
nothing was saved since the model was initialised.
:raises RuntimeError: if the loaded library predates ABI 1 minor extension 2.

.. py:method:: coupled_layout()

Return the owner of each 3-DOF block of the coupled vector (``CableDyn_GetCoupledLayout``):
a tuple of ``(point_id, kind)`` pairs, block ``k`` holding the degrees of freedom
``3k .. 3k+2``. ``kind`` is ``"fixed"``, ``"coupled"`` (``Coupled`` or ``Vessel``),
``"free"`` or ``"connect"``. On a point-system deck every line-bound point has a block, in
deck ``POINTS`` order; on the coupled aggregate (finite-EI lines, bodies or rods) only the
``Coupled`` points do.

:rtype: tuple[tuple[int, str], ...]
:raises CableDynError: on an uninitialised model or one built from raw arrays.

.. py:method:: host_dofs()

Return the indices of the coupled degrees of freedom the host drives, those of the
``"coupled"`` blocks of :meth:`coupled_layout`, as an integer array. With ``x`` the
``(3, n)`` host positions of those points in layout order,
``q[model.host_dofs()] = x.reshape(-1, order="F")`` fills them in a full coupled vector.

:rtype: numpy.ndarray

.. py:property:: initialized
:type: bool

Expand Down Expand Up @@ -666,7 +730,8 @@ library is located. Array ordering, frames, and units at the coupling boundary f
.. py:property:: time
:type: float

Simulation time (s): 0 after initialisation, advanced by every completed step.
Simulation time (s): 0 after initialisation, advanced by every completed step, and set back
by :meth:`restore_state`.

.. py:property:: deck
:type: pathlib.Path | None
Expand Down Expand Up @@ -711,8 +776,10 @@ imports without the shared library.

.. py:function:: abi_minor()

Return the extension level of ABI 1 of the loaded library: 1 when it has the object queries
behind :attr:`CableDyn.lines` and :meth:`CableDyn.channel`, 0 for an older library.
Return the extension level of ABI 1 of the loaded library: 2 when it also 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.

:rtype: int

Expand Down
Loading
Loading