fix: refine a coarse finite-EI static that fails its stability test

CHANGELOG.md

@@ -19,6 +19,15 @@ All notable changes to CableDyn are recorded in this file. The format follows
   `EI = 0` + finite-EI route) the finite-EI cable steps with their residual, tangent and solve
   counts and times. Every output file is the same with and without it. See the manual's
   command-line page (Run-time profile).
+- A note when a finite-EI line starts its dynamics from a static state that is unstable out of
+  its vertical plane. A line solved in that plane (free in torsion, no current or end direction
+  across it) has its out-of-plane DOFs held in the statics and released in the dynamics. On
+  elements longer than half the bending length the touchdown can make that state unstable out of
+  the plane, which the planar solve does not see. One stability test with the dynamic
+  constraints now runs at the hand-off (0.35 ms on an 87-element lazy wave, 6 ms on 2048
+  elements; on a line with `ATTACHMENTS`, on the discrete equilibrium after the attachment
+  polish) and the note names the line, its mesh and the factor that meets the bending length,
+  and recommends a finer mesh or `adaptive_mesh True`. Results do not change.
 - Torsion of finite-EI lines in coupled OpenFAST (`CompMooring = 5`) and FAST.Farm runs. The
   End A frame of a line restrained in torsion turns with the platform orientation, the torque
   moment is returned to the platform, `PtfmInit` twists the line in the static initialisation,
@@ -60,6 +69,19 @@ All notable changes to CableDyn are recorded in this file. The format follows
   `MD_Shared` farm (`validation/scripts/fastfarm_shared_ab.py`): tension means agree to 0.02 %,
   extremes to 0.25 %, and platform motions to millimetres. The migration guide now says that on
   a line with no `Fixed` end `FairTen` and `AnchTen` name the opposite ends from MoorDyn's.
+- The power cable of `examples/iea15mw_umaine_mixed_cabledyn.dat` is meshed to the
+  half-bending-length rule: 248 elements (2 m, 2.5 m and 2.5 m in its three sections) instead
+  of 87 (4 m, 4 m and 10 m). On the 10 m grounded elements the touchdown was under-resolved and
+  the static state, solved in the vertical plane of the cable, was unstable out of that plane.
+  The static fairlead tension of the cable changes from 11 898 N to 11 922 N (11 921 N on a
+  1 m mesh), its anchor tension from 1218 N to 1230 N, and the touchdown curvature from
+  0.058 1/m to 0.079 1/m (0.080 1/m on the 1 m mesh). The curvature output moves with the
+  mesh: `Curv4N20`/`BendMom4N20` (76 m from the hang-off) become `Curv4N38`/`BendMom4N38`
+  (74 m, the peak of the sag bend). In the one-hour full-turbine run of the validation record
+  the hang-off tension statistics are unchanged (11.5 ± 1.1 kN), the touchdown curvature peaks
+  at 0.109 1/m instead of 0.075 1/m, and the anchor tension stays at its static 1.23 kN, where
+  the coarse mesh showed stick-slip peaks up to 4.1 kN. The validation record and the tutorials
+  are updated.
 
 ### Fixed
 
@@ -79,9 +101,9 @@ All notable changes to CableDyn are recorded in this file. The format follows
   out of its plane. The seabed contact acts at the nodes, which carry no moment, so at an
   anchor resting on the floor the end moment of the end element's weight turned the free end
   tangent into the floor: the element dipped below the seabed between its nodes (27 mm for the
-  power cable of `examples/iea15mw_umaine_mixed_cabledyn.dat`) and carried axial forces from
-  −47 kN to +127 kN about a line tension of 1.2 kN. Once the hang-off swayed, the element
-  buckled sideways; with seabed friction the anchor tension then locked at about 2.5 times its
+  power cable of `examples/iea15mw_umaine_mixed_cabledyn.dat` on its former 10 m grounded
+  elements) and carried axial forces from −47 kN to +127 kN about a line tension of 1.2 kN.
+  Once the hang-off swayed, the element buckled sideways; with seabed friction the anchor tension then locked at about 2.5 times its
   static value for the rest of the run (1.22 kN to 3.1 kN in a coupled OpenFAST run while the
   platform drifted toward the anchor), and without friction the end nodes wandered by up to
   0.18 m. The seabed now carries the end element's weight with its end moment at a held line end
@@ -102,6 +124,20 @@ All notable changes to CableDyn are recorded in this file. The format follows
   grounded run turned sideways on the seabed: when the refinement of the catenary
   continuation stops on a compression in a current, its failure now names the current limit,
   so the driver retries out of the plane.
+- A finite-EI line solved in 3D (restrained in torsion, or with an end connection direction or
+  a current out of the vertical plane of its chord) on a deck mesh too coarse at touchdown or at a section
+  change no longer stops with "the converged state is an unstable equilibrium". The stable
+  equilibrium had read as a saddle: elements longer than the bending length cannot follow
+  the bend, the axial force at their Gauss points oscillates into compression, and that
+  compression lowered the out-of-plane stiffness until the stability test failed. Such a
+  state is now refined, from the mesh the route returned, to the mesh whose elements are at
+  most half the bending length: the catenary-continuation route is repeated there, as for a
+  failed polish, and the state of the mesh-sequenced route is prolongated there and polished.
+  This also covers a mesh that an adaptive or safety refinement left too coarse; a mesh that
+  already meets the rule is not refined again. A note names both meshes. An equilibrium that
+  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.
 
 ## [0.1.1] - 2026-10-09
 

CMakeLists.txt

@@ -2014,6 +2014,65 @@ add_test(NAME driver_clamped_cable_pinned_rod
     -DWORKDIR=${CMAKE_CURRENT_BINARY_DIR}/driver_clamped_cable_pinned_rod
     -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
 set_tests_properties(driver_clamped_cable_pinned_rod PROPERTIES LABELS "fortran;driver;integration")
+# A lazy-wave cable restrained in torsion (3D static solve) whose deck mesh is too coarse at
+# touchdown: the deck-mesh equilibrium reads as unstable, the refined one is stable and used.
+add_test(NAME driver_lazy_wave_torsion_coarse_refined
+  COMMAND ${CMAKE_COMMAND} -DDRIVER=$<TARGET_FILE:cabledyn> -DEXPECT_RC=0
+    "-DARGS=${CMAKE_CURRENT_SOURCE_DIR}/tests/data/lazy_wave_touchdown_torsion_coarse.dat|coarse"
+    "-DONCE=failed the stability test with elements longer than half the bending length"
+    "-DMUST_MATCH=stable on the refined mesh of 348 elements;torsion solved"
+    -DWORKDIR=${CMAKE_CURRENT_BINARY_DIR}/driver_lazy_wave_torsion_coarse_refined
+    -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
+set_tests_properties(driver_lazy_wave_torsion_coarse_refined PROPERTIES
+  LABELS "fortran;driver;integration;static;torsion")
+# The same deck with the mesh-sequenced route first: its state is prolongated to the refined mesh.
+add_test(NAME driver_lazy_wave_torsion_coarse_sequenced
+  COMMAND ${CMAKE_COMMAND} -DDRIVER=$<TARGET_FILE:cabledyn> -DEXPECT_RC=0
+    "-DARGS=${CMAKE_CURRENT_SOURCE_DIR}/tests/data/lazy_wave_touchdown_torsion_coarse_sequenced.dat|coarse"
+    "-DONCE=failed the stability test with elements longer than half the bending length"
+    "-DMUST_MATCH=stable on the refined mesh of 348 elements;torsion solved"
+    -DWORKDIR=${CMAKE_CURRENT_BINARY_DIR}/driver_lazy_wave_torsion_coarse_sequenced
+    -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
+set_tests_properties(driver_lazy_wave_torsion_coarse_sequenced PROPERTIES
+  LABELS "fortran;driver;integration;static;torsion")
+# The same cable free in torsion (planar static): the coarse planar state is unstable out of its
+# plane and the hand-off names it once; on a mesh that resolves the bending length it does not.
+add_test(NAME driver_lazy_wave_planar_coarse_note
+  COMMAND ${CMAKE_COMMAND} -DDRIVER=$<TARGET_FILE:cabledyn> -DEXPECT_RC=0
+    "-DARGS=${CMAKE_CURRENT_SOURCE_DIR}/tests/data/lazy_wave_touchdown_planar_coarse.dat|coarse"
+    "-DONCE=starts the dynamics from a static state solved in its vertical plane that is unstable"
+    "-DMUST_MATCH=mesh of 87 elements, the coarsest 10.00 m long;4x meets that length"
+    -DWORKDIR=${CMAKE_CURRENT_BINARY_DIR}/driver_lazy_wave_planar_coarse_note
+    -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
+set_tests_properties(driver_lazy_wave_planar_coarse_note PROPERTIES
+  LABELS "fortran;driver;integration;static")
+add_test(NAME driver_lazy_wave_planar_refined_quiet
+  COMMAND ${CMAKE_COMMAND} -DDRIVER=$<TARGET_FILE:cabledyn> -DEXPECT_RC=0
+    "-DARGS=${CMAKE_CURRENT_SOURCE_DIR}/tests/data/lazy_wave_touchdown_planar_refined.dat|refined"
+    "-DMUST_NOT=unstable out of"
+    -DWORKDIR=${CMAKE_CURRENT_BINARY_DIR}/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")
+# 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
+  COMMAND ${CMAKE_COMMAND} -DDRIVER=$<TARGET_FILE:cabledyn> -DEXPECT_RC=0
+    "-DARGS=${CMAKE_CURRENT_SOURCE_DIR}/tests/data/lazy_wave_touchdown_planar_coarse_att.dat|coarse_att"
+    "-DONCE=starts the dynamics from a static state solved in its vertical plane that is unstable"
+    "-DMUST_MATCH=mesh of 87 elements, the coarsest 10.00 m long;4x meets that length;25 attachment.s. lumped"
+    -DWORKDIR=${CMAKE_CURRENT_BINARY_DIR}/driver_lazy_wave_planar_coarse_att_note
+    -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
+set_tests_properties(driver_lazy_wave_planar_coarse_att_note PROPERTIES
+  LABELS "fortran;driver;integration;static")
+add_test(NAME driver_lazy_wave_planar_refined_att_quiet
+  COMMAND ${CMAKE_COMMAND} -DDRIVER=$<TARGET_FILE:cabledyn> -DEXPECT_RC=0
+    "-DARGS=${CMAKE_CURRENT_SOURCE_DIR}/tests/data/lazy_wave_touchdown_planar_refined_att.dat|refined_att"
+    "-DMUST_NOT=unstable out of"
+    -DWORKDIR=${CMAKE_CURRENT_BINARY_DIR}/driver_lazy_wave_planar_refined_att_quiet
+    -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake)
+set_tests_properties(driver_lazy_wave_planar_refined_att_quiet PROPERTIES
+  LABELS "fortran;driver;integration;static")
 
 if(WIN32 AND CABLEDYN_RUNTIME_DLLS)
   add_test(

VALIDATION.md

@@ -317,10 +317,10 @@ scripts, results, and source provenance are in
     ~3% std. Tension agreement with MoorDyn is scored in the settled case above and
     in the DLC matrix below.
   - *Mixed deck*: the shipped example `iea15mw_umaine_mixed_cabledyn.dat` (three
-    chain moorings and an 87-element finite-EI power cable that touches down on the
+    chain moorings and a 248-element finite-EI power cable that touches down on the
     200 m seabed) runs to completion under full coupled physics with finite, bounded
-    channels. Coupled touchdown is covered by the 40 Hz `openfast_touchdown` test; no
-    full-DLC touchdown result is claimed.
+    channels. Coupled touchdown is covered by the 40 Hz `openfast_touchdown` test and by
+    the one-hour full-turbine run in the coupled finite-EI touchdown row below.
   - *Wall-clock*: see *Coupled throughput* under [L5](#wall-clock-time).
   - *`PtfmInit`*: MoorDyn-F's convention (rigid transform of Coupled/Vessel points,
     undisplaced reference `Position` + `TranslationDisp`); tested by
@@ -734,7 +734,7 @@ stop with a named error.
 | Active tension (`CtrlChan`) | Pass verified | CONTROL parsing, last-segment length/rate modulation, and exact unit tests; coupled A/B in which a ServoDyn cable-control DLL drives the same pay-out/haul-in `DeltaL` schedule into `=5` (CableDyn) and `=3` (stock MoorDyn) in one binary: hold tensions agree to <0.03% and the tension responses to <0.6% (controlled fairleads) / <0.7% (anchors) ([`validation/scripts/activetension/`](https://github.com/SMI-Lab-Inha/CableDyn/tree/main/validation/scripts/activetension), [`validation/scripts/openfast_activetension_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_activetension_ab.py)) |
 | Coupled `Rigid6` bodies + `Point3` buoys | Pass verified | 6-DOF `Rigid6` motion with hydrostatic (`C33`/`C44`/`C55`) restoring, checkpoint state (bit-identical `openfast -restart` of a 13.9 MN-swinging tethered body), and SeaState drag / Froude–Krylov / added mass. `Point3` buoys take buoyancy and drag/added-mass/FK; a submerged volume-only buoy takes FK. Tests: `case_coupled_rigid6`/`_mirror`/`_fluid`, `case_coupled_point3_buoy`/`_fluid` |
 | Coupled rigid rods | Pass verified | host-driven `Rod<N>A/B` endpoints, correction rewind, bit-identical 24-scalar-per-rod checkpoint state, and two Gauss fluid nodes per rod with SeaState drag/Froude–Krylov/added mass; `case_coupled_rod`, `_mirror`, and `_fluid` pass, and the OpenFAST module compiles with rod decks enabled |
-| Coupled finite-EI touchdown/contact | Pass verified | flat `WtrDpth` and equivalent constant structured bathymetry initialise and step with matching loads; friction and checkpoint restore are tested. The IEA-15 mixed example has 38 grounded nodes and completes a 20 s aggregate trajectory at `dtM=0.025 s` with 2 m surge, 1 m heave, and 0.5 m/s host current, without fallback or stall recovery, at most 14 Newton iterations. A full-turbine run of the same model (one hour after a 200 s transient; TurbSim normal turbulence, 10.6 m/s, 17 % TI; JONSWAP Hs 8 m, Tp 12 s, aligned with the wind and the cable; AeroDyn with the rotor held at 7.55 rpm, no controller, rigid blades and tower; SeaState grid covering the lines) completes without recoveries or non-finite values. The cable's hang-off tension is 11.5 ± 1.1 kN (static 11.9 kN, maximum 17.9 kN), the same 38 nodes stay grounded, and the peak curvature, 0.160 1/m at the hog bend, is mesh-converged (0.156 1/m on a refined mesh); the 10 m elements of the laid section under-resolve the touchdown curvature by about 30 %. The chain-only twin of the run matches stock MoorDyn over 1200 s to 0.3 % in platform motion and fairlead tension statistics. The anchor tension of the laid cable is 1.39 kN (median, static 1.22 kN) with wave-frequency stick-slip peaks up to 4.1 kN lasting under 1 s; before the anchor-end correction of this release it locked at about 2.75 kN for the whole run |
+| Coupled finite-EI touchdown/contact | Pass verified | flat `WtrDpth` and equivalent constant structured bathymetry initialise and step with matching loads; friction and checkpoint restore are tested. The IEA-15 mixed example (its power cable on 248 elements, each at most half the bending length) has 149 grounded nodes and completes a 20 s aggregate trajectory at `dtM=0.025 s` with 2 m surge, 1 m heave, and 0.5 m/s host current, without fallback or stall recovery, at most 12 Newton iterations. A full-turbine run of the same model (one hour after a 200 s transient; TurbSim normal turbulence, 10.6 m/s, 17 % TI; JONSWAP Hs 8 m, Tp 12 s, aligned with the wind and the cable; AeroDyn with the rotor held at 7.55 rpm, no controller, rigid blades and tower; SeaState grid covering the lines) completes without recoveries or non-finite values. The cable's hang-off tension is 11.5 ± 1.1 kN (static 11.9 kN, maximum 17.9 kN). The 149 nodes grounded at the static state stay grounded, joined by one more once the platform has drifted (the touchdown moves 2.5 m toward the platform). The peak curvature is 0.156 1/m at the sag bend, 72 m from the hang-off, and 0.109 1/m at the touchdown. On the former 87-element mesh (10 m elements along the laid section) the peak was 0.160 1/m and the touchdown curvature 0.075 1/m, under-resolved by about 30 %. The chain-only twin of the run matches stock MoorDyn over 1200 s to 0.3 % in platform motion and fairlead tension statistics. The anchor tension of the laid cable stays at its static 1.23 kN (maximum 1.24 kN): the seabed friction of the 370 m laid section holds the tension changes at the touchdown. On the former mesh it read 1.39 kN (median) with wave-frequency stick-slip peaks up to 4.1 kN lasting under 1 s, which the resolved mesh does not show, and before the anchor-end correction of this release it locked at about 2.75 kN for the whole run. The run takes 27.1 min of wall time (18.8 min on the former mesh) |
 | `WaterKin` from file | Pass verified | See [WaterKin and SeaState modes](#waterkin-and-seastate-modes) |
 | Syrope polyester (`SYROPE:` syntax; [Falkenberg et al., 2017](https://cabledyn.readthedocs.io/en/latest/references.html#ref-falkenberg2017)) | Pass verified | MoorDyn-F/C `BA_s|BA_d` rate and force equations; analytic position/velocity tangents with finite-difference checks; projected, bracketed backward-Euler slow-state update with a strong-unloading boundary test; OWC running maximum; `SYROPE IC` `Tmax0/Tmean0` history with range/order checks; both states carried through every lifecycle stage and the coupled checkpoint. `BA_s` is kept separate from line axial damping (`BA`) and tested against double counting. Composite, hydrodynamic, finite-EI, current, and wave combinations stop with a named error |
 | VIV (`compVIV`) | Not supported | outside CableDyn's scope |

doc/modeling.rst

@@ -86,6 +86,22 @@ refine regions with high curvature or rapidly varying load: hang-off and bend-st
 buoyancy-module transitions, sag bends, touchdown, and short weighted attachments. Avoid using a
 material boundary solely as a substitute for mesh refinement.
 
+**Starting mesh for a finite-EI line.** At touchdown, at a sag or hog bend and on each side of a
+section change, keep the element length at most half the bending length
+:math:`(EI/|w|)^{1/3}` of the section, with :math:`w` its submerged weight per metre. For a
+power cable with :math:`EI = 2\times10^4` N m² and :math:`w = 158` N/m that is 2.5 m. A longer
+element cannot follow the bend: it stays stiff in bending, and its stiff axial term absorbs the
+mismatch, so the pointwise axial force oscillates about the element mean, by tens of kN on a
+lazy wave of 1–2 kN tension at 10 m elements. The ``.t.out`` segment tensions, evaluated at the
+element midpoints, show these spikes and negative values near touchdown and at section changes;
+they shrink as the mesh is refined, and the element-mean force (what enters equilibrium, see
+``tensile_safety`` in :doc:`theory`) is far smoother. The compressed Gauss points also lower the
+out-of-plane stiffness: a line solved in 3D (restrained in torsion, or with an end connection
+direction or a current out of its vertical plane) can read as an unstable equilibrium on such a
+mesh. The static solve then refines that state to the rule above, whichever route reached it and
+whether or not an adaptive refinement preceded, and reports it in a note (see
+:doc:`troubleshooting`); meshing to the rule avoids the extra solve.
+
 Perform a mesh study on engineering observables, not node identity. At minimum compare endpoint
 tension and the peak/position of curvature or touchdown response. Refine until the change is below
 the project tolerance. Cross-code comparisons should interpolate by normalised arc length as

doc/openfast.rst

@@ -201,7 +201,7 @@ Mixed moorings and power cables
 One deck may combine ``EI = 0`` chains and finite-EI (``EI > 0``) power cables; each line uses
 its own element. In ``iea15mw_umaine_mixed_cabledyn.dat`` line 4 runs from a platform hang-off
 to a fixed termination on the 200 m seabed; its bare/buoyant/bare sections form the lazy wave and
-a grounded tail (38 of 88 nodes on the seabed at equilibrium). ``WtrDpth``, ``kBot``, ``cBot``,
+a grounded tail (149 of 249 nodes on the seabed at equilibrium). ``WtrDpth``, ``kBot``, ``cBot``,
 and ``frictionMu`` define contact; a structured ``bathymetryFile`` may replace the flat floor.
 CableDyn finds touchdown during static initialisation. Inspect ``<RootName>.CD.static.out``
 (curvature, grounded length, section transitions, minimum bend radius) before the time history.