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
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,14 @@ All notable changes to CableDyn are recorded in this file. The format follows
`EI = 0` + finite-EI route) the finite-EI cable steps with their residual, tangent and solve
counts and times. Every output file is the same with and without it. See the manual's
command-line page (Run-time profile).
- Torsion of finite-EI lines in coupled OpenFAST (`CompMooring = 5`) and FAST.Farm runs. The
End A frame of a line restrained in torsion turns with the platform orientation, the torque
moment is returned to the platform, `PtfmInit` twists the line in the static initialisation,
the `Torq`/`Twist` channels are written, and the unwrapped twist is restored on a checkpoint
restart. The C API and the standalone deck that mixes `EI = 0` and finite-EI lines without a
body, which move the line ends by translation only, still refuse torsion columns by name, and
so does OpenFAST linearisation of a line restrained in torsion. See the manual's OpenFAST page
(Line torsion).

### Changed

Expand Down
5 changes: 5 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1785,6 +1785,11 @@ 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_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})
set_tests_properties(coupled_torsion PROPERTIES LABELS "fortran;unit;static;dynamic;openfast")

add_executable(test_torsion_orcaflex tests/test_torsion_orcaflex.f90)
target_link_libraries(test_torsion_orcaflex PRIVATE cabledyn_core)
add_test(NAME torsion_orcaflex
Expand Down
26 changes: 23 additions & 3 deletions VALIDATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,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-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
comparison without an acceptance value. **Informative** is reported but not used for
Expand Down Expand Up @@ -875,13 +876,32 @@ in parentheses).
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.
- **T-11 coupled route** (`coupled_torsion`, `torsion_deck`; OpenFAST runs). On the aggregate
surface the OpenFAST and FAST.Farm shells drive, the straight neutral line of T-2 with its End A
on the platform fairlead twists by `−roll` when the platform rolls about the line axis: a
non-stepping update gives `Twist1 = −20°` and `GJ(−roll)/L` at both ends, with the fairlead
moment equal to that torque about the line axis and resisting the roll; a 60 °/s roll gives the
quasi-static torque at every step (twist error 1.8e-15°, torque 1.7e-13 N·m), and the aggregate
column equals the single coupled cable driven with the same calls bit for bit. 1.5 turns of roll
in 18° steps carry no `2π` slip, a snapshot–step–restore–step is bit-identical, and a
non-stepping turn of 100° stops by name without changing the state. `PtfmInit` yaw over a
vertical line and a FAST.Farm `Turbine2` yaw give the static twist `+yaw` (15° and 10°, 1e-5).
The shell's checkpoint recipe, which restores the committed twist before it moves the fairlead
to the restart pose, continues bit-identically after 150° of roll, where the previous order is
refused by the 90° bound. In OpenFAST (IEA-15 MW VolturnUS-S with three chains and a lazy-wave
power cable restrained in torsion, 60 s of irregular SeaState waves, no wind) the run
completes with `Torq4N1 = GJ·Twist4/L`, the twist follows the platform yaw (±0.14° against
±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.
- **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.
`ATTACHMENTS`, modal analysis, the configuration blend (also on the coupled entries), misuse of
the roll column, channels on an unrestrained line, a coupled caller that passes no orientation
(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 no torque–tension coupling, and does not resolve self-contact. Dynamic loop
Expand Down
16 changes: 9 additions & 7 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -80,17 +80,19 @@ Line and constitutive capability
- single-section taut dynamic line with OWC and two history states; composite, hydro,
finite-EI, current, and wave combinations fail closed by name
* - Torsion of finite-EI lines
- Standalone only, with limits
- 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
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`)
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`)
* - 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
20 changes: 11 additions & 9 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -815,15 +815,17 @@ Behaviour:

Scope. A torsionally restrained line needs a finite-EI line with a `Fixed` End B, an explicit
`GJ` on every section, and, at End A, a `Fixed`, `Coupled`/`Vessel` point or a Rigid6
`Body<N>` point. Each of the following stops with a named error: torsion on an `EI = 0` line,
on a rod end or on a `Point3` body, a line with `ATTACHMENTS`, modal analysis (`nModes`), a
dynamic run with `False alpha_force_blend`, any restrained end (one end included) in a coupled
OpenFAST or FAST.Farm run or in a deck mixing `EI = 0` and finite-EI lines without a body
(`torsion is not yet supported in a deck that mixes ...`; with a body such a deck runs on the
multibody route, which supports torsion), and a `Torq`/`Twist` channel on a line that is not
restrained at both ends. Seabed
friction does not resist twist (the laid part of a line twists freely), and there is no
torque–tension coupling.
`Body<N>` point; in a coupled OpenFAST or FAST.Farm run the End A frame turns with the platform
(see the manual's OpenFAST page, Line torsion). Each of the following stops with a named error:
torsion on an `EI = 0` line, on a rod end or on a `Point3` body, a line with `ATTACHMENTS`,
modal analysis (`nModes`), a dynamic or coupled run with `False alpha_force_blend`, any
restrained end (one end included) in a standalone deck mixing `EI = 0` and finite-EI lines
without a body or through the C API, which move the line ends by translation only (`a line
restrained in torsion needs a host that turns its fairlead frame ...`; with a body such a deck
runs on the multibody route, which supports torsion), OpenFAST linearisation of a line
restrained in torsion, and a `Torq`/`Twist` channel on a line that is not restrained at both
ends. Seabed friction does not resist twist (the laid part of a line twists freely), and there
is no torque–tension coupling.

### EQUIVALENT BUOYANCY (optional)

Expand Down
19 changes: 19 additions & 0 deletions doc/openfast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,25 @@ direction reversal of exactly 180° in one host update is rejected, because the
is not unique. Formal linearisation (``Linearize = True``) with a platform-relative end
connection fails during initialisation. Row grammar: :doc:`driver_format`.

Line torsion
------------

A finite-EI line restrained in torsion at both ends (``END CONNECTIONS`` torsion columns, see
:ref:`theory-torsion`) runs coupled as it does standalone. Its End A frame is given in platform
axes and turns with the OpenFAST point-mesh orientation, whatever the bending connection, so a
platform roll, pitch or yaw about the line's end direction twists the line. The torque moment is
returned to OpenFAST with the connection moment, the ``Torq<L>N<J>`` and ``Twist<L>``
channels are available, ``PtfmInit`` twists the line in the static initialisation, and the
unwrapped twist is part of the checkpoint state. End B must be a ``Fixed`` point. Within one
step the line may turn by more than 90° about its end direction, because the step is cut into
substeps; an output probe moves the frame without a step, is limited to 90° from the
committed twist, and stops by name beyond it (a restart first restores the checkpoint's twist,
so it is not limited this way). Formal
linearisation of a line restrained in torsion fails during initialisation: the torque's
rotational stiffness has no column in the translation-only quasi-static reduction. The C API
and the standalone deck that mixes ``EI = 0`` and finite-EI lines without a body move the line
ends by translation only and refuse torsion columns.

Lifecycle features
------------------

Expand Down
17 changes: 12 additions & 5 deletions doc/troubleshooting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -342,11 +342,18 @@ Torsion
- outside the torsion scope (:doc:`capabilities`). Move End A to a ``Fixed``,
``Coupled``/``Vessel`` point or a Rigid6 body, or represent the modules as a smeared
buoyancy section.
* - ``torsion is not yet supported in coupled OpenFAST runs`` / ``torsion is not yet supported
in a deck that mixes EI = 0 and finite-EI lines without a BODY, nor in coupled OpenFAST or
FAST.Farm runs``
- run the torsional line standalone (a mixed deck with a body runs on the multibody route,
which supports torsion), or set ``TorsStiffness Free`` in every ``END CONNECTIONS`` row.
* - ``a line restrained in torsion needs a host that turns its fairlead frame``
- the standalone deck that mixes ``EI = 0`` and finite-EI lines without a body, and the C
API, move the line ends by translation only. Run the line in a coupled OpenFAST or
FAST.Farm run, add a body (such a deck runs on the multibody route, which supports
torsion), or set ``TorsStiffness Free`` in every ``END CONNECTIONS`` row.
* - ``formal OpenFAST linearization of a line restrained in torsion is not supported``
- linearise the model with ``TorsStiffness Free``; the torque's rotational stiffness is not
part of the quasi-static reduction.
* - ``torsion: the twist would move more than pi/2 from its committed value``
- the host turned a fairlead by more than 90° about the line's end direction without a
step (an output probe or a non-stepping input update). Keep the platform turn per
coupling step well below 90°.
* - ``a body holding a line restrained in torsion turns by more than 90 deg in one step even
after 6 step halvings``
- the body turns faster than one step can follow the twist; reduce ``dtM``.
Expand Down
29 changes: 18 additions & 11 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -3805,9 +3805,11 @@ def _check_torsion_lines(
solved as without the columns. Restrained at both ends, torsion is solved: End B must
be Fixed, every section type needs an explicit GJ > 0, no ATTACHMENTS, End A neither a
rod end nor on a body other than Rigid6. A deck with torsion runs dynamics only with
the force-blended generalised-alpha and takes no modal analysis. The coupled routes
and a standalone mixed EI = 0 + finite-EI deck without bodies (``aggregate_route``,
run on the aggregate) refuse any torsion column, one restrained end included.
the force-blended generalised-alpha (a coupled run is always dynamic) and takes no
modal analysis. A standalone mixed EI = 0 + finite-EI deck without bodies
(``aggregate_route``, run on the aggregate, which moves the line ends by translation
only) refuses any torsion column, one restrained end included; the coupled OpenFAST
and FAST.Farm routes turn the fairlead frame with the platform and accept it.
"""
# _check_attachments has already accepted every LineID as an integer
attachment_lines = {str(_native_int(row.tokens[0])) for row in self._rows("ATTACHMENTS")}
Expand Down Expand Up @@ -3861,19 +3863,24 @@ def _check_torsion_lines(
"a Rigid6 body"
)
torsion_lines.add(line_id)
# native CD_Init_Deck_Aggregate (deck_has_torsion_columns): the coupled routes and a
# standalone mixed EI = 0 + finite-EI deck without bodies refuse any restrained end
if has_torsion_column and (self.caller_driven or aggregate_route):
# native CD_Init_Deck_Aggregate (deck_has_torsion_columns): a standalone mixed EI = 0 +
# finite-EI deck without bodies moves its line ends by translation only and refuses any
# restrained end; the OpenFAST and FAST.Farm hosts turn the fairlead frame
if has_torsion_column and aggregate_route and not self.caller_driven:
raise DeckFormatError(
f"{self._label}: torsion is not yet supported in a deck that mixes EI = 0 and "
"finite-EI lines without a BODY, nor in coupled OpenFAST or FAST.Farm runs (with a "
"BODY such a deck runs on the multibody route, which supports torsion); set "
"TorsStiffness Free in every END CONNECTIONS row"
f"{self._label}: a line restrained in torsion needs a host that turns its fairlead "
"frame: coupled OpenFAST and FAST.Farm runs do, while the C API and a standalone "
"deck that mixes EI = 0 and finite-EI lines without a BODY move the line ends by "
"translation only (with a BODY such a deck runs on the multibody route, which "
"supports torsion); set TorsStiffness Free in every END CONNECTIONS row"
)
if not torsion_lines:
return torsion_lines
tmax_row = option_by_key.get("tmax")
dynamic = has_tmax and tmax_row is not None and _native_float(tmax_row.values[0]) > 0.0
# a coupled run is always dynamic (the host owns TMax)
dynamic = self.caller_driven or (
has_tmax and tmax_row is not None and _native_float(tmax_row.values[0]) > 0.0
)
blend_row = option_by_key.get("alpha_force_blend")
force_blend = blend_row is None or blend_row.values[0].lower() in {
"true",
Expand Down
17 changes: 13 additions & 4 deletions python/tests/test_deck_native_parity.py
Original file line number Diff line number Diff line change
Expand Up @@ -886,16 +886,25 @@ def test_torsion_line_rules_follow_the_native_checks():
one_end = _edit(_TORSION, (_TORSION_ROW_A, "1 A Rigid 1 0 0 Free 0 0 1 0\n"))
_rejects(one_end, "is not torsionally restrained at both ends")
DeckFile.from_text(_edit(one_end, ("Torq1N1\nTwist1N41\nTwist1\n", "FairTen1\n")))
# the dynamic run needs the force blend; modal analysis and the coupled routes refuse torsion
# the dynamic run needs the force blend; modal analysis refuses torsion
dynamic = _edit(_TORSION, ("0.0 TMax\n", "10.0 TMax\n"))
DeckFile.from_text(dynamic)
_rejects(
_options(dynamic, "False alpha_force_blend"), "needs the force-blended generalised-alpha"
)
_rejects(_options(_TORSION, "3 nModes"), "modal analysis .* with torsion is not yet supported")
_rejects(_TORSION, "nor in coupled OpenFAST or FAST.Farm runs", caller_driven=True)
# the coupled routes refuse one restrained end too (any torsion column), after the line rules
_rejects(one_end, "nor in coupled OpenFAST or FAST.Farm runs", caller_driven=True)
# the coupled OpenFAST and FAST.Farm routes turn the fairlead frame with the platform and
# accept torsion, one restrained end included; a coupled run is always dynamic, so it
# needs the force blend whatever the deck's TMax
DeckFile.from_text(_TORSION, caller_driven=True)
DeckFile.from_text(
_edit(one_end, ("Torq1N1\nTwist1N41\nTwist1\n", "FairTen1\n")), caller_driven=True
)
_rejects(
_options(_TORSION, "False alpha_force_blend"),
"needs the force-blended generalised-alpha",
caller_driven=True,
)
_rejects(ei0, "require a finite-EI line; line 1 has EI = 0", caller_driven=True)


Expand Down
Loading
Loading