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
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,17 @@ All notable changes to CableDyn are recorded in this file. The format follows
and `SYROPE IC` applies to every Syrope section of the line. On a 400 m polyester section
between chains every element starts on its OWC to 2e-11, and a still run keeps the fairlead
tension. Example `composite_chain_syrope_chain.dat`, on a moving vessel.
- Torsional inertia and damping of finite-EI lines: in the dynamics a line restrained in torsion
carries a twist angle at every node, against directors that follow the node tangents by the
smallest rotation over each step, with the polar rotary inertia `Irn` of its LINE TYPES row and
the torsional damping `Bt` of a new third part of the `GJ` column (`GJ|K|Bt`, negative for a
damping ratio). The torque now varies along the line (`Torq<L>N<J>` is the node's) and
travels as a torsional wave; the statics stay condensed, and in the limit of a negligible
inertia the dynamics reproduce the condensed torsion. The step solves the angles with the
cable in one band of half-width 13; the twist state joins the snapshot, the recovering step
and the OpenFAST checkpoint mirror. Decks with torsion whose `Irn` was a placeholder (the
column was unused before) need the section's real value. The Python deck reader and builder
take `GJ|K|Bt` (builder `gj=(GJ, K, Bt)`).
- Torque–tension coupling of finite-EI cables: the 14-column LINE TYPES row's `GJ` column takes
`GJ|K`, with `K` the coupling of an armoured cable or wire rope (`T = EA ε + K τ`,
`M = GJ τ + K ε`). The cable carries the axial stiffness `EA − K²/GJ` of a section free to twist.
Expand Down
15 changes: 15 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -632,6 +632,16 @@ 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_twist_kernel tests/test_hermite_twist_kernel.f90)
target_link_libraries(test_hermite_twist_kernel PRIVATE cabledyn_core)
add_test(NAME hermite_twist_kernel COMMAND test_hermite_twist_kernel)
set_tests_properties(hermite_twist_kernel PROPERTIES LABELS "fortran;unit")

add_executable(test_nodal_twist_dynamic tests/test_nodal_twist_dynamic.f90)
target_link_libraries(test_nodal_twist_dynamic PRIVATE cabledyn_core)
add_test(NAME nodal_twist_dynamic COMMAND test_nodal_twist_dynamic)
set_tests_properties(nodal_twist_dynamic PROPERTIES LABELS "fortran;unit;dynamic;openfast")

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
Expand Down Expand Up @@ -1394,6 +1404,9 @@ if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU" AND CMAKE_C_COMPILER_ID STREQUAL "GN
# 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")
# And with the nodal twist (polar inertia, torsional damping, the 7-DOF-per-node band).
add_test(NAME step_allocations_nodal_twist COMMAND test_step_allocations nodal)
set_tests_properties(step_allocations_nodal_twist PROPERTIES LABELS "fortran;dynamic;memory")
endif()

add_executable(test_snap_load tests/test_snap_load.f90)
Expand Down Expand Up @@ -2789,6 +2802,8 @@ if(CABLEDYN_ENABLE_COVERAGE)
test_line
test_hermite_cable
test_hermite_torsion_kernel
test_hermite_twist_kernel
test_nodal_twist_dynamic
test_hermite_torsion_static
test_hermite_torsion_dynamic
test_hermite_cable_static
Expand Down
30 changes: 28 additions & 2 deletions VALIDATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ article's methods, are compared in
| **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 |
| **T-13** | Nodal twist (torsional inertia and damping) | condensed torsion in the limit of no inertia; continuum torsional wave; `ζ = ω Bt/(2 GJ)`; energy; restart | ≤6e-7 against the condensed torsion; wave torque 0.07 %; decrement 6 %; energy band 4.9e-4; restart bit-identical | see [Torsion](#torsion) | Pass |
| **T-12** | Torque–tension coupling | `T = EA ε + K τ`, `M = GJ τ + K ε` closed forms; kernel FD; march | ≤1e-7 against every closed form; kernel gradient 1.7e-10, Hessian 9.8e-11 | see [Torsion](#torsion) | Pass |
| **T-11** | Torsion on the coupled OpenFAST / FAST.Farm route | `GJ (−roll)/L`; single coupled cable; uninterrupted run | twist ≤1.8e-15°, torque ≤1.7e-13 N·m; aggregate = single cable bit for bit; restart bit-identical (aggregate and `openfast -restart`) | see [Torsion](#torsion) | Pass |

Expand Down Expand Up @@ -999,6 +1000,30 @@ in parentheses).

A 20 s march that moves End A 0.1 m away and rolls it −90° ends on the static values of that
state to 1e-7. `GJ|0` equals the uncoupled cable bit for bit, and `K² ≥ EA GJ` stops by name.
- **T-13 nodal twist** (`nodal_twist_dynamic`, `hermite_twist_kernel`). The reference twist of the
time-parallel-transported directors equals the direct composition of the smallest rotations
to 1e-13 (interior element, rigid End A, rigid End B, one element rigid at both ends, an
elastic end's spring), equals the fine transport along the element with the holonomy to
1e-6, and has the gradient and Hessian of its finite differences. On the 10 m line
(EA 1e5 N, EI 100 N·m², GJ 80 N·m², 20 elements):
- with `Irn = 1e-9 kg·m` it reproduces the condensed torsion through 300 steps of sway, a
roll of more than a turn and an imposed twist, for clamped, bending-pinned and elastic
ends: centreline to 1.3e-10 m, mean torque 1.7e-12, node torques 5.9e-7, end force 9.9e-8
and end moment 5.5e-7 relative;
- with `Irn = 0.5 kg·m`, rolled at half its first torsional frequency, the held end carries
the continuum torque `GJ A k/sin(kL)` to 0.07 %;
- with `Bt` for `ζ_1 = 0.05`, the first torsional mode rings down with the logarithmic
decrement 0.334 against 0.315 (6 %, the faster higher modes not yet gone);
- in free vibration at `ρ∞ = 1` the energy stays in a band of 4.9e-4 of the vibration energy
(3.8e-4 without torsion), and a run restored from a snapshot or rebuilt from the checkpoint
mirror continues bit-identically.

The torsion gates of `torsion_deck`, `coupled_torsion` and `torsion_coupling` run in the
limit of a negligible polar inertia (`Irn = 1e-12` and `1e-9 kg·m`), whose closed forms they
check; at a direct non-stepping write of the coupled end, the end element alone takes the
roll (`GJ (−roll)/l_e`) against the frozen interior. The example
`torsion_lazy_wave_hangoff_twist.dat` (Irn of the section) moves by at most 7e-5 of the
torque against the condensed torsion.
- **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"`
Expand All @@ -1008,8 +1033,9 @@ in parentheses).
(the C API) and a standalone 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 does not resolve self-contact. The torque–tension coupling is checked against
Limits. The torsion model takes no seabed friction against twist and does not resolve
self-contact; its statics are condensed (uniform torque). The nodal twist's inertia and damping
are checked against the continuum and modal closed forms only. The torque–tension coupling is checked against
closed forms only; there is no cross-code or experimental record of it. Dynamic loop
formation (hockling) and a twisted slack catenary against OrcaFlex are not part of this record,
and there is no experimental torsion case.
Expand Down
12 changes: 7 additions & 5 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -83,18 +83,20 @@ Line and constitutive capability
fail closed by name
* - Torsion of finite-EI lines
- Supported 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``), with torque–tension coupling (``GJ|K``), in statics with a stability check and buckling descent, and in dynamics
- isotropic torsion of a finite-EI line restrained in torsion at both ends
(``END CONNECTIONS`` torsion columns, explicit ``GJ``), with torque–tension coupling
(``GJ|K``): condensed (uniform torque) in statics with a stability check and buckling
descent, and a twist angle at every node in dynamics, with the polar inertia ``Irn`` and
torsional damping (``GJ|K|Bt``),
with turning Rigid6 bodies, ``vesselMotion``/``vesselRAO`` and the ``motionFile`` roll
column standalone, and with the platform orientation in coupled OpenFAST and FAST.Farm
runs (torque returned to the platform, ``PtfmInit``, checkpoints; see
:doc:`openfast`); ``Torq``/``Twist`` channels and standalone range graphs. Stopped by
name: the standalone mixed ``EI = 0`` + finite-EI aggregate and the C API (which move the
line ends by translation only), OpenFAST linearisation of a line restrained in torsion,
rod ends, bodies other than Rigid6, lines with ``ATTACHMENTS``, modal analysis, and
``False alpha_force_blend``. Not modelled: seabed friction against twist, torque–tension
coupling, anisotropic sections, self-contact of a loop (see :ref:`theory-torsion`)
``False alpha_force_blend``. Not modelled: seabed friction against twist, anisotropic
sections, self-contact of a loop (see :ref:`theory-torsion`)
* - Hockling loops, nonlinear cross-section laws
- Not provided
- the buckling onset and the post-buckled shape are computed, but a loop that closes on
Expand Down
14 changes: 11 additions & 3 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -256,18 +256,26 @@ row decides:
A stock-order header applies only to the 10-column row.

**Optional finite-EI columns.** A 14-column row adds `GAs`, `GJ`, `Irt`, `Irn` (shear stiffness,
torsional stiffness, transverse and axial rotary inertia per length):
torsional stiffness, transverse and polar (axial) rotary inertia per length):
`Name Diam Mass EA BA EI GAs GJ Irt Irn Cd_n Cd_t Ca_n Ca_t`. The four extra values must be finite
and either all `0` or all `> 0`. All zero, or the 10-column row, selects the circular-section
closure `GAs = EA/(2(1+0.3))`, `GJ = EI/(1+0.3)`, `Irt = m d²/16`, `Irn = m d²/8`. The closure
serves the secondary Cosserat path only: a finite-EI line restrained in torsion
([END CONNECTIONS](#end-connections-optional-finite-ei-lines)) takes `GJ` [N·m²/rad] from the
14-column row of each of its sections and stops by name without it. `GAs`, `Irt` and `Irn` are
not used by the cubic-Hermite route, but the all-or-nothing rule still asks for positive values.
14-column row of each of its sections and stops by name without it. In the dynamics such a line
carries a twist angle at every node, whose polar rotary inertia is `Irn` [kg·m²/m]
(`m r²/2` for a solid round section; see [Nodal twist](theory.rst)): give the section's real
value, as a placeholder `Irn` gives the line a wrong torsional inertia. `GAs` and `Irt` are not
used by the cubic-Hermite route, but the all-or-nothing rule still asks for positive values.
The `GJ` column may be written `GJ|K`, with `K` [N·m] the torque–tension coupling of an armoured
cable or wire rope (`T = EA ε + K τ`, `M = GJ τ + K ε`; see
[Torque–tension coupling](theory.rst)). It needs a finite-EI, linear-elastic type with
`K² < EA·GJ`; the two-moving-end compatibility route refuses it. `GJ|0` is the plain `GJ`.
`GJ|K|Bt` adds the torsional damping `Bt` [N·m²·s] of the nodal twist (the torque
`Bt dτ/dt`, stiffness-proportional: a torsional mode of frequency `ω` has the damping ratio
`ω Bt/(2 GJ)`); a negative `Bt` is `-ζ`, the fraction of an element's critical torsional damping
`l0 √(GJ Irn)` on the final mesh, as `BA` is for the axial damping. It needs a finite-EI type;
`GJ|0|Bt` is damping without coupling.

**Viscoelastic axial stiffness (MoorDyn `ElasticMod`).** The EA and BA columns accept
bar-separated parts:
Expand Down
16 changes: 10 additions & 6 deletions doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -733,22 +733,26 @@ Line-node channels
- deg
* - ``Torq<L>N<J>``
- torque (twisting moment) at node ``J`` of a line restrained in torsion at both ends
(``END CONNECTIONS`` ``TorsStiffness``, see :doc:`driver_format`). It is uniform along the
line, :math:`M = (\Phi - \Theta_{\text{eff}})/C` (:math:`\Theta_{\text{eff}} = \Theta`
without torque–tension coupling); positive for a right-handed twist of End B relative
(``END CONNECTIONS`` ``TorsStiffness``, see :doc:`driver_format`). In the statics it is
uniform along the line, :math:`M = (\Phi - \Theta_{\text{eff}})/C`
(:math:`\Theta_{\text{eff}} = \Theta` without torque–tension coupling); in the dynamics it
is the nodal twist's torque at the node, the mean of its two elements' (an end node's
element; :ref:`nodal twist <theory-nodal-twist>`). Positive for a right-handed twist of End B relative
to End A about the End A → End B tangent, as OrcaFlex's ``Torque``
- N·m
* - ``Twist<L>N<J>``
- material twist of the cable itself from End A to node ``J``, the sum of the element
twists :math:`M L_e/GJ_e` (less :math:`(K/GJ)(l_e - L_e)` under torque–tension coupling)
over the elements between them: 0 at End A, and at End B the
twists :math:`M L_e/GJ_e` (less :math:`(K/GJ)(l_e - L_e)` under torque–tension coupling;
in the dynamics the nodal twist's element twists) over the elements between them: 0 at
End A, and at End B the
twist of the line without the windup of its torsional end springs. OrcaFlex reports the
twist rate (``Twist``, deg/m) instead; here it is integrated from End A
- deg
* - ``Twist<L>``
- total twist of the line, :math:`\Phi - \Theta = M C`, including the windup of
torsional end springs: the imposed twist :math:`\Phi` less the geometric twist
:math:`\Theta` the line takes up by writhing out of its plane
:math:`\Theta` the line takes up by writhing out of its plane (in the dynamics the
element twists plus the end springs' windup)
- deg

Touchdown channels
Expand Down
Loading
Loading