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
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,13 @@ All notable changes to CableDyn are recorded in this file. The format follows
`sqrt(EA/m)`) the time step `dtM` resolves in fewer than six steps gets a note with the
period and a `dtM` that resolves it, on the standalone, mixed and OpenFAST routes. Results do
not change.
- OpenFAST with `dtM` larger than `DT`: between CableDyn solves the coupled loads are
extrapolated from the last two solves instead of held (deck `OPTIONS predictLoads`, default
`True`; `False` keeps the hold). The error drops from first to second order in `dtM`: on the
IEA-15 MW VolturnUS-S at `dtM = 0.1 s` and `DT = 0.025 s` the platform motions differ from a
`dtM = DT` run by at most 0.12 % of their standard deviation, against 0.42 % held. Runs at
`dtM = DT` (the default) do not change; the previous solve's loads are checkpointed, so a restart
continues the extrapolation.

### Changed

Expand Down
8 changes: 8 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -333,6 +333,7 @@ add_library(cabledyn_obj OBJECT
src/CableDyn_Precision.f90
src/CableDyn_FatalReport.f90
src/CableDyn_Profile.f90
src/CableDyn_LoadPredictor.f90
src/CableDyn_PathIO.f90
src/CableDyn_Banner.f90
src/CableDyn_Linalg.f90
Expand Down Expand Up @@ -1103,6 +1104,13 @@ add_test(NAME dtm_advisor
COMMAND test_dtm_advisor ${CMAKE_SOURCE_DIR}/examples/iea15mw_umaine_mixed_cabledyn.dat)
set_tests_properties(dtm_advisor PROPERTIES LABELS "fortran;unit;openfast")

# The load predictor between supercycled OpenFAST solves: used only between consecutive commits,
# exact at the commit and for loads linear in time, second order otherwise.
add_executable(test_load_predictor tests/test_load_predictor.f90)
target_link_libraries(test_load_predictor PRIVATE cabledyn_core)
add_test(NAME load_predictor COMMAND test_load_predictor)
set_tests_properties(load_predictor PROPERTIES LABELS "fortran;unit;openfast")

# The same deck initialises without a static compression/mesh note: the touchdown
# contact kink is element-local, the smoothed element-mean axial force is tensile.
add_executable(test_flagship_compression_note tests/test_flagship_compression_note.f90)
Expand Down
3 changes: 2 additions & 1 deletion doc/faq.rst
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,8 @@ OpenFAST coupling
:class: note

CableDyn solves on ``dtM`` (the glue ``DT`` unless the deck sets a larger ``dtM``) and, with a
larger ``dtM``, holds its committed loads/channels between solves on the faster glue clock of
larger ``dtM``, holds its committed channels between solves (its coupled loads are
extrapolated from the last two solves) on the faster glue clock of
OpenFAST (maintained by NLR, the National Laboratory of the Rockies, formerly NREL). A smaller
``DT_Out`` records more copies of the held value; it does not add physical bandwidth. Plot
``<OpenFASTRoot>.CD.out`` for the solver-native record containing one row per genuine CableDyn
Expand Down
5 changes: 3 additions & 2 deletions doc/modeling.rst
Original file line number Diff line number Diff line change
Expand Up @@ -200,8 +200,9 @@ performance comparisons keep the default.
Choose ``dtM`` by convergence of peaks, phase, rainflow ranges, and accumulated damage—not only by
solver success. Numerical stability at a large implicit step is not evidence of fatigue accuracy.
In OpenFAST the default is ``dtM = DT`` (a solve every glue step); with a larger deck ``dtM``,
loads and assembled OpenFAST channels are zero-order-held between CableDyn solves, which delays
the loads by about ``dtM/2`` (see :doc:`openfast`). The separate ``.CD.out`` contains only genuine committed
the coupled loads are extrapolated from the last two CableDyn solves (or held, with
``predictLoads False``, which delays them by about ``dtM/2``) and the assembled OpenFAST channels
are held between solves (see :doc:`openfast`). The separate ``.CD.out`` contains only genuine committed
``dtM`` samples, while ``DT_Out`` changes the assembled OpenFAST recording cadence only. Neither
file convention substitutes for a time-step convergence study, which should cover the forcing
bandwidth, the shortest element transit time, contact switching, and constitutive relaxation
Expand Down
38 changes: 27 additions & 11 deletions doc/openfast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,10 @@ Time step

``DT`` is the OpenFAST glue step; ``dtM`` is CableDyn's committed step. With no deck ``dtM``,
CableDyn solves every glue step (``dtM = DT``). A deck ``dtM`` that is a whole multiple of ``DT``
solves once per that many glue steps and holds its loads (zero-order hold) between commits, which
is faster but delays the loads (see the note below). The console reports the result, for
solves once per that many glue steps, which is faster. Between commits the coupled loads are
extrapolated from the last two commits (deck ``OPTIONS predictLoads``, the default) or, with
``predictLoads False``, held at the last commit, which delays them (see the note below). The
console reports the result, for
example ``CableDyn time step dtM = 2.50000E-02 s (1 x glue DT; deck dtM)``. A deck ``dtM``
larger than ``DT`` but not a whole multiple of it is never coarsened: CableDyn uses the largest
multiple of ``DT`` that does not exceed it and reports a warning with both values (``dtM = 0.025``
Expand All @@ -92,15 +94,29 @@ peaks, and damage. If CableDyn needs a smaller step than the glue step, reduce `

.. note::

With ``dtM`` larger than ``DT``, CableDyn holds its loads between commits, so the platform
receives the mooring load on average half a ``dtM`` late. A spring force delayed this way
acts on the platform as a negative damping of about the mooring stiffness times ``dtM/2``. For a catenary mooring this
is small: in the three-seed DLC-1.1 comparison of :doc:`validation` the platform motions with
``dtM`` above ``DT`` agree with MoorDyn within 0.6 % in mean and standard deviation, but the
fairlead tension's standard deviation differs by about 3 % from CableDyn's own solution at
every glue step. For stiff taut, semi-taut or tension-leg moorings the lag can be comparable
to the system's own damping. Check such systems, and any fatigue or tension-range result, at
a smaller ``dtM`` (down to ``dtM = DT``) before relying on them.
With ``dtM`` larger than ``DT``, the loads CableDyn returns at a glue step a fraction
:math:`\tau = (t - t_c)/\mathrm{dtM}` past its last commit :math:`t_c` are extrapolated from
that commit and the one before, :math:`F = F_c + \tau\,(F_c - F_p)`. Their error is of
second order in ``dtM`` (:math:`\tau(1+\tau)\,\mathrm{dtM}^2 \ddot F/2`). Held instead
(``predictLoads False``), the platform receives the mooring load on average half a ``dtM``
late, and a spring force delayed this way acts on the platform as a negative damping of about
the mooring stiffness times ``dtM/2``.

On the IEA-15 MW VolturnUS-S in a turbulent 600 s DLC-1.6 environment at ``dtM = 0.1 s``
(four glue steps of 0.025 s), the platform surge, sway, roll and pitch time series differ from
the ``dtM = DT`` run by at most 0.12 % of their standard deviation with the extrapolation, on
the chain mooring as on the chain and power-cable mooring, where the held loads give up to
0.42 %. The chain-only run took a fifth less time (116 s against 141 s for ``dtM = DT``
on the same machine). In the three-seed DLC-1.1 comparison
of :doc:`validation`, made with held loads, the platform motions with ``dtM`` above ``DT``
agree with MoorDyn within 0.6 % in mean and standard deviation, but the fairlead tension's
standard deviation differs by about 3 % from CableDyn's own solution at every glue step.

The extrapolation does not change how the lines themselves are integrated: each line still
steps on ``dtM``, so its own resolution (see the ``dtM`` advisory in :doc:`modeling`) decides
its tension accuracy, and the output channels and the ``.CD.out`` record the committed
samples. For stiff taut, semi-taut or tension-leg moorings, and for any fatigue or
tension-range result, check a smaller ``dtM`` (down to ``dtM = DT``) before relying on it.

Fluid source
~~~~~~~~~~~~
Expand Down
9 changes: 9 additions & 0 deletions doc/options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -527,6 +527,15 @@ Finite-EI cable controls
controlled one-way comparison, not a physical operating configuration
- OpenFAST (coupled finite-EI cables)
- ``True cable_load_feedback``
* - ``predictLoads`` / ``predict_loads``
- logical
- ``True``
- with ``dtM`` larger than the glue ``DT``: ``True`` extrapolates the coupled loads between
CableDyn solves from the last two, ``False`` holds the last solve's loads (about ``dtM/2``
late). No effect at ``dtM = DT``; the output channels hold the committed samples either way
(see :doc:`openfast`)
- OpenFAST
- ``False predictLoads``

Ambient fluid and prescribed motion
-----------------------------------
Expand Down
9 changes: 9 additions & 0 deletions src/CableDyn_DeckDriver.f90
Original file line number Diff line number Diff line change
Expand Up @@ -634,6 +634,9 @@ MODULE CableDyn_DeckDriver
! channels remain available; FALSE suppresses only its reaction at the host
! moving-point boundary. The default preserves ordinary two-way coupling.
LOGICAL :: cable_load_feedback = .TRUE.
! OpenFAST supercycling (dtM > DT): extrapolate the coupled loads between dtM solves from the
! last two (CableDyn_LoadPredictor); FALSE holds the last solve's loads
LOGICAL :: predict_loads = .TRUE.
! Opt-in adaptive mesh for COUPLED finite-EI cables: when set, a cable whose static IC is
! diagnosed under-resolved (CD_HermiteCable_Resolution_Metrics fragile) is refined by
! warm-started cubic-Hermite prolongation before the coupled dynamic run. Default FALSE keeps
Expand Down Expand Up @@ -1018,6 +1021,8 @@ MODULE CableDyn_DeckDriver
LOGICAL :: host_wave_enabled = .FALSE.
LOGICAL :: host_current_enabled = .FALSE.
LOGICAL :: cable_load_feedback = .TRUE.
! Deck OPTION predictLoads (the OpenFAST shell; see CD_AGG_ModuleType%predict_loads)
LOGICAL :: predict_loads = .TRUE.
! OPTION maxStrain, for the per-step plausibility guard of the coupled EI=0 lines.
REAL(wp) :: max_strain = 0.5_wp
REAL(wp), ALLOCATABLE :: host_current_profile_z(:)
Expand Down Expand Up @@ -6540,6 +6545,7 @@ SUBROUTINE CD_Init_Deck_Aggregate(deck_path, dt, agg, ErrStat, ErrMsg, env_gravi
END IF
agg%n_turbines = nturb
agg%cable_load_feedback = opts%cable_load_feedback
agg%predict_loads = opts%predict_loads
agg%max_strain = opts%max_strain

! The standalone driver retains DeckOptions and evaluates a WaveKinMod-1 Fourier
Expand Down Expand Up @@ -7636,6 +7642,7 @@ SUBROUTINE CD_End_Deck_Aggregate(agg)
agg%host_wave_enabled = .FALSE.
agg%host_current_enabled = .FALSE.
agg%cable_load_feedback = .TRUE.
agg%predict_loads = .TRUE.
agg%max_strain = 0.5_wp
IF (ALLOCATED(agg%host_current_profile_z)) DEALLOCATE (agg%host_current_profile_z)
IF (ALLOCATED(agg%host_current_profile_velocity)) DEALLOCATE (agg%host_current_profile_velocity)
Expand Down Expand Up @@ -14244,6 +14251,8 @@ SUBROUTINE apply_option(line, opts, ErrStat, ErrMsg)
END SELECT
CASE ('cable_load_feedback', 'cableloadfeedback')
CALL rd_bool(val, opts%cable_load_feedback, ErrStat, ErrMsg)
CASE ('predict_loads', 'predictloads')
CALL rd_bool(val, opts%predict_loads, ErrStat, ErrMsg)
CASE ('tensile_safety', 'tensilesafety')
CALL rd_tensile_mode(val, opts%tensile_mode, ErrStat, ErrMsg)
CASE ('tensile_strain_tolerance', 'tensilestraintolerance')
Expand Down
45 changes: 45 additions & 0 deletions src/CableDyn_LoadPredictor.f90
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
! File: src/CableDyn_LoadPredictor.f90
! SPDX-License-Identifier: Apache-2.0
! Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University
MODULE CableDyn_LoadPredictor
!! Coupled loads between supercycled mooring solves. When the mooring steps on dtM, a whole
!! number of host steps, the host still asks for the loads at every one of its steps. Held at
!! the last committed solve they lag the platform by up to dtM; extrapolated linearly from
!! the last two committed solves,
!!
!! F(t) = F_c + tau (F_c - F_p), tau = (t - t_c)/dtM in [0, 1],
!!
!! they follow it to second order: the error is of order dtM^2 F'' instead of dtM F'. The
!! extrapolation is used only when the two solves are exactly one dtM apart (consecutive
!! commits), so the first interval of a run, or after a gap, keeps the held loads.
USE CableDyn_Precision, ONLY: wp
IMPLICIT NONE
PRIVATE
PUBLIC :: CD_Predictor_Ready, CD_Predictor_Fraction, CD_Predict_Loads

CONTAINS

PURE LOGICAL FUNCTION CD_Predictor_Ready(t_commit, t_prev, dt) RESULT(ready)
!! The previous committed solve (time t_prev; negative when there is none) is the one
!! immediately before the last (time t_commit): exactly dt earlier, within 1e-6 dt.
REAL(wp), INTENT(IN) :: t_commit, t_prev, dt
ready = .FALSE.
IF (.NOT. (dt > 0.0_wp .AND. t_prev >= 0.0_wp)) RETURN
ready = ABS((t_commit - t_prev) - dt) <= 1.0e-6_wp*dt
END FUNCTION CD_Predictor_Ready

PURE REAL(wp) FUNCTION CD_Predictor_Fraction(t, t_commit, dt) RESULT(tau)
!! The fraction of the mooring step elapsed since the last committed solve, clamped to
!! [0, 1] (no extrapolation beyond one step, none backwards).
REAL(wp), INTENT(IN) :: t, t_commit, dt
tau = MAX(0.0_wp, MIN(1.0_wp, (t - t_commit)/dt))
END FUNCTION CD_Predictor_Fraction

PURE SUBROUTINE CD_Predict_Loads(f_last, f_prev, tau, f)
!! F = F_c + tau (F_c - F_p), element by element.
REAL(wp), INTENT(IN) :: f_last(:, :), f_prev(:, :), tau
REAL(wp), INTENT(OUT) :: f(:, :)
f = f_last + tau*(f_last - f_prev)
END SUBROUTINE CD_Predict_Loads

END MODULE CableDyn_LoadPredictor
4 changes: 4 additions & 0 deletions src/CableDyn_OpenFAST_Aggregate.f90
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,9 @@ MODULE CableDyn_OpenFAST_Aggregate
! cable march, environmental loading, and output channels active but zeros
! its moving-point load and moment for a controlled one-way comparison.
LOGICAL :: cable_load_feedback = .TRUE.
! Deck OPTION predictLoads: the OpenFAST shell extrapolates the coupled loads between
! supercycled solves (TRUE) or holds the last solve's (FALSE)
LOGICAL :: predict_loads = .TRUE.
! Deck OPTION maxStrain: the per-step plausibility bound on the EI=0 system lines.
REAL(wp) :: max_strain = 0.5_wp
INTEGER :: ncp_sys = 0 ! moving points owned by sys
Expand Down Expand Up @@ -330,6 +333,7 @@ SUBROUTINE CD_AGG_Init_From_Deck(self, deck_path, dt, ErrStat, ErrMsg, env_gravi
candidate%host_wave_enabled = parts%host_wave_enabled
candidate%host_current_enabled = parts%host_current_enabled
candidate%cable_load_feedback = parts%cable_load_feedback
candidate%predict_loads = parts%predict_loads
candidate%max_strain = parts%max_strain
IF (ALLOCATED(parts%host_current_profile_z)) THEN
candidate%host_current_profile_z = parts%host_current_profile_z
Expand Down
Loading
Loading