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.
- 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.
A line restrained in torsion adds the stretch's share of the twist, `−Σ (K/GJ)(l − L)`, to its
condensed torque, in statics and dynamics and on every route that carries torsion. The node
and element tensions, the element profile, the twist channels and the static and dynamic
`tensile_safety` audits include the coupling, so a stretched cable that opposite-sense torsion
puts into compression is caught. A stretched straight cable reproduces
`T = EA ε`, `M = K ε` between rigid ends and `T = (EA − K²/GJ) ε` with a free end. `GJ|0` is the
uncoupled cable bit for bit. The Python deck reader and builder take `GJ|K` (builder
`gj=(GJ, K)`).
- Section-frame curvature channels `CurvX<L>N<J>` and `CurvY<L>N<J>` on finite-EI lines: the
curvature vector on the cable's cross-section axes, for the fatigue of an armour wire or
conductor at a fixed point of the section. The axes start at End A from the end connection
Expand Down
8 changes: 7 additions & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2081,6 +2081,11 @@ target_link_libraries(test_syrope_composite PRIVATE cabledyn_core)
add_test(NAME syrope_composite COMMAND test_syrope_composite)
set_tests_properties(syrope_composite PROPERTIES LABELS "fortran;driver;integration;static;dynamic")

add_executable(test_torsion_coupling tests/test_torsion_coupling.f90)
target_link_libraries(test_torsion_coupling PRIVATE cabledyn_core)
add_test(NAME torsion_coupling COMMAND test_torsion_coupling)
set_tests_properties(torsion_coupling PROPERTIES LABELS "fortran;unit;driver;integration;static")

add_executable(test_coupled_torsion tests/test_coupled_torsion.f90)
target_link_libraries(test_coupled_torsion PRIVATE cabledyn_core)
add_test(NAME coupled_torsion COMMAND test_coupled_torsion WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
Expand Down Expand Up @@ -2735,7 +2740,8 @@ if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU")
test_hermite_drag_dynamics
test_hermite_axial_damping
test_hermite_cable_control
test_endconn_spring)
test_endconn_spring
test_torsion_coupling)
target_compile_options(${_cabledyn_exact_real_test} PRIVATE -Wno-compare-reals)
endforeach()
target_compile_options(test_openfast_aggregate PRIVATE
Expand Down
14 changes: 13 additions & 1 deletion 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-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 |

**Pass** meets the stated acceptance value. **Pass measured** records a measured
Expand Down Expand Up @@ -988,6 +989,16 @@ in parentheses).
±0.12°), and
`openfast -restart` from 30 s reproduces all 1200 later rows of the OpenFAST and CableDyn
outputs bit for bit. No full FAST.Farm run is part of this record.
- **T-12 torque–tension coupling** (`torsion_coupling`). The effective twist
`Θ − Σ (K/GJ)(l_e − L_e)` of the kernel has the gradient and Hessian of its finite differences on
a curved line (1.7e-10, 9.8e-11). A straight neutral 99 m cable (EA 1e7 N, GJ 5e4 N·m², K 4e5 N·m)
stretched to 100 m gives the closed forms to the printed digits:
- both ends rigid in torsion: `T = EA ε` and `M = K ε`;
- free at one end: `T = (EA − K²/GJ) ε`;
- with a 90° pretwist: `T = EA ε + K Φ/L`, `M = GJ Φ/L + K ε` and `Twist1 = 90°`.

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.
- **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 @@ -998,7 +1009,8 @@ in parentheses).
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
against twist, and does not resolve self-contact. 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
2 changes: 1 addition & 1 deletion doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ Line and constitutive capability
- 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``), in statics with a stability check and buckling descent, and in dynamics
explicit ``GJ``), with torque–tension coupling (``GJ|K``), in statics with a stability check and buckling descent, and in dynamics
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
Expand Down
4 changes: 4 additions & 0 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,10 @@ 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.
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`.

**Viscoelastic axial stiffness (MoorDyn `ElasticMod`).** The EA and BA columns accept
bar-separated parts:
Expand Down
8 changes: 5 additions & 3 deletions doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -734,12 +734,14 @@ Line-node channels
* - ``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)/C`; positive for a right-handed twist of End B relative
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
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``,
:math:`M \sum L_e/GJ_e` over the elements between them: 0 at End A, and at End B the
- 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
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
Expand Down
33 changes: 30 additions & 3 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -471,11 +471,38 @@ and the end tangent together), so the virtual work of the body moment is exact;
line it is the torque along the line axis. The static body equilibrium uses the same moment and
its stiffness :math:`\mathbf{a}\mathbf{a}^{\mathsf T}/C`, :math:`\mathbf{a} = \partial\Theta/\partial\boldsymbol{\omega}_A`.

**Torque–tension coupling.** The helical armour of a power cable or a wire rope couples
stretch and twist. With the coupling :math:`K` of the section (``GJ|K`` in the ``GJ`` column, see
:doc:`driver_format`), the section laws are

.. math::

T = EA\,\varepsilon + K\,\tau, \qquad M = GJ\,\tau + K\,\varepsilon ,

with :math:`\tau` the material twist rate and :math:`EA\,GJ > K^2`. The torque is still uniform
along the line, so the twist rate :math:`\tau = (M - K\varepsilon)/GJ` follows the strain
pointwise and the condensation stays exact. The cable carries the axial stiffness
:math:`EA - K^2/GJ` of a section free to twist, and the twist the ends see is

.. math::

\Theta_{\text{eff}} = \Theta - \sum_e \frac{K_e}{GJ_e}\,(l_e - L_{0,e}), \qquad
M = \frac{\Phi - \Theta_{\text{eff}}}{C} ,

where :math:`l_e = \int_e \lvert\mathbf{r}'\rvert\,\mathrm{d}s` is the stretched element
length, integrated on the bending rule with its gradient and Hessian. Everything else above,
including the rank-one tangent, the step limit and the stability test, holds with
:math:`\Theta_{\text{eff}}`. The coupling part has no :math:`2\pi` ambiguity, so the first
evaluation unwraps the holonomy alone. A line free to twist at one end carries no torque and
the axial stiffness :math:`EA - K^2/GJ`. Restrained at both ends, a straight stretched line
cannot twist, so it carries :math:`T = EA\,\varepsilon` and :math:`M = K\varepsilon`. The node
tension adds the element's :math:`(K/GJ)\,M`, and the twist channels sum the element twists
:math:`M L_0/GJ - (K/GJ)(l - L_0)`.

**Limits.** Seabed friction does not resist twist, so the laid part of a line twists freely
(the friction torque of a cable on the seabed can be comparable with the twist torque near
touchdown). There is no torque–tension coupling of armoured cables or wire ropes, no
anisotropic or pre-twisted section, and no self-contact: a loop that closes on itself is not
resolved. The model is that of :ref:`Meier, Popp & Wall (2014) <ref-meier2014>` and
touchdown). There is no anisotropic or pre-twisted section, and no self-contact: a loop that
closes on itself is not resolved. The model is that of :ref:`Meier, Popp & Wall (2014) <ref-meier2014>` and
:ref:`Bergou et al. (2008) <ref-bergou2008>` restricted to the isotropic, torque-free-span case;
it is not a new formulation.

Expand Down
16 changes: 11 additions & 5 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,8 @@ class LineType:
gas, gj, irt, irn : float | None
Optional finite-EI columns (shear and torsional stiffness, rotary
inertias). All four set writes the 14-column row; all ``None`` writes
the 10-column row.
the 10-column row. ``gj`` may be ``(GJ, K)``, with ``K`` the
torque-tension coupling in N m (written ``GJ|K``).
cl, df, cf : float | None
Optional cross-flow VIV columns of a type (MoorDyn's lift
coefficient and the half-range and centre of the synchronisation band
Expand All @@ -211,7 +212,7 @@ class LineType:
can: float = 0.0
cat: float = 0.0
gas: float | None = None
gj: float | None = None
gj: float | tuple[float, float] | None = None
irt: float | None = None
irn: float | None = None
cl: float | None = None
Expand Down Expand Up @@ -1627,7 +1628,7 @@ def add_line_type(
can: float = 0.0,
cat: float = 0.0,
gas: float | None = None,
gj: float | None = None,
gj: float | tuple[float, float] | None = None,
irt: float | None = None,
irn: float | None = None,
cl: float | None = None,
Expand Down Expand Up @@ -2658,7 +2659,12 @@ def _line_type_table(self) -> tuple[str, str, list[list[str]]]:
extra = (item.gas, item.gj, item.irt, item.irn)
if all(value is not None for value in extra):
wide = True
row += [_num(value, what) for value in extra]
if isinstance(item.gj, tuple) and len(item.gj) != 2:
raise ValueError(f"{what}: gj is GJ or (GJ, K)")
row += [
_multi(value, what) if index == 1 else _num(value, what)
for index, value in enumerate(extra)
]
elif any(value is not None for value in extra):
raise ValueError(f"{what}: give all of gas, gj, irt, irn or none")
row += [_num(v, what) for v in (item.cdn, item.cdt, item.can, item.cat)]
Expand Down Expand Up @@ -3165,7 +3171,7 @@ def line_type(self, row: DeckRecord) -> None:
can=_f(values["can"]),
cat=_f(values["cat"]),
gas=_f(values["gas"]) if wide else None,
gj=_f(values["gj"]) if wide else None,
gj=_fmulti(values["gj"]) if wide else None,
irt=_f(values["irt"]) if wide else None,
irn=_f(values["irn"]) if wide else None,
cl=_f(values["cl"]) if "cl" in values else None,
Expand Down
38 changes: 33 additions & 5 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -2654,6 +2654,8 @@ def numeric(token: str, row: DeckRecord, field: str) -> float:
viv_type_names: set[str] = set()
for row in self.line_types:
for index in (1, 2, *range(5, len(row.tokens))):
if len(row.tokens) == 14 and index == 7:
continue # the GJ column, GJ or GJ|K, is read below
numeric(row.tokens[index], row, f"LINE TYPES column {index + 1}")
ea_parts = row.tokens[3].split("|")
ba_parts = row.tokens[4].split("|")
Expand Down Expand Up @@ -2740,26 +2742,52 @@ def numeric(token: str, row: DeckRecord, field: str) -> float:
if ei > 0.0 and (is_syrope or len(ea_parts) > 1):
model = "Syrope" if is_syrope else "viscoelastic stiffness"
raise DeckFormatError(f"{self._at(row)}: {model} is not supported with EI > 0")
gj_value = 0.0
if len(row.tokens) == 14:
# the GJ column is GJ or GJ|K (K the torque-tension coupling, N m)
gj_parts = row.tokens[7].split("|")
if len(gj_parts) > 2:
raise DeckFormatError(
f'{self._at(row)}: LINE TYPES GJ column "{row.tokens[7]}" takes GJ or GJ|K'
)
gj_value = numeric(gj_parts[0], row, "GJ")
ktt = numeric(gj_parts[1], row, "GJ|K coupling") if len(gj_parts) == 2 else 0.0
finite_ei = [
numeric(row.tokens[index], row, f"LINE TYPES column {index + 1}")
for index in range(6, 10)
numeric(row.tokens[6], row, "LINE TYPES column 7"),
gj_value,
numeric(row.tokens[8], row, "LINE TYPES column 9"),
numeric(row.tokens[9], row, "LINE TYPES column 10"),
]
if any(value != 0.0 for value in finite_ei) and any(
value <= 0.0 for value in finite_ei
):
raise DeckFormatError(
f"{self._at(row)}: explicit GAs/GJ/Irt/Irn must all be positive"
)
if ktt != 0.0:
name = row.tokens[0]
if not ei > 0.0:
raise DeckFormatError(
f"{self._at(row)}: LINE TYPES {name}: torque-tension coupling (GJ|K) "
"needs a finite-EI cable (EI > 0)"
)
if is_syrope or len(ea_parts) > 1:
raise DeckFormatError(
f"{self._at(row)}: LINE TYPES {name}: torque-tension coupling (GJ|K) "
"needs a linear-elastic EA"
)
if not (gj_value > 0.0 and ea_static * gj_value > ktt * ktt):
raise DeckFormatError(
f"{self._at(row)}: LINE TYPES {name}: torque-tension coupling needs "
"GJ > 0 and K^2 < EA GJ"
)
line_type_meta[row.tokens[0].lower()] = (
numeric(row.tokens[1], row, "Diam"),
numeric(row.tokens[2], row, "Mass"),
ea_static,
ei,
)
line_type_gj[row.tokens[0].lower()] = (
numeric(row.tokens[7], row, "GJ") if len(row.tokens) == 14 else 0.0
)
line_type_gj[row.tokens[0].lower()] = gj_value
# Syrope keeps its BA_s on the working-curve model (native BA slot = 0)
line_type_scales[row.tokens[0].lower()] = (
0.0 if is_syrope else ba_values[0],
Expand Down
48 changes: 48 additions & 0 deletions python/tests/test_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -938,3 +938,51 @@ def test_title_is_read_only_after_the_banner() -> None:
assert DeckModel.from_text(banner_only).title == "CableDyn deck"
preamble = "preamble" + chr(10) + text
assert DeckModel.from_text(preamble).title == "single chain catenary"


def test_torque_tension_coupling_round_trips_in_the_gj_column(tmp_path: Path) -> None:
model = _chain_model(tmp_path)
cable = model.add_line_type(
"cable",
diam=0.2,
mass=40.0,
ea=5.0e8,
ei=1.0e4,
gas=1.0e8,
gj=(1.0e4, 2.0e5),
irt=0.1,
irn=0.05,
)
assert cable.gj == (1.0e4, 2.0e5)
target = model.save(tmp_path / "coupled.dat")
deck = DeckFile.read(target)
row = next(r for r in deck.line_types if r.tokens[0] == "cable")
assert [float(v) for v in row.tokens[7].split("|")] == [1.0e4, 2.0e5]
loaded = DeckModel.load(target)
assert next(t for t in loaded.line_types if t.name == "cable").gj == (1.0e4, 2.0e5)


@pytest.mark.parametrize(
("gj", "ei", "message"),
[
("1.0e4|1.0e7", "1.0e4", r"K\^2 < EA GJ"),
("1.0e4|1.0e3", "0.0", "needs a finite-EI cable"),
("1.0e4|1.0e3|5.0", "1.0e4", r"takes GJ or GJ\|K"),
],
)
def test_torque_tension_coupling_refusals(tmp_path: Path, gj: str, ei: str, message: str) -> None:
model = _chain_model(tmp_path)
model.add_line_type(
"cable", diam=0.2, mass=40.0, ea=5.0e8, ei=1.0e4, gas=1.0e8, gj=1.0e4, irt=0.1, irn=0.05
)
text = model.to_text(validate=False)
bad = re.sub(
r"^cable\s.*$",
f"cable 0.2 40.0 5.0e8 0.0 {ei} 1.0e8 {gj} 0.1 0.05 0.0 0.0 0.0 0.0",
text,
flags=re.M,
)
path = tmp_path / "bad.dat"
path.write_text(bad, encoding="utf-8")
with pytest.raises(DeckFormatError, match=message):
DeckFile.read(path)
Loading
Loading