fix(output): the geometric curvature and section moment of a stretched line

CMakeLists.txt

@@ -2763,6 +2763,15 @@ if(Python3_Interpreter_FOUND)
     LABELS "python;driver;integration;static;validation"
     SKIP_RETURN_CODE 77
     ENVIRONMENT "${_cabledyn_python_test_environment}")
+  # The curvature of a stretched cable is the geometric one and the bend moment the section's:
+  # both follow the elastica of the element energy at strains up to 1.2 %.
+  add_test(NAME driver_curvature_stretch
+           COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_curvature_stretch.py
+                   $<TARGET_FILE:cabledyn>)
+  set_tests_properties(driver_curvature_stretch PROPERTIES
+    LABELS "python;driver;integration;static;validation"
+    SKIP_RETURN_CODE 77
+    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.

VALIDATION.md

@@ -78,7 +78,7 @@ article's methods, are compared in
 | **L3-6d** | Moving-touchdown dynamic contact | OrcaFlex 11.6d installed | curv 0.48/0.58%, tension 0.74/0.90/0.80%, TDP 0.08 m, migration 2–3 m/cycle | curv <3–5%, tension <2–3%, TDP excursion bounds <1.5 m | Pass |
 | **L3-6e** | Out-of-plane / 3D whirl response | OrcaFlex 11.6d | 3D curv 0.52%, interior Y env ≤1.0 mm, sag ≤22 mm, tension 0.14/0.17/0.12% | curv <3%, env <5 cm, tension <2–3% | Pass |
 | **L3-7** | 1-hour VolturnUS-S mooring dynamic | OrcaFlex 11.6d | `FairTen` mean 0.27%, std 0.26%, min/max 0.50/0.43%, Fourier 0.27/1.14% | ≤5% | Pass |
-| **L3-8** | Bend stiffener at a clamped hang-off (5 m tapered polyurethane) | OrcaFlex 11.6d (stiffener attachment) / planar elastica | curvature 0.51% of root; cable moment 0.18%, section moment 0.18%, deflection angle 0.003°; local curvature 0.24% (0.1 m elements) | <1.5% / <2%, 0.05°, <0.5% | Pass |
+| **L3-8** | Bend stiffener at a clamped hang-off (5 m tapered polyurethane) | OrcaFlex 11.6d (stiffener attachment) / planar elastica | curvature 0.45% of root; cable moment 0.01%, section moment 0.01%, deflection angle 0.0001°; local curvature 0.27% (0.1 m elements) | <1.5% / <2%, 0.05°, <0.5% | Pass |
 | **L3-H** | Holcombe static lazy-wave experiment | measured marker geometry | position RMSE 1.07–1.89% of suspended length; peak marker-curvature error 0.34–5.54% | end-restraint bracket | Pass |
 | **L3-B** | Bergdahl chain experiment, 30 orbit conditions | measured upper-end force | RMSE 1.58 N; MAPE 3.11%; Pearson 0.993; Lin concordance 0.989 | full published matrix | Pass |
 | **L-fig** | Along-arc curvature overlay (CableDyn / OrcaFlex / MoorDyn-F ±4×) | 3-code committed record | CableDyn peak 0.11% from OrcaFlex | <0.5% | Pass |
@@ -275,19 +275,19 @@ initialisation.
   polyurethane stiffener (0.5 m cylinder of 0.60 m, cone to 0.22 m, bore 0.20 m, E 50 MPa;
   16 times the cable's EI at the root), on 0.05 m elements. The static curvature over the
   stiffener and 3 m beyond follows OrcaFlex 11.6d with the stiffener given as a line attachment
-  within **0.51% of the root curvature** (root 0.4523 against 0.4522 1/m;
+  within **0.45% of the root curvature** (root 0.4528 against 0.4522 1/m;
   [`orcaflex_bend_stiffener.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/orcaflex_bend_stiffener.py)).
-  Against an independent collocation solution of the planar extensible elastica with
-  `EI(s)` and the sleeve's weight, the cable's own moment follows within **0.18%** of its root
-  value, cable and sleeve moments add up to the section moment within **0.18%**, the node
-  positions within **0.6 mm**, and the end force's deflection from the clamp axis within
-  **0.003°** (32.37°). Node by node, relative to the local value floored at 0.1% of the root
-  curvature, the curvature follows the elastica within **0.97 / 0.49 / 0.24 / 0.18%** on
+  Against an independent collocation solution of the planar extensible elastica of the element
+  energy with `EI(s)` and the sleeve's weight, the cable's own moment follows within **0.01%** of
+  its root value, cable and sleeve moments add up to the section moment within **0.01%**, the node
+  positions within **0.03 mm**, and the end force's deflection from the clamp axis within
+  **0.0001°** (32.37°). Node by node, relative to the local value floored at 0.1% of the root
+  curvature, the curvature follows the elastica within **0.99 / 0.52 / 0.27 / 0.06%** on
   0.2 / 0.15 / 0.1 / 0.05 m elements (gates 1 / 1 / 0.5 / 0.5%), under either output recovery,
   and under the stiffener the element peaks of `.elements.out`, read through `bend_check`,
-  within **the same figures** on the same gates; 0.12% of it at the root is
-  the order-`T/EA` difference between the elastica's bending law and the element energy's,
-  not mesh error.
+  within **the same figures** on the same gates. On a cable strained up to 1.2%
+  (`driver_curvature_stretch`) the curvature and the section moment follow the same elastica
+  within **0.006%** and **0.001%** of the local value.
 - **L-fig curvature overlay**: `l3_lazywave_dynamic` writes each site's along-arc
   curvature profile.
   [`validation/scripts/curvature_profile_overlay.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/curvature_profile_overlay.py)

doc/driver_format.md

@@ -1553,8 +1553,8 @@ bending moment. None of these channels is mandatory.
 | `Body<N>…`, `Rod<N>…` | Rigid6 body and rod channels in the MoorDyn-F names: position, attitude, velocity and acceleration (`P`, `R`, `V`, `RV`, `A`, `RA`), net force and moment (`F`, `M`), rod end tensions (`TenA`, `TenB`), submerged fraction (`Sub`) and rod node positions (`Rod<N>N<k>P`). Available on every route that carries bodies or rods, OpenFAST included; the full list and units are in [Outputs](outputs.rst) | see Outputs |
 | `Point<P>F{x,y,z}`, `Point<P>FH` | resultant of the line-end and cable end forces on point P (each the `FairTen`/`AnchTen` end force): the anchor load of a Fixed point shared by several lines, the line load a free point balances; `FH` is its horizontal magnitude. Available on every route (static, `EI = 0`, finite-EI, multibody and OpenFAST) | N |
 | `Ten<L>N<J>` | line L effective tension at node J. EI = 0 lines: the mean of the two adjacent segment tensions. Finite-EI lines: the axial component of the section force recovered from nodal equilibrium (`OutputRecovery element`: the length-weighted mean of the adjacent element-mean axial forces). End nodes report the line-end force of `FairTen`/`AnchTen` | N |
-| `Curv<L>N<J>` | line L curvature at node J. `EI = 0` lines: geometric curvature of the circle through the node and its two neighbours (end nodes take the adjacent interior value). Cubic-Hermite lines: `BendMom<L>N<J>` / EI, the larger of the two sides at a section junction (`OutputRecovery element`: exact curvature of the continuous centreline, the larger one-sided element value at an interior node) | 1/m |
-| `BendMom<L>N<J>` | line L bend moment = EI × curvature **relative to the stress-free reference shape** (≈ 0 at the reference; the finite-EI reference is straight). Finite-EI lines: recovered from nodal equilibrium, the moment the neighbouring elements carry (`OutputRecovery element`: EI × the larger one-sided exact curvature); 0 on EI = 0 lines. Under a bend stiffener: the cable's own share, the line type's EI × curvature | N·m |
+| `Curv<L>N<J>` | line L curvature at node J. `EI = 0` lines: geometric curvature of the circle through the node and its two neighbours (end nodes take the adjacent interior value). Cubic-Hermite lines: the geometric curvature of the stretched line, (1 + ε) `BendMom<L>N<J>` / EI with ε the axial strain at the node, the larger of the two sides at a section junction (`OutputRecovery element`: exact curvature of the continuous centreline, the larger one-sided element value at an interior node) | 1/m |
+| `BendMom<L>N<J>` | line L bend moment = EI × curvature / (1 + ε), the moment that balances the forces on the section, **relative to the stress-free reference shape** (≈ 0 at the reference; the finite-EI reference is straight). Finite-EI lines: recovered from nodal equilibrium, the moment the neighbouring elements carry (`OutputRecovery element`: EI × the larger one-sided exact curvature); 0 on EI = 0 lines. Under a bend stiffener: the cable's own share, the section moment × the line type's EI / EI(s) | N·m |
 | `StfMom<L>N<J>` | line L share of the section moment a bend stiffener carries at node J (the section moment less `BendMom<L>N<J>`; 0 outside the stiffener); only on a line with STIFFENERS | N·m |
 | `L<L>N<J>p{x,y,z}` | line L node J position component | m |
 | `L<L>N<J>v{x,y,z}` | line L node J velocity component (0 in static-only runs) | m/s |

doc/options.rst

@@ -492,7 +492,8 @@ Finite-EI cable controls
        static-profile and range-graph columns, ``.t.out`` segment tensions).
        ``equilibrium`` recovers them from nodal equilibrium: the effective tension
        :math:`\mathbf F\cdot\mathbf t`, the moment the neighbouring elements carry, and
-       curvature = moment / ``EI`` (see :ref:`theory-output-recovery`). ``element`` reports the
+       the geometric curvature (1 + strain) × moment / ``EI`` (see
+       :ref:`theory-output-recovery`). ``element`` reports the
        length-weighted element-mean axial force :math:`EA(\lvert\mathbf r'\rvert - 1)`, the
        larger one-sided exact curvature (on an element with a bend stiffener sleeve, the recovered
        moment over ``EI(s)``), and the axial resultant at the element midpoint as the

doc/outputs.rst

@@ -695,9 +695,11 @@ Line-node channels
    * - ``Curv<L>N<J>``
      - curvature at node ``J``. ``EI = 0`` lines: discrete curvature of the circle through
        the node and its two neighbours (end nodes take the adjacent interior value).
-       Cubic-Hermite lines: ``BendMom<L>N<J>`` / ``EI``, the larger of the two sides at a
-       section junction (under a bend stiffener the section moment over the stiffness ``EI(s)``
-       at the node, :ref:`theory-bend-stiffeners`), and the exact geometric curvature where
+       Cubic-Hermite lines: the geometric curvature of the stretched line, the reciprocal of the
+       bend radius, ``(1 + ε) BendMom<L>N<J>`` / ``EI`` with ``ε`` the axial strain at the node,
+       the larger of the two sides at a section junction (under a bend stiffener ``(1 + ε)``
+       times the section moment over the stiffness ``EI(s)`` at the node,
+       :ref:`theory-bend-stiffeners`), and the exact geometric curvature where
        ``EI`` is below ``max(|w| L0^2)/12`` times 1 m (:ref:`theory-output-recovery`) (``OutputRecovery
        element``: exact curvature of the continuous
        centreline, the larger of the two one-sided element values at an interior node; the
@@ -717,15 +719,15 @@ Line-node channels
        returns them for every node
      - 1/m
    * - ``BendMom<L>N<J>``
-     - bend moment ``EI × κ`` measured relative to the stress-free reference shape (the
-       cubic-Hermite reference is straight). Finite-EI lines: the component normal to the tangent
-       of the moment recovered from nodal equilibrium, the mean of the two neighbouring elements
+     - bend moment ``EI × κ / (1 + ε)``, the moment that balances the forces on the section (it
+       is ``EI × κ`` to within the axial strain ``ε``), measured relative to the stress-free
+       reference shape (the cubic-Hermite reference is straight). Finite-EI lines: the moment
+       recovered from nodal equilibrium, the mean of the two neighbouring elements
        (one-sided at a line end, where it is the end connection moment);
        ``OutputRecovery element``: ``EI`` times the larger one-sided exact curvature. 0 on
        ``EI = 0`` lines. Under a bend stiffener (``STIFFENERS``) it is the cable's own share,
-       the line type's ``EI`` times the curvature, which is the section moment over the
-       stiffness ``EI(s)`` at the node; the stiffener's share is ``StfMom<L>N<J>`` and the two
-       add up to the section moment
+       the section moment times the line type's ``EI`` over the stiffness ``EI(s)`` at the node;
+       the stiffener's share is ``StfMom<L>N<J>`` and the two add up to the section moment
      - N·m
    * - ``StfMom<L>N<J>``
      - the share of the section moment a bend stiffener carries at node ``J``, the section