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
63 changes: 63 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,69 @@ All notable changes to CableDyn are recorded in this file. The format follows
is still unstable on the refined mesh stops as before. Decks that solved before give the
same results. `tests/data/lazy_wave_touchdown_torsion_coarse.dat` is the regression case,
solved with each route first.
- A finite-EI line over a bathymetry that is not a plane along its chord no longer fails its
statics on a few centimetres of roughness. The catenary seed is laid on the plane fitted to
the bathymetry along the chord, which need not pass through the anchor, and it was rejected
as soon as a node dipped about 1e-6 of the line length below that plane. The
catenary-continuation route then stopped at once, and the mesh-sequenced fallback often ended
on a kinked branch ("unresolved/kinked equilibrium"). In a sweep of a chain on a rough
seabed, 39 of 96 runs on a 25 m survey grid failed this way, at every roughness from 2 cm to
0.5 m. The seed is now measured against the actual bed: a node deeper below it than its
static penalty penetration (submerged weight over `kBot` × `Diam` × length) is lifted onto
the bed, a shallower one is left to the contact solve, and the continuation, which queries
the full surface, settles the contact. The equilibrium is audited, tested for stability and
checked for kinks as before. A line too long for the fitted plane is also walked into place
from a retreated anchor over such a bathymetry (the moved anchor kept at its height above
the bed under it); as the bed can hold the excess length in its dips, a failed walk there
is not reported as proof that the line is too long, and the mesh-sequenced route still runs.
All 192 finite-EI runs of the sweep now solve, within 1 % of the fairlead force on a mesh
four times finer and 0.8 % of the `EI = 0` line. Decks over a flat seabed or a planar
bathymetry are unchanged, and so are all shipped examples and test decks. A deck over a
non-planar bathymetry that solved before can now take the catenary-continuation route
instead of the mesh-sequenced one, or start from a seed lifted out of a bump: in the sweep
29 of 153 such runs changed, the fairlead force by at most 0.03 % and the anchor tension by
at most 2.2 % (on 0.5 m roughness, where the anchor tension of the same deck differs by up
to 13 % on a mesh four times finer). The decks `ROUGH_1001` to `ROUGH_1003` of the cable
statics matrix (with mesh twins) are the regression cases.
- A line resting in a trench, a valley or a pit of a gridded bathymetry now has a static
equilibrium. Along every interior grid line the bilinear surface has a crease, and a node on
it took the normal of one adjacent cell, so a node that had to rest in a concave crease was
pushed back across it from either side and had no equilibrium. An `EI = 0` chain whose
frictionless tension falls to zero inside a trench (its excess length resting slack at the
bottom) failed with "no admissible static equilibrium", and so did a grounded run on a
two-dimensional rough seabed, which slides sideways into a valley along a grid line; a
finite-EI line on such a seabed could fail its first dynamic step. Each crease is now
rounded within a band of half-width 5 % of the smaller grid spacing next to its line, by
the cubic fillet `J (d - |u|)^3 / (6 d^2)` of the slope jump `J` across the line, applied as
a tensor product in both directions, so that the surface is twice continuously
differentiable. It moves the surface by at most `|J| d / 6` along one line (1.7 cm for a
slope jump of 0.2 on a 10 m grid; at a crossing of two lines the two roundings add), and a
grid that is exactly planar, and every patch without a crease (one that would move the
surface by less than 1 µm), keep the bilinear surface bit for bit; the rounding errors of a
plane written to two or three decimals are themselves creases and are rounded by a fraction
of a millimetre. In a band the elastic contact force is the gradient of the penalty
potential of the normal penetration (up to the twist of a bilinear cell, which the tangent
leaves out as before), with its Hessian as the tangent, in the statics and the dynamics
alike. Every bathymetry query uses
this surface, the Python `Bathymetry` and its seabed clearance included. A `Fixed` point at
the tabulated depth of a creased grid node rests on the seabed and is placed on the rounded
surface. In the statics campaign the `EI = 0` decks on bathymetry solve 40 of 43 (32
before; the three left have anchors below the seabed), a 30 m trench now solves at every
depth from 2 m to 30 m (5 of 11 before), with the anchor tension `w` times the trench depth
as for a chain piled at the bottom (the fairlead tension within 0.15 % of the same trench
sampled with a level bottom cell, on a mesh four times finer), and the `EI = 0` rough-seabed
sweep solves 192 of 192 (191). Decks over a flat seabed or a planar bathymetry are unchanged, and so are all shipped
examples and test decks. Decks over creased bathymetries that solved before change: the
fairlead tension by at most 0.04 % (0.4 % for an `EI = 0` run that settles in another valley
of a two-dimensional rough seabed), the anchor tension by up to 8.5 %. The rounding removes
horizontal reactions of the one-sided normals: on a 2 m trench the two ends' horizontal
forces now agree to 0.02 % (1.2 % before), and the anchor tension of a finite-EI line on a
rough two-dimensional seabed is half as far from the one on a mesh four times finer. The
decks `trench_touchdown_pile`, `trench_grounded_run_pile` and `rough2d_seabed` of the `EI = 0`
statics robustness matrix are the regression cases, with an independent nodal force balance
on the rounded surface. When the anchor walk of a finite-EI line over a non-planar bathymetry
reaches a state that is rejected, the failure no longer states that the line is too long for
its span to hang as a catenary, which is proven over a planar seabed only.

## [0.1.1] - 2026-10-09

Expand Down
17 changes: 17 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2054,6 +2054,23 @@ add_test(NAME driver_lazy_wave_planar_refined_quiet
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
set_tests_properties(driver_lazy_wave_planar_refined_quiet PROPERTIES
LABELS "fortran;driver;integration;static")
# A Fixed anchor in a crease of a bathymetry grid: at the tabulated depth it rests on the seabed
# and is placed on the rounded surface; 1 cm below the rounded surface, between it and the grid
# surface but within the seabed tolerance of neither, it is rejected.
add_test(NAME driver_anchor_crease_tabulated
COMMAND ${CMAKE_COMMAND} -DDRIVER=$<TARGET_FILE:cabledyn> -DEXPECT_RC=0
"-DARGS=${CMAKE_CURRENT_SOURCE_DIR}/tests/data/anchor_crease_tabulated.dat|tabulated"
"-DMUST_NOT=lies below the seabed"
-DWORKDIR=${CMAKE_CURRENT_BINARY_DIR}/driver_anchor_crease_tabulated
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
set_tests_properties(driver_anchor_crease_tabulated PROPERTIES LABELS "fortran;driver;static;seabed")
add_test(NAME driver_anchor_crease_between
COMMAND ${CMAKE_COMMAND} -DDRIVER=$<TARGET_FILE:cabledyn> -DEXPECT_RC=1
"-DARGS=${CMAKE_CURRENT_SOURCE_DIR}/tests/data/anchor_crease_between.dat|between"
"-DMUST_MATCH=POINT 2 .Fixed. lies below the seabed"
-DWORKDIR=${CMAKE_CURRENT_BINARY_DIR}/driver_anchor_crease_between
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
set_tests_properties(driver_anchor_crease_between PROPERTIES LABELS "fortran;driver;static;seabed")
# The same pair with the buoyant stretch built from discrete ATTACHMENTS: the hand-off check runs
# on the discrete equilibrium the attachment polish gives.
add_test(NAME driver_lazy_wave_planar_coarse_att_note
Expand Down
7 changes: 6 additions & 1 deletion doc/file_formats.rst
Original file line number Diff line number Diff line change
Expand Up @@ -343,7 +343,12 @@ Validation
``16·ε`` relative.
* Rows may come in any order. Grid spacing does not have to be uniform.

The seabed is interpolated bilinearly within each grid cell. On a slope the
The seabed is interpolated bilinearly within each grid cell, and the creases of that
surface along the interior grid lines are rounded within a band of half-width 5 % of
the smaller grid spacing next to each line (a cubic fillet that makes the surface
twice continuously differentiable; see :doc:`theory`). The rounding moves the surface
by at most a sixth of the slope jump across the line times the band half-width, and
leaves a planar grid and every patch without a crease exactly bilinear. On a slope the
frictionless contact force acts along the surface normal, and its stiffness includes
the slope of that surface. Outside the grid, depth is clamped to
the value at the nearest edge.
Expand Down
3 changes: 2 additions & 1 deletion doc/python_postprocessing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -465,7 +465,8 @@ Clearance
:func:`cabledyn.seabed_clearance` returns the vertical clearance ``z - z_floor(x, y)`` of every
node at every sample, less an optional ``radius``, above a flat seabed (pass its elevation,
``-WtrDpth``) or a :class:`~cabledyn.Bathymetry` read with :func:`cabledyn.read_bathymetry` from
the deck's ``x y depth`` file (bilinear, clamped at the grid edges, as in the solver). It
the deck's ``x y depth`` file (bilinear with its creases rounded, clamped at the grid edges, as
in the solver). It
reproduces the solver's ``Clearance`` range graph. The :class:`~cabledyn.SeabedClearance`
reports the minimum with its time, node, and arc length, a profile at any time, and a range
graph.
Expand Down
68 changes: 63 additions & 5 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -790,12 +790,59 @@ A vertical axis (no horizontal projection) takes
:math:`\mu_n`. An equal pair runs the isotropic law unchanged.

A structured bathymetry grid gives :math:`z_\text{floor}(x, y)` by bilinear interpolation,
clamped to the nearest edge outside the grid. On a sloped patch the elastic contact is
clamped to the nearest edge outside the grid, with the creases of that surface rounded.
Along every interior grid line the bilinear surface has a crease: its slope across the line
jumps by :math:`J` (the second difference of the tabulated depths). A node that must rest in a
concave crease, a valley along a grid line or the bottom of a pit, takes the normal of one cell
or the other and has no static equilibrium there; a slack chain piled at the bottom of a
trench and a frictionless grounded run slid sideways into a valley both end there. Each
crease is therefore rounded within a band of half-width :math:`\delta_k`, 5 % of the smaller
grid spacing next to line :math:`k`. Along one axis the interpolant :math:`g(x)` becomes

.. math::

\tilde g(x) = g(x) + J_k\,h(x - x_k), \qquad
h(u) = \frac{(\delta_k - |u|)^3}{6\,\delta_k^2} \quad (|u| < \delta_k), \qquad h = 0 \text{ elsewhere}.

:math:`h'(0^+) - h'(0^-) = -1` cancels the slope jump, and :math:`h`, :math:`h'` and :math:`h''`
vanish at :math:`|u| = \delta_k`, so :math:`\tilde g` is :math:`C^2`. Its curvature
:math:`J_k (\delta_k - |u|)/\delta_k^2` has the sign of the jump, so a valley stays convex and
gains no spurious pit. The surface is the tensor product of the two rounded interpolants,
:math:`z_\text{floor} = f + h_x J_x(y) + h_y \big(J_y(x) + h_x M\big)`, with :math:`f` the
bilinear surface, :math:`J_x(y)` the jumps of the grid rows across the :math:`x` line
interpolated linearly along it, :math:`J_y(x)` likewise, and :math:`M` the mixed second
difference of the grid where two lines cross. Its height, gradient and curvature are
continuous everywhere within the grid. Outside the bands it is the bilinear surface, and
inside the band of one line it moves by at most :math:`|J|\,\delta/6`; where two bands
cross the two roundings and the mixed term add. A 0.2 slope jump on a 10 m grid moves
it by 1.7 cm, within the static penetration of a chain (``w/(kBot Diam)``, 11 cm for a
120 mm chain at ``kBot = 1e5``). A crease that would move the surface by less than 1 µm is not
rounded: an exactly planar grid and every patch without a crease keep the bilinear surface
exactly. A plane written to two or three decimals has creases of the size of its rounding,
which are rounded by a fraction of a millimetre. The grid edges are not rounded, and outside the grid the
surface stays level. Every height and gradient query uses this one surface: the contact of
the ``EI = 0`` and the Hermite path, statics and dynamics, the friction frame and capacity,
the seabed clearance and touchdown outputs, and the Python post-processing
(``cabledyn.Bathymetry``). The friction capacity uses the normal force :math:`f_n^{(k)}(g/s)`;
inside a band it leaves out the curvature term of the contact force below, of the order of
the penetration times the curvature. A ``Fixed`` point placed at the
tabulated depth of a creased grid node lies up to :math:`|J|\,\delta/6` below the rounded
surface; it rests on the seabed and is placed on the rounded surface.

On a sloped patch the elastic contact is
frictionless and normal to the surface, on the ``EI = 0`` and the Hermite path alike: with
:math:`s = \sqrt{1 + z_{,x}^2 + z_{,y}^2}` the force is :math:`f_n^{(k)}(g/s)\,\mathbf{n}`,
:math:`\mathbf{n} = (-z_{,x}, -z_{,y}, 1)/s`, and its tangent
:math:`f_n^{(k)\prime}\,\mathbf{n}\mathbf{n}^{\mathsf T}` (the grid curvature is not
differentiated); on a level floor this is exactly the vertical law above. Its damping acts on
:math:`f_n^{(k)\prime}\,\mathbf{n}\mathbf{n}^{\mathsf T}` (the twist of a bilinear cell is not
differentiated); on a level floor this is exactly the vertical law above. Inside a crease band,
where the surface curves, the elastic force is the gradient of the penalty potential
:math:`E(g/s)` of the normal penetration, :math:`-f_n^{(k)}\,\partial(g/s)/\partial\mathbf{q}`:
the normal force plus :math:`f_n^{(k)}\,g\,\nabla s/s^2`, a term of the order of the
penetration times the curvature, and its tangent is the Hessian of that potential (third
derivatives of the surface left out). The static energy minimisation then agrees with the
force up to the twist of the bilinear cell, which is left out of the tangent as on a sloped
patch, and a node held in a rounded valley by its curvature has a consistent stiffness. Its
damping acts on
the velocity along :math:`\mathbf{n}`, and a friction capacity is :math:`\mu` times its
magnitude. The static solve and the dynamics use the same law, so a grounded run on a slope
rests at a static equilibrium of the march; its tension changes along the slope by the weight
Expand Down Expand Up @@ -882,7 +929,14 @@ mesh-sequenced route described below first and this route as its fallback):
declared seabed plane (flat ``WtrDpth``, or the least-squares plane of a structured bathymetry
along the chord) or hung in mid-water when there is no seabed. The solve runs in the vertical
plane of the chord, translated to the anchor, so a translated or rotated deck gives the same
numbers to round-off. When the only catenary through the endpoints passes below a planar
numbers to round-off. Over a bathymetry that is not a plane along the chord (a surveyed
seabed with roughness, bumps or dips), the seed laid on the fitted plane meets the actual bed
wherever the bed rises above that plane: every seed node deeper below the actual bed than its
static penalty penetration (nodal submerged weight over the nodal contact stiffness
``kBot`` :math:`\times` ``Diam`` :math:`\times` length) is lifted onto the bed, and the
continuation below, which queries the full surface, settles the contact. Such a seed is
never rejected for its penetration; the equilibrium it leads to is audited like any other.
When the only catenary through the endpoints passes below a planar
seabed (flat, or a structured bathymetry whose profile under the chord is straight), the
line is too long for its span to hang as a catenary. Without buoyant sections the line is a
convex curve between the chord and the seabed, so it cannot be longer than the path down to
Expand All @@ -899,7 +953,11 @@ mesh-sequenced route described below first and this route as its fallback):
short of the anchor (the bow snaps through, or the line would have to lie on itself), or the
bathymetry does not continue its plane behind the anchor, the run stops and names the
geometry: no admissible planar equilibrium clear of the seabed was found, the line being too
long for its span to hang as a catenary, with where the walk stopped. A walked state that
long for its span to hang as a catenary, with where the walk stopped. A line too long for
the plane fitted to a non-planar bathymetry is walked the same way, the moved anchor kept
at its height above the bed under it and the seed draped as above; as such a bed can hold
the excess length in its dips, a failed walk there proves nothing, and the mesh-sequenced
route runs before the run stops. A walked state that
the audit below rejects (self-contact, instability) hands over to the mesh-sequenced route,
and is named the same way when that finds none; with ``tensile_safety True`` a walked state
in compression is rejected by name (a bow held by bending is compressed).
Expand Down
11 changes: 11 additions & 0 deletions doc/troubleshooting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -453,6 +453,17 @@ but a few geometries are genuinely hard:
exist: the surplus must fold or form another contact region. CableDyn rejects a resulting
element-localized wad through the curvature safety check. This is not fixed by relaxing Newton
tolerances; revise the physical support/contact model or geometry.
- **A line resting in a trench, valley or pit of a gridded bathymetry.** A frictionless grounded
run's tension :math:`T = T_0 + w\,(z - z_0)` falls with depth. In a trench deep enough it reaches
zero, and an ``EI = 0`` line then rests slack at the bottom with its excess length piled there;
the anchor tension of the run rising from the pile is :math:`w` times the depth of the trench
below the anchor, whatever the line length. On a two-dimensional rough bed the run slides
sideways into the valleys. Both rest in the creases of the bilinear grid, which the solver
rounds over 5 % of the grid spacing (see :doc:`theory`) so that a node has an equilibrium
there. A pile appears in the static profile as coincident nodes with zero tension and large
turning angles; a finite-EI line carries compression there instead, which the driver notes.
With 5 m elements on steep trench walls the end tensions of a pile still change by about 1 %
on a mesh four times finer: refine the line over the trench when they matter.
- **A twisted finite-EI line.** ``torsion continuation stalled at Phi = ... (target ...)``
reports the imposed twist the static ramp reached: beyond it the line has no nearby static
equilibrium on the path, typically because a loop is forming (hockling), which needs a
Expand Down
Loading
Loading