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
73 changes: 73 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,21 @@ All notable changes to CableDyn are recorded in this file. The format follows
moorings, and quote their results for the enlarged grid. With the `MD_Shared` grid, the
line-1 fairlead tension standard deviation of the tutorial was 18 % too high. See the
manual's OpenFAST page (SeaState grid).
- Active tensioning of finite-EI cables in OpenFAST (`CompMooring = 5`). A `CONTROL` row may
now name a finite-EI (cubic-Hermite) cable, alone or in a deck with `EI = 0` lines. Before
each mooring step, ServoDyn's `CableDeltaL` and `CableDeltaLdot` scale every cable element of
the line's fairlead-side deck segment by (S + `DeltaL`)/S, with the matching rate, so the
segment becomes S + `DeltaL` long. The cable's mass, attachment masses, tributary lengths and
seabed contact coefficients follow the new lengths, and the axial damping acts on the rate of
the strain the elastic force uses, so a segment paid out at constant strain carries no damping
force. The force-blended generalised-α step takes its committed force at the lengths of the
preceding step, so a pay-out ramp follows the quasi-static tension at any `rhoInf`; a deck
that controls a finite-EI cable under `False alpha_force_blend` fails at initialisation with
a message that names the line, as that blend has no such treatment. A command outside
MoorDyn-F's bounds stops the run as for `EI = 0` lines (see Changed), and FAST.Farm decks
still reject `CONTROL`. A zero command, with a `DeltaLdot` of either sign, leaves the run
bit-identical to an uncontrolled one, and a checkpoint restart continues bit-identically. See
the manual's deck format page (CONTROL).

### Changed

Expand Down Expand Up @@ -318,6 +333,16 @@ All notable changes to CableDyn are recorded in this file. The format follows
0.63 m against 0.64 m converged, where the linear interpolation gave 0.23 m. On the
`EI = 0` chain of `examples/chain_range_tdp.dat` the largest step falls from 2.59 m to 1.33 m.
The TDP now lies on the contact-onset height, and `TDP<L>Grd` uses the same location.
- Active tensioning (`CONTROL`) of an `EI = 0` line now stops the run when a command leaves
MoorDyn-F's bounds, as MoorDyn-F does: with `UnstrLen` the line's unstretched length and N its
number of segments, a `DeltaL` above `UnstrLen`/N or below −0.5 `UnstrLen`/N, the comparisons
MoorDyn-F makes, so a command MoorDyn-F accepts is accepted (on a line of one section
`UnstrLen`/N is the controlled segment's initial length). The message names the channel, the
line, the command and the bound. A command beyond these bounds had printed a one-time warning
and been applied. A command within the bounds that would make the controlled segment of a
line of several sections non-positive also stops the run. Finite-EI cables take the same
bounds. Every row is checked before any line changes, and a row that still fails takes back
the lines the command had already changed, so a refused command changes nothing.
- Faster wave kinematics of directional and multi-train seas (`wavetrain` rows, spectral
`waves` rows, `WaveSpreading`). Each component's phase cosine is now computed once for the
surface elevation and the kinematics, and its depth profile with one exponential instead of
Expand Down Expand Up @@ -520,6 +545,54 @@ All notable changes to CableDyn are recorded in this file. The format follows
than a factor four, as the manual states; it had kept the first tangent for the whole step,
which a slow linear contraction could exhaust (30 iterations at the start of the 5 m heave
cells of the L2-2 parity test with the force blend).
- Active tensioning (`CONTROL`) of an `EI = 0` line now changes the segment at the line's
fairlead-side end, the end on a host-driven point (`Coupled`, `Vessel`, `Turbine<J>`,
`Body<N>` or a `Coupled`/`Vessel` rod end), and the segment at the `NodeB` written in the
deck when both or neither ends are host-driven, as MoorDyn-F does for a deck in its own order.
It had always changed the segment at CableDyn's End A, the `NodeA` of a line that the
automatic anchor-first swap leaves in deck order. Two kinds of line change: a line kept in
deck order whose only host-driven end is its `NodeB`, such as a stock-order
`Connect`-to-`Vessel` clump leg or a line from a `Fixed` anchor to a coupled rod end, now
controls the segment at the host-driven end instead of the one at its `NodeA`; and a line
with both or no host-driven ends that the swap leaves in deck order, such as a
`Connect`-to-`Fixed` or `Connect`-to-`Connect` line, a `Fixed` hang-off above a
`Free`/`Connect` point, or a line between two vessel points, now controls the segment at its
`NodeB`. Lines from a `Fixed` anchor to a `Coupled`, `Vessel` or `Body<N>` point,
written in either order, and lines written fairlead first from a host-driven `NodeA` control
the same segment as before.
- Active tensioning (`CONTROL`) of `EI = 0` lines no longer lags behind the commanded length
on a pay-out or haul-in ramp. A length update had re-derived the committed acceleration
under the new length, and the next generalised-α step evaluated its blended configuration
with the new length only, so the force of each length change entered the committed side of
the blend. The committed state now keeps its acceleration and the lengths and rates it was
reached with, and each share of the step after a change takes the lengths of its own time
level. With the force-blended step (the default), the step-start force is evaluated at the
committed lengths and rates: the internal force, every dynamic load, every step-start
quantity of the release cap (stretch, tension, secant and law stiffness, dashpot tension, and
the one-step dissipation budget of a dashpot slack at the step start),
and the distributed external load and seabed coefficients those lengths give; the cap's
end-state quantities take the new lengths; the end-of-step force takes the new lengths, and the inertia (the
structural and added mass, which the force blend keeps at the α level) the blended ones.
Under `False alpha_force_blend` the step blends the old and new lengths with the
configuration. An acceleration re-derived between a command and the next step, as a host
state update does, is solved at the committed lengths, as the step evaluates its committed
side, and leaves them committed. On a taut line paid out at a tension change of 1 N per step,
the tension follows the closed form to 1.8 mN at `rhoInf` 0.4 and 0 alike (the start-up
transient), where a step-start force at the new lengths lags by 2.6 N. In
the coupled OpenFAST comparison with stock MoorDyn (`validation/scripts/activetension/`), the
controlled fairlead tensions had run up to 97 kN (4.1 %) above MoorDyn during the pay-out and
148 kN (6.3 %) below it during the haul-in, at `rhoInf` 0.4 and still 58 kN and 89 kN at
`rhoInf` 0; they now stay within 3 kN (0.13 %). The hold tensions, which the published
comparison scores, move by less than 0.01 %, and the scorer now also gates the ramps.
This change leaves runs without `CONTROL`, and a zero command, bit-identical. A checkpoint restart
re-applies the restored command as the committed state's, so a restart during a ramp
continues bit-identically. A step that `ei0_substeps auto` solves in sub-steps spreads the
length change over them: the committed lengths are part of the state each pass starts from,
each sub-step ends at the lengths and rates interpolated linearly in time (the last at the
new ones), and the trigger takes the step-start tensions at the committed lengths. On a line
turning by 2.3° per step and paid out at 0.05 m/s, the sub-stepped march equals one taken as
given at a quarter of the step to 3e-8 N; applying the whole change in the first sub-step
departs from it by 22 N.
- The development environment (`environment.yml`) excludes OpenBLAS 0.3.34, which caused the
access violation in the modal analysis tests listed under Known issues for 0.1.1. On AMD
Zen 4 and Zen 5 CPUs that expose AVX-512, OpenBLAS 0.3.34 enlarges the GEMM blocking,
Expand Down
11 changes: 11 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -653,6 +653,14 @@ target_link_libraries(test_hermite_axial_damping PRIVATE cabledyn_core)
add_test(NAME hermite_axial_damping COMMAND test_hermite_axial_damping)
set_tests_properties(hermite_axial_damping PROPERTIES LABELS "fortran;unit;dynamic;damping")

# Active line control of a finite-EI cable: the length update rebuilds the caches a fresh
# build carries (bit for bit), is atomic and rewinds exactly; hanging, taut and paid-out
# vertical cables meet their closed forms; a slow ramp ends at the static equilibrium.
add_executable(test_hermite_cable_control tests/test_hermite_cable_control.f90)
target_link_libraries(test_hermite_cable_control PRIVATE cabledyn_core)
add_test(NAME hermite_cable_control COMMAND test_hermite_cable_control)
set_tests_properties(hermite_cable_control PROPERTIES LABELS "fortran;unit;dynamic;hermite")

add_executable(test_hermite_added_mass tests/test_hermite_added_mass.f90)
target_link_libraries(test_hermite_added_mass PRIVATE cabledyn_core)
add_test(NAME hermite_added_mass COMMAND test_hermite_added_mass)
Expand Down Expand Up @@ -2347,6 +2355,7 @@ if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU")
test_hermite_cable
test_hermite_drag_dynamics
test_hermite_axial_damping
test_hermite_cable_control
test_endconn_spring)
target_compile_options(${_cabledyn_exact_real_test} PRIVATE -Wno-compare-reals)
endforeach()
Expand All @@ -2355,6 +2364,7 @@ if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU")
-Wno-uninitialized
-Wno-maybe-uninitialized)
target_compile_options(test_torsion_deck PRIVATE -Wno-uninitialized -Wno-maybe-uninitialized)
target_compile_options(test_hermite_cable_control PRIVATE -Wno-uninitialized -Wno-maybe-uninitialized)
endif()

if(CABLEDYN_ENABLE_COVERAGE)
Expand Down Expand Up @@ -2403,6 +2413,7 @@ if(CABLEDYN_ENABLE_COVERAGE)
test_hermite_cable_dynamic
test_hermite_drag_dynamics
test_hermite_axial_damping
test_hermite_cable_control
test_hermite_added_mass
test_hermite_wave_forcing
test_lazywave_dynamics
Expand Down
3 changes: 2 additions & 1 deletion VALIDATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -757,7 +757,8 @@ stop with a named error.
| Farm + restart / Farm + linearisation | Not applicable | FAST.Farm has no restart and does not call module linearisation; the same applies to stock MoorDyn |
| Line failures (`FAILURE` table) | Pass verified | MoorDyn semantics on both paths (reserve-point pre-allocation, time or tension trigger, detach onto a massless Free point); standalone (point systems and free Rigid6 bodies), coupled, and checkpoint-replay tests |
| Viscoelastic stiffness (`ElasticMod > 1`; [Hall et al., 2023](https://cabledyn.readthedocs.io/en/latest/references.html#ref-hall2023)) | Pass verified | both MoorDyn forms as per-element two-branch series-Kelvin laws eliminated implicitly in the generalised-α step; the standard linear solid is recovered only when the fast-branch dashpot `BA_D` is zero; `md_viscoelastic` r-test 0.007–0.97% at 5× dt; the coupled module carries `dl_1` in the checkpoint state |
| Active tension (`CtrlChan`) | Pass verified | CONTROL parsing, last-segment length/rate modulation, and exact unit tests; coupled A/B in which a ServoDyn cable-control DLL drives the same pay-out/haul-in `DeltaL` schedule into `=5` (CableDyn) and `=3` (stock MoorDyn) in one binary: hold tensions agree to <0.03% and the tension responses to <0.6% (controlled fairleads) / <0.7% (anchors) ([`validation/scripts/activetension/`](https://github.com/SMI-Lab-Inha/CableDyn/tree/main/validation/scripts/activetension), [`validation/scripts/openfast_activetension_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_activetension_ab.py)) |
| Active tension (`CtrlChan`) | Pass verified | CONTROL parsing, last-segment length/rate modulation, and exact unit tests; coupled A/B in which a ServoDyn cable-control DLL drives the same pay-out/haul-in `DeltaL` schedule into `=5` (CableDyn) and `=3` (stock MoorDyn) in one binary: hold tensions agree to <0.03% and the tension responses to <0.6% (controlled fairleads) / <0.7% (anchors); during the pay-out and haul-in ramps the tensions differ by at most 0.13% (controlled fairleads) / 0.39% (anchors) of the baseline tension, with the force-blended step evaluating its step-start force at the committed lengths (the fairleads had differed by up to 4.1% and 6.3% before the length update kept the committed lengths in the generalised-alpha step; the holds were unaffected) ([`validation/scripts/activetension/`](https://github.com/SMI-Lab-Inha/CableDyn/tree/main/validation/scripts/activetension), [`validation/scripts/openfast_activetension_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_activetension_ab.py)) |
| Active tension of finite-EI cables (no MoorDyn-F counterpart) | Pass scoped | coupled A/B with the active-tension model above, line 1 a finite-EI cable of small bending stiffness (EI = 1e5 N m², 50 elements) against stock MoorDyn's chain: during the ramps its tensions differ by at most 0.21% (fairlead) / 0.86% (anchor) of the baseline at `rhoInf` 0.4, and its hold responses by 1.9–2.3% (against the `EI = 0` twin of the same deck this hold difference falls from about 2% at 50 to 0.3% at 100 segments); a restart mid-ramp and `NumCrctn = 1` are bit-identical. Aggregate and model tests: closed forms on axial vertical cables (top reaction w(L + ΔL) to 2e-7, taut top tension EA(H − L′)/L′ + wL′/2 to 1e-12, Kelvin–Voigt pay-out lag BA·H·L̇/L′² to 1e-5 of the lag), slow-ramp end state equal to the static solve of the edited lengths to 2e-6 of the displacement, damping Jacobian with the length rate against finite differences, caches equal to a fresh build and snapshot/restore bit for bit, bit-identical zero command and checkpoint restart (`test_hermite_cable_control`, `test_hermite_axial_damping`, `case_aggregate_cable_control`, `case_restart_cable_control`) |
| Coupled `Rigid6` bodies + `Point3` buoys | Pass verified | 6-DOF `Rigid6` motion with hydrostatic (`C33`/`C44`/`C55`) restoring, checkpoint state (bit-identical `openfast -restart` of a 13.9 MN-swinging tethered body), and SeaState drag / Froude–Krylov / added mass. `Point3` buoys take buoyancy and drag/added-mass/FK; a submerged volume-only buoy takes FK. Tests: `case_coupled_rigid6`/`_mirror`/`_fluid`, `case_coupled_point3_buoy`/`_fluid` |
| Coupled rigid rods | Pass verified | host-driven `Rod<N>A/B` endpoints, correction rewind, bit-identical 24-scalar-per-rod checkpoint state, and two Gauss fluid nodes per rod with SeaState drag/Froude–Krylov/added mass; `case_coupled_rod`, `_mirror`, and `_fluid` pass, and the OpenFAST module compiles with rod decks enabled |
| Coupled pinned rods (`Pinned`, `CoupledPinned`/`VesselPinned`) | Pass verified | `openfast_pinned_rod` on the aggregate: a dry rod (10 m, 500 kg) released at 30° swings with the elliptic-integral compound-pendulum period to 1.6e-4 at `dt = T/100`, End A on the pin to 0 m; a held `CoupledPinned` node reproduces the `Pinned` rod to round-off (1e-12), returns zero moment, and its force equals the analytic pin reaction to 2.0e-13 of `mg`; a pin accelerating at 2 m/s² gives the mean angle `atan(a/g)` to 1e-6 rad and the period of `sqrt(g² + a²)` to 1.6e-4; a harmonic pin motion follows the linear base-excitation solution to 1.5e-3 / 3.7e-4 of the amplitude at `T0/100` / `T0/200` (ratio 4.03); a 0.1 s step sub-cycled 7 times reproduces a run at the sub-step size to 1e-14 rad and 4e-10 N for a drifting pin; a 1 m `Pinned` rod that carries no line (dry and hanging, or buoyant and upright under water) at a 0.6 s step (`omega0 dt` 2.29 / 3.42, beyond the explicit limit 2) sub-cycles it 6 / 9 times from its own swing stiffness `|W d_g - B d_b|`, equals the run at the sub-step size bit for bit, stays within its release angle and keeps the elliptic-integral period to 6.0e-3 / 5.9e-3 (taken whole, the step turns the rod over); a `CoupledPinned` pin crossing the free surface within one step at constant velocity (a 1 kg/m rod lifted from submerged to dry in 0.1 s, `omega dt` 2.13 wet; a 33 kg/m rod lowered from dry to submerged in 0.6 s, 2.29 dry) takes at least 6 sub-steps from its step-start wetting (more from the waterplane near the surface) and ends within 5e-5 / 3e-4 rad of a run at a sixtieth of the step, where the end-of-step wetting alone gives one sub-step and an angle error of 0.20 / 0.69 rad; on a stiff seabed (`kBot` 1e7 N/m³) a `Pinned` rod whose far end rests on the bed (0.1 s step) and a `Free` rod lying on it (0.05 s step) sub-cycle their contact mode (34–36 and 26 sub-steps), stay at rest on the bed over 5 s (angle change 3.8e-3 / 4e-15 rad, the undamped static settlement) and end within 1.9e-6 / 8e-8 of a run at a tenth of the step, where the sub-steps of the lines and swing alone (1 and 4) throw them off the bed (4.2 rad, 0.8 m); an output probe returns `-m (I_c/I_p) a_p` within 1e-10 of `mg` (not `-m a_p`), and its pin force moves by 2e-11 N when the held end acceleration of the attached tethers changes their end load by 8 N; snapshot/restore, probe restore and restart overlay are bit-identical, the restored state's loads before the next step included; a step without the staged rods (the step-start pin carried by the rod) is bit-identical to the staged one; a `Free` or `Coupled` rod with an end without a line is refused by name; with `PtfmInit` the static start leaves 1.4e-8 N·m about the pin. OpenFAST (IEA-15 UMaine, JONSWAP Hs 6 m, 60 s, `dtM = DT = 0.025 s`) with line 1 hung from a 4 m `CoupledPinned` rod at its fairlead: `openfast -restart` at 30 s reproduces every later OpenFAST output row bit for bit (`NumCrctn` 0 and 1), `NumCrctn = 1` equals `NumCrctn = 0` bit for bit, and surge/heave/pitch statistics stay within 0.2 % / 0.4 % / 1.7 % (mean) of the deck with line 1 on a `Coupled` point |
Expand Down
9 changes: 4 additions & 5 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -192,11 +192,10 @@ OpenFAST coverage

The ``CompMooring = 5`` shell covers normal coupled time-domain stepping with its own ``dtM``,
nonzero ``PtfmInit``, correction iterations, SeaState fields, checkpoint/restart, scoped
quasi-static ``dYdu`` linearisation, line failures, active-tension control for ``EI = 0`` lines,
and FAST.Farm shared moorings. Restart and linearisation do not arise under FAST.Farm, which
does not call those module operations. Active ServoDyn control of a finite-EI cable
remains rejected. See :doc:`openfast` for setup and :doc:`coupling_boundary` for the interface
contract.
quasi-static ``dYdu`` linearisation, line failures, active-tension control of ``EI = 0`` lines
and finite-EI cables, and FAST.Farm shared moorings. Restart and linearisation do not arise under
FAST.Farm, which does not call those module operations, and active-tension control is rejected
there. See :doc:`openfast` for setup and :doc:`coupling_boundary` for the interface contract.

How to interpret this page
--------------------------
Expand Down
6 changes: 4 additions & 2 deletions doc/coupling.rst
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,10 @@ solve is mathematically incorrect; changing ``NumCrctn`` does not change that de
Outside that surface the module fails closed — a clear fatal error, never a silent wrong
answer — on:

- active ServoDyn control (``CableDeltaL``) of a finite-EI cable, or any ``CONTROL`` section
in FAST.Farm (``EI = 0`` line control is supported in a single-turbine model),
- any ``CONTROL`` section in FAST.Farm (active ServoDyn control, ``CableDeltaL``, of
``EI = 0`` lines and finite-EI cables is supported in a single-turbine model), a
command outside MoorDyn-F's bounds or one that would make a controlled segment
non-positive, and ``CONTROL`` of a finite-EI cable under ``False alpha_force_blend``,
- coupled ``Rigid6`` bodies and rods in a FAST.Farm deck,
- deck ``waves``/``wavetrain`` OPTIONS (the host SeaState supplies the waves), and a deck
``current`` except as a steady current on a single-turbine, pure ``EI = 0`` deck without
Expand Down
Loading
Loading