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
69 changes: 69 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,19 @@ All notable changes to CableDyn are recorded in this file. The format follows
Coupling a host (CFD) solver, that compares the call sequence step by step with MoorDyn's C
API: initialisation, vector layout, end-of-step motion, outer correctors, load summation,
the fixed step of the aggregate route, and units.
- Run audit of tension-only (`EI = 0`) lines in the standalone driver. On the initial state and
at every output step it tracks the largest turn of a taut segment's chord, the segments that
snap from slack to taut, and non-physical tension spikes: a segment whose tension (the elastic
tension, or that of its viscoelastic or Syrope law) at one step exceeds four times its own one
step before and after, ten times the largest tension anywhere on the line one step before and
after, and the largest tension of the initial state. The first spike of a line is reported as
a warning, once per line, and the run summary counts them. The run ends with a note when a
taut segment turned by more than 1° in one step (the mean and standard deviation of the
tension err by about 1 % and more above it; 1.3 % at 2.9° on a heaving chain), and when
segments snapped taut while the axial wave crosses a segment more than once per step, so the
snap peaks are not resolved in time. The standalone driver also prints a note for a dynamic
deck with `rhoInf` above 0.95, on the missing numerical dissipation. See the manual's
troubleshooting page.

### Changed

Expand Down Expand Up @@ -153,6 +166,62 @@ All notable changes to CableDyn are recorded in this file. The format follows

### Fixed

- Tension spikes of tension-only (`EI = 0`) lines that go slack. The generalised-α step evaluated
the axial force and the dynamic loads at the blended configuration
`q_α = (1 − α_f) q_{n+1} + α_f q_n`. A segment that was slack at the start of a step and
carries tension at `q_α` then ends the step stretched beyond it,
`q_{n+1} = (q_α − α_f q_n)/(1 − α_f)`, and a segment going slack within a step returned more
work to the motion than its strain energy. Both happened silently at the default
`rhoInf = 0.4`, at every `dtM` from 0.002 to 0.2 s, on realistic input: a light, axially stiff
cable (80 kg/m, EA 8e8 N) under 3 m heave reported 4.2 MN at the fairlead and 3.4 MN at the
anchor (`dtM` 0.0025 s) and 20 MN at the anchor (`dtM` 0.1 s), against 0.1 to 0.18 MN at
`rhoInf = 0`, at `dtM` down to 0.25 ms and with a finite-EI model; the same cable in an `Hs`
8 m JONSWAP sea 0.41 MN at the anchor against 0.043 MN; the shipped viscoelastic polyester in
15 m surge 2.69 MN against 1.80 MN; a semi-taut chain–polyester leg 9.5 MN at the anchor
against 4.6 MN; and a line on a stiff seabed failed the plausibility guard. The step now blends
forces, `(1 − α_f) r(q_{n+1}, v_{n+1}) + α_f r(q_n, v_n)`, as the finite-EI path does, for the
axial force and every dynamic load (damping, viscoelastic and Syrope laws, seabed, drag,
Froude–Krylov, buoyancy; added mass stays at `q_α`). The step-start force is evaluated afresh
at the committed state, so no state is added and restarts stay exact. An element that
releases within a step returns at most its strain energy over the step, so a release can no
longer create energy. Its step-start force acts along its step-start chord for the whole step,
so the cap takes the shortening projected on that chord, which a segment that turns as it goes
slack exceeds by far (a nearly unstretched segment turning by 90° would otherwise return
hundreds of times its strain energy), and it fades out continuously as the end state crosses
the rest length. The viscoelastic and Syrope segments are capped the same way with the tension
of their law, their end tension estimated with a secant stiffness bounded by the law's axial
stiffness, so that damping carried at a vanishing stretch does not make the cap switch
abruptly (the same cable made lightly damped viscoelastic peaks at 0.085 MN at the anchor at
`dtM` 0.1 s, a snap that step does not resolve, against 0.145 MN without the cap on its
segments and 0.082 to 0.095 MN at 0.5 to 2.5 ms). An elastic segment with axial damping
keeps the step-start dashpot force along its old chord too; where its end state is slack, or
taut by less than `α_f/(1 − α_f)` of its stretch, the cap covers that force as well, crediting
the dashpot's end share, so that the whole blend of a segment ending slack returns at most its
strain energy unless that end share alone returns more (in the test chain it returned up to
2750 times that with only the elastic share capped); a damped segment that ends taut beyond
that band keeps the plain force blend. The seabed contact of
a node that lifts off within a step is not capped (see the manual's theory page). At the
default `rhoInf` the reproducers now give 0.10 / 0.09 MN, 0.092 / 0.106 MN, 0.075 / 0.043 MN
and 1.80 MN, as their references, and the stiff-seabed line runs to completion; the
chain–polyester anchor snap peaks at 5.7 MN at `dtM` 0.05 s, a single-step peak (4.6 MN at
0.0025 s) that the new snap note reports. On a linear element the scheme is unchanged, so taut
lines keep their accuracy: every MoorDyn-C, OrcaFlex, analytic and experimental comparison that
runs locally still passes, and its reported error moves by at most 0.35 percentage points (the
minimum fairlead tension of the one-hour VolturnUS-S record, 0.15 % to 0.50 %; the snap-load
peak at 20 ms improves from 2.76 %, published as 2.7 %, to 1.5 %; see VALIDATION.md). Every
`EI = 0` dynamic output changes. Over the shipped examples the statistics of the tensions
change by at most 0.23 % (mean) and 0.9 % (maximum), except the two `als_volturnus` decks,
whose pre-failure anchor snap at 250 s is resolved by one or two samples and peaks 10 % lower.
Static runs and finite-EI lines are unchanged. The step costs up to 6 % more wall time on
`EI = 0` dynamic decks (one more force evaluation per step and about 4 % more Newton
iterations). `False alpha_force_blend`, which until now applied to finite-EI lines only,
selects the former scheme for `EI = 0` lines as well. Lines that the C API builds without a
deck (`CableDyn_InitLine`, `CableDyn_InitLines`) always take the force blend.
- `modified_newton` on `EI = 0` lines (with or without the force blend, so also under
`False alpha_force_blend`) rebuilds the tangent when an iterate reduces the residual by less
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).
- 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
6 changes: 6 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1781,6 +1781,12 @@ add_executable(test_dynamics_regressions tests/test_dynamics_regressions.f90)
target_link_libraries(test_dynamics_regressions PRIVATE cabledyn_core)
add_test(NAME dynamics_regressions COMMAND test_dynamics_regressions)
set_tests_properties(dynamics_regressions PROPERTIES LABELS "fortran;driver;integration;dynamic")
# Tension-only lines going slack and snapping taut at the default rhoInf: force blend, release
# cap and the driver's run audit (the driver executable is passed for its stdout).
add_executable(test_ei0_slack_dynamics tests/test_ei0_slack_dynamics.f90)
target_link_libraries(test_ei0_slack_dynamics PRIVATE cabledyn_core)
add_test(NAME ei0_slack_dynamics COMMAND test_ei0_slack_dynamics $<TARGET_FILE:cabledyn>)
set_tests_properties(ei0_slack_dynamics PROPERTIES LABELS "fortran;driver;integration;dynamic")

add_executable(test_deck_reader_io tests/test_deck_reader_io.f90)
target_link_libraries(test_deck_reader_io PRIVATE cabledyn_core)
Expand Down
28 changes: 17 additions & 11 deletions VALIDATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,15 +74,15 @@ article's methods, are compared in
| **L3-6c** | Irregular-sea (JONSWAP) dynamic lazy-wave | OrcaFlex 11.6d (same 80-component sea) | curv 0.21%; tension 0.20/0.19/0.23%; wave-driven curv rise 1.0%, tension range 2.1% | curv <2%, tension <1%; rise <15%, range <10% | Pass |
| **L3-6d** | Moving-touchdown dynamic contact | OrcaFlex 11.6d installed | curv 0.48/0.58%, tension 0.74/0.90/0.80%, TDP 0.08 m, migration 2–3 m/cycle | curv <3–5%, tension <2–3%, TDP excursion bounds <1.5 m | Pass |
| **L3-6e** | Out-of-plane / 3D whirl response | OrcaFlex 11.6d | 3D curv 0.52%, interior Y env ≤1.0 mm, sag ≤22 mm, tension 0.14/0.17/0.12% | curv <3%, env <5 cm, tension <2–3% | Pass |
| **L3-7** | 1-hour VolturnUS-S mooring dynamic | OrcaFlex 11.6d | `FairTen` mean 0.28%, std 0.25%, min/max 0.15/0.43%, Fourier 0.27/1.13% | ≤5% | Pass |
| **L3-7** | 1-hour VolturnUS-S mooring dynamic | OrcaFlex 11.6d | `FairTen` mean 0.27%, std 0.26%, min/max 0.50/0.43%, Fourier 0.27/1.14% | ≤5% | Pass |
| **L3-H** | Holcombe static lazy-wave experiment | measured marker geometry | position RMSE 1.07–1.89% of suspended length; peak marker-curvature error 0.34–5.54% | end-restraint bracket | Pass |
| **L3-B** | Bergdahl chain experiment, 30 orbit conditions | measured upper-end force | RMSE 1.58 N; MAPE 3.11%; Pearson 0.993; Lin concordance 0.989 | full published matrix | Pass |
| **L3-B** | Bergdahl chain experiment, 30 orbit conditions | measured upper-end force | RMSE 1.58 N; MAPE 3.13%; Pearson 0.993; Lin concordance 0.989 | full published matrix | Pass |
| **L-fig** | Along-arc curvature overlay (CableDyn / OrcaFlex / MoorDyn-F ±4×) | 3-code committed record | CableDyn peak 0.11% from OrcaFlex | <0.5% | Pass |
| **L4-1** | Coupled platform + mooring | synthetic reference | bit-for-bit | — | Pass |
| **L4-1b** | VolturnUS-S coupled platform + power cable | OpenFAST v5.0.0 (CompMooring 5 vs 3) | platform DOFs <0.6% (3-seed DLC-1.1); fairlead and anchor <0.001% static | <3% platform | Pass |
| **L4-1c** | Lozon lazy-wave cable under coupled FOWT motion, 3 depths | OrcaFlex 11.6d | curv amplification 0.05/0.09/0.01%; dyn curv 0.24/0.35/1.01%; tension <0.7% | ampl <2%, curv <2–3%, tension <1.5–2% | Pass |
| **L4-rot** | Coupled mooring rotational stiffness | held 1° pitch geometry | upwind −16.0 kN, downwind +7.8 kN each; first-order restoring moment | signs + first-order | Pass |
| **L5-stab** | Snap-load Δt-stability | sub-CFL fine-dt (0.5 ms) self-ref | peak 2.7% at dt = 20 ms (explicit limit 3.2 ms) | — | Pass |
| **L5-stab** | Snap-load Δt-stability | sub-CFL fine-dt (0.5 ms) self-ref | peak 1.5% at dt = 20 ms (explicit limit 3.2 ms) | — | Pass |
| **L5-stab** | Snap-load Δt-stability, implicit and explicit steps | MoorDyn-C explicit step limit | 20 ms implicit; ~1 ms explicit | — | Pass |
| **L5-V** | VolturnUS-S 1-hr mooring wall-clock | measured, matched protocol | CableDyn 18.1–32 s across repeated runs (full Newton) vs OrcaFlex 14.5 s; heave-only config 10.3 s | — | Pass (response at L3-7) |
| **L5-wc** | Wall-clock vs explicit C solver | external-C RK2 (WD chain) | L2 0.967 s vs external-C 0.541 s; traces validated | matched comparison reported | Pass measured |
Expand Down Expand Up @@ -178,7 +178,7 @@ initialisation.
- **L3-1 WD0050 static** (`l3_orcaflex_static`): fairlead/anchor **0.154% /
0.848%**. The OrcaFlex reference is within 0.657/0.731% of MoorDyn-C.
- **L3-2 regular-wave dynamic** (`l3_orcaflex_wave_dynamic`): mean fairlead
tension **0.298%** (2% acceptance), swing **8.405%** (15% acceptance) against an
tension **0.298%** (2% acceptance), swing **8.411%** (15% acceptance) against an
OrcaFlex reference with implicit dt 0.005 s. Wave stretching changes the OrcaFlex
swing by only 0.18%, and the unpinned OrcaFlex dt=0.1 s is not converged
(refinement moves it toward CableDyn). The residual comes from surface-piercing
Expand Down Expand Up @@ -255,10 +255,11 @@ initialisation.
**0.14 / 0.17 / 0.12%**.
- **L3-7 1-hour mooring dynamic** (`l3_longduration_mooring`): VolturnUS-S
all-chain line driven for one hour by 5 m/90 s surge + 2 m/12 s heave. Over the
steady 3400 s window the `FairTen` channel differs from OrcaFlex by **0.28% in
mean, 0.25% in std, 0.15 / 0.43% in minimum / maximum, and 0.27% (90 s) / 1.13%
steady 3400 s window the `FairTen` channel differs from OrcaFlex by **0.27% in
mean, 0.26% in std, 0.50 / 0.43% in minimum / maximum, and 0.27% (90 s) / 1.14%
(12 s) in Fourier amplitude**. The end-element tension carries the 1.28% static
offset of L2-V in its mean and extremes.
offset of L2-V in its mean and extremes. The force-blended `EI = 0` step moved the
minimum by +7 kN (0.15% before) and the other statistics by at most 0.01%.
- **L-fig curvature overlay**: `l3_lazywave_dynamic` writes each site's along-arc
curvature profile.
[`validation/scripts/curvature_profile_overlay.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/curvature_profile_overlay.py)
Expand Down Expand Up @@ -287,10 +288,13 @@ scripts, results, and source provenance are in
- **L3-B Bergdahl dynamic chain test**
([Bergdahl et al., 2016](https://cabledyn.readthedocs.io/en/latest/references.html#ref-bergdahl2016)):
over the full 30-condition period-radius matrix, cycle-maximum upper-end force
has RMSE 1.58 N, mean absolute percentage error 3.11%, Pearson correlation
has RMSE 1.58 N, mean absolute percentage error 3.13%, Pearson correlation
0.993, and Lin concordance 0.989. Two phase-averaged measured histories have
waveform RMSEs of 5.95% and 2.54% of their force ranges. Halving the mesh length
and the time step changes the mean cycle maximum by at most 0.49% and 0.28%. The
waveform RMSEs of 5.95% and 2.54% of their force ranges; these two were computed with the
executable of the 2026-10-09 record (the configuration-blended `EI = 0` step), because the
article supplement's `expData.dat` they need was not available for the rerun (see the
experiment's README and `provenance.json`). Halving the mesh length
and the time step changes the mean cycle maximum by at most 0.52% and 0.19%. The
0.3125 ms step resolves the segment axial modes that the snap loads excite; at
1.25 ms the maxima are 2–15% higher and vary from cycle to cycle.

Expand Down Expand Up @@ -373,7 +377,9 @@ scripts, results, and source provenance are in
- **Snap load** (`snap_load`): a grounded tension-only line goes slack, then snaps
to ~10 MN. Implicit generalised-α integrates it at **dt = 20 ms, above the
explicit CFL limit of about 3.2 ms**, with every step converged (stable up to about
30 ms in a sweep); the peak is within **2.7%** of the 0.5 ms sub-CFL reference.
30 ms in a sweep); the peak is within **1.5%** of the 0.5 ms sub-CFL reference
(1.1% at 10 ms, 0.05% at 5 ms). Before the force-blended `EI = 0` step these were
2.76 / 0.62 / 0.16%; the 2.76% at 20 ms is the value published as 2.7% (truncated).
- **Implicit and explicit steps**: on the matched near-taut snap, MoorDyn-C's
explicit RK2 needs `dtM ≲ 1 ms`, as expected of an explicit scheme at this line
stiffness; CableDyn's implicit step remains stable at **20 ms**.
Expand Down
5 changes: 4 additions & 1 deletion doc/capi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1044,7 +1044,10 @@ solve returns ``CD_C_SOLVE_FAIL``.

The Newton settings are fixed at their
defaults: relative residual tolerance :math:`10^{-8}`, at most 30 iterations per step, and at
most 12 line-search backtracks.
most 12 line-search backtracks. So is the generalised-α scheme: these lines always take the
force-blended step (``alpha_force_blend`` ``True``, with the release cap on a tension-only line,
:doc:`theory`). They cannot select the configuration blend of 0.1.1 and earlier
(``False alpha_force_blend``), which only a deck sets, through ``CableDyn_InitDeck``.

``CableDyn_InitLines``
~~~~~~~~~~~~~~~~~~~~~~
Expand Down
2 changes: 1 addition & 1 deletion doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -1006,7 +1006,7 @@ syntax form. The most frequently edited keywords are:
| `cable_load_feedback` | coupled finite-EI cable reaction switch. `True` returns cable force and moment to the host. `False` marches the cable with the same moving boundary and host fluid field and keeps its output channels, but returns zero force and moment; use it for a one-way comparison, not as a physical model | `True` |
| `adaptive_mesh` | `True`/`False`; allow finite-EI mesh refinement when the static resolution check is fragile | `False` |
| `cable_statics` | `continuation` or `sequenced`: which finite-EI static route runs first (the other is its fallback); both results are audited | `continuation` |
| `alpha_force_blend` | `True`/`False`; generalised-α blend of the finite-EI dynamics: forces (`True`) or the configuration `q_αf` (`False`), which biases the mean tension of a rotating line at large `dtM` | `True` |
| `alpha_force_blend` | `True`/`False`; generalised-α blend of the finite-EI and `EI = 0` dynamics: forces (`True`) or the configuration `q_αf` (`False`), which biases the mean tension of a rotating finite-EI line at large `dtM` and lets `EI = 0` segments that go slack report spurious tension spikes | `True` |
| `tensile_safety` | `False`, `warn`, or `True`; audits the element-mean axial force (three-point Gauss mean of the signed axial resultant, averaged over an element and its two neighbours). `True` rejects. `warn` commits the state, counts accepted-step events, and reports the worst force, threshold, element and time (the printed `xi` is always 0.5, the element centre) | `False` |
| `tensile_strain_tolerance` | non-negative strain band for the dynamic tensile audit | `2e-6` |
| `recovery_max_substeps` | integer from 4 to 65536; maximum step subdivision for dynamic-step recovery on tension-only and bending lines. Internal prescribed states lie on one C2 quintic trajectory and land on the nominal coupling endpoint. The standalone summary reports recovered intervals and the largest subdivision used | `1024` |
Expand Down
Loading
Loading