From 9a488f41a6f552169ecce9b9f4e0fad04d146379 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Wed, 21 Oct 2026 20:02:17 +0900 Subject: [PATCH 1/2] fix(openfast): restore the held SeaState fields on a supercycled restart A committed mooring step holds the SeaState fields sampled at its interval end at the node positions of its start. On openfast -restart the module re-sampled them at the restored, end-of-step positions. At dtM = DT this was harmless, because the next solve re-samples before any load is served; with dtM larger than DT the loads served until the next solve came from the re-sampled fields, and the restarted run drifted from the uninterrupted one (up to 2e-3 of a tension's standard deviation in the CableDyn record, on held and extrapolated loads alike). A full-precision trace placed the first difference at the first load served after the restart, with identical host inputs. The OtherState carries the held fields (fluid_held: velocity, acceleration, free-surface elevation and dynamic pressure at the line nodes), saved at Init and at every committed step, and the restart hands them back to the aggregate instead of re-sampling. A checkpoint without them re-samples as before. openfast -restart at 50 s now reproduces every later OpenFAST and .CD.out row of the IEA-15 VolturnUS-S chain mooring at dtM = 0.1 s (extrapolated and held loads) and at dtM = DT, and of the chain and power-cable mooring at dtM = 0.05 s. Uninterrupted runs do not change. Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 6 +++ VALIDATION.md | 2 +- doc/openfast.rst | 4 +- src/openfast/CableDyn_OF.f90 | 68 +++++++++++++++++++++++++++--- src/openfast/CableDyn_Registry.txt | 1 + src/openfast/CableDyn_Types.f90 | 18 ++++++++ 6 files changed, 91 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 83346b62..5edbc66d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -44,6 +44,12 @@ All notable changes to CableDyn are recorded in this file. The format follows ### Fixed +- OpenFAST with `dtM` larger than `DT`: an `openfast -restart` re-sampled the SeaState fields of the + committed step at its end positions instead of restoring the fields the step held (sampled at + its start positions), so the loads served until the next solve, and the run after them, + differed slightly from the uninterrupted run (up to 2e-3 of a tension's standard deviation). + The checkpoint now carries the held fields, and a restart continues the run bit for bit at any + `dtM`; checkpoints written before this change re-sample as before. - 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`. diff --git a/VALIDATION.md b/VALIDATION.md index bd2f11fd..e572b2fd 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -746,7 +746,7 @@ stop with a named error. | Nonzero `PtfmInit` | Pass verified | 6-DOF displaced free decay ≤0.51% | | Correction iterations (`NumCrctn > 0`) | Pass verified | bit-identical to own `NumCrctn = 0` run | | SeaState wave/current kinematics | Pass verified | wave A/B ≤0.16% of range | -| Checkpoint-restart (incl. Free/Connect points) | Pass verified | restarted window = continuous run to 0.0 | +| Checkpoint-restart (incl. Free/Connect points) | Pass verified | restarted window = continuous run to 0.0; also with supercycling (`dtM` > `DT`, the held SeaState fields and the predictor loads checkpointed): IEA-15 VolturnUS-S, turbulent wind and JONSWAP sea, `openfast -restart` at 50 s reproduces every later OpenFAST and `.CD.out` row of the chain mooring at `dtM` = 4 `DT` (extrapolated and held loads) and `DT`, and of the chain + 248-element power-cable mooring at `dtM` = 2 `DT` | | Linearisation | Pass verified (quasi-static stiffness) | quasi-static `dYdu` compared entry by entry with stock MoorDyn's zero-frequency reduction `D − C A⁻¹ B` (full-precision `.lin` output): fairlead stiffness 0.07–0.10%, transverse `H/X` term 0.29%, platform 6×6 diagonals ≤0.10%; standalone static FD 1.5e-5; transverse term equals `H/X`. Velocity/acceleration columns are zero by design ([`openfast_lin_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_lin_ab.py)) | | FAST.Farm shared moorings + clumps + channel record | Pass verified | 600 s A/B of the r-test `MD_Shared` farm against stock MoorDyn (same deck, analysis from 100 s; [`fastfarm_shared_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/fastfarm_shared_ab.py)): tension means ≤0.02%, minima and maxima ≤0.25%, platform motions within millimetres and 0.001°; shared-line tension std 2.2–2.7% lower, 1.0% at half the mooring step (CableDyn's implicit step at the 0.05 s coupling step against MoorDyn's 1e-4 s explicit step). On the shared lines, which have no Fixed end, `FairTen`/`AnchTen` name the opposite ends from MoorDyn's (see the migration guide). MoorDyn's initial settling does not converge for the anchor legs 6 and 7 (2.4 m excess length at t = 0), a start-up transient over by 100 s that most likely set the 3% end of the earlier 60 s record | | Slack-line tension convention | Pass verified | tension-only dynamics; BA on slack lines matches `MoorDyn_Line.f90` | diff --git a/doc/openfast.rst b/doc/openfast.rst index 1ebeed5d..93828d61 100644 --- a/doc/openfast.rst +++ b/doc/openfast.rst @@ -343,7 +343,9 @@ The same module takes part in OpenFAST's checkpoint, linearisation, farm and con without an auxiliary process: * **Checkpoint/restart** serialises the committed line, constitutive, connection, body, and rod - state needed to continue the trajectory. A checkpoint is accepted only on a committed CableDyn + state needed to continue the trajectory, with the SeaState fields the committed step holds and, + with ``dtM`` larger than ``DT``, the loads of the solve before it (the load predictor), so a + restart continues the run bit for bit at any ``dtM``. A checkpoint is accepted only on a committed CableDyn step, so choose ``ChkptTime`` as a whole multiple of ``dtM``; a checkpoint written between two commits stops the restart with a message that says so. On restart the module writes a temporary deck copy, ``.CD.rst.dat``, beside the ``MooringFile``, rebuilds the model diff --git a/src/openfast/CableDyn_OF.f90 b/src/openfast/CableDyn_OF.f90 index 0a29426c..5526e5ed 100644 --- a/src/openfast/CableDyn_OF.f90 +++ b/src/openfast/CableDyn_OF.f90 @@ -848,6 +848,7 @@ SUBROUTINE CD_Init(InitInp, u, p, x, xd, z, other, y, m, DTcoupling, InitOut, Er ! state. Seeding after the static solve matches the stock-MoorDyn convention: ! the IC is the still-water equilibrium, wave kinematics act from t = 0. CALL sample_wavefield( Inst(id), p, m, 0.0_DbKi, ErrStat2, ErrMsg2, at_init=.TRUE. ) + IF (ErrStat2 < AbortErrLev) CALL save_held_fluid( Inst(id), other ) CALL SetErrStat( ErrStat2, ErrMsg2, ErrStat, ErrMsg, RoutineName ) IF (ErrStat >= AbortErrLev) RETURN END IF @@ -1315,6 +1316,7 @@ SUBROUTINE rebuild_from_checkpoint( t, u1, p, x, other, m, ErrStat, ErrMsg ) CHARACTER(2100) :: rst_deck INTEGER(IntKi) :: id, old_id, stale_id, i, es, ncp, nlines, il, ndofl, nin, k, ic, csz, koff LOGICAL :: use_extf, profile_requested, preserve_profile + LOGICAL :: restored ! held fluid fields restored from the checkpoint CHARACTER(ErrMsgLen) :: em INTEGER(IntKi) :: ErrStat2 CHARACTER(ErrMsgLen) :: ErrMsg2 @@ -1493,14 +1495,18 @@ SUBROUTINE rebuild_from_checkpoint( t, u1, p, x, other, m, ErrStat, ErrMsg ) CALL SetErrStat( ErrStat2, ErrMsg2, ErrStat, ErrMsg, RoutineName ) IF (ErrStat >= AbortErrLev) RETURN - ! restore the ambient-fluid fields the reference's committed state carried: the - ! last pre-checkpoint solve sampled the WaveField at ITS interval end (= the - ! restart time), so sampling here reproduces those fields on the restored - ! positions. Without this the first post-restart load evaluations would see still - ! water and ring for a few steps. + ! restore the ambient-fluid fields the reference's committed state carried. The last + ! pre-checkpoint solve sampled the WaveField at ITS interval end (= the restart time) at + ! the node positions of its START, and held them: the checkpoint carries them, and with + ! supercycling they act on the loads served until the next solve. A checkpoint without + ! them (written before they were saved) re-samples at the restored, end-of-step + ! positions, which matches only at dtM = DT, where the next solve re-samples before any + ! load is served. Without either the first post-restart load evaluations would see + ! still water and ring for a few steps. Inst(id)%active = .TRUE. ! sample_wavefield reads through the live instance IF (use_extf) THEN - CALL sample_wavefield( Inst(id), p, m, t, ErrStat2, ErrMsg2 ) + CALL restore_held_fluid( Inst(id), other, restored, ErrStat2, ErrMsg2 ) + IF (ErrStat2 < AbortErrLev .AND. .NOT. restored) CALL sample_wavefield( Inst(id), p, m, t, ErrStat2, ErrMsg2 ) CALL SetErrStat( ErrStat2, ErrMsg2, ErrStat, ErrMsg, RoutineName ) IF (ErrStat >= AbortErrLev) THEN CALL release_instance( id ) @@ -1700,6 +1706,7 @@ SUBROUTINE CD_UpdateStates( t, n, u, t_array, p, x, xd, z, other, m, ErrStat, Er IF (Inst(id)%use_extfluid) THEN IF (Inst(id)%prof_enabled) CALL SYSTEM_CLOCK(prof_phase0) CALL sample_wavefield( Inst(id), p, m, t + p%dtCoupling, ErrStat2, ErrMsg2 ) + IF (ErrStat2 < AbortErrLev) CALL save_held_fluid( Inst(id), other ) IF (Inst(id)%prof_enabled) THEN CALL SYSTEM_CLOCK(prof_c1) Inst(id)%prof_n_wave = Inst(id)%prof_n_wave + 1_IntKi @@ -2476,6 +2483,55 @@ SUBROUTINE CD_CalcOutput( t, u, p, x, xd, z, other, y, m, ErrStat, ErrMsg ) END SUBROUTINE CD_CalcOutput !---------------------------------------------------------------------------------------------------------------------------------- + SUBROUTINE save_held_fluid( inst_e, other ) + !! Mirror the held ambient-fluid fields of the committed step (fx_vel, fx_acc, fx_wl, + !! fx_pd, as last handed to the aggregate by sample_wavefield) into the OtherState, so a + !! restart serves its loads from the same fields (restore_held_fluid). + TYPE(CD_OF_Instance), INTENT(IN ) :: inst_e + TYPE(CD_OtherStateType), INTENT(INOUT) :: other + INTEGER(IntKi) :: nf + nf = inst_e%nfluid + IF (ALLOCATED(other%fluid_held)) THEN + IF (SIZE(other%fluid_held) /= 8*nf) DEALLOCATE (other%fluid_held) + END IF + IF (.NOT. ALLOCATED(other%fluid_held)) ALLOCATE (other%fluid_held(8*nf)) + other%fluid_held(1:3*nf) = RESHAPE(REAL(inst_e%fx_vel, DbKi), [3*nf]) + other%fluid_held(3*nf + 1:6*nf) = RESHAPE(REAL(inst_e%fx_acc, DbKi), [3*nf]) + other%fluid_held(6*nf + 1:7*nf) = REAL(inst_e%fx_wl, DbKi) + other%fluid_held(7*nf + 1:8*nf) = REAL(inst_e%fx_pd, DbKi) + END SUBROUTINE save_held_fluid + + SUBROUTINE restore_held_fluid( inst_e, other, restored, ErrStat, ErrMsg ) + !! Hand the held ambient-fluid fields of a checkpoint (save_held_fluid) back to the + !! aggregate; restored is .FALSE. when the checkpoint does not carry them for this + !! instance's fluid nodes. + TYPE(CD_OF_Instance), INTENT(INOUT) :: inst_e + TYPE(CD_OtherStateType), INTENT(IN ) :: other + LOGICAL, INTENT( OUT) :: restored + INTEGER(IntKi), INTENT( OUT) :: ErrStat + CHARACTER(*), INTENT( OUT) :: ErrMsg + INTEGER(IntKi) :: nf, es + CHARACTER(ErrMsgLen) :: em + ErrStat = ErrID_None + ErrMsg = '' + restored = .FALSE. + nf = inst_e%nfluid + IF (.NOT. ALLOCATED(other%fluid_held)) RETURN + IF (SIZE(other%fluid_held) /= 8*nf) RETURN + inst_e%fx_vel = RESHAPE(REAL(other%fluid_held(1:3*nf), wp), [3, nf]) + inst_e%fx_acc = RESHAPE(REAL(other%fluid_held(3*nf + 1:6*nf), wp), [3, nf]) + inst_e%fx_wl = REAL(other%fluid_held(6*nf + 1:7*nf), wp) + inst_e%fx_pd = REAL(other%fluid_held(7*nf + 1:8*nf), wp) + CALL CD_AGG_SetFluidFields( inst_e%agg, inst_e%fx_vel, inst_e%fx_acc, inst_e%fx_wl, es, em, & + dynamic_pressure=inst_e%fx_pd ) + IF (es /= CD_AGG_OK) THEN + ErrStat = ErrID_Fatal + ErrMsg = 'CableDyn mooring module: restoring the held fluid fields: '//TRIM(em) + RETURN + END IF + restored = .TRUE. + END SUBROUTINE restore_held_fluid + SUBROUTINE shift_predictor_loads( inst_e, other ) !! The load predictor's previous commit when a new mooring step starts: the loads served !! since the last commit, when CalcOutput evaluated them there (its committed loads), and diff --git a/src/openfast/CableDyn_Registry.txt b/src/openfast/CableDyn_Registry.txt index 78e960e0..a4c32cf2 100644 --- a/src/openfast/CableDyn_Registry.txt +++ b/src/openfast/CableDyn_Registry.txt @@ -361,6 +361,7 @@ typedef ^ OtherStateType IntKi restart_serial - typedef ^ ^ DbKi t_commit - -1 - "time of the last committed mooring advance; a live instance whose committed clock is AHEAD of a restored OtherState's (a same-process checkpoint rewind) also triggers the rebuild" - typedef ^ ^ DbKi pred_t - -1 - "load predictor: time of the committed solve before the last (negative: none), from which the coupled loads between supercycled solves are extrapolated" - typedef ^ ^ DbKi pred_loads {:} - - "load predictor: the coupled forces (3 x ncp) and then moments (3 x ncp) of that solve" - +typedef ^ ^ DbKi fluid_held {:} - - "the held ambient-fluid fields of the last committed mooring step (velocity, acceleration, free-surface elevation, dynamic pressure at the line nodes), restored at a restart instead of re-sampled" - ## ============================== Parameters ============================================================================================================================================ typedef ^ ParameterType IntKi nLineTypes - 0 - "number of line types" "" diff --git a/src/openfast/CableDyn_Types.f90 b/src/openfast/CableDyn_Types.f90 index c88607f7..e654f304 100644 --- a/src/openfast/CableDyn_Types.f90 +++ b/src/openfast/CableDyn_Types.f90 @@ -395,6 +395,7 @@ MODULE CableDyn_Types REAL(DbKi) :: t_commit = -1 !< time of the last committed mooring advance; a live instance whose committed clock is AHEAD of a restored OtherState's (a same-process checkpoint rewind) also triggers the rebuild [-] REAL(DbKi) :: pred_t = -1 !< load predictor: time of the committed solve before the last (negative: none), from which the coupled loads between supercycled solves are extrapolated [-] REAL(DbKi) , DIMENSION(:), ALLOCATABLE :: pred_loads !< load predictor: the coupled forces (3 x ncp) and then moments (3 x ncp) of that solve [-] + REAL(DbKi) , DIMENSION(:), ALLOCATABLE :: fluid_held !< the held ambient-fluid fields of the last committed mooring step (velocity, acceleration, free-surface elevation, dynamic pressure at the line nodes), restored at a restart instead of re-sampled [-] END TYPE CD_OtherStateType ! ======================= ! ========= CD_ParameterType ======= @@ -2991,6 +2992,18 @@ subroutine CD_CopyOtherState(SrcOtherStateData, DstOtherStateData, CtrlCode, Err end if DstOtherStateData%pred_loads = SrcOtherStateData%pred_loads end if + if (allocated(SrcOtherStateData%fluid_held)) then + LB(1:1) = lbound(SrcOtherStateData%fluid_held) + UB(1:1) = ubound(SrcOtherStateData%fluid_held) + if (.not. allocated(DstOtherStateData%fluid_held)) then + allocate(DstOtherStateData%fluid_held(LB(1):UB(1)), stat=ErrStat2) + if (ErrStat2 /= 0) then + call SetErrStat(ErrID_Fatal, 'Error allocating DstOtherStateData%fluid_held.', ErrStat, ErrMsg, RoutineName) + return + end if + end if + DstOtherStateData%fluid_held = SrcOtherStateData%fluid_held + end if end subroutine subroutine CD_DestroyOtherState(OtherStateData, ErrStat, ErrMsg) @@ -3003,6 +3016,9 @@ subroutine CD_DestroyOtherState(OtherStateData, ErrStat, ErrMsg) if (allocated(OtherStateData%pred_loads)) then deallocate(OtherStateData%pred_loads) end if + if (allocated(OtherStateData%fluid_held)) then + deallocate(OtherStateData%fluid_held) + end if end subroutine subroutine CD_PackOtherState(RF, Indata) @@ -3014,6 +3030,7 @@ subroutine CD_PackOtherState(RF, Indata) call RegPack(RF, InData%t_commit) call RegPack(RF, InData%pred_t) call RegPackAlloc(RF, InData%pred_loads) + call RegPackAlloc(RF, InData%fluid_held) if (RegCheckErr(RF, RoutineName)) return end subroutine @@ -3029,6 +3046,7 @@ subroutine CD_UnPackOtherState(RF, OutData) call RegUnpack(RF, OutData%t_commit); if (RegCheckErr(RF, RoutineName)) return call RegUnpack(RF, OutData%pred_t); if (RegCheckErr(RF, RoutineName)) return call RegUnpackAlloc(RF, OutData%pred_loads); if (RegCheckErr(RF, RoutineName)) return + call RegUnpackAlloc(RF, OutData%fluid_held); if (RegCheckErr(RF, RoutineName)) return end subroutine subroutine CD_CopyParam(SrcParamData, DstParamData, CtrlCode, ErrStat, ErrMsg) From ed4c3a4516800d414d422b33cedfb783241b751d Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Wed, 21 Oct 2026 20:13:33 +0900 Subject: [PATCH 2/2] docs(changelog): state that older checkpoints cannot be restarted Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 4 +++- src/openfast/CableDyn_OF.f90 | 12 +++++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5edbc66d..d3575692 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,7 +49,9 @@ All notable changes to CableDyn are recorded in this file. The format follows its start positions), so the loads served until the next solve, and the run after them, differed slightly from the uninterrupted run (up to 2e-3 of a tension's standard deviation). The checkpoint now carries the held fields, and a restart continues the run bit for bit at any - `dtM`; checkpoints written before this change re-sample as before. + `dtM`. The checkpoint layout changes with this and with the load predictor's fields: a + checkpoint written by an earlier CableDyn cannot be restarted with this one (OpenFAST + checkpoints are not versioned; restart with the executable that wrote them). - 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`. diff --git a/src/openfast/CableDyn_OF.f90 b/src/openfast/CableDyn_OF.f90 index 5526e5ed..439402fa 100644 --- a/src/openfast/CableDyn_OF.f90 +++ b/src/openfast/CableDyn_OF.f90 @@ -1498,11 +1498,13 @@ SUBROUTINE rebuild_from_checkpoint( t, u1, p, x, other, m, ErrStat, ErrMsg ) ! restore the ambient-fluid fields the reference's committed state carried. The last ! pre-checkpoint solve sampled the WaveField at ITS interval end (= the restart time) at ! the node positions of its START, and held them: the checkpoint carries them, and with - ! supercycling they act on the loads served until the next solve. A checkpoint without - ! them (written before they were saved) re-samples at the restored, end-of-step - ! positions, which matches only at dtM = DT, where the next solve re-samples before any - ! load is served. Without either the first post-restart load evaluations would see - ! still water and ring for a few steps. + ! supercycling they act on the loads served until the next solve. Init saves the first + ! fields, so a checkpoint of an instance that takes host fluid always carries them; + ! re-sampling at the restored, end-of-step positions remains only as a defensive + ! fallback (it matches only at dtM = DT, where the next solve re-samples before any load + ! is served). Without either the first post-restart load evaluations would see still + ! water and ring for a few steps. (OpenFAST checkpoints are not versioned: one written by + ! an earlier CableDyn, without these fields, cannot be restarted with this one.) Inst(id)%active = .TRUE. ! sample_wavefield reads through the live instance IF (use_extf) THEN CALL restore_held_fluid( Inst(id), other, restored, ErrStat2, ErrMsg2 )