feat: add torsion to the Hermite finite-EI cable

CHANGELOG.md

@@ -8,6 +8,16 @@ All notable changes to CableDyn are recorded in this file. The format follows
 
 ## [Unreleased]
 
+### Added
+
+- Torsion of finite-EI lines in the standalone driver (condensed, quasi-static, uniform torque):
+  `END CONNECTIONS` columns `TorsStiffness NxX NxY NxZ [Pretwist]`, a `motionFile` roll column,
+  the torque returned to Rigid6 bodies, channels `Torq<L>N<J>`, `Twist<L>N<J>` and `Twist<L>`,
+  range-graph columns, `DeckModel` and channel support in Python, and the example
+  `torsion_lazy_wave_hangoff_twist.dat`. Validated in VALIDATION.md (Torsion). Routes outside
+  its scope, coupled OpenFAST (NLR) runs included, stop with a named error; results without
+  torsion are unchanged.
+
 ### Fixed
 
 - The static solve of a taut, neutrally buoyant finite-EI line (mass per length equal to

CMakeLists.txt

@@ -323,6 +323,7 @@ add_library(cabledyn_obj OBJECT
   src/CableDyn_EndConnection.f90
   src/CableDyn_Vessel.f90
   src/CableDyn_HermiteCable.f90
+  src/CableDyn_HermiteTorsion.f90
   src/CableDyn_HermiteCableStatic.f90
   src/CableDyn_HermiteCableDynamic.f90
   src/CableDyn_Conventions.f90
@@ -562,6 +563,28 @@ target_link_libraries(test_hermite_cable PRIVATE cabledyn_core)
 add_test(NAME hermite_cable COMMAND test_hermite_cable)
 set_tests_properties(hermite_cable PROPERTIES LABELS "fortran;unit;static")
 
+add_executable(test_hermite_torsion_kernel tests/test_hermite_torsion_kernel.f90)
+target_link_libraries(test_hermite_torsion_kernel PRIVATE cabledyn_core)
+add_test(NAME hermite_torsion_kernel
+         COMMAND test_hermite_torsion_kernel ${CMAKE_CURRENT_SOURCE_DIR}/tests/data/torsion_oracle_reference.txt)
+set_tests_properties(hermite_torsion_kernel PROPERTIES LABELS "fortran;unit;static")
+
+add_executable(test_hermite_torsion_static tests/test_hermite_torsion_static.f90)
+target_link_libraries(test_hermite_torsion_static PRIVATE cabledyn_core)
+add_test(NAME hermite_torsion_static
+         COMMAND test_hermite_torsion_static ${CMAKE_CURRENT_SOURCE_DIR}/tests/data/torsion_analytic_refs.txt)
+set_tests_properties(hermite_torsion_static PROPERTIES LABELS "fortran;unit;static;validation")
+
+add_executable(test_torsion_validation tests/test_torsion_validation.f90)
+target_link_libraries(test_torsion_validation PRIVATE cabledyn_core)
+add_test(NAME torsion_validation
+         COMMAND test_torsion_validation ${CMAKE_CURRENT_SOURCE_DIR}/tests/data/torsion_analytic_refs.txt)
+set_tests_properties(torsion_validation PROPERTIES LABELS "fortran;unit;static;validation")
+add_executable(test_hermite_torsion_dynamic tests/test_hermite_torsion_dynamic.f90)
+target_link_libraries(test_hermite_torsion_dynamic PRIVATE cabledyn_core)
+add_test(NAME hermite_torsion_dynamic COMMAND test_hermite_torsion_dynamic)
+set_tests_properties(hermite_torsion_dynamic PROPERTIES LABELS "fortran;unit;dynamic;validation")
+
 add_executable(test_hermite_cable_static tests/test_hermite_cable_static.f90)
 target_link_libraries(test_hermite_cable_static PRIVATE cabledyn_core)
 add_test(NAME hermite_cable_static COMMAND test_hermite_cable_static)
@@ -1180,6 +1203,9 @@ if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU" AND CMAKE_C_COMPILER_ID STREQUAL "GN
            COMMAND test_step_allocations ${CMAKE_CURRENT_SOURCE_DIR}/tests/data/range_mixed_alloc.dat
                    200.0 200 ranges)
   set_tests_properties(step_allocations_ranges PROPERTIES LABELS "fortran;openfast;dynamic;memory")
+  # The same gate on a finite-EI cable with condensed torsion (a turning parent and a changing twist).
+  add_test(NAME step_allocations_torsion COMMAND test_step_allocations torsion)
+  set_tests_properties(step_allocations_torsion PROPERTIES LABELS "fortran;dynamic;memory")
 endif()
 
 add_executable(test_snap_load tests/test_snap_load.f90)
@@ -1650,6 +1676,17 @@ target_link_libraries(test_clamped_cable_ends PRIVATE cabledyn_core)
 add_test(NAME clamped_cable_ends COMMAND test_clamped_cable_ends)
 set_tests_properties(clamped_cable_ends PROPERTIES LABELS "fortran;driver;integration;static;dynamic")
 
+add_executable(test_torsion_deck tests/test_torsion_deck.f90)
+target_link_libraries(test_torsion_deck PRIVATE cabledyn_core)
+add_test(NAME torsion_deck COMMAND test_torsion_deck)
+set_tests_properties(torsion_deck PROPERTIES LABELS "fortran;driver;integration;static;dynamic")
+
+add_executable(test_torsion_orcaflex tests/test_torsion_orcaflex.f90)
+target_link_libraries(test_torsion_orcaflex PRIVATE cabledyn_core)
+add_test(NAME torsion_orcaflex
+         COMMAND test_torsion_orcaflex ${CMAKE_CURRENT_SOURCE_DIR}/tests/data/torsion_orcaflex_refs.txt)
+set_tests_properties(torsion_orcaflex PROPERTIES LABELS "fortran;driver;integration;static;validation;l3")
+
 add_executable(test_rod_hydro tests/test_rod_hydro.f90)
 target_link_libraries(test_rod_hydro PRIVATE cabledyn_core)
 add_test(NAME rod_hydro COMMAND test_rod_hydro)
@@ -1795,6 +1832,16 @@ foreach(_lozon_case IN ITEMS
     LABELS "fortran;driver;integration;example;lozon")
 endforeach()
 
+# Torsion example: a lazy-wave cable twisted two turns at the hang-off through the motionFile
+# roll column (condensed torsion, quasi-static).
+add_test(
+  NAME example_torsion_lazy_wave_hangoff_twist
+  COMMAND cabledyn
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/torsion_lazy_wave_hangoff_twist.dat"
+    "${CMAKE_CURRENT_BINARY_DIR}/example_torsion_lazy_wave_hangoff_twist")
+set_tests_properties(example_torsion_lazy_wave_hangoff_twist PROPERTIES
+  LABELS "fortran;driver;integration;example;dynamic")
+
 # The teaching/reference deck enumerates all active defaults and documents every
 # mutually exclusive alternative.  Keep it runnable so the canonical OPTIONS
 # example cannot drift away from the production parser.
@@ -1919,6 +1966,7 @@ if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU")
                          -Wno-compare-reals
                          -Wno-uninitialized
                          -Wno-maybe-uninitialized)
+  target_compile_options(test_torsion_deck PRIVATE -Wno-uninitialized -Wno-maybe-uninitialized)
 endif()
 
 if(CABLEDYN_ENABLE_COVERAGE)
@@ -1957,6 +2005,9 @@ if(CABLEDYN_ENABLE_COVERAGE)
       test_robust_init
       test_line
       test_hermite_cable
+      test_hermite_torsion_kernel
+      test_hermite_torsion_static
+      test_hermite_torsion_dynamic
       test_hermite_cable_static
       test_hermite_sequenced
       test_hermite_resolution

VALIDATION.md

@@ -88,6 +88,16 @@ article's methods, are compared in
 | **L5-wc** | Wall-clock vs explicit C solver | external-C RK2 (WD chain) | L2 0.967 s vs external-C 0.541 s; traces validated | matched comparison reported | Pass measured |
 | **L5-DPC** | Pinned-TDP lazy-wave spans, 80/200/800 m | OrcaFlex / refined MoorDyn-F | CableDyn 1.55/4.64/7.37 s; OrcaFlex 2.29/4.56/23.17 s; MoorDyn-F 249/145/243 s | resolved meshes, same host, one thread | Pass measured |
 | **L5-pk** | Snap-load peak, 3-code | MoorDyn-C + OrcaFlex | 4.86 / 6.32 / 10.22 MN | — | Informative |
+| **T-1** | Torsion kernel: twist of the centreline, gradient, Hessian | automatic differentiation; finite differences | ≤3.8e-15; ≤5.3e-11 | <1e-10; <1e-6 | Pass |
+| **T-2** | Pure torsion (multi-section, end springs, five turns) | `Φ/C`; OrcaFlex 11.6d | round-off; ≤1.7e-8 | <1e-12; <1e-7 | Pass |
+| **T-3** | Greenhill onset, clamped, `TL²/EI` −20 to 1600 | van der Heijden et al. (2003) eq. 33 | ≤3.9e-5 (32 elements); ≤6.5e-6 (128) | <1e-4; <1e-3 | Pass |
+| **T-4** | Onset, bending-pinned torsional (semi-tangential) end | `tan x = −x/3` | 6.4e-7 / 4.5e-7 | <1e-4 | Pass |
+| **T-5** | Onsets against OrcaFlex 11.6d (clamped and pinned) | OrcaFlex, extrapolated to zero segment length | ≤3.0e-5 | <2e-4 | Pass |
+| **T-6** | Lazy-wave cable twisted 0–5 turns at the hang-off | OrcaFlex 11.6d | torque ≤0.019%, peak curvature ≤0.056%, offset ≤27 mm, tension ≤0.091% | 1% / 1% / 0.1 m / 0.5% | Pass |
+| **T-7** | Kirchhoff helix, four turns | helical equilibrium | end force 1.5e-4, end moment 6.5e-5 | <5e-3 | Pass |
+| **T-8** | Cross-check with the Cosserat rod path | Cosserat path | shape 4.2e-4 L, torque 5.2e-5 | <1% | Pass |
+| **T-9** | Bordered Newton step on post-buckled states | predicted linear rate without the rank-one term | 3 iterations; rate 0.055 / 0.217 vs 0.055 / 0.218 | ≤4; within 25% | Pass |
+| **T-10** | Torsion dynamics, restart and body torque | quasi-static torque, energy, uninterrupted run, pendulum | torque 2.2e-16; energy band 4.9e-4; restart bit-identical; pendulum 6.4e-5 | see [Torsion](#torsion) | Pass |
 
 **Pass** meets the stated acceptance value. **Pass measured** records a measured
 comparison without an acceptance value. **Informative** is reported but not used for
@@ -776,6 +786,108 @@ self-driven WaveKinMod-1 waves with WaterKin CurrentMod-2 host current, and a ho
 SeaState using its own user-current CurrMod-2, which cannot be split into wave and
 current parts.
 
+## Torsion
+
+Condensed isotropic torsion of finite-EI lines (theory in the
+[manual](https://cabledyn.readthedocs.io/en/latest/theory.html#condensed-torsion)) is checked
+against closed forms, against the Cosserat rod path, and against OrcaFlex 11.6d. The OrcaFlex
+values are summary values in `tests/data/torsion_orcaflex_refs.txt`, written by
+[`validation/scripts/orcaflex_torsion_reference.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/orcaflex_torsion_reference.py)
+(OrcFxAPI 11.6d, line torsion included, statics tolerance 1e-9 for pure torsion and 1e-8
+otherwise, `TensionTorqueCoupling` 0, no seabed friction; about 5 min). Torque is positive for a
+right-handed twist of End B relative to End A, the OrcaFlex sign; OrcaFlex reports twist as a
+rate in deg/m and end twisting stiffness in kN·m/deg. Every case below is a CTest test (names
+in parentheses).
+
+- **T-1 twist kernel** (`hermite_torsion_kernel`). The geometric twist `Θ` of the centreline,
+  its gradient and Hessian, with clamped and articulated ends, match automatic differentiation of
+  an independent implementation on random large-deformation lines (Θ ≤4.4e-16, gradient
+  ≤9.2e-16, Hessian ≤3.8e-15, relative) and finite differences (Hessian 5.3e-11). `Θ` is
+  invariant under rigid rotation (2.2e-15), zero for planar curves, and equals `−τℓ` on a helix
+  (9.0e-7 at 48 elements, fourth order); unwrapping is continuous through three turns; the
+  `π/2` step limit and the fold guard stop by name.
+- **T-2 pure torsion** (`hermite_torsion_static`, `torsion_deck`, `torsion_orcaflex`). A straight
+  clamped rod with alternating `GJ` and end springs carries `Φ/C` to round-off with no lateral
+  drift; through the deck, `Torq`, `Twist<L>N<J>` and `Twist<L>` follow `GJ Φ/L` and the
+  end-spring compliance. Against OrcaFlex (90°, 450°, 1800° and −90°, `γ_A` 30° / `γ_B` 120°, two
+  sections in series) the deck torque agrees to the 8 digits of the output. OrcaFlex's line in
+  this case has `EI` 1 kN·m², so every case but ±90° lies above its buckling onset; OrcaFlex
+  statics stays on the straight branch there, while CableDyn's stability check leaves it for the
+  buckled shape. The deck therefore uses `EI` 1e3 kN·m²; the straight-branch torque does not
+  depend on `EI`.
+- **T-3 Greenhill onset** (`hermite_torsion_static`, `torsion_validation`). The critical torque
+  of a straight clamped rod under the dead tension `T`, bisected on the static stability report,
+  against eq. 33 of van der Heijden et al. (2003): at `TL²/EI` = −20, 0, 10, 50, 200 the 32-element
+  error is 1.8e-5, 9.0e-6, 7.5e-6, 6.8e-6 and 3.9e-5 with an observed order of 3.7 to 3.9; at
+  400 and 1600, where the onset approaches the infinite-rod value `2√(EI T)` (ratio 1.0124 and
+  1.0031), the 128-element error is 3.8e-7 and 6.5e-6. Above the onset the straight state is
+  reported unstable and the static solve descends to a stable buckled state of lower energy and
+  relaxed torque. Dynamic loop formation and self-contact are not resolved (see Limits below).
+- **T-4 semi-tangential end** (`hermite_torsion_static`). A bending-pinned end restrained in
+  torsion carries the torque about the bisector of the connection direction and the tangent.
+  The onset is the root of `tan x = −x/3` (4.9112877 EI/L at `T = 0`, 7.2692742 at
+  `TL²/EI = 10`), reproduced to 6.4e-7 and 4.5e-7; it is not Greenhill's `2π EI/L` for an
+  axial-torque hinge.
+- **T-5 onsets against OrcaFlex** (`torsion_orcaflex`). OrcaFlex detects the onset by
+  bisection on its modal stability flag and converges at second order in the segment length;
+  extrapolated, it reproduces eq. 33 to 3e-8–9e-6. CableDyn at 32 elements differs from the
+  extrapolated OrcaFlex value by 9.1e-6, 7.4e-6, 5.0e-6 and 3.0e-5 (clamped, `TL²/EI` 0, 10, 50,
+  200) and 4.9e-6 and 6.8e-7 (OrcaFlex's bending-free end with a twisting spring, `TL²/EI` 0 and
+  10), which confirms that both codes transmit torque semi-tangentially at such an end.
+- **T-6 lazy-wave cable** (`torsion_orcaflex`). The Lozon et al. (2025) Gulf of Mexico 80 m
+  cable with an illustrative `GJ` of 50 kN·m² is clamped at both ends in its untwisted static
+  orientation and twisted 1 to 5 turns at the hang-off. Against OrcaFlex at 0.375 m segments,
+  the hang-off torque agrees to ≤0.019%, the geometric twist `Θ` to ≤1.8e-4 turn per imposed turn
+  (`Θ` = 0.188 turn at 5 turns, so the torque is 3.8% below `GJ Φ/L`), the peak interior
+  curvature to ≤0.056% (0.1197 against 0.1196 1/m at 5 turns), the out-of-plane offset to ≤27 mm
+  of 6.8 m and the hang-off tension to ≤0.091%. The torque is uniform along the line. At zero
+  twist the restrained deck reproduces the same cable without torsion columns (positions
+  identical, tensions to 1.1e-8), the zero-twist parity case.
+- **T-7 Kirchhoff helix** (`torsion_validation`). A rod clamped on four turns of a helix (radius
+  1, pitch angle 30°, `EI` 1, 96 elements) with `Φ = Θ_helix + M C`, `M` = 0.5, stays on the helix
+  (radius drift 2.4e-4 of the radius), and the end reaction, taken as the derivative of the
+  discrete energy, is the helical wrench `F` = 0.058013 along the axis and `K` = 0.899519 about it
+  to 1.5e-4 and 6.5e-5. A three-dimensional sagging line restrained with `Φ` equal to its own
+  untwisted `Θ` (0.61 rad) reproduces the solve without torsion to solver tolerance.
+- **T-8 Cosserat cross-check** (`torsion_validation`). The same rod, solved by the cubic-Hermite
+  element with condensed torsion (16 elements) and by the secondary Cosserat rod path (128
+  elements with shear, a different formulation with nodal rotations), clamped with its far end
+  displaced and turned by `exp([0.25, −0.3, 1.2])`: the shapes agree to 4.2e-4 of the length and
+  the torques to 5.2e-5. Pure torsion agrees to round-off. The Cosserat path has no stability
+  report, so Greenhill onsets are not cross-checked on it.
+- **T-9 bordered Newton step** (`torsion_validation`). On a rod buckled out of plane at 1.05 and
+  1.20 times its clamped onset (`GJ = 2.5 EI`, the reference cable's ratio), Newton with the
+  bordered tangent `B + ∇Θ∇Θᵀ/C` (Sherman–Morrison on the band factor) returns from a 1e-6
+  perturbation in 3 iterations. Without the rank-one term the iteration converges only linearly,
+  at the rate `ρ = ∇Θᵀ B⁻¹ ∇Θ / C` predicted for it: ρ = 0.055 and 0.218, observed 0.055 and
+  0.217 (5 and 9 iterations). On these stable states `B` itself remains positive definite.
+- **T-10 dynamics, restart and bodies** (`hermite_torsion_dynamic`, `torsion_deck`). An imposed
+  twist step gives `GJ Φ/L` from the first step (2.2e-16): torsion has no inertia. A parent turned
+  through 1.5 turns carries the twist without a `2π` slip. A bowed, twisted line in free vibration
+  (`ρ∞ = 1`, no drag) keeps its total energy, torsional part included, within a band of 4.9e-4
+  of the vibration energy over ten periods, while the torsional share swings by 22%. A run
+  restored from a snapshot or rebuilt from the checkpoint mirror after more than one turn
+  continues bit-identically. A Rigid6 body on a twisted line receives the torque along the line
+  axis (3.6e-12), its net wrench equals the line loads, it turns against the torque in statics
+  (net moment ≤1e-6 N·m), and released with a roll rate it swings as a torsional pendulum at
+  `√(GJ/(L I))` to 6.4e-5 of the torque amplitude, with clamped and with bending-pinned
+  torsional ends. Stepped coarsely from rest, at `Ω Δt` = 2 and 5, the pendulum follows the closed
+  form of the march's trapezoidal body integrator at every step (≤9.7e-8°), so the body–twist
+  coupling is stable at any step. The `motionFile` roll column and a rolling vessel give
+  `Twist<L> = −roll` and the quasi-static torque at every step.
+- **Backward compatibility and refusals** (`torsion_deck`, full suite). Without torsion columns,
+  with `Free` columns (whatever their normal), or with one restrained end, every output is
+  byte-identical to the 6-column deck, and `Rigid`, `Infinity`, `Inf` and a quoted `"Rigid"`
+  give the same run. Malformed rows, a missing `GJ`, an `EI = 0` line, a rod end, a `Point3` body,
+  `ATTACHMENTS`, modal analysis, the configuration blend, misuse of the roll column, channels on
+  an unrestrained line, the coupled entries and a mixed `EI = 0` + finite-EI deck without a body
+  stop with named errors.
+
+Limits. The torsion model is quasi-static (no torsional inertia), takes no seabed friction
+against twist and no torque–tension coupling, and does not resolve self-contact. Dynamic loop
+formation (hockling) and a twisted slack catenary against OrcaFlex are not part of this record,
+and there is no experimental torsion case.
+
 ## Cross-code comparison method
 
 Cross-code validation compares physical observables, not another solver's internal

doc/capabilities.rst

@@ -79,18 +79,32 @@ Line and constitutive capability
      - Supported with limits
      - single-section taut dynamic line with OWC and two history states; composite, hydro,
        finite-EI, current, and wave combinations fail closed by name
-   * - Torsion, hockling, nonlinear cross-section laws
+   * - Torsion of finite-EI lines
+     - Standalone only, with limits
+     - condensed isotropic torsion (uniform torque, quasi-static: no torsional inertia) of a
+       finite-EI line restrained in torsion at both ends (``END CONNECTIONS`` torsion columns,
+       explicit ``GJ``), in statics with a stability check and buckling descent, and in dynamics
+       with turning Rigid6 bodies, ``vesselMotion``/``vesselRAO`` and the ``motionFile`` roll
+       column; ``Torq``/``Twist`` channels and range graphs. Stopped by name: coupled OpenFAST
+       and FAST.Farm, the mixed ``EI = 0`` + finite-EI aggregate, rod ends, bodies other than
+       Rigid6, lines with ``ATTACHMENTS``, modal analysis, ``False alpha_force_blend``, and C API
+       object queries (which take ``EI = 0`` decks only). Not modelled: seabed friction against
+       twist, torque–tension coupling, anisotropic sections, self-contact of a loop (see
+       :ref:`theory-torsion`)
+   * - Hockling loops, nonlinear cross-section laws
      - Not provided
-     - the production elements carry no torsion; the secondary Cosserat path
-       (:doc:`solver_paths`) is not a production route
+     - the buckling onset and the post-buckled shape are computed, but a loop that closes on
+       itself is not resolved; the secondary Cosserat path (:doc:`solver_paths`) is not a
+       production route
    * - Discrete attachments (``ATTACHMENTS``: buoyancy modules, clumps)
      - Supported
      - lumped at nodes of a finite-EI cable, standalone and coupled; rejected on the two-moving-end
        compatibility solver
    * - Modal analysis (``nModes``)
      - Standalone only
      - natural frequencies and mode shapes of each line about its static equilibrium (all
-       ``EI = 0`` lines, or all finite-EI lines on the Hermite route; flat seabed)
+       ``EI = 0`` lines, or all finite-EI lines on the Hermite route; flat seabed); a deck with
+       torsion is rejected
    * - VIV (``compVIV``)
      - Not implemented
      - use another validated model; CableDyn rejects the request