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
3 changes: 2 additions & 1 deletion doc/capi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 *``
Expand Down
3 changes: 2 additions & 1 deletion doc/options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions doc/python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"})
Expand Down Expand Up @@ -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:
Expand Down
3 changes: 2 additions & 1 deletion python/cabledyn/model.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
31 changes: 31 additions & 0 deletions python/tests/test_cabledyn.py
Original file line number Diff line number Diff line change
Expand Up @@ -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))
3 changes: 2 additions & 1 deletion python/tests/test_deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 55 additions & 0 deletions python/tests/test_deck_native_parity.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
8 changes: 7 additions & 1 deletion src/CableDyn_CAPI.f90
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 '// &
Expand Down
9 changes: 7 additions & 2 deletions src/CableDyn_DeckDriver.f90
Original file line number Diff line number Diff line change
Expand Up @@ -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, &
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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

Expand Down
14 changes: 13 additions & 1 deletion src/CableDyn_OpenFAST_Aggregate.f90
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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).
Expand Down
26 changes: 25 additions & 1 deletion src/CableDyn_OpenFAST_FMF.f90
Original file line number Diff line number Diff line change
Expand Up @@ -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, &
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
3 changes: 3 additions & 0 deletions src/CableDyn_Precision.f90
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
11 changes: 11 additions & 0 deletions tests/test_openfast_aggregate.f90
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading