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
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,19 @@ All notable changes to CableDyn are recorded in this file. The format follows

### Added

- OpenFAST linearisation with the line dynamics, as MoorDyn-F's: the continuous states are the
interior-node positions of every `EI = 0` line (MoorDyn's names and order) and the free
degrees of freedom of every finite-EI cable (node positions and tangents), then their
velocities, with `A`, `B`, `C` and `D` by central differences of the accelerations solved at the
perturbed state. On the UMaine chains the stiffness `D - C A^-1 B` matches MoorDyn-F's to 0.1 %
and the lowest nine line-mode frequencies to 0.3 %; with a lazy-wave power cable every coupled
point matches the deck's own static solutions to 3e-4, also with a hang-off spring. A cable
end connection with a numeric stiffness now linearises. The viscoelastic slow-branch stretch
and the Syrope slow strain are first-order states, so the reduction gives these ropes' relaxed
static stiffness (each matches its deck's static solutions to 7e-5; held, they would read the
chain 0.6 % and the polyester 2.9 times too stiff). Free/Connect points, a `Rigid` cable end
connection, VIV lines, bodies, rods, buoys, torsion and `CONTROL` fail closed with named
messages. This replaces the quasi-static linearisation without states.
- 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
37 changes: 28 additions & 9 deletions VALIDATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -372,13 +372,32 @@ scripts, results, and source provenance are in
([`validation/scripts/openfast_lin_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_lin_ab.py)):
the twin decks linearise once at t = 0. Each run has platform DOFs only, still water, and HydroDyn
`ExctnMod = RdtnMod = 0`. MoorDyn's relaxation runs for `TmaxIC = 400 s`, and both `.lin` files are
written with `OutFmt = ES24.15E3`. CableDyn's quasi-static `dYdu` (no states) is compared with
MoorDyn's zero-frequency reduction `D − C A⁻¹ B` over 882 states. The per-fairlead stiffness agrees
to **0.07–0.10%** (line 1: 49 741 / 49 706 N/m in-plane horizontal) and the transverse `H/X` term
to 0.29%. The platform 6×6 diagonals agree to **≤0.10%** (surge 77 211 / 77 156 N/m,
roll 2.6473e8 / 2.6466e8 N·m/rad), and every entry to ≤1.0e-3 of √(KᵢᵢKⱼⱼ). Standalone CableDyn
static solves reproduce the block by finite differences to 1.5e-5, and its transverse term equals
the analytic `H/X`. Both 50-segment models sit 7–12% above the continuous elastic catenary
written with `OutFmt = ES24.15E3`. Both codes linearise the line dynamics over the same 882 states
(each interior node's position and velocity, in MoorDyn's layout and names), and their
zero-frequency reductions `D − C A⁻¹ B` are compared. The per-fairlead stiffness agrees to
**≤0.10%** (line 1: 49 741 / 49 706 N/m in-plane horizontal) and the transverse `H/X` term to 0.29%.
The platform 6×6 diagonals agree to **≤0.10%** (surge 77 211 / 77 156 N/m, roll 2.6473e8 /
2.6466e8 N·m/rad), and every entry to ≤1.1e-3 of √(KᵢᵢKⱼⱼ). Standalone CableDyn static solves
reproduce the block by finite differences to 1e-5, and its transverse term equals the analytic
`H/X`. Both state matrices are stable, and the lowest nine line modes agree in frequency to
**0.04–0.30%** (CableDyn's consistent mass against MoorDyn's lumped mass). The damping ratios are
half MoorDyn's: both difference the quadratic drag over ±0.1 m/s, and CableDyn's drag, integrated
over the element, gives half the slope for a one-node perturbation. A mixed deck
(`examples/iea15mw_umaine_mixed_cabledyn.dat`, seabed friction off) adds 2976 states of the
lazy-wave power cable (positions and tangents of its free nodes, and their rates). Every coupled
point's linearised stiffness equals central differences of the deck's own static solutions to
≤3.3e-4, the cable's 36.0 / 2.62 / 38.5 N/m included, and also with a 5e4 N·m/rad hang-off spring.
Two step sizes had to be small. A millimetre position step lifted the cable's grounded nodes out
of their 0.3 mm seabed penetration on one side of the difference, and a 5 cm coupled-point step
slackened the chain's last element. Each halved a stiffness (the cable's sway stiffness read 242
instead of 2.6 N/m). States and inputs now take 1 µm. The rope models' constitutive states are
first-order states, checked the same way against each deck's static solutions. A viscoelastic
variant of the UMaine chains (`EA 3.27e9|6.54e9`, 150 slow-branch stretches) matches to 7e-5;
held, the stretches would read the chain 0.6 % too stiff. A taut three-leg Syrope polyester
spread with a `SYROPE IC` history (60 slow strains) matches to 6e-6, where held slow strains
would read it 2.9 times too stiff. With every element on one segment of the working-curve
table, the single-secant static start is exact; legs straddling a table kink differ by 2 %,
because that static start takes one secant for the whole line. Both 50-segment models sit 7–12% above the continuous elastic catenary
because of the touchdown discretisation; refining to 800 segments converges to it within 0.1%.
MoorDyn's reduction needs the full-precision `OutFmt`. With the usual `ES10.3E2` (4 digits),
`D ≈ 1e8 N/m` cancels to a ~1e4 N/m result and the block is 57% asymmetric with sign-flipped
Expand Down Expand Up @@ -489,7 +508,7 @@ sizes, timing ranges, memory, Newton work, and the OrcaFlex mesh sweep are in
remeshing), on the development workstation. Each binary output has
exactly 144,001 rows from 600 s to 4200 s with 47 channels. The OpenFAST runtime
Jacobian is the fixed-state direct-feedthrough derivative; formal linearisation
uses the re-equilibrated quasi-static stiffness.
differentiates the line dynamics with the line states registered.

### Numerical robustness

Expand Down Expand Up @@ -780,7 +799,7 @@ stop with a named error.
| Correction iterations (`NumCrctn > 0`) | Pass verified | bit-identical to own `NumCrctn = 0` run |
| SeaState wave/current kinematics | Pass verified | wave A/B ≤0.16% of range |
| Checkpoint-restart (incl. Free/Connect points) | Pass verified | restarted window = continuous run to 0.0; also with supercycling (`dtM` > `DT`, the held SeaState fields and the predictor loads checkpointed): IEA-15 VolturnUS-S, turbulent wind and JONSWAP sea, `openfast -restart` at 50 s reproduces every later OpenFAST and `.CD.out` row of the chain mooring at `dtM` = 4 `DT` (extrapolated and held loads) and `DT`, and of the chain + 248-element power-cable mooring at `dtM` = 2 `DT`. A finite-EI cable also checkpoints its committed boundary (held DOFs, end-connection directions, vessel frame): before, the rebuild took its fairlead from the restored input mesh, which differs in the last bits, and on the IEA-15 mixed deck restarted at 6 s the lazy-wave cable's `.CD.out` channels drifted by up to 9.4e-7 (relative) within 4 s; now all rows to 10 s match bit for bit at `dtM` = `DT` and 2 `DT`, `NumCrctn` 0 and 1, and with a rigid fairlead END CONNECTIONS row |
| Linearisation | Pass verified (quasi-static stiffness) | quasi-static `dYdu` compared entry by entry with stock MoorDyn's zero-frequency reduction `D − C A⁻¹ B` (full-precision `.lin` output): fairlead stiffness 0.07–0.10%, transverse `H/X` term 0.29%, platform 6×6 diagonals ≤0.10%; standalone static FD 1.5e-5; transverse term equals `H/X`. Velocity/acceleration columns are zero by design ([`openfast_lin_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_lin_ab.py)) |
| Linearisation | Pass verified (line dynamics) | line states as MoorDyn-F's (882 on the UMaine chains); zero-frequency reduction `D − C A⁻¹ B` compared entry by entry with stock MoorDyn's (full-precision `.lin` output): fairlead stiffness ≤0.10%, transverse `H/X` term 0.29%, platform 6×6 diagonals ≤0.10%; lowest nine line-mode frequencies 0.04–0.30%, both state matrices stable; a mixed deck with a lazy-wave power cable (2976 cable states) matches its own static solutions at every coupled point to ≤3.3e-4, also with a hang-off spring ([`openfast_lin_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_lin_ab.py)) |
| FAST.Farm shared moorings + clumps + channel record | Pass verified | 600 s A/B of the r-test `MD_Shared` farm against stock MoorDyn (same deck, analysis from 100 s; [`fastfarm_shared_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/fastfarm_shared_ab.py)): tension means ≤0.02%, minima and maxima ≤0.25%, platform motions within millimetres and 0.001°; shared-line tension std 2.2–2.7% lower, 1.0% at half the mooring step (CableDyn's implicit step at the 0.05 s coupling step against MoorDyn's 1e-4 s explicit step). On the shared lines, which have no Fixed end, `FairTen`/`AnchTen` name the opposite ends from MoorDyn's (see the migration guide). MoorDyn's initial settling does not converge for the anchor legs 6 and 7 (2.4 m excess length at t = 0), a start-up transient over by 100 s that most likely set the 3% end of the earlier 60 s record |
| Slack-line tension convention | Pass verified | tension-only dynamics; BA on slack lines matches `MoorDyn_Line.f90` |
| Farm + restart / Farm + linearisation | Not applicable | FAST.Farm has no restart and does not call module linearisation; the same applies to stock MoorDyn |
Expand Down
50 changes: 42 additions & 8 deletions doc/openfast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -326,8 +326,9 @@ hang-off the declared direction is given in platform axes and follows the OpenFA
orientation; its angular velocity and acceleration enter the implicit residual and tangent, and
the connection moment is returned to OpenFAST. Fixed-end directions are global. A rigid
direction reversal of exactly 180° in one host update is rejected, because the shortest rotation
is not unique. Formal linearisation (``Linearize = True``) with a platform-relative end
connection fails during initialisation. Row grammar: :doc:`driver_format`.
is not unique. Formal linearisation (``Linearize = True``) supports pinned and numeric-stiffness
connections; a ``Rigid`` row fails during initialisation, because only the axial stretch of its
end tangent is a degree of freedom (see `Linearisation`_). Row grammar: :doc:`driver_format`.

Line torsion
------------
Expand Down Expand Up @@ -413,15 +414,48 @@ without an auxiliary process:
Each is a separate qualification: a successful ordinary run does not qualify restart,
linearisation, control, failure, or farm behaviour for a new model.

Two different Jacobians
~~~~~~~~~~~~~~~~~~~~~~~
Jacobians
~~~~~~~~~

During time marching, the OpenFAST input–output solver asks for the instantaneous output
derivative with the cable state frozen; CableDyn evaluates it by symmetric perturbation of the
coupled input while preserving the committed state. In a ``Linearize = True`` run CableDyn
registers no dynamic states and reports the re-equilibrated quasi-static stiffness instead.
These are different derivatives and must not be interchanged. ``NumCrctn`` controls glue
correction passes; it does not change which derivative is used.
coupled input while preserving the committed state. A ``Linearize = True`` run differentiates the
line dynamics themselves (`Linearisation`_). ``NumCrctn`` controls glue correction passes; it does
not change which derivative is used.

Linearisation
~~~~~~~~~~~~~

With ``Linearize = True`` CableDyn linearises the line dynamics, as MoorDyn-F does. The continuous
states are the positions of every ``EI = 0`` line's interior nodes and of every finite-EI cable's
free degrees of freedom (node positions and tangents ``m = dr/ds``), followed by their velocities.
``EI = 0`` states carry MoorDyn's names and order (``Line 1 node 1 Px, m`` … ``Vz, m/s``); a cable's
are named ``Cable 1 node 2 Px, m``, ``Cable 1 node 2 Tx, -`` (tangent) and ``Cable 1 node 2 dTx,
1/s`` (its rate), with node 1 at End A. The matrices ``A``, ``B``, ``C`` and ``D`` are central
differences: at each perturbed state or input, the accelerations are solved without a time step.
Positions, tangents and coupled-point displacements are stepped by 1 µm, which stays inside the
seabed penetration of a light cable and the stretch of every taut element. Velocities are stepped
by 0.1 m/s, MoorDyn-F's step.

The zero-frequency reduction ``D − C A⁻¹ B`` is the static mooring stiffness. It agrees with
MoorDyn-F and with CableDyn's own static solutions (:doc:`validation`). Quadratic drag has no
slope at rest, so the 0.1 m/s step gives its equivalent linear damping at that velocity amplitude.
CableDyn integrates the drag over the element, and a one-node step then gives about half of
MoorDyn-F's lumped value.

The constitutive states of the rope models are first-order states, named ``Line 1 segment 3 dl1,
m`` and ``Line 1 segment 3 slow strain, -`` (elements counted from End B, as the nodes): each
viscoelastic element's slow-branch stretch and each Syrope element's slow strain, differentiated
through their own laws. ``D − C A⁻¹ B`` then gives the relaxed static stiffness of these ropes,
not their instantaneous one. Two load histories are held at their operating-point values: the
Syrope running maximum (small motions below it stay on its working curve) and the seabed-friction
stick anchors (a stuck laid run). Linearise from a settled operating point, such as the still-water
start at ``t = 0``.

Initialisation fails with a named message for Free and Connect points, Point3 buoys, Rigid6 bodies
and rods, a line restrained in torsion, a line with VIV (``Cl > 0``: it oscillates about a lock-in
cycle, not an equilibrium), a ``CONTROL`` section, a cable with a ``Rigid`` end connection, and
FAST.Farm. Their states are not linearisation states. Time-domain runs support all of them.

Performance
-----------
Expand Down
15 changes: 9 additions & 6 deletions doc/troubleshooting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -403,8 +403,8 @@ Torsion
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.
- linearise the model with ``TorsStiffness Free``; the twist and the torque carry no
linearisation state.
* - ``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
Expand Down Expand Up @@ -846,10 +846,13 @@ aborts with a CableDyn fatal error, check whether the deck uses one of these com
* - a finite-EI cable in the same deck as Rigid6 bodies, rods, or ``Connect``/``Free`` points
- model the cable and the body/point system in separate decks or use the supported
combinations in :doc:`capabilities`
* - OpenFAST linearisation with a platform-relative cable ``END CONNECTIONS`` row
(``formal OpenFAST linearization with a platform-relative cable end connection is not
supported``) or with a ``CONTROL`` section
- linearise a pinned-hang-off, uncontrolled variant of the deck; time-domain runs support both
* - OpenFAST linearisation of a cable with a ``Rigid`` ``END CONNECTIONS`` row (``formal
OpenFAST linearization of a cable with a rigid end connection is not supported``), of a deck
with ``Free`` or ``Connect`` points or a line with VIV (``Cl > 0``), or with a ``CONTROL``
section
- linearise a variant with a numeric rotational stiffness at the hang-off, the lines attached to
``Fixed`` or ``Coupled`` points, ``Cl = 0`` and no ``CONTROL`` section; time-domain runs
support all of them
* - a ``Rigid`` end-connection direction reversed by exactly 180 degrees in one host update
- drive the platform through intermediate orientations
* - VIV on a finite-EI line with two moving ends (``needs its End B fixed``)
Expand Down
Loading
Loading