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
87 changes: 87 additions & 0 deletions doc/api_python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -494,6 +494,66 @@ library is located. Array ordering, frames, and units at the coupling boundary f

Release the native handle. Calling it again is harmless.

.. py:method:: init_line(q0, v0, elem_conn, l0, ea, rho_a, fixed_dofs, tension_only, rho_inf)

Initialise from one line meshed by the caller (``CableDyn_InitLine``). The model is
structural only: two-node ``EI = 0`` axial elements with a consistent mass matrix, without
gravity, buoyancy, seabed, hydrodynamics or structural damping, and without a static solve.
The handle has no deck and no points; the views of :attr:`lines` run from the last node of
``q0`` to its first.

:param q0: Initial node positions (m), flat ``(3 * n_nodes,)`` or column-per-point
``(3, n_nodes)``; a ``(3, 3)`` array is rejected as ambiguous.
:type q0: array_like
:param v0: Initial node velocities (m/s), shaped as ``q0``.
:type v0: array_like
:param elem_conn: **1-based** node pair of each element, flat ``(2 * n_elem,)`` or
``(n_elem, 2)``. An integer array.
:type elem_conn: array_like
:param l0: Unstretched length of each element (m), ``(n_elem,)``.
:type l0: array_like
:param ea: Axial stiffness of each element (N), ``(n_elem,)``.
:type ea: array_like
:param rho_a: Mass per unit unstretched length of each element (kg/m), ``(n_elem,)``.
:type rho_a: array_like
:param fixed_dofs: **1-based** DOFs the caller prescribes, in the order of the coupled
vector; node ``k`` owns DOFs ``3k-2``, ``3k-1`` and ``3k``. May be empty.
:type fixed_dofs: array_like
:param tension_only: If true an element goes slack instead of carrying compression.
:type tension_only: bool
:param rho_inf: Generalised-α spectral radius, in ``[0, 1]``.
:type rho_inf: float
:raises ValueError: on a wrong shape, a non-finite value, or ``rho_inf`` outside
``[0, 1]``, before the library is called.
:raises TypeError: on a non-real array, a non-integer index array, or a non-numeric
scalar, before the library is called.
:raises CableDynError: if the library rejects the values (an index out of range, a repeated
fixed DOF, a non-positive ``l0``, ``ea`` or ``rho_a``) or the initial acceleration solve
fails. The handle must then be initialised again and a saved state is lost, unless it
held a model on the coupled aggregate, which stays live with its save.

.. py:method:: init_lines(n_nodes, n_elem, n_fixed, q0, v0, elem_conn, l0, ea, rho_a, fixed_dofs, tension_only, rho_inf, coupled_map=None)

Initialise from several lines meshed by the caller (``CableDyn_InitLines``), each as in
:meth:`init_line`, in one system. Every array is the concatenation, in line order, of that
line's :meth:`init_line` array; ``elem_conn`` and ``fixed_dofs`` stay local to each line.

:param n_nodes: Node count of each line, at least 2.
:type n_nodes: array_like
:param n_elem: Element count of each line, at least 1.
:type n_elem: array_like
:param n_fixed: Prescribed DOF count of each line, at least 0.
:type n_fixed: array_like
:param coupled_map: Connects lines at shared points. Every line has exactly six fixed DOFs,
and entry ``6 * i + j`` (0-based ``i``, ``j``) is the **1-based** system DOF of line
``i``'s ``j``-th fixed DOF. The entries use every index from 1 to their maximum, which is
the coupled DOF count; loads and Jacobian entries of a shared DOF are summed. ``None``
keeps the lines independent, their ``fixed_dofs`` in turn forming the coupled vector.
:type coupled_map: array_like | None
:raises ValueError: as :meth:`init_line`, and if the counts do not match the arrays.
:raises TypeError: as :meth:`init_line`.
:raises CableDynError: as :meth:`init_line`, and on a ``coupled_map`` with a gap.

.. py:method:: last_error()

Return the library's most recent diagnostic message for this instance.
Expand Down Expand Up @@ -753,6 +813,33 @@ library is located. Array ordering, frames, and units at the coupling boundary f
:raises CableDynError: on a model built without a host fluid field, or if the call
fails.

.. py:method:: calc_output_derivatives(q, v, a)

Return the coupled loads at an operating point and their analytic Jacobians
(``CableDyn_CalcOutputDerivatives``). Each line's interior DOFs are condensed out: interior
positions and velocities are held and interior accelerations eliminated through the mass
matrix, so ``dload_da`` is :math:`-(M_{cc} - M_{cf} M_{ff}^{-1} M_{fc})`, and the blocks are
those of :meth:`update_states` followed by :meth:`calc_output`.

This call **sets the model state**, as :meth:`update_states` does, also when a later stage
of it fails; the previous state is not restored and :attr:`time` does not change. The
library's unused ``eps_fd`` argument is not exposed.

:param q: Operating-point positions (m).
:type q: array_like
:param v: Operating-point velocities (m/s).
:type v: array_like
:param a: Operating-point accelerations (m/s\ :sup:`2`).
:type a: array_like
:returns: ``(loads, dload_dq, dload_dv, dload_da, added_mass)``. ``loads`` is flat,
``(n_coupled_dof,)`` (N). The others are ``(n_coupled_dof, n_coupled_dof)`` with
``J[i, j]`` the derivative of load ``i`` with respect to coupled DOF ``j``: N/m, N·s/m,
kg and kg; ``added_mass`` is ``-dload_da``.
:rtype: tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]
:raises ValueError: if an array has the wrong shape or a non-finite value.
:raises CableDynError: if the library rejects the call, as on a model on the coupled
aggregate (finite-EI lines, bodies or rods), which has no load derivatives.

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

Prescribe external fluid kinematics at every system point.
Expand Down
6 changes: 4 additions & 2 deletions doc/capi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -348,8 +348,10 @@ These rules apply to every entry point. The Python package uses the same array o
``CableDyn_InitDeckAt`` on an initialised handle replaces the model only on success. If the
new initialisation fails, the previous model is kept unchanged, and so is the state saved by
``CableDyn_SaveState``; a successful one discards that save. ``CableDyn_InitLine`` and
``CableDyn_InitLines`` build the point model in place: after a failure the handle must be
initialised again, and the saved state is discarded. The one exception is a handle whose
``CableDyn_InitLines`` build the point model in place: a failure during the build leaves the
handle to be initialised again, an input rejected before it leaves the previous model live
(``CableDyn_IsInitialized`` tells which), and either way the saved state is discarded. The one
exception is a handle whose
deck model runs on the coupled aggregate (finite-EI lines, bodies or rods): a failed
``InitLine``/``InitLines`` leaves that model live, and its saved state with it.
* **Time.** The library keeps no clock. Only ``dt`` enters ``CableDyn_Step``, and the host owns
Expand Down
63 changes: 59 additions & 4 deletions doc/python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -762,10 +762,8 @@ environment variable ``CABLEDYN_BLAS_THREADS`` changes that (:doc:`capi`).
Array ordering is defined in :ref:`capi:Calling conventions`; frames, fluid fields, and
lifecycle rules are defined in :doc:`coupling_boundary`. Use this API only when the Python
process owns time integration; use ``CompMooring = 5`` for OpenFAST (:doc:`openfast`). The Python
class covers deck initialisation and the coupled step/output cycle; raw-array initialisation
(``CableDyn_InitLine`` and
``CableDyn_InitLines``) and output Jacobians (``CableDyn_CalcOutputDerivatives``) are available
through the C API (:doc:`capi`).
class covers deck initialisation, raw-array lines, the coupled step/output cycle and the load
Jacobians (see `Raw-array lines and load Jacobians`_).

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
Expand Down Expand Up @@ -831,6 +829,63 @@ start time of the pass, so a pass retried with a smaller ``dt`` restores as well
self.model.step(dt, self.q, self.v, self.a)
return self.model.calc_output()[self.host].reshape(3, -1, order="F")

Raw-array lines and load Jacobians
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:meth:`~cabledyn.CableDyn.init_line` and :meth:`~cabledyn.CableDyn.init_lines` build a model from
lines the caller has meshed, without a deck. These lines are **structural only**: two-node
``EI = 0`` axial elements with a consistent mass matrix, without gravity, buoyancy, seabed,
hydrodynamics or structural damping, and without a static solve, so the state starts at ``q0``,
``v0`` exactly. Use a deck for anything else. As in the C API, ``elem_conn``, ``fixed_dofs`` and
``coupled_map`` are **1-based**, and the order of ``fixed_dofs`` is the order of the coupled
vector:

.. code-block:: python

import numpy as np
from cabledyn import CableDyn

n_elem = 10
nodes = np.linspace(0.0, 1.0, n_elem + 1)[:, None] * [100.5, 0.0, 0.0]
first = np.arange(1, n_elem + 1)

with CableDyn() as model:
model.init_line(
q0=nodes.reshape(-1),
v0=np.zeros(nodes.size),
elem_conn=np.column_stack([first, first + 1]), # 1-based node pairs
l0=np.full(n_elem, 10.0), # m
ea=np.full(n_elem, 1.0e7), # N
rho_a=np.full(n_elem, 50.0), # kg/m
fixed_dofs=[1, 2, 3, 31, 32, 33], # both end nodes, 1-based
tension_only=True,
rho_inf=0.8,
)
q, v, a = model.get_coupled_motion()
loads, dload_dq, dload_dv, dload_da, added_mass = model.calc_output_derivatives(q, v, a)

:meth:`~cabledyn.CableDyn.init_lines` takes the counts of each line, then the same arrays
concatenated in line order, with connectivity and ``fixed_dofs`` local to each line. Its optional
``coupled_map`` connects lines at shared points; see ``CableDyn_InitLines`` in :doc:`capi`.
Shapes, non-finite values and non-integer indices raise ``ValueError`` or ``TypeError`` before the
library is called, which changes nothing. The library judges the values (an index out of range, a
repeated fixed DOF, a non-positive length) and raises :class:`cabledyn.CableDynError`; the handle
must then be initialised again, unless it held a model on the coupled aggregate, which stays live.

:meth:`~cabledyn.CableDyn.calc_output_derivatives` returns the loads at an operating point and
their analytic Jacobians, ``J[i, j]`` being the derivative of load ``i`` with respect to coupled
DOF ``j``, and works on raw lines and on decks of the point route. A model on the coupled aggregate
has no load derivatives and raises :class:`cabledyn.CableDynError`. Each line's interior DOFs are
condensed out: interior positions and velocities are held and interior accelerations eliminated
through the mass matrix, so the blocks are those of ``update_states`` followed by ``calc_output``,
the instantaneous response of the end loads to the end motion. ``added_mass`` is ``-dload_da``.

.. warning::

``calc_output_derivatives`` **sets the model state**: on return the model is at the operating
point, as after ``update_states``, and the previous state is not restored. Call
``update_states`` with the previous kinematics to return to them.

Objects and output channels
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
56 changes: 56 additions & 0 deletions python/cabledyn/_lib.py
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,46 @@ def library_path() -> str:
_lib.CableDyn_GetLastError.restype = None

_DBL = POINTER(c_double)
_INT = POINTER(c_int)

_lib.CableDyn_InitLine.argtypes = [
c_void_p,
c_int,
c_int,
_DBL,
_DBL,
_INT,
_DBL,
_DBL,
_DBL,
_INT,
c_int,
c_int,
c_double,
_INT,
]
_lib.CableDyn_InitLine.restype = None

_lib.CableDyn_InitLines.argtypes = [
c_void_p,
c_int,
_INT,
_INT,
_INT,
_DBL,
_DBL,
_INT,
_DBL,
_DBL,
_DBL,
_INT,
_INT,
c_int,
c_int,
c_double,
_INT,
]
_lib.CableDyn_InitLines.restype = None

_lib.CableDyn_UpdateStates.argtypes = [c_void_p, _DBL, _DBL, _DBL, c_int, POINTER(c_int)]
_lib.CableDyn_UpdateStates.restype = None
Expand All @@ -108,6 +148,22 @@ def library_path() -> str:
_lib.CableDyn_CalcOutput.argtypes = [c_void_p, _DBL, c_int, POINTER(c_int)]
_lib.CableDyn_CalcOutput.restype = None

_lib.CableDyn_CalcOutputDerivatives.argtypes = [
c_void_p,
_DBL,
_DBL,
_DBL,
c_int,
c_double,
_DBL,
_DBL,
_DBL,
_DBL,
_DBL,
_INT,
]
_lib.CableDyn_CalcOutputDerivatives.restype = None

_lib.CableDyn_GetCoupledMotion.argtypes = [c_void_p, _DBL, _DBL, _DBL, c_int, POINTER(c_int)]
_lib.CableDyn_GetCoupledMotion.restype = None

Expand Down
Loading
Loading