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
23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -321,6 +321,29 @@ All notable changes to CableDyn are recorded in this file. The format follows
`vreg F/(mu N)`) where it slid back and forth at a few mm/s. This changes the results of decks
with rods or bodies on a frictional seabed; none of the shipped examples or existing tests has
one.
- Node output channels of a finite-EI line whose mesh the static solve refined read the wrong
node, silently. `Ten<L>N<J>`, `Curv<L>N<J>`, `BendMom<L>N<J>`, `L<L>N<J>p/v/a{x,y,z}`,
`L<L>N<J>Dec`/`Azi`, `Torq<L>N<J>` and `Twist<L>N<J>` name a deck node (1 + the total
`NumSegs` of the line's sections) and are checked against that count, but after an automatic
refinement (adaptive, stability or curvature refinement) they reported node `J` of the refined
mesh. On the lazy-wave cable of `tests/data/lazy_wave_touchdown_planar_coarse.dat` with its top
section cut from 20 to 4 elements (refined from 71 to 1136 elements), `Ten4N34`, the deck node
at the 220 m touchdown, reported 5488 N, the tension at 41 m from End A, against 1544 N, and
`BendMom4N54`, on the seabed at 420 m, 1214 N·m against 0. Each refined line now maps its deck
nodes onto the final mesh by their unstretched arc length from End A (an exact match, which
does not assume a uniform refinement; a deck node not on the mesh fails closed), and the node
channels read deck nodes on every route: standalone static and dynamic cubic-Hermite, mixed
`EI = 0` + finite-EI, multibody, OpenFAST and the C API `CableDyn_EvalChannel`. `.static.out`,
the range graphs, the per-line files and `CableDyn_GetLineValues` still list every node of the
refined mesh; `.static.out` then carries a `DeckNode` column naming the deck node of each row
(0 for a node the refinement added), `.Line<L>.p.out` a `# DeckNode` comment line (also on the
multibody march, which writes no `.static.out`), and the new C API quantity
`CD_C_LINE_DECK_NODE` (10) of `CableDyn_GetLineValues`, Python `Line.deck_nodes`, gives the
same numbering in process. The Python `StaticProfile.deck_node_arc_lengths`,
`LineNodeHistory.deck_nodes`, `node_range_graph`, `profile_at`/`profiles_at` and
`line_range_graph` place main-output node channels at their deck node, from a static profile,
a per-line position file or `LinePositions` read from one. `EI = 0` lines are never refined, and every output of a deck whose meshes are
not refined is unchanged. See the manual's output reference (Node channels on a refined line).

- Tension spikes of tension-only (`EI = 0`) lines that go slack. The generalised-α step evaluated
the axial force and the dynamic loads at the blended configuration
Expand Down
24 changes: 24 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1503,6 +1503,30 @@ if(Python3_Interpreter_FOUND)
message(STATUS "anchor_uplift_channels: skipped (numpy not importable in ${Python3_EXECUTABLE})")
endif()

# Node channels on a refined finite-EI line name deck nodes: the static profile's DeckNode
# column, the standalone static and dynamic cubic-Hermite routes, the mixed route (the OpenFAST
# aggregate evaluator) and the C API on the coarse lazy-wave deck the static solve refines
# (needs numpy).
if(_range_tdp_numpy_rc EQUAL 0)
if(WIN32 AND CABLEDYN_RUNTIME_DLLS)
set(_node_channels_library "${CMAKE_BINARY_DIR}/runtime/$<TARGET_FILE_NAME:cabledyn_shared>")
else()
set(_node_channels_library "$<TARGET_FILE:cabledyn_shared>")
endif()
add_test(NAME node_channels_refined_line
COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_node_channels_refined.py
--exe $<TARGET_FILE:cabledyn>
--deck ${CMAKE_CURRENT_SOURCE_DIR}/tests/data/lazy_wave_touchdown_planar_coarse.dat
--output ${CMAKE_BINARY_DIR}/node_channels_refined_line
--library ${_node_channels_library})
set_tests_properties(node_channels_refined_line PROPERTIES
LABELS "python;integration;static;dynamic;capi"
TIMEOUT 600
ENVIRONMENT "${_cabledyn_python_test_environment}")
else()
message(STATUS "node_channels_refined_line: skipped (numpy not importable in ${Python3_EXECUTABLE})")
endif()

# The arbiter imports numpy + scipy at load time; only register the test when they are
# importable, so an image with python3 but without those packages does not fail the
# validation suite with ModuleNotFoundError before any CableDyn gate runs.
Expand Down
22 changes: 17 additions & 5 deletions doc/capi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1760,16 +1760,21 @@ handle numbers its lines 1..n).
* - ``CableDyn_NObjects``
- number of objects of ``kind``
* - ``CableDyn_GetObjectInfo``
- ``id``; ``n_nodes`` (lines: node count; rods: ``NumSegs + 1``; points and bodies: 1);
- ``id``; ``n_nodes`` (lines: node count of the final mesh; rods: ``NumSegs + 1``; points and
bodies: 1);
``subtype`` (lines: 1 finite-EI, 0 EI = 0; points: 1 Fixed, 2 Coupled, 3 Free,
4 Connect)
* - ``CableDyn_GetLineValues``
- one quantity along the line, End A first: ``CD_C_LINE_POSITION`` (1),
- one quantity at every node of the line's final mesh, End A first:
``CD_C_LINE_POSITION`` (1),
``_VELOCITY`` (2), ``_ACCELERATION`` (4), 3 values per node, xyz interleaved;
``_TENSION`` (3, the ``Ten<L>N<k>`` node tension), ``_CURVATURE`` (5),
``_BEND_MOMENT`` (6, zero on an EI = 0 line), ``_DECLINATION`` (7), ``_AZIMUTH`` (8),
one value per node; ``_SEGMENT_TENSION`` (9), one value per segment. ``n_out`` must
equal the value count.
one value per node; ``_SEGMENT_TENSION`` (9), one value per segment;
``_DECK_NODE`` (10), one value per node: the deck node ``J`` of the node (the ``<J>``
of the node channels), 0 for a node a mesh refinement added, ``1 … n_nodes`` on a line
meshed as the deck. ``n_out`` must equal the value count. A library without code 10
rejects it with ``CD_C_BAD_INPUT``.
* - ``CableDyn_GetPointState``
- position, velocity and the resultant force of the attached lines (``Point<P>F``),
3 doubles each
Expand All @@ -1782,7 +1787,14 @@ handle numbers its lines 1..n).
of End A with the axis roll and pitch from vertical; velocity and wrench about End A
* - ``CableDyn_EvalChannel``
- the value of one ``OUTPUTS`` token (:doc:`outputs`), for example ``FairTen1``,
``L2N5px``, ``Curv1N3``, ``Point4Fz``, ``Body1Pz`` or ``Rod2TenA``
``L2N5px``, ``Curv1N3``, ``Point4Fz``, ``Body1Pz`` or ``Rod2TenA``; a line-node token
names a deck node

On a finite-EI line whose mesh the static solve refined, ``n_nodes`` and the
``CableDyn_GetLineValues`` arrays cover every node of the refined mesh, while a node token of
``CableDyn_EvalChannel`` (``Ten1N5``, ``L1N5px``) names deck node 5 at its node of that mesh
(:ref:`outputs-refined-nodes`); ``CD_C_LINE_DECK_NODE`` locates it: the array row whose value is
5.

A ``NULL`` output pointer skips that output, except for the ``out`` array of
``CableDyn_GetLineValues`` and the ``value`` of ``CableDyn_EvalChannel``; the latter is not
Expand Down
3 changes: 2 additions & 1 deletion doc/options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -376,7 +376,8 @@ Finite-EI cable controls
keeps the declared ``NumSegs`` authoritative but does not disable the folded-element
safety check, nor the automatic refinement of a deck mesh that cannot resolve the
curvature of the equilibrium (reported). When ``True``, reaching the refinement cap while
the mesh remains fragile is reported
the mesh remains fragile is reported. Node output channels keep naming the deck nodes
on a refined mesh (:ref:`outputs-refined-nodes`)
- both (finite-EI lines)
- ``True adaptive_mesh``
* - ``alpha_force_blend`` / ``alphaforceblend``
Expand Down
46 changes: 41 additions & 5 deletions doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -183,15 +183,18 @@ Example (static route)::
----------------------------------------------

The along-arc static configuration, one row per node of every line (a *range graph* of the static
state). It is independent of the ``OUTPUTS`` selection. On a dynamic cubic-Hermite or mixed
state): every node of the line's final mesh, so a finite-EI line whose mesh the static solve
refined has more rows than deck nodes (see :ref:`outputs-refined-nodes`). It is independent of
the ``OUTPUTS`` selection. On a dynamic cubic-Hermite or mixed
run it records the converged initial state that the march starts from.

Layout: title line, header row, **units row**, then data. The title reads
``CableDyn static configuration profile (deformed arc; public node order EndA -> EndB)``
(static route), ``CableDyn standalone static configuration (deformed arc; public node order
End A -> End B)`` (cubic-Hermite route) or ``CableDyn coupled static configuration (deformed
arc; public node order End A -> End B)`` (mixed route and OpenFAST). The columns are identical
on every route:
on every route; the ``DeckNode`` column follows only when the static solve refined the mesh of a
finite-EI line of the run:

.. list-table::
:header-rows: 1
Expand Down Expand Up @@ -231,6 +234,12 @@ on every route:
* - ``Azimuth``
- ``(deg)``
- axial-tangent azimuth from +X toward +Y, in [0, 360)
* - ``DeckNode``
- ``(-)``
- the deck node of the row, the ``<J>`` of the node channels (1 = End A … 1 + the total
``NumSegs`` of the line's sections = End B); 0 for a node the refinement added. An
``EI = 0`` line, never refined, numbers its rows as the deck. Written only when a line's
mesh was refined

Plot ``Curvature`` or ``Tension`` against ``ArcLength`` for a fatigue or strength check.

Expand Down Expand Up @@ -335,9 +344,13 @@ channels instead) and accept ``r``.
moment, declination and seabed clearance (and torque and twist on a line with torsion),
one row per node (see below)

``<L>`` is the deck line id. Each file starts with a ``#`` comment line (e.g.
``<L>`` is the deck line id. The files list every node and segment of the line's final mesh,
also on a finite-EI line whose mesh the static solve refined (:ref:`outputs-refined-nodes`).
Each file starts with a ``#`` comment line (e.g.
``# CableDyn static line node positions; public node order EndA -> EndB``) and a header row;
there is no units row — units are in the column names.
there is no units row — units are in the column names. On a refined line the ``.p.out`` file
has a second comment line, ``# DeckNode`` followed by one tab-separated integer per node: the
deck node of that node, 0 for a node the refinement added.

.. list-table::
:header-rows: 1
Expand Down Expand Up @@ -381,7 +394,8 @@ End A -> End B)``.
- Meaning
* - ``Node``
- ``(-)``
- node number, 1 = End A … N = End B
- node number of the line's final mesh, 1 = End A … N = End B (the ``Node`` of
``.static.out``)
* - ``ArcLength``
- ``(m)``
- cumulative deformed chord length from End A at the first sample (``t = 0``, the static
Expand Down Expand Up @@ -463,6 +477,28 @@ numeric id written with leading zeros (``Ten1N02`` = ``Ten1N2``), or an alias sp
``LINES`` and ``POINTS`` ids (not array positions); ``<J>`` is a node number on line ``<L>``,
1 = End A to ``N`` = End B, where ``N`` = 1 + the total ``NumSegs`` of the line's sections.

.. _outputs-refined-nodes:

Node channels on a refined line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``<J>`` is always a node of the **deck** mesh. The static solve of a finite-EI line can refine
its mesh (``OPTIONS adaptive_mesh``, or the automatic refinement after a failed stability test
or an unresolved curvature, which a note of the initialization report names). A refinement splits
deck elements, so each deck node is a node of the refined mesh at the same unstretched arc length
from End A, and ``Ten<L>N<J>``, ``Curv<L>N<J>``, ``BendMom<L>N<J>``, ``L<L>N<J>…``,
``Torq<L>N<J>`` and ``Twist<L>N<J>`` report deck node ``J`` there, on every route (standalone,
mixed, multibody, OpenFAST and the C API ``CableDyn_EvalChannel``). ``.static.out``, the range
graphs, the per-line files and the C API ``CableDyn_GetLineValues`` list every node of the
refined mesh instead, and ``.elements.out`` every element. To find deck node ``J`` among them,
take the ``.static.out`` row whose ``DeckNode`` is ``J``: its ``Node`` is the node number in the
range graph and the per-line files (and the array row + 1 of ``CableDyn_GetLineValues``), its
``ArcLength`` the node's deformed arc length. The ``# DeckNode`` line of ``.Line<L>.p.out`` gives
the same numbering on routes that write no ``.static.out`` (the multibody march), and the C API
quantity ``CD_C_LINE_DECK_NODE`` (Python ``Line.deck_nodes``) in process. The deck node also lies
where the ``ReferenceArcStart`` of ``.elements.out`` equals its unstretched arc length from End A
(``ReferenceArcEnd`` of the last element for End B). ``EI = 0`` lines are never refined.

Line-end channels
~~~~~~~~~~~~~~~~~

Expand Down
4 changes: 3 additions & 1 deletion doc/python_postprocessing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -329,7 +329,9 @@ moment along a line, with ``plot()`` and ``export()``:
functions below rebuild envelopes from other files.
* :func:`cabledyn.node_range_graph` builds it from the ``Ten<L>N<J>``, ``Curv<L>N<J>``, or
``BendMom<L>N<J>`` channels of a main output over a time window. Node positions come from a
static profile of the run, a ``{node: arc}`` mapping, or the node numbers.
static profile of the run, a ``{node: arc}`` mapping, or the node numbers. The channels name
deck nodes; on a line whose mesh the static solve refined, the profile's ``DeckNode`` column
places them (:ref:`outputs-refined-nodes`).
* :func:`cabledyn.static_range_graph` builds it from a ``.static.out`` profile.
* :func:`cabledyn.element_range_graph` builds it from a cubic-Hermite ``.elements.out`` table:
the peak curvature or bend moment of each element, where it occurs between the nodes, or the
Expand Down
4 changes: 3 additions & 1 deletion python/cabledyn/model.py
Original file line number Diff line number Diff line change
Expand Up @@ -394,7 +394,9 @@ def channel(self, token: str) -> float:

``token`` uses the deck OUTPUTS vocabulary (``FairTen1``, ``L2N5px``,
``Curv1N3``, ``Point4Fz``, ``Body1Pz``, ``Rod2TenA``, ...) and returns the
value the standalone driver writes for that channel at the same state.
value the standalone driver writes for that channel at the same state. A
node channel names a deck node, also on a finite-EI line whose mesh the
static solve refined.
"""
with self._lock:
self._object_views()
Expand Down
36 changes: 33 additions & 3 deletions python/cabledyn/objects.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,9 @@
"segment_tension": (9, 1),
}

#: C ABI code of the deck node of each mesh node (``CD_C_LINE_DECK_NODE``).
_LINE_DECK_NODE = 10

PointKind = Literal["fixed", "coupled", "free", "connect"]
_POINT_KINDS: dict[int, PointKind] = {1: "fixed", 2: "coupled", 3: "free", 4: "connect"}

Expand Down Expand Up @@ -147,9 +150,12 @@ def _check(self, call: str, status: int) -> None:
class Line(_View):
"""One line (mooring line or cable) of an in-process model.

Nodes run from End A (index 0) to End B, the order of the ``L<L>N<k>`` output
channels (node ``k`` is array row ``k - 1``) and of the ``.Line<L>.p.out``
files. Segments run in the same order.
Nodes run from End A (index 0) to End B, the order of the ``.Line<L>.p.out``
files; segments run in the same order. The arrays hold every node of the
line's final mesh. The output channels (:meth:`~cabledyn.CableDyn.channel`,
``Ten<L>N<J>``, ``L<L>N<J>px``, ...) name deck nodes: on the deck mesh deck
node ``J`` is array row ``J - 1``; on a finite-EI line whose mesh the static
solve refined, :attr:`deck_nodes` locates them among the mesh nodes.
"""

_kind = OBJ_LINE
Expand All @@ -165,6 +171,30 @@ def n_segments(self) -> int:
"""Segment (element) count, ``n_nodes - 1``."""
return self._info.n_nodes - 1

@property
def deck_nodes(self) -> npt.NDArray[np.int64]:
"""Deck node of each node of the final mesh ``(n_nodes,)``.

Entry ``k`` is the deck node ``J`` (the ``<J>`` of the node output
channels) at array row ``k``, or 0 for a node a mesh refinement added.
On the deck mesh it is ``1 .. n_nodes``. Rows of the line arrays at deck
node ``J`` are ``numpy.flatnonzero(line.deck_nodes == J)``.

Raises
------
CableDynError
If the library predates this query (``CD_C_LINE_DECK_NODE``).
"""
buf = _buffer(None, (self.n_nodes,))
with self._model._lock:
handle = self._handle()
status = c_int()
self._model._lib.CableDyn_GetLineValues(
handle, self.index, _LINE_DECK_NODE, _dbl(buf), buf.size, byref(status)
)
self._check("CableDyn_GetLineValues", status.value)
return np.rint(buf).astype(np.int64)

@property
def finite_ei(self) -> bool:
"""Whether the line carries bending stiffness (the cubic-Hermite element)."""
Expand Down
Loading
Loading