diff --git a/CHANGELOG.md b/CHANGELOG.md index cb6f2dfa..7a8f1286 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 @@ -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 diff --git a/CMakeLists.txt b/CMakeLists.txt index 88408f78..e52727c8 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -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) diff --git a/doc/faq.rst b/doc/faq.rst index e8f035f8..8a5af7e3 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -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 ``.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 + ``.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 diff --git a/doc/modeling.rst b/doc/modeling.rst index 38231b0b..267b99dd 100644 --- a/doc/modeling.rst +++ b/doc/modeling.rst @@ -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 ----------------------------- diff --git a/doc/tutorial_openfast.rst b/doc/tutorial_openfast.rst index 7614aac0..8a8d8324 100644 --- a/doc/tutorial_openfast.rst +++ b/doc/tutorial_openfast.rst @@ -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. diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index 926b7a53..d4efa545 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -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 @@ -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 @@ -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) @@ -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 @@ -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.' diff --git a/src/CableDyn_OpenFAST_Aggregate.f90 b/src/CableDyn_OpenFAST_Aggregate.f90 index 783ee0c6..7b4e7dc2 100644 --- a/src/CableDyn_OpenFAST_Aggregate.f90 +++ b/src/CableDyn_OpenFAST_Aggregate.f90 @@ -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 diff --git a/tests/check_driver_advisories.cmake b/tests/check_driver_advisories.cmake index aab9b326..d34e8a4c 100644 --- a/tests/check_driver_advisories.cmake +++ b/tests/check_driver_advisories.cmake @@ -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}") @@ -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") diff --git a/tests/test_dtm_advisor.f90 b/tests/test_dtm_advisor.f90 new file mode 100644 index 00000000..1931d73f --- /dev/null +++ b/tests/test_dtm_advisor.f90 @@ -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