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
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@ All notable changes to CableDyn are recorded in this file. The format follows
their sections and, in OpenFAST, `CalcOutput` into the kinematics overlay, the output channels
and the restore, and the SeaState sampling into the node queries, the grid checks and the
hand-over of the fields. Results do not change.
- dtM advisory: at initialisation, a line whose axial period (twice its length over
`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.

### Changed

Expand All @@ -31,6 +35,11 @@ All notable changes to CableDyn are recorded in this file. The format follows
bit-identical to the full assembly (lines with torsion keep the full assembly). In the same
run this cuts `CalcOutput` to 9 s and the run to 194 s. Results do not change.

### Fixed

- The FAQ and the OpenFAST tutorial still gave 0.1 s as the default `dtM` in OpenFAST; since
0.2.0 it is the glue `DT`.

## [0.2.0] - 2026-10-20

### Added
Expand Down
8 changes: 8 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1095,6 +1095,14 @@ set_tests_properties(hermite_node_reaction PROPERTIES
LABELS "fortran;unit;dynamic;openfast;contact"
ENVIRONMENT "OPENBLAS_CORETYPE=Sandybridge")

# The dtM advisor on the coupled route: the mixed example's power cable (axial period 0.351 s)
# is noted at dtM = 0.1 s with a dtM that resolves it; nothing is noted at 0.05 s.
add_executable(test_dtm_advisor tests/test_dtm_advisor.f90)
target_link_libraries(test_dtm_advisor PRIVATE cabledyn_core)
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 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
18 changes: 10 additions & 8 deletions doc/faq.rst
Original file line number Diff line number Diff line change
Expand Up @@ -83,18 +83,20 @@ OpenFAST coupling
.. admonition:: Why do CableDyn channels look stepped in an OpenFAST plot?
:class: note

CableDyn solves on ``dtM`` (0.1 s by default) and holds its committed loads/channels between
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 solve. Set deck ``dtM = DT`` only when glue-rate
solves are required, and demonstrate damage/range convergence by reducing ``dtM``.
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
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
solve. A larger ``dtM`` is faster; demonstrate damage/range convergence by reducing it, and
heed the initialisation note on a line whose axial period it does not resolve
(:doc:`modeling`).

.. admonition:: Why did ``dtM = 0.025 s`` make my coupled run much slower?
:class: note

Equal ``dtM`` and OpenFAST ``DT`` intentionally request a nonlinear CableDyn solve on every glue
step, four times as many as the 0.1 s default. The release executables are serial; the
Equal ``dtM`` and OpenFAST ``DT`` (the default) request a nonlinear CableDyn solve on every glue
step, four times as many as ``dtM = 0.1 s`` at ``DT = 0.025 s``. The release executables are serial; the
threading advice in this answer applies only to source builds configured with OpenMP. On such
builds an ``EI = 0`` line evaluates its elements in parallel only from 8192 elements and a
finite-EI cable from 32 elements, while separate lines can still run concurrently; nested
Expand Down
15 changes: 15 additions & 0 deletions doc/modeling.rst
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,21 @@ bandwidth, the shortest element transit time, contact switching, and constitutiv
times. For prescribed motion, row 1 defines the actual :math:`t=0` position, velocity, and
acceleration and must be consistent with the intended initial state.

**dtM advisory.** At initialisation each line's axial period is estimated as that of a bar fixed
at both ends, :math:`T_\text{ax} = 2\sum_j l_j/\sqrt{EA_j/m_j}` over its sections (unstretched
lengths, dry mass per length, and the dynamic ``EA`` of a viscoelastic type with constant dynamic
stiffness). A line that ``dtM`` resolves in fewer than six steps gets an initialisation note
with the period, the number of steps and a ``dtM`` that resolves it, on the standalone, mixed and
OpenFAST routes. The threshold comes from the IEA-15 MW mixed example in a turbulent 600 s
OpenFAST run: its power cable (:math:`T_\text{ax} = 0.351` s) matches the ``dtM = DT``
fairlead tension within 0.3 % of its standard deviation at 7 steps (``dtM = 0.05 s``), while at
3.5 steps (0.1 s) its axial dynamics are damped and its peak tension is about 35 % high; the chains
(0.78 s) keep their tension statistics within 0.3 % at 7.8 steps. The estimate leaves out added
mass and the catenary compliance, and types whose stiffness depends on the load (``ElasticMod``
3, Syrope) are not assessed. The note is a lower bound, not a convergence study: segment-scale
snap waves need a far smaller step (above), and the platform side of a larger ``dtM`` is
discussed in :doc:`openfast`.

8. Request auditable outputs
-----------------------------

Expand Down
4 changes: 2 additions & 2 deletions doc/tutorial_openfast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -360,8 +360,8 @@ Exercises
1. **Wind.** Set ``CompInflow = 1`` and ``CompAero = 2`` in a copy of the ``.fst`` (the
``MD_Shared`` InflowWind and AeroDyn files are already present) and compare the mean surge and
line-1 tension with the parked case.
2. **Supercycling.** Remove the ``dtM`` row from ``CableDyn_UMaine.dat``. The console now
reports ``dtM = 0.1 s (4 x glue DT; the default)``, CableDyn solves once per four glue steps,
2. **Supercycling.** Set ``dtM`` to 0.1 in ``CableDyn_UMaine.dat``. The console now
reports ``dtM = 0.1 s (4 x glue DT; deck dtM)``, CableDyn solves once per four glue steps,
and ``.CD.out`` has one row per 0.1 s. Here the line-1 tension statistics over 10–70 s barely
move (mean 2.456 MN, std 0.116 MN, against 2.456 and 0.115 MN); verify that for your own
quantities before adopting a coarser step.
Expand Down
62 changes: 57 additions & 5 deletions src/CableDyn_DeckDriver.f90
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,8 @@ MODULE CableDyn_DeckDriver
! is not positive.
REAL(wp), PARAMETER :: COARSE_SECTION_FRACTION = 0.125_wp
REAL(wp), PARAMETER :: STATIC_STRAIN_NOTE_DEFAULT = 0.1_wp
! dtM advisor (axial_period_note): the fewest steps of dtM per axial period of a line
REAL(wp), PARAMETER :: AXIAL_STEPS_PER_PERIOD = 6.0_wp

PUBLIC :: CD_Run_Deck_Driver
PUBLIC :: CD_Deck_Equilibrium_Jacobian_Check
Expand Down Expand Up @@ -991,9 +993,9 @@ MODULE CableDyn_DeckDriver
LOGICAL :: force_is_total = .TRUE.
! Static-initialisation notes of the line, one per text line (append_note_line): those of a
! finite-EI line (compression, mesh refinement, accepted residual floor, a run past its
! anchor), the fold note of an EI = 0 line (ei0_fold_note) and the static strain note of any
! line; empty when there is nothing to report. It holds a whole cable note (1024) and a
! strain note.
! anchor), the fold note of an EI = 0 line (ei0_fold_note), and the static strain note and
! the dtM advisory (axial_period_note) of any line; empty when there is nothing to report.
! It holds a whole cable note (1024) and the two others.
CHARACTER(2048) :: note = ''
END TYPE CD_LineInitSummary

Expand Down Expand Up @@ -7086,8 +7088,9 @@ SUBROUTINE CD_Init_Deck_Aggregate(deck_path, dt, agg, ErrStat, ErrMsg, env_gravi
DO il = 1, SIZE(agg%init_lines)
CALL static_strain_note(agg%init_lines(il)%line_id, agg%init_lines(il)%fair_tension, sections, types, opts, &
strain_note)
IF (LEN_TRIM(strain_note) == 0) CYCLE
CALL append_note_line(agg%init_lines(il)%note, strain_note)
IF (LEN_TRIM(strain_note) > 0) CALL append_note_line(agg%init_lines(il)%note, strain_note)
CALL axial_period_note(agg%init_lines(il)%line_id, dt, sections, types, strain_note)
IF (LEN_TRIM(strain_note) > 0) CALL append_note_line(agg%init_lines(il)%note, strain_note)
END DO
IF (PRESENT(range_files)) THEN
IF (range_files) CALL warn_coarse_sections(lines, sections)
Expand Down Expand Up @@ -10113,6 +10116,51 @@ SUBROUTINE percent_text(percent, text)
END SUBROUTINE percent_text
END SUBROUTINE static_strain_note

SUBROUTINE axial_period_note(line_id, dt, sections, types, note)
!! The dtM advisor: a line whose axial period is resolved by fewer than
!! AXIAL_STEPS_PER_PERIOD steps of dt. The period is that of a bar fixed at both ends,
!! twice the axial-wave transit time sum(l / sqrt(EA / m)) over the line's sections, with
!! the unstretched lengths, the dry mass per length and, for a viscoelastic type of
!! constant dynamic stiffness, its dynamic EA (the stiffness a fast load sees). Added mass
!! is left out, so the estimate errs short. Coarser steps damp the line's axial dynamics
!! (the generalised-alpha rhoInf) and misstate its tension peaks: with the IEA-15 MW mixed
!! example the cable (0.35 s) is converged at 7 steps per period and about 35 % high in peak
!! tension at 3.5. Types whose stiffness depends on the load (ElasticMod 3, Syrope) are not
!! assessed. Only a note: nothing is changed.
INTEGER, INTENT(IN) :: line_id
REAL(wp), INTENT(IN) :: dt
TYPE(DeckSection), INTENT(IN) :: sections(:)
TYPE(DeckLineType), INTENT(IN) :: types(:)
CHARACTER(*), INTENT(OUT) :: note
INTEGER :: j, k
REAL(wp) :: transit, ea, period
CHARACTER(32) :: b1, b2, b3, b4

note = ''
IF (.NOT. (dt > CD_ZERO)) RETURN
transit = CD_ZERO
DO j = 1, SIZE(sections)
IF (sections(j)%line_id /= line_id) CYCLE
k = find_type(types, sections(j)%ltype_name)
IF (k < 1) RETURN
IF (types(k)%is_syrope .OR. types(k)%elastic_mod == 3) RETURN
ea = types(k)%ea
IF (types(k)%elastic_mod == 2) ea = MAX(ea, types(k)%ea_d)
IF (.NOT. (ea > CD_ZERO .AND. types(k)%mass > CD_ZERO .AND. sections(j)%length > CD_ZERO)) RETURN
transit = transit + sections(j)%length/SQRT(ea/types(k)%mass)
END DO
period = 2.0_wp*transit
IF (.NOT. (period > CD_ZERO) .OR. period >= AXIAL_STEPS_PER_PERIOD*dt) RETURN
WRITE (b1, '(F12.4)') dt
WRITE (b2, '(F12.3)') period
WRITE (b3, '(F12.1)') period/dt
WRITE (b4, '(F12.4)') period/AXIAL_STEPS_PER_PERIOD
note = 'LINE '//TRIM(int_to_str(line_id))//': dtM = '//TRIM(ADJUSTL(b1))//' s resolves its axial period of '// &
TRIM(ADJUSTL(b2))//' s (twice its length over sqrt(EA/m)) in '//TRIM(ADJUSTL(b3))//' steps, fewer than '// &
TRIM(int_to_str(NINT(AXIAL_STEPS_PER_PERIOD)))//': its axial dynamics are damped and its tension peaks '// &
'can be wrong. A dtM of at most '//TRIM(ADJUSTL(b4))//' s resolves them'
END SUBROUTINE axial_period_note

SUBROUTINE warn_line_below_anchor(lines, points, sections, q_all, q_off)
!! Standard-output WARNING for a deck with no seabed (no WtrDpth or bathymetryFile) on
!! which a line hangs below its lowest Fixed end by more than max(1 m, 1 % of its
Expand Down Expand Up @@ -32618,6 +32666,10 @@ SUBROUTINE print_deck_init_report(deck_path, lines, points, sections, n_finite,
IF (PRESENT(types) .AND. PRESENT(opts)) THEN
CALL static_strain_note(summaries(i)%line_id, summaries(i)%fair_tension, sections, types, opts, strain_note)
IF (LEN_TRIM(strain_note) > 0) WRITE (error_unit, '(A)') ' Note: '//TRIM(strain_note)//'.'
IF (opts%has_dtm .AND. opts%tmax > CD_ZERO) THEN
CALL axial_period_note(summaries(i)%line_id, opts%dtM, sections, types, strain_note)
IF (LEN_TRIM(strain_note) > 0) WRITE (error_unit, '(A)') ' Note: '//TRIM(strain_note)//'.'
END IF
END IF
END DO
WRITE (error_unit, '(A)') ' CableDyn initialization completed.'
Expand Down
3 changes: 2 additions & 1 deletion src/CableDyn_OpenFAST_Aggregate.f90
Original file line number Diff line number Diff line change
Expand Up @@ -2049,7 +2049,8 @@ SUBROUTINE CD_AGG_GetInitLine(self, i, line_id, tension, force, inclination, dec
note)
!! Return one line's unconditional converged-static fairlead result in deck order, and
!! (optional note) its static-initialisation notes, one per text line: those of a finite-EI
!! cable, or the fold note of an EI = 0 line ('' if none).
!! cable or the fold note of an EI = 0 line, the static strain note and the dtM advisory
!! ('' if none).
TYPE(CD_AGG_ModuleType), INTENT(IN) :: self
INTEGER, INTENT(IN) :: i
INTEGER, INTENT(OUT) :: line_id
Expand Down
14 changes: 13 additions & 1 deletion tests/check_driver_advisories.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
# * a prescribed motion that starts moving (a harmonic started at t = 0 is at its peak
# velocity) prints a start-up shock note; one that starts from rest does not;
# * a slack anchored line on a deck with no seabed (an OpenFAST MooringFile run
# standalone) prints a no-seabed warning; a deck with a water depth does not.
# standalone) prints a no-seabed warning; a deck with a water depth does not;
# * a dtM that resolves a line's axial period (2 x 410 m / sqrt(1.674e9 / 390) = 0.396 s) in
# fewer than 6 steps prints the dtM advisory: 4.0 steps at 0.1 s, none at 0.05 s (7.9).
foreach(_required DRIVER WORK NO_SEABED_DECK SEABED_DECK)
if(NOT DEFINED ${_required} OR "${${_required}}" STREQUAL "")
message(FATAL_ERROR "check_driver_advisories: missing ${_required}")
Expand Down Expand Up @@ -93,6 +95,16 @@ require_text("sine start" "${_sine_log}" "Note: motionFile point 2 starts moving
require_text("sine start" "${_sine_log}" "Start the motion from rest")
run_driver("start from rest" "${WORK}/rest.dat" "${WORK}/rest" _rest_log)
forbid_text("start from rest" "${_rest_log}" "starts moving at")
forbid_text("start from rest" "${_rest_log}" "axial period")

string(REPLACE "0.05 dtM" "0.1 dtM" _coarse_head "${_deck_head}")
# the motion record on the coarser dtM grid
file(WRITE "${WORK}/coarse.txt" "0.0 2 0.0 0.0 0.000 0.0 0.0 0.0 0.0 0.0 0.0\n0.1 2 0.0 0.0 0.000 0.0 0.0 0.0 0.0 0.0 0.0\n0.2 2 0.0 0.0 0.000 0.0 0.0 0.0 0.0 0.0 0.0\n")
file(WRITE "${WORK}/coarse.dat" "${_coarse_head}coarse.txt motionFile\n${_deck_tail}")
run_driver("coarse dtM" "${WORK}/coarse.dat" "${WORK}/coarse" _coarse_log)
require_text("coarse dtM" "${_coarse_log}"
"Note: LINE 1: dtM = 0.1000 s resolves its axial period of 0.396 s (twice its length over sqrt(EA/m)) in 4.0 steps, fewer than 6")
require_text("coarse dtM" "${_coarse_log}" "A dtM of at most 0.0660 s resolves them.")

run_driver("no seabed" "${NO_SEABED_DECK}" "${WORK}/no_seabed" _no_seabed_log)
require_text("no seabed" "${_no_seabed_log}" "below its Fixed anchor and the deck has no seabed")
Expand Down
75 changes: 75 additions & 0 deletions tests/test_dtm_advisor.f90
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
! File: tests/test_dtm_advisor.f90
! SPDX-License-Identifier: Apache-2.0
! Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University
PROGRAM test_dtm_advisor
!! The dtM advisor on the coupled (aggregate) route: the IEA-15 MW mixed mooring example built
!! with the mooring step of an OpenFAST run. Its power cable (80 m bare, 100 m buoyant, 420 m
!! bare) has an axial period of 0.351 s, which dtM = 0.1 s resolves in 3.5 steps: its
!! initialisation note names the period and a dtM that resolves it, while the chains (0.778 s,
!! 7.8 steps) are not noted. At dtM = 0.05 s (7.0 steps) no line is noted.
USE CableDyn_Precision, ONLY: wp
USE CableDyn_OpenFAST_Aggregate, ONLY: CD_AGG_ModuleType, CD_AGG_Init_From_Deck, CD_AGG_GetInitLine, &
CD_AGG_End, CD_AGG_OK
IMPLICIT NONE

CHARACTER(1024) :: deck
INTEGER :: nfail

nfail = 0
IF (COMMAND_ARGUMENT_COUNT() < 1) THEN
WRITE (*, '(A)') 'FAIL: the mixed example deck path argument is required'
ERROR STOP 1
END IF
CALL GET_COMMAND_ARGUMENT(1, deck)
CALL check_step(0.1_wp, .TRUE.)
CALL check_step(0.05_wp, .FALSE.)
IF (nfail > 0) THEN
WRITE (*, '(A,I0,A)') 'FAIL: ', nfail, ' assertion(s) failed'
ERROR STOP 1
END IF
WRITE (*, '(A)') 'PASS: the dtM advisor notes the cable at dtM = 0.1 s and nothing at 0.05 s'

CONTAINS

SUBROUTINE require(cond, msg)
LOGICAL, INTENT(IN) :: cond
CHARACTER(*), INTENT(IN) :: msg
IF (.NOT. cond) THEN
WRITE (*, '(A)') 'FAIL: '//TRIM(msg)
nfail = nfail + 1
END IF
END SUBROUTINE require

SUBROUTINE check_step(dt, cable_noted)
REAL(wp), INTENT(IN) :: dt
LOGICAL, INTENT(IN) :: cable_noted
TYPE(CD_AGG_ModuleType) :: agg
CHARACTER(2048) :: note
CHARACTER(512) :: em
CHARACTER(16) :: tag
REAL(wp) :: tension, force(3), incl, decl, azi
INTEGER :: es, i, line_id
LOGICAL :: noted

WRITE (tag, '(F5.3)') dt
CALL CD_AGG_Init_From_Deck(agg, TRIM(deck), dt, es, em)
CALL require(es == CD_AGG_OK, 'dtM '//TRIM(tag)//': init: '//TRIM(em))
IF (es /= CD_AGG_OK) RETURN
DO i = 1, 4
CALL CD_AGG_GetInitLine(agg, i, line_id, tension, force, incl, decl, azi, es, em, note=note)
CALL require(es == CD_AGG_OK, 'dtM '//TRIM(tag)//': line summary: '//TRIM(em))
noted = INDEX(note, 'axial period') > 0
IF (line_id == 4 .AND. cable_noted) THEN
CALL require(noted, 'dtM '//TRIM(tag)//': the cable is noted')
CALL require(INDEX(note, 'LINE 4: dtM = 0.1000 s resolves its axial period of 0.351 s') > 0 .AND. &
INDEX(note, 'in 3.5 steps, fewer than 6') > 0 .AND. &
INDEX(note, 'A dtM of at most 0.0585 s resolves them') > 0, &
'dtM '//TRIM(tag)//': the cable note gives the period, the steps and the remedy: '//TRIM(note))
ELSE
CALL require(.NOT. noted, 'dtM '//TRIM(tag)//': line '//CHAR(48 + line_id)//' is not noted: '//TRIM(note))
END IF
END DO
CALL CD_AGG_End(agg, es, em)
END SUBROUTINE check_step

END PROGRAM test_dtm_advisor
Loading