fix(output): recover node tension through touchdown on coarse meshes

CHANGELOG.md

@@ -10,6 +10,16 @@ All notable changes to CableDyn are recorded in this file. The format follows
 
 ### Added
 
+- Documentation of the negative `BA` (damping ratio) form: it damps each element's own axial
+  mode at the given ratio, so the line's axial modes are damped at `zeta n pi / (2N)` and less on
+  a finer mesh (`BA = -1`: 1.6 % for the first mode on 100 elements, 0.8 % on 200); the manual
+  gives the `BA` in N·s for a mesh-independent material damping ratio.
+- Seabed-friction resolution note: friction acts at the nodes, so on a coarse grounded mesh the
+  tension of the laid part and near touchdown steps by up to mu w L per node as the line lands
+  and lifts (a 10 m lazy-wave mesh swung a grounded segment tension by 1600 N where 1 m elements
+  give 120 N). At initialisation a finite-EI line whose grounded elements lock more than 15 % of
+  the touchdown tension is noted with the grounded element length that resolves it (flat
+  seabed; standalone and OpenFAST). Results do not change.
 - The run-time profile (`CABLEDYN_PROFILE=1`, standalone driver and OpenFAST) splits the steps
   of `EI = 0` lines into residual-only evaluations, residual and tangent evaluations, LU
   factorisations and back-substitutions, with their counts and times, and separates the
@@ -49,6 +59,11 @@ All notable changes to CableDyn are recorded in this file. The format follows
 
 ### Changed
 
+- A finite-EI static solve in a current that fails because seabed friction holds the grounded
+  run while the current pushes the suspended span into the touchdown now stops after the
+  catenary-continuation route has diagnosed it, as the frictionless grounded-run case already
+  did, instead of also running the mesh-sequenced route to its iteration budget (a 1000 m lazy
+  wave in 440 m of water: 22 s to 17.7 s, same message). Converging decks do not change.
 - The Windows release executables (`CableDyn_driver.exe`, `openfast.exe`) are compiled for
   processors with AVX2 (x86-64-v3: Intel Haswell and AMD Excavator or newer; CMake option
   `CABLEDYN_TARGET_AVX2`), which makes the driver 13-33% faster on the benchmark decks
@@ -75,6 +90,13 @@ All notable changes to CableDyn are recorded in this file. The format follows
   from the step and a fresh evaluation differ slightly; the restore discarded the cache and took
   the fresh path. The snapshot now keeps the cached force with the state, and the restore brings
   it back unless a load setter invalidated it since. Runs without restores do not change.
+- Finite-EI node tension, curvature and bend moment at touchdown (node channels, range graphs):
+  the recovery spread a grounded node's floor reaction over the touchdown element, which is on
+  the floor at one end only, and understated the tension of the last suspended node by the
+  floor reaction of half an element (5.3 % on a 10 m lazy-wave mesh). A node's floor reaction is
+  now shared by the grounded elements beside it; the touchdown element takes none. The same
+  coarse mesh now follows a four times finer one within 3 % through touchdown. Line end forces
+  (`FairTen`, `AnchTen`) and the solution do not change.
 - OpenFAST with `dtM` larger than `DT`: an `openfast -restart` re-sampled the SeaState fields of the
   committed step at its end positions instead of restoring the fields the step held (sampled at
   its start positions), so the loads served until the next solve, and the run after them,

CMakeLists.txt

@@ -2284,6 +2284,15 @@ if(Python3_Interpreter_FOUND)
   set_tests_properties(driver_ei0_fold_layouts PROPERTIES
     LABELS "python;driver;integration;static"
     ENVIRONMENT "${_cabledyn_python_test_environment}")
+  # Node tension through touchdown on a coarse mesh (10 m grounded elements) follows a four
+  # times finer reference within 3.5 %: the touchdown element, grounded at one end only, takes
+  # no share of its grounded node's floor reaction.
+  add_test(NAME driver_touchdown_recovery
+           COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_touchdown_recovery.py
+                   $<TARGET_FILE:cabledyn>)
+  set_tests_properties(driver_touchdown_recovery PROPERTIES
+    LABELS "python;driver;integration;static"
+    ENVIRONMENT "${_cabledyn_python_test_environment}")
 endif()
 # A clamped finite-EI cable with a buoyant section on a Rigid6 body: the body static solve
 # holds the objects at their deck poses, warns once, and reports no balanced clamped end loads.

doc/conventions.rst

@@ -48,7 +48,9 @@ are in degrees.
      - ``0`` selects the ``EI = 0`` cable path
    * - Axial damping ``BA``
      - N·s
-     - a negative value is a damping ratio :math:`-\zeta` (dimensionless); see :doc:`theory`
+     - a negative value is a damping ratio :math:`-\zeta` (dimensionless) of each element's axial
+       mode, so the damping of the line's own axial modes depends on the mesh; give ``BA`` in
+       N·s for mesh-independent damping (see :doc:`theory`)
    * - End-connection stiffness
      - N·m/rad
      - ``END CONNECTIONS`` table

doc/options.rst

@@ -109,7 +109,10 @@ Environment and seabed
        ``dtM``/``TMax`` in the standalone driver. Line nodes carry stick-slip friction springs; in
        a current the static solve holds the line with friction springs from its still-water laid
        shape, and the march continues them (``staticsFriction asLaid`` holds it toward its
-       as-laid position instead, in still water too). The isotropic shorthand of
+       as-laid position instead, in still water too). Friction acts at the nodes, so a coarse
+       grounded mesh steps the tension of the laid part; the initialisation report notes a
+       finite-EI line whose grounded elements are too long (*Mesh resolution* in :doc:`theory`).
+       The isotropic shorthand of
        ``frictionMuAxial``/``frictionMuLateral``. Not supported (the deck is rejected) with a
        ``FAILURE`` section, on a deck with ``Connect``/``Free`` points or ``Point3`` buoys, or
        on a deck whose lines attach to ``Rigid6`` bodies or rods unless it runs on the default
@@ -346,7 +349,12 @@ rejected as unknown. The dynamic Newton controls are set with ``dynamic_solver``
      - logical
      - ``False``
      - ``True`` enables guarded within-step tangent reuse on every dynamic solver the deck builds.
-       It does not relax convergence tolerances and should be qualified against full Newton
+       It does not relax convergence tolerances and should be qualified against full Newton.
+       Measured against full Newton: 8-12 % faster on free-hanging finite-EI cables (lazy wave,
+       buoyed cable), about 1.5 times slower on finite-EI lines on the seabed (contact fails the
+       reuse contraction test and rebuilds the tangent), 3 % slower to 5 % faster on ``EI = 0``
+       systems;
+       results move at the solver tolerance (Bergdahl mean cycle maxima within 0.16 %)
      - both
      - ``False modified_newton``
    * - ``recovery_max_substeps`` / ``recoverymaxsubsteps``

doc/theory.rst

@@ -456,6 +456,24 @@ element as
 using the final element length after any mesh refinement. The damping share is included in
 the reported tension.
 
+**The damping ratio form depends on the mesh.** ``BA`` resolved this way is proportional to the
+element length, so it is a property of the discretisation, not of the material. For a uniform
+line of :math:`N` elements the axial mode :math:`n` (wavenumber :math:`n\pi/L`) has the damping
+ratio
+
+.. math::
+
+   \zeta_n = \frac{BA\,\omega_n}{2\,EA} = \zeta\,\frac{n\pi}{2N} ,
+
+so the element-scale modes (:math:`n \approx N`) are damped at up to :math:`(\pi/2)\,\zeta`, as intended
+(the convention suppresses segment-scale axial noise, the same one as MoorDyn's negative
+``BA``), while the line's global axial modes are damped much less, and less again on a finer
+mesh: ``BA = -1`` on 100 elements gives the first axial mode 1.6 %, and 0.8 % on 200 elements.
+Results that depend on the axial damping (tension peaks of snatch loads, the decay of axial
+oscillations) therefore change with the mesh. For mesh-independent damping give ``BA`` in N·s:
+a material damping ratio :math:`\zeta_1` of the first axial mode of a line of length :math:`L` is
+:math:`BA = 2\,\zeta_1\,EA/\omega_1` with :math:`\omega_1 = (\pi/L)\sqrt{EA/\rho_A}`.
+
 Viscoelastic rope (MoorDyn ``ElasticMod`` 2 and 3)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -884,6 +902,16 @@ failed or subdivided step, join the aggregate snapshot, and are part of the Open
 checkpoint. The force and its position and velocity Jacobians (through :math:`N`) are exact.
 Unlike a velocity-regularised Coulomb law, the spring holds its force at rest.
 
+**Mesh resolution.** Because friction acts at the nodes, the tension along the laid part changes
+in steps of up to :math:`\mu w L` (:math:`w` the submerged weight per length, :math:`L` the
+element length) instead of continuously, and as the line lands and lifts at touchdown each node
+locks or releases that much. On a coarse grounded mesh the tension of the laid part and near
+touchdown then swings in time by about that amount. On a 600 m lazy-wave cable in 200 m of
+water (:math:`\mu = 0.35`) the standard deviation of a grounded segment tension was 491, 136, 42
+and 33 N with 10, 5, 2.5 and 1 m elements, where :math:`\mu w L` is 46, 22, 11 and 4.5 % of the
+touchdown tension. When a finite-EI line's grounded elements exceed 15 %, the initialisation
+report notes it with the grounded element length that resolves it.
+
 .. _static-friction:
 
 **Friction in statics.** With seabed friction a static equilibrium is not unique: a grounded

src/CableDyn_DeckDriver.f90

@@ -2235,12 +2235,15 @@ RECURSIVE SUBROUTINE build_one_hermite_cable(ln, sections, types, points, opts,
       IF (pass == 3) THEN
         IF (.NOT. symmetric_current_retry()) EXIT route_pass
       END IF
-      ! A catenary-continuation route that stopped on the frictionless grounded-run
-      ! diagnosis (the current drives the run on the seabed into compression) is not
-      ! rescued by the mesh-sequenced route, which reaches the same planar limit after
-      ! up to a minute; only the symmetry-breaking passes can.
+      ! A catenary-continuation route that stopped on a grounded-run diagnosis (the current
+      ! drives the run on the seabed into compression; with friction, the friction holds the
+      ! grounded run while the current pushes the suspended span into the touchdown) is not
+      ! rescued by the mesh-sequenced route, which reaches the same limit only after its
+      ! iteration budget (17 s on a 1000 m lazy wave in 440 m of water); only the
+      ! symmetry-breaking passes can.
       IF (pass == 2 .AND. .NOT. opts%cable_statics_sequenced .AND. &
-          INDEX(primary_msg, 'the run on the seabed') > 0) THEN
+          (INDEX(primary_msg, 'the run on the seabed') > 0 .OR. &
+           INDEX(primary_msg, 'the friction holds the grounded run') > 0)) THEN
         sequence_msg = 'not run: the catenary-continuation route diagnosed the grounded run'
         CYCLE route_pass
       END IF
@@ -3056,6 +3059,8 @@ RECURSIVE SUBROUTINE build_one_hermite_cable(ln, sections, types, points, opts,
       IF (es /= CD_HCDYN_OK) THEN
         CALL fail(ErrStat, ErrMsg, 'finite-EI Hermite seabed recompute wiring failed: '//TRIM(em)); RETURN
       END IF
+      IF (opts%friction_mu > CD_ZERO .AND. .NOT. PRESENT(bathymetry) .AND. &
+          (opts%tmax > CD_ZERO .OR. .NOT. standalone_mode)) CALL friction_resolution_note()
       ! The static friction force of every node becomes the initial force of its
       ! elastic-plastic spring, so the march starts in the static equilibrium.
       IF (static_friction) THEN
@@ -4370,6 +4375,72 @@ SUBROUTINE report_note(text)
       IF (PRESENT(init_note)) CALL append_note_line(init_note, text)
     END SUBROUTINE report_note
 
+    SUBROUTINE friction_resolution_note()
+      !! Seabed friction acts at the nodes: as the line lands and lifts at touchdown, a grounded
+      !! element locks or releases up to mu w L of friction (mu the axial friction coefficient,
+      !! w its submerged weight per length, L its length), and the tension of the laid part and
+      !! near touchdown steps by that much. A note, on a flat seabed, when a grounded element's mu w L
+      !! exceeds FRICTION_TENSION_FRACTION of the static tension at touchdown, with the element
+      !! length that keeps it below; nothing is changed. On a 600 m lazy wave in 200 m of water
+      !! (mu 0.35) the standard deviation of a grounded segment tension was 491, 136, 42 and 33 N
+      !! with 10, 5, 2.5 and 1 m elements, where mu w L is 46, 22, 11 and 4.5 % of the touchdown
+      !! tension: converged below about 15 %.
+      REAL(wp), PARAMETER :: FRICTION_TENSION_FRACTION = 0.15_wp
+      REAL(wp) :: mu, quantum, q_max, l_max, w_max, t_td, gap_tol, l_res
+      REAL(wp), ALLOCATABLE :: t_nodes(:)
+      INTEGER :: k, nnd, ned, i_td, es_rec
+      LOGICAL, ALLOCATABLE :: grounded(:)
+      CHARACTER(32) :: b1, b2, b3, b4, b5
+      CHARACTER(512) :: text
+      CHARACTER(1024) :: em_rec
+      mu = opts%friction_mu
+      IF (opts%friction_mu_axial > CD_ZERO) mu = opts%friction_mu_axial
+      nnd = cable%line%nn
+      ned = cable%line%ne
+      IF (nnd < 2) RETURN
+      ALLOCATE (grounded(nnd))
+      gap_tol = 0.01_wp*MAXVAL(diam)
+      DO k = 1, nnd
+        grounded(k) = cable%line%q(6*(k - 1) + 3) <= contact_z + gap_tol
+      END DO
+      q_max = CD_ZERO; l_max = CD_ZERO; w_max = CD_ZERO
+      DO k = 1, ned
+        IF (.NOT. (grounded(k) .AND. grounded(k + 1))) CYCLE
+        quantum = mu*MAX(cable%line%w(k), CD_ZERO)*cable%line%l0(k)
+        IF (quantum > q_max) THEN
+          q_max = quantum; l_max = cable%line%l0(k); w_max = cable%line%w(k)
+        END IF
+      END DO
+      IF (.NOT. (q_max > CD_ZERO)) RETURN
+      ! the touchdown node: a grounded node beside a suspended one (the first from End B,
+      ! internal node 1), and its tension from nodal equilibrium, as the tension channels report
+      ! it (the elastic EA (|r'| - 1) of a node is dominated by the discretisation of a stiff EA)
+      i_td = 0
+      DO k = 1, nnd - 1
+        IF (grounded(k) .NEQV. grounded(k + 1)) THEN
+          i_td = MERGE(k, k + 1, grounded(k)); EXIT
+        END IF
+      END DO
+      IF (i_td < 1) RETURN
+      ALLOCATE (t_nodes(nnd))
+      CALL CD_HermiteCable_Dyn_Node_Recovery(cable%line, es_rec, em_rec, tension=t_nodes)
+      IF (es_rec /= CD_HCDYN_OK) RETURN
+      t_td = t_nodes(i_td)
+      IF (.NOT. (t_td > CD_ZERO) .OR. q_max <= FRICTION_TENSION_FRACTION*t_td) RETURN
+      l_res = FRICTION_TENSION_FRACTION*t_td/(mu*w_max)
+      WRITE (b1, '(F12.1)') l_max
+      WRITE (b2, '(I0)') NINT(q_max)
+      WRITE (b3, '(I0)') NINT(100.0_wp*q_max/t_td)
+      WRITE (b4, '(I0)') NINT(t_td)
+      WRITE (b5, '(F12.2)') l_res
+      text = 'line '//TRIM(int_to_str(ln%id))//': seabed friction acts at the nodes, so a grounded element of '// &
+             TRIM(ADJUSTL(b1))//' m locks or releases up to '//TRIM(ADJUSTL(b2))//' N (friction coefficient x '// &
+             'submerged weight x length) as the line lands and lifts, '//TRIM(ADJUSTL(b3))//' % of the '// &
+             TRIM(ADJUSTL(b4))//' N tension at touchdown: on this mesh the tensions of the laid part and near '// &
+             'touchdown step by that much. Grounded elements of at most '//TRIM(ADJUSTL(b5))//' m resolve it'
+      CALL report_note(text)
+    END SUBROUTINE friction_resolution_note
+
   END SUBROUTINE build_one_hermite_cable
 
   SUBROUTINE attachment_nodes(l0, arc_public, node, max_offset)