diff --git a/doc/capi.rst b/doc/capi.rst index b28eabd3..ab4c8943 100644 --- a/doc/capi.rst +++ b/doc/capi.rst @@ -1452,7 +1452,8 @@ is stored. A non-finite field returns ``CD_C_BAD_INPUT``. - ``double`` - -- - -- - - step size [s], finite and greater than 0 + - step size [s], finite and at least ``1e-100`` (the time integration divides by + ``dt**2``; a smaller step is ``CD_C_BAD_INPUT``) * - ``q_coupled``, ``v_coupled``, ``a_coupled`` - in - ``const double *`` diff --git a/doc/options.rst b/doc/options.rst index 42fe703b..e259ba35 100644 --- a/doc/options.rst +++ b/doc/options.rst @@ -261,7 +261,8 @@ Clock and initial condition * - ``dtM`` / ``dt`` - real, s - absent (static-only) - - finite, > 0. In the standalone driver ``dtM`` and ``TMax`` are given together or not at + - finite, at least ``1e-100`` (the time integration divides by ``dtM**2``). In the + standalone driver ``dtM`` and ``TMax`` are given together or not at all; only ``TMax = 0``, which marches no step, needs no ``dtM`` - standalone step; OpenFAST targets ``0.1`` s when absent, rounds it to at least one whole glue ``DT``, and reports the value used diff --git a/doc/python.rst b/doc/python.rst index 378db20e..8517c5fa 100644 --- a/doc/python.rst +++ b/doc/python.rst @@ -787,8 +787,8 @@ active ANSI code page; a path that code page cannot represent is rejected with ` :class:`cabledyn.CableDynError` and leaves the model at the start of the step. A step that ends without meeting the Newton tolerance raises :class:`cabledyn.ConvergenceError`, which carries ``n_iter`` and ``stalled``; the model has then already advanced to ``t + dt`` with its best -iterate, so retrying the same step would advance time twice. ``dt`` must be a finite positive -real number, and array arguments must be real-valued: a string, complex, or boolean ``dt`` and a +iterate, so retrying the same step would advance time twice. ``dt`` must be a finite real number +of at least ``1e-100``, and array arguments must be real-valued: a string, complex, or boolean ``dt`` and a complex or non-numeric array raise ``TypeError`` before the library is called. Calls on one ``CableDyn`` instance are serialised by an internal lock; separate instances may run on separate threads. Deck initialisation is serialised inside the library, so instances created from many diff --git a/python/cabledyn/deck_file.py b/python/cabledyn/deck_file.py index a70839c3..a6ad7d83 100644 --- a/python/cabledyn/deck_file.py +++ b/python/cabledyn/deck_file.py @@ -327,6 +327,8 @@ _NATIVE_MAX_GRAVITY = 1.0e3 _NATIVE_MAX_WATER_DENSITY = 1.0e5 _NATIVE_MAX_FLUID_SPEED = 1.0e3 +# native CD_MIN_TIME_STEP: the smallest dtM (the time integration divides by dtM^2) +_NATIVE_MIN_TIME_STEP = 1.0e-100 _NATIVE_MAX_WAVE_HEIGHT = 1.0e3 _NATIVE_WAVE_PERIOD_RANGE = (0.1, 1.0e5) _DISABLED_MOTION_FILE_VALUES = frozenset({"0", "none"}) @@ -1261,6 +1263,9 @@ def _scalar_option_value_error(keyword: str, value: str) -> str | None: return "must be finite" if positive and numeric <= 0.0: return "must be positive" + # native check_option_row_value rule 'time step' + if key == "dtm" and numeric < _NATIVE_MIN_TIME_STEP: + return "must be at least 1e-100 s: the time integration divides by its square" if lower is not None and numeric < lower: return f"must be >= {lower:g}" if upper is not None and numeric > upper: diff --git a/python/cabledyn/model.py b/python/cabledyn/model.py index ac0b6a49..138019cd 100644 --- a/python/cabledyn/model.py +++ b/python/cabledyn/model.py @@ -810,7 +810,8 @@ def step(self, dt: float, q: ArrayInput, v: ArrayInput, a: ArrayInput) -> int: without meeting the Newton tolerance raises :class:`ConvergenceError`; the model has then already advanced to ``t + dt`` with its best iterate. ``dt`` must be a finite positive real number (a string, complex, or - boolean value raises :class:`TypeError`). + boolean value raises :class:`TypeError`); the library refuses one below + ``1e-100`` s, as the time integration divides by ``dt**2``. """ step_dt = _as_real_scalar(dt, "dt", positive=True) with self._lock: diff --git a/python/tests/test_cabledyn.py b/python/tests/test_cabledyn.py index d0f079da..08990829 100644 --- a/python/tests/test_cabledyn.py +++ b/python/tests/test_cabledyn.py @@ -220,3 +220,34 @@ def test_error_types_import_without_loading_the_library(): assert issubclass(ConvergenceError, CableDynError) error = ConvergenceError("CableDyn_Step", "tolerance not met", n_iter=40, stalled=True) assert error.status == 4 and error.n_iter == 40 and error.stalled + + +@pytest.mark.parametrize("dt", [1e-101, 1e-160, 1e-300, 5e-324]) +def test_a_step_below_the_smallest_time_step_is_named(dt): + # the implicit march divides by dt^2: below 1e-100 s the step is refused by name, not left + # to overflow inside the line solve + with cabledyn.CableDyn(VOLTURNUS_DECK) as m: + q, v, a = m.get_coupled_motion() + before = m.calc_output() + with pytest.raises( + cabledyn.CableDynError, match=r"below the smallest time step, 1e-100 s" + ) as err: + m.step(dt, q, v, a) + assert "BAD_INPUT" in str(err.value) + assert np.array_equal(m.calc_output(), before) + m.step(1e-100, q, v, a) # the bound itself steps + assert np.all(np.isfinite(m.calc_output())) + with cabledyn.CableDyn() as m: + m.init_line( + [0, 0, 0, 1, 0, 0, 2, 0, 0], + np.zeros(9), + [1, 2, 2, 3], + [1.0, 1.0], + [1e6, 1e6], + [1.0, 1.0], + [1, 2, 3, 7, 8, 9], + False, + 0.5, + ) + with pytest.raises(cabledyn.CableDynError, match=r"below the smallest time step, 1e-100 s"): + m.step(dt, [0, 0, 0, 2, 0, 0], np.zeros(6), np.zeros(6)) diff --git a/python/tests/test_deck_file.py b/python/tests/test_deck_file.py index bd6e1196..09682893 100644 --- a/python/tests/test_deck_file.py +++ b/python/tests/test_deck_file.py @@ -4108,7 +4108,8 @@ def test_subnormal_dtm_is_rejected_before_the_step_count(): DeckFile.from_text(text) -@pytest.mark.parametrize("dtm", ["1e-300", "1e-12"]) +# (a dtM below 1e-100 s is refused before the step count: test_deck_native_parity) +@pytest.mark.parametrize("dtm", ["1e-90", "1e-12"]) def test_step_count_beyond_the_native_counter_is_a_format_error(dtm): text = _minimal_chain_source().replace( "100.0 WtrDpth", f"100.0 WtrDpth\n{dtm} dtM\n30.0 TMax", 1 diff --git a/python/tests/test_deck_native_parity.py b/python/tests/test_deck_native_parity.py index 71e3d15c..628fbbe0 100644 --- a/python/tests/test_deck_native_parity.py +++ b/python/tests/test_deck_native_parity.py @@ -2822,3 +2822,58 @@ def test_stiffener_diameter_bound_matches_the_driver(od, accepted, tmp_path): else: assert completed.returncode == 1, completed.stderr[-600:] assert "RootOD and TipOD must be at most 1e3 m" in completed.stderr + + +# ------------------------------------------------------------------ the smallest time step + +# the implicit marches divide by dt^2, which overflows the inertia terms near 1e-155 s +_TINY_STEPS = [ + ("1e-100", True), + ("1e-60", True), + ("1e-101", False), + ("1e-160", False), + ("1e-300", False), +] + + +@pytest.mark.parametrize(("dt", "accepted"), _TINY_STEPS) +def test_dtm_has_a_smallest_value(dt, accepted): + text = _edit(_HELD, ("0.1 dtM\n10.0 TMax\n", f"{dt} dtM\n{2 * float(dt)!r} TMax\n")) + if accepted: + DeckFile.from_text(text) + else: + _rejects(text, r"dtM must be at least 1e-100 s") + # every row is checked, also one a later row overrides + _rejects( + _edit(_HELD, ("0.1 dtM\n", f"{dt} dtM\n0.1 dtM\n")), r"dtM must be at least 1e-100 s" + ) + + +@pytest.mark.skipif( + not _PARITY_DRIVER or not Path(_PARITY_DRIVER).is_file(), + reason="set CABLEDYN_TEST_DRIVER to a built native driver to run the time-step parity", +) +@pytest.mark.parametrize(("dt", "accepted"), _TINY_STEPS) +@pytest.mark.parametrize("ei", ["0.0", "1.0e4"], ids=["ei0", "finite-ei"]) +def test_dtm_bound_matches_the_driver(dt, accepted, ei, tmp_path): + text = _edit( + _HELD, + ("0.1 dtM\n10.0 TMax\n", f"{dt} dtM\n{2 * float(dt)!r} TMax\n"), + (" -1.0 0.0 1.37", f" -1.0 {ei} 1.37"), + ) + deck = tmp_path / "step.dat" + deck.write_text(text, encoding="utf-8") + completed = subprocess.run( + [_PARITY_DRIVER, str(deck), str(tmp_path / "step")], + capture_output=True, + text=True, + errors="replace", + cwd=tmp_path, + timeout=600, + env={**os.environ, "OMP_NUM_THREADS": "1", "OPENBLAS_NUM_THREADS": "1"}, + check=False, + ) + assert completed.returncode == (0 if accepted else 1), completed.stderr[-600:] + assert _accepted(deck) == accepted + if not accepted: + assert "dtM must be at least 1e-100 s" in completed.stderr diff --git a/src/CableDyn_CAPI.f90 b/src/CableDyn_CAPI.f90 index d76c3ff7..58c0dcdd 100644 --- a/src/CableDyn_CAPI.f90 +++ b/src/CableDyn_CAPI.f90 @@ -35,7 +35,7 @@ MODULE CableDyn_CAPI CD_FAST_NCoupledDOF, CD_FAST_NPoints, CD_FAST_NLines, CD_FAST_OK, CD_FAST_BADINPUT, & CD_FAST_NOT_INITIALIZED, CD_FAST_ALLOCFAIL, CD_FAST_UpdatePointFluidFields USE CableDyn_OpenFAST_HermiteFMF, ONLY: CD_HFMF_ModuleType, CD_HFMF_Section_Curvature, CD_HFMF_OK - USE CableDyn_Precision, ONLY: wp, CD_ZERO, CD_ONE + USE CableDyn_Precision, ONLY: wp, CD_ZERO, CD_ONE, CD_MIN_TIME_STEP USE CableDyn_System, ONLY: CD_SystemType, CD_System_Line_NDOF, CD_Get_System_PointBlocks, CD_SYSTEM_OK, & CD_POINT_COUPLED IMPLICIT NONE @@ -1369,6 +1369,12 @@ SUBROUTINE CableDyn_Step(handle, dt, q_ptr, v_ptr, a_ptr, n_coupled_dof, converg n_iter = 0_C_INT CALL coupled_inputs(handle, q_ptr, v_ptr, a_ptr, n_coupled_dof, h, q_c, v_c, a_c, err_stat) IF (err_stat /= CD_C_OK) RETURN + ! a positive step too small to integrate (NaN, Inf and dt <= 0 are named by the route) + IF (dt > 0.0_C_DOUBLE .AND. dt < REAL(CD_MIN_TIME_STEP, C_DOUBLE)) THEN + CALL set_status(h, CD_C_BAD_INPUT, 'CableDyn_Step: dt is below the smallest time step, 1e-100 s: '// & + 'the time integration divides by dt^2', err_stat) + RETURN + END IF IF (h%use_agg) THEN IF (h%agg_host_fluid .AND. .NOT. h%fluid_ready) THEN CALL set_status(h, CD_C_BAD_INPUT, 'CableDyn_Step: the model takes a host fluid field: call '// & diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index 36e8d753..fbf448b6 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -30,7 +30,7 @@ MODULE CableDyn_DeckDriver !! connected to Rigid6 bodies and rods (moment returned) are supported within the documented !! scope. Features outside it parse but FAIL CLOSED with a clear error naming the unsupported !! feature. - USE CableDyn_Precision, ONLY: wp, CD_ZERO, CD_ONE + USE CableDyn_Precision, ONLY: wp, CD_ZERO, CD_ONE, CD_MIN_TIME_STEP USE CableDyn_FatalReport, ONLY: CD_Fatal_Report_Time USE CableDyn_Loads, ONLY: CD_Submerged_Weight, CD_Equivalent_Buoyant_Section, CD_Assemble_Distributed_Load USE CableDyn_Assemble, ONLY: CD_Compute_Cable_Tension, CD_Cable_Free_Bandwidth, & @@ -18207,8 +18207,10 @@ SUBROUTINE check_option_row_value(kw, val, ErrStat, ErrMsg) IF (key(1:13) == 'aslaidtension' .AND. VERIFY(TRIM(key(14:)), '0123456789') == 0) key = 'aslaidtension' END IF SELECT CASE (TRIM(key)) - CASE ('g', 'gravity', 'rhow', 'wtrdnsty', 'water_density', 'wtrdpth', 'water_depth', 'dtm', 'dt', 'dtwave') + CASE ('g', 'gravity', 'rhow', 'wtrdnsty', 'water_density', 'wtrdpth', 'water_depth', 'dtwave') rule = 'positive' + CASE ('dtm', 'dt') + rule = 'time step' CASE ('tmax', 'tensile_strain_tolerance', 'tensilestraintolerance', 'ramptime', 'ramp_time', 'tramp', & 'maxstrain', 'max_strain', 'rangestart', 'range_start', 'vivrmswindow', 'viv_rms_window') rule = 'non-negative' @@ -18245,6 +18247,9 @@ SUBROUTINE check_option_row_value(kw, val, ErrStat, ErrMsg) IF (x < CD_ZERO) CALL fail(ErrStat, ErrMsg, 'OPTION '//TRIM(kw)//' must be >= 0') CASE ('unit') IF (x < CD_ZERO .OR. x > CD_ONE) CALL fail(ErrStat, ErrMsg, 'OPTION '//TRIM(kw)//' must lie in [0, 1]') + CASE ('time step') + IF (.NOT. (x >= CD_MIN_TIME_STEP)) CALL fail(ErrStat, ErrMsg, 'OPTION '//TRIM(kw)//' must be at least '// & + '1e-100 s: the time integration divides by its square') END SELECT END SUBROUTINE check_option_row_value diff --git a/src/CableDyn_OpenFAST_Aggregate.f90 b/src/CableDyn_OpenFAST_Aggregate.f90 index 3fb0d595..0b965d12 100644 --- a/src/CableDyn_OpenFAST_Aggregate.f90 +++ b/src/CableDyn_OpenFAST_Aggregate.f90 @@ -41,7 +41,7 @@ MODULE CableDyn_OpenFAST_Aggregate !! pattern) -- the coupling dt freezes at Init and CD_AGG_Step_Moving fails closed on a step !! dt that differs from it (a mismatched size would silently desync the cables, whose !! generalised-alpha step carries the Init dt, from the mooring columns). - USE CableDyn_Precision, ONLY: wp, CD_ZERO, CD_ONE, CD_All_Finite + USE CableDyn_Precision, ONLY: wp, CD_ZERO, CD_ONE, CD_All_Finite, CD_MIN_TIME_STEP USE CableDyn_PathIO, ONLY: CD_Open_Write USE CableDyn_FatalReport, ONLY: CD_Fatal_Thread_Init USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY: int64 @@ -382,6 +382,12 @@ SUBROUTINE CD_AGG_Init_From_Deck(self, deck_path, dt, ErrStat, ErrMsg, env_gravi ErrMsg = 'CableDyn_OpenFAST_Aggregate: dt must be positive' RETURN END IF + IF (dt < CD_MIN_TIME_STEP) THEN + ErrStat = CD_AGG_BADINPUT + ErrMsg = 'CableDyn_OpenFAST_Aggregate: dt is below the smallest time step, 1e-100 s: the time '// & + 'integration divides by dt^2' + RETURN + END IF ALLOCATE (candidate, parts, STAT=istat) IF (istat /= 0) THEN ErrStat = CD_AGG_ALLOCFAIL @@ -1128,6 +1134,12 @@ SUBROUTINE CD_AGG_Step_Moving(self, dt, position, velocity, acceleration, conver ErrMsg = 'CableDyn_OpenFAST_Aggregate: step dt must be positive' RETURN END IF + IF (dt < CD_MIN_TIME_STEP) THEN + ErrStat = CD_AGG_BADINPUT + ErrMsg = 'CableDyn_OpenFAST_Aggregate: dt is below the smallest time step, 1e-100 s: the time '// & + 'integration divides by dt^2' + RETURN + END IF ! Fixed-dt contract: the cables advance with the Init dt frozen into their gen-alpha step, so a ! step dt differing from it would desync the cable columns from the mooring columns. Fail closed ! rather than silently mis-integrate (self%dt > 0 is guaranteed by Init's dt validation). diff --git a/src/CableDyn_OpenFAST_FMF.f90 b/src/CableDyn_OpenFAST_FMF.f90 index 2ac5ba61..64624aad 100644 --- a/src/CableDyn_OpenFAST_FMF.f90 +++ b/src/CableDyn_OpenFAST_FMF.f90 @@ -8,7 +8,7 @@ MODULE CableDyn_OpenFAST_FMF !! current registry-style types, point-mesh adapter, and lifecycle shell into a !! single Init/UpdateStates/CalcOutput/End object graph. The generated OpenFAST !! binding must preserve this behavior when it is linked against OpenFAST types. - USE CableDyn_Precision, ONLY: wp, CD_ZERO + USE CableDyn_Precision, ONLY: wp, CD_ZERO, CD_MIN_TIME_STEP USE CableDyn_Model, ONLY: CD_ModelType USE CableDyn_System, ONLY: CD_SystemType, CD_SystemPointType, CD_LineEndpointBinding, CD_Get_System_PointBlocks, & CD_System_NDynamicPoints, & @@ -113,6 +113,12 @@ SUBROUTINE CD_FMF_Init_From_Points(self, models, points, bindings, dt, ErrStat, ErrMsg = 'CableDyn_OpenFAST_FMF: dt must be positive' RETURN END IF + IF (dt < CD_MIN_TIME_STEP) THEN + ErrStat = CD_FMF_BADINPUT + ErrMsg = 'CableDyn_OpenFAST_FMF: dt is below the smallest time step, 1e-100 s: the time '// & + 'integration divides by dt^2' + RETURN + END IF candidate%init_input%n_coupled_dof = 0 candidate%init_input%dt = dt CALL CD_FAST_Init_From_Points(candidate%fast, models, points, bindings, es, em) @@ -171,6 +177,12 @@ SUBROUTINE CD_FMF_Init_From_Deck(self, deck_path, dt, ErrStat, ErrMsg, env_gravi ErrMsg = 'CableDyn_OpenFAST_FMF: dt must be positive' RETURN END IF + IF (dt < CD_MIN_TIME_STEP) THEN + ErrStat = CD_FMF_BADINPUT + ErrMsg = 'CableDyn_OpenFAST_FMF: dt is below the smallest time step, 1e-100 s: the time '// & + 'integration divides by dt^2' + RETURN + END IF candidate%init_input%dt = dt ! The host marches the coupled system (CD_FMF_Step at the caller's dt), so the ! deck's own dtM/TMax standalone-marching pairing is advisory here. Absent @@ -230,6 +242,12 @@ SUBROUTINE CD_FMF_Init_From_System(self, system, dt, gravity, rho_water, ErrStat ErrMsg = 'CableDyn_OpenFAST_FMF: dt must be positive' RETURN END IF + IF (dt < CD_MIN_TIME_STEP) THEN + ErrStat = CD_FMF_BADINPUT + ErrMsg = 'CableDyn_OpenFAST_FMF: dt is below the smallest time step, 1e-100 s: the time '// & + 'integration divides by dt^2' + RETURN + END IF candidate%init_input%dt = dt candidate%fast%system = system IF (.NOT. CD_FAST_IsInitialized(candidate%fast)) THEN @@ -335,6 +353,12 @@ SUBROUTINE CD_FMF_Step(self, dt, position, velocity, acceleration, converged, st ErrMsg = 'CableDyn_OpenFAST_FMF: step dt must be positive' RETURN END IF + IF (dt < CD_MIN_TIME_STEP) THEN + ErrStat = CD_FMF_BADINPUT + ErrMsg = 'CableDyn_OpenFAST_FMF: dt is below the smallest time step, 1e-100 s: the time '// & + 'integration divides by dt^2' + RETURN + END IF CALL CD_FAST_Set_PointMesh_State(self%point_mesh, position, velocity, acceleration, es, em) IF (es /= CD_FAST_MESH_OK) THEN CALL map_mesh_status(es, em, ErrStat, ErrMsg) diff --git a/src/CableDyn_Precision.f90 b/src/CableDyn_Precision.f90 index 96da7929..69156bd5 100644 --- a/src/CableDyn_Precision.f90 +++ b/src/CableDyn_Precision.f90 @@ -15,6 +15,9 @@ MODULE CableDyn_Precision REAL(wp), PARAMETER, PUBLIC :: CD_ZERO = 0.0_wp REAL(wp), PARAMETER, PUBLIC :: CD_ONE = 1.0_wp + ! The smallest time step any march takes: the implicit integrators divide by dt^2, which + ! overflows the inertia terms near 1e-155 s; this bound keeps a wide margin above that. + REAL(wp), PARAMETER, PUBLIC :: CD_MIN_TIME_STEP = 1.0e-100_wp PUBLIC :: CD_All_Finite, CD_Is_Finite diff --git a/tests/test_openfast_aggregate.f90 b/tests/test_openfast_aggregate.f90 index ab9d75f8..3b472d30 100644 --- a/tests/test_openfast_aggregate.f90 +++ b/tests/test_openfast_aggregate.f90 @@ -563,6 +563,17 @@ SUBROUTINE case_pure_mooring_equals_fmf() LOGICAL :: ca, cf, sa, sf CALL write_volturnus_deck('agg_pure.dat') + ! a host step below the smallest time step (1e-100 s) is refused by name at initialisation + BLOCK + TYPE(CD_AGG_ModuleType) :: tiny_agg + TYPE(CD_FMF_ModuleType) :: tiny_fmf + CALL CD_AGG_Init_From_Deck(tiny_agg, 'agg_pure.dat', 1.0e-200_wp, es, em) + CALL require(es /= CD_AGG_OK .AND. INDEX(em, 'smallest time step, 1e-100 s') > 0, & + 'pure:agg-init refuses dt = 1e-200 s by name: '//TRIM(em)) + CALL CD_FMF_Init_From_Deck(tiny_fmf, 'agg_pure.dat', 1.0e-200_wp, es, em) + CALL require(es /= CD_FMF_OK .AND. INDEX(em, 'smallest time step, 1e-100 s') > 0, & + 'pure:fmf-init refuses dt = 1e-200 s by name: '//TRIM(em)) + END BLOCK CALL CD_AGG_Init_From_Deck(agg, 'agg_pure.dat', DT, es, em) CALL require(es == CD_AGG_OK .AND. CD_AGG_IsInitialized(agg), 'pure:agg-init: '//TRIM(em)) IF (es /= CD_AGG_OK) RETURN