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
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,18 @@ All notable changes to CableDyn are recorded in this file. The format follows
cable's fairlead to the restored input mesh, whose last bits differ from the boundary the
uninterrupted run committed, and the cable's `.CD.out` channels drifted by up to 1e-6
(relative) within seconds. The checkpoint now carries the cable's committed boundary.
- A finite-EI line longer than its span with no net weight, or too little for its bending
stiffness (0.001 N/m on a 120 m line with `EI` 1e4 N m²), failed its static solve: both routes
reached the compressed straight strut or stalled at the round-off of the axial forces. Such a
line is now solved heavier and carried back to its own weight in the vertical plane of its
chord. A weightless line bows as the Euler elastica (end thrust and bow to 3e-5 of the exact
solution); nothing in the deck chooses the side of its bow, so it is solved bowed downward and
a note says so. With its ends one above the other it is still refused, by name.
- A line along +X reported its tangent azimuth (`L<L>N<J>Azi`, the static profile's `Azimuth`)
at 0 or about 360 from one row to the next as it swayed a fraction of a degree to either
side, or by the sign of a round-off component: in OpenFAST about half the rows of a cable in
the x-z plane read 359.9x. A line whose chord heads within 45° of +X now reports its azimuths
in (−180, 180], every other line in [0, 360) as before.

## [0.3.0] - 2026-10-23

Expand Down
26 changes: 23 additions & 3 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2458,9 +2458,14 @@ function(cabledyn_msg_test name deck rc must_match must_not)
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
set_tests_properties(driver_msg_${name} PROPERTIES LABELS "fortran;driver;integration;static")
endfunction()
# A neutrally buoyant finite-EI line longer than its span has no catenary and no tension-only bow.
cabledyn_msg_test(weightless_finite_ei msg_weightless_finite_ei.dat 2
"weightless .neutrally buoyant. line is longer than its span;shorten the line to its span, or give it net weight"
# A neutrally buoyant finite-EI line longer than its span has no catenary: it bows under the
# compression its bending stiffness carries, and the run says that nothing chose the bow's side.
cabledyn_msg_test(weightless_finite_ei msg_weightless_finite_ei.dat 0
"line 1 is weightless and longer than its span, so it bows;solved bowed downward in the vertical plane"
"net-heavy")
# With its ends one above the other nothing chooses the side of the bow either: refused, by name.
cabledyn_msg_test(weightless_finite_ei_vertical msg_weightless_finite_ei_vertical.dat 2
"weightless .neutrally buoyant. line is longer than its vertical span;nothing chooses the side of the bow;offset its ends horizontally"
"net-heavy")
# An EI=0 line type rejected as net-buoyant whose mass is a relative 4e-9 below the displaced water
# mass is named weightless and slack; one a relative 2e-6 below it keeps the plain message.
Expand Down Expand Up @@ -2601,6 +2606,21 @@ if(Python3_Interpreter_FOUND)
else()
message(STATUS "statics_robustness_matrix: skipped (numpy/scipy not importable in ${Python3_EXECUTABLE})")
endif()
# A finite-EI line longer than its span with little or no net weight: the weightless bow is the
# pinned-pinned elastica, light lines bow toward their weight, and a march from the bow stays at rest.
if(_statics_matrix_deps_rc EQUAL 0)
add_test(
NAME light_slack_statics
COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_light_slack_statics.py
--exe $<TARGET_FILE:cabledyn>
--output ${CMAKE_CURRENT_BINARY_DIR}/light_slack_statics)
set_tests_properties(light_slack_statics PROPERTIES
LABELS "python;driver;integration;static;validation"
TIMEOUT 600
ENVIRONMENT "${_cabledyn_python_test_environment}")
else()
message(STATUS "light_slack_statics: skipped (numpy/scipy not importable in ${Python3_EXECUTABLE})")
endif()
endif()

add_executable(test_driver_channels tests/test_driver_channels.f90)
Expand Down
20 changes: 18 additions & 2 deletions doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ finite-EI line of the run:
- signed inclination below horizontal, ``Declination − 90``
* - ``Azimuth``
- ``(deg)``
- axial-tangent azimuth from +X toward +Y, in [0, 360)
- axial-tangent azimuth from +X toward +Y, in the line's range (:ref:`outputs-azimuth-range`)
* - ``DeckNode``
- ``(-)``
- the deck node of the row, the ``<J>`` of the node channels (1 = End A … 1 + the total
Expand Down Expand Up @@ -486,6 +486,21 @@ fairlead) runs from its fairlead here (:doc:`migrating`), so its ``N<J>`` is Moo
``N<NumSegs+1-J>``. The per-line files (``Node<J>…`` columns) number the same way. A run whose
outputs name line nodes says so in a note, and ``N0`` is rejected rather than read as another node.

.. _outputs-azimuth-range:

Azimuth range
~~~~~~~~~~~~~

The azimuth of a line's tangent (``L<L>N<J>Azi``, the ``Azimuth`` column of the static profile
and the azimuth of the initialisation summary) is reported in **(−180, 180]** on a line whose
chord from End A to End B, at the deck positions, heads within 45° of +X, and in **[0, 360)** on
every other line. The cut of a line's range then lies at least 45° from its heading: a line
swaying about its heading reads continuously, where a line along +X would otherwise jump
between 0 and 360 as it moves a fraction of a degree to either side. The range is fixed for
the run, so the motion of the line cannot switch it. A round-off component across the cut
reads on its included side (0, or 180 in the signed range), and one across +X reads exactly 0.
A line a host builds through the C interface without a deck reports [0, 360).

.. _outputs-refined-nodes:

Node channels on a refined line
Expand Down Expand Up @@ -691,7 +706,8 @@ Line-node channels
- declination of the node's axial tangent from +Z (0 = up, 90 = horizontal, 180 = down)
- deg
* - ``L<L>N<J>Azi``
- azimuth of the node's axial tangent from +X toward +Y, in [0, 360)
- azimuth of the node's axial tangent from +X toward +Y, in the line's range
(:ref:`outputs-azimuth-range`)
- deg
* - ``Torq<L>N<J>``
- torque (twisting moment) at node ``J`` of a line restrained in torsion at both ends
Expand Down
11 changes: 11 additions & 0 deletions doc/solver_paths.rst
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,17 @@ Every attempt uses the same physical inputs, tolerance, and acceptance checks. N
contact hierarchy are projected to the declared floor before polishing; this changes only the
prolonged seed, never the contact law or the final equations.

**Weight continuation** (a light slack line). A line longer than its span with too little net
weight for its bending stiffness (:math:`|w| < 100\,EI/L^3`) has no catenary to start from, and
both routes can end on the compressed straight strut or stall at the round-off of its axial
forces. When both fail, the line is solved heavier, with :math:`100\,EI/L^3` of the sign of its
net weight added (downward for a weightless line), and that equilibrium is carried back to its
own weight in the vertical plane of its chord, accepting the round-off floor of the axial
forces. It applies to a planar line in still water over a level seabed, without attachments or
``tensile_safety True``, whose chord is not vertical. A weightless line bows as the Euler
elastica; nothing in the deck chooses the plane or the side of the bow, and a note says how it
was solved (:doc:`theory`).

**Acceptance checks.** A residual-converged state is rejected when the sampled
:math:`\max(L_0\,\kappa)` of any element exceeds 0.7 (an unresolved fold). With
``adaptive_mesh = True``, exhausting the refinement cap while curvature resolution or
Expand Down
5 changes: 3 additions & 2 deletions doc/standalone_driver.rst
Original file line number Diff line number Diff line change
Expand Up @@ -142,8 +142,9 @@ force inclination differs slightly from the tangent inclination because the end
the end node's share of the distributed load (and, on a finite-EI line, the end shear).
``declination`` is the angle from global ``+Z`` (the convention also used by OrcaFlex): 0 degrees
up, 90 degrees
horizontal, and 180 degrees down. ``azimuth`` is measured from global ``+X`` toward ``+Y`` in
``[0, 360)``. Therefore ``inclination = declination - 90 degrees``; the two values are printed
horizontal, and 180 degrees down. ``azimuth`` is measured from global ``+X`` toward ``+Y``, in
``(-180, 180]`` on a line heading within 45 degrees of ``+X`` and in ``[0, 360)`` otherwise
(:ref:`outputs-azimuth-range`). Therefore ``inclination = declination - 90 degrees``; the two values are printed
together deliberately so the convention is auditable.

For the production Hermite finite-EI route, the reported vector is the complete fairlead reaction,
Expand Down
26 changes: 26 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1479,6 +1479,32 @@ mesh-sequenced route described below first and this route as its fallback):
mesh-sequenced solve below, audited alike. On the Lozon cables the two routes give the same
equilibrium to the solver tolerance (positions within 2e-5 m, curvature within 1e-6 1/m).

A line longer than its span with little net weight for its bending stiffness has no catenary
to start from. With no weight at all it bows under the axial compression its bending stiffness
carries, the Euler elastica (about :math:`\pi^2 EI/L^2`). Both routes can then end on the
compressed straight strut, a saddle, or stall at the round-off of the axial forces,
:math:`EA\,\varepsilon\,|\mathbf r|/h` (the axial strain is formed from coordinate differences over
an element of length :math:`h`), which a weightless line's unit force scale puts above the
tolerance. When both routes fail on a slack line with :math:`|w| < 100\,EI/L^3` (largest
:math:`EI`), the line is solved with the auxiliary weight :math:`w_a = 100\,EI/L^3` added to every
element, of the sign of its net weight and downward for a weightless one, which the routes
handle. That equilibrium is carried back to the line's own weight by a continuation in the
weight, held in the vertical plane of the chord: steps of a quarter of the remaining
:math:`w_a`, the last from :math:`w_a/256` to none, a failed step halved. The steps accept the
round-off floor :math:`8\,EA\,\varepsilon\,|\mathbf r|_{\max}/h_{\min}` of the axial forces when it
lies above the tolerances of the routes, and a floor above the static tolerance is reported as
for the routes. The result is audited and checked for stability like theirs. The continuation
runs on a planar line in still water over a level seabed, without attachments or
``tensile_safety True``, whose chord is not vertical (the auxiliary weight must have a
component across it). For a weightless line nothing in the deck chooses the plane or the side
of the bow: the limit of a vanishing weight puts it on the lower side in the vertical plane of
the chord, and a note says so. Its tangent there has one zero eigenvalue, the bow turning about
the chord: the planar solve holds that mode, and a dynamic run leaves it free and at rest. On a
pinned 120 m line
with its ends 113 m apart the end thrust and the mid-span bow match the inextensible elastica,
:math:`P = 4K(m)^2EI/L^2` and :math:`\delta = \sqrt{m}\,L/K(m)` with
:math:`\text{chord}/L = 2E(m)/K(m) - 1`, to :math:`3\times10^{-5}` and :math:`10^{-6}` relative.

A deck current loads the line at rest with its steady Morison drag (the relative velocity is
the current itself; the element fluid velocity is the mean of the current at its two nodes,
as in the dynamics). The drag follows the line and is not a potential force: it is carried
Expand Down
25 changes: 17 additions & 8 deletions doc/troubleshooting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -488,14 +488,23 @@ but a few geometries are genuinely hard:
- **A large grounded touchdown on the** ``EI = 0`` **path.** A long, near-horizontal grounded run can
make the linear-Lagrange tangent singular regardless of seed. If the case is a lazy-wave or
bending-dominated cable, use the finite-EI path (``EI > 0``), which is built for it.
- **A weightless finite-EI line longer than its span.** ``the weightless (neutrally buoyant)
line is longer than its span`` means every element has zero net weight (to a relative 1e-6 of
its displaced weight, attachments included). Such a line has no catenary: with no weight a
tension-only line is straight, and a longer one could only bow by bending under axial
compression, which a cable does not carry. Shorten the line to its span, or give it net weight
(a larger ``MassDenInAir``, or clumps) or a tension that holds it taut. A line heavier than
water with the same symptom gets ``the net-heavy line is too long for its span to hang as a
catenary`` instead.
- **A weightless finite-EI line longer than its span.** Every element has zero net weight (to a
relative 1e-6 of its displaced weight, attachments included), so the line has no catenary: it
bows under the axial compression its bending stiffness carries (the Euler elastica). It is
solved, with the note ``line N is weightless and longer than its span``: nothing in the deck
chooses the plane or the side of the bow, so it is solved bowed downward in the vertical plane
through its ends, the limit of a vanishing net weight, and the bow can turn about the chord at
no cost. If the line has a net weight, however small, give it (``MassDenInAir``) to settle
the shape; a light line, heavy or buoyant, bows toward its weight
(:doc:`solver_paths`, weight continuation). With its ends one above the other nothing chooses
the side of the bow: ``the weightless (neutrally buoyant) line is longer than its vertical
span`` stops the run. In a current, with attachments, over a non-level seabed, under
``tensile_safety True`` or with an end connection out of the plane of the chord the
continuation does not apply, and a line the routes cannot solve stops with ``the weightless
(neutrally buoyant) line is longer than its span``. Shorten the line to its span, or give it
net weight (a larger ``MassDenInAir``, or clumps) or a tension that holds it taut. A line
heavier than water that is too long for its span gets ``the net-heavy line is too long for
its span to hang as a catenary`` instead.
- **A finite-EI lazy-wave cable at too coarse a mesh.** An under-resolved arch or touchdown
carries a large element ``h·κ`` and can stall the dynamic Newton. The resolution metric flags
this; the builder can auto-refine a fragile mesh when the deck opts in (``adaptive_mesh True``).
Expand Down
13 changes: 6 additions & 7 deletions python/tests/test_native_model.py
Original file line number Diff line number Diff line change
Expand Up @@ -373,15 +373,14 @@ def test_home_relative_deck_path_is_expanded(tmp_path, monkeypatch):


def test_long_failure_message_is_kept_whole():
# The weightless-line diagnosis names the cause, three nested solver reasons, and the
# remedy; it is longer than the 1024 characters the handle once retained, and its closing
# advice must reach the caller.
deck = REPO / "tests" / "data" / "msg_weightless_finite_ei.dat"
# A deck path of 1100 characters that does not exist: the diagnosis names the whole path and
# the reason, longer than the 1024 characters the handle once retained, and its closing
# reason must reach the caller.
deck = "missing_" + "d" * 1100 + ".dat"
with cabledyn.CableDyn() as m:
with pytest.raises(CableDynError) as caught:
m.init_deck(deck)
detail = caught.value.detail
assert len(detail) > 1024
assert "weightless (neutrally buoyant) line is longer than its span" in detail
assert detail.endswith("or a tension that holds it taut")
assert "net-heavy" not in detail
assert "cannot open deck: " in detail and deck in detail
assert detail.endswith("(file not found)")
Loading
Loading