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
27 changes: 27 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,33 @@ All notable changes to CableDyn are recorded in this file. The format follows
and checkpoint state; `Tf` 0 or no row leaves runs unchanged to the bit. A VIV FRAME row now
needs LINE TYPES `Cl > 0` or a WAKE OSCILLATOR row; the Python deck reader and builder follow.

- A long-run check of the VIV synchronisation model (`viv_long_run`, 400 cycles). With every node
of a finite-EI cable moved across the flow, the shedding phase follows the closed-form solution
of its equation (Adler's) with an error that grows linearly in time and falls fourfold per
halving of the step: 0.017 rad after 400 cycles at 100 steps per cycle; inside the
synchronisation band the phase lag holds to 3e-5 rad. On a taut line locked in, finite-EI and
`EI = 0`, the load powers close the line's energy balance to 2e-4 of the VIV work at second
order, and the response amplitude, VIV power and lock-in frequency of the run's two halves agree
within 0.18 %.

### Changed

- `run_study` (and `cabledyn-study`) with `jobs > 1` runs every case with `OMP_NUM_THREADS=1`
unless the environment sets it, and `study.json` records the value (`omp_num_threads`). Many
processes that each start an OpenMP team oversubscribed the cores: 24 lazy-wave runs at 24 jobs
took 19.1 s with the OpenMP default and 16.7 s with one thread each. The Python manual gives the
measured batch scaling (13.3 times faster at 24 jobs on a 24-core workstation, 15.1 at 48).
- The load power channels (`VIVPow`, `DragPow`, `DampPow` and their per-length forms) of a line
evaluate its node powers once per output row instead of once per channel, on finite-EI cables,
`EI = 0` lines and line systems. Outputs are unchanged to the bit; with the three line totals
the VIV examples run about 11 % faster (`viv_taut_cable_inline.dat` 2.39 s to 2.14 s; the same
line with 200 elements at 100 steps per cycle 18.1 s to 16.1 s).
- The bending damping of a finite-EI cable (`EI|Bb`, `EI|-zeta|f`) evaluates the second
derivatives of the curvature only where the position Jacobian needs them, not in every residual
evaluation. Results are unchanged to the bit; the Delta Flume case 9 deck of
`validation/experiments/delta_flume` (64 elements, 80 000 steps) runs in 58.6 s instead of
73.2 s.

### Fixed

- The statics of a finite-EI line through the free surface could fail at isolated currents:
Expand Down
9 changes: 9 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1430,6 +1430,15 @@ target_link_libraries(test_hermite_load_power PRIVATE cabledyn_core)
add_test(NAME hermite_load_power COMMAND test_hermite_load_power)
set_tests_properties(hermite_load_power PROPERTIES LABELS "fortran;dynamic;viv")

# Long VIV runs (400 cycles at 100 and 200 steps per cycle): the shedding phase under prescribed
# motion against Adler's closed form (linear error growth, second order), and a locked-in taut
# line of both kinds (energy closure of the load powers, stationary statistics and frequency).
# About 26 s in Release and 160 s in Debug locally.
add_executable(test_viv_long_run tests/test_viv_long_run.f90)
target_link_libraries(test_viv_long_run PRIVATE cabledyn_core)
add_test(NAME viv_long_run COMMAND test_viv_long_run)
set_tests_properties(viv_long_run PROPERTIES LABELS "fortran;dynamic;viv;slow" TIMEOUT 1200)

add_executable(test_load_power_deck tests/test_load_power_deck.f90)
target_link_libraries(test_load_power_deck PRIVATE cabledyn_core)
add_test(NAME load_power_deck COMMAND test_load_power_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
Expand Down
1 change: 1 addition & 0 deletions VALIDATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ article's methods, are compared in
| **L2-VIV** | Cross-flow VIV lock-in of a taut 100 m line, U = 0.06–0.42 m/s | MoorDyn-C v2.7.2 (RK2, `dtM` 5e-4 s) and MoorDyn-F (OpenFAST v5 `moordyn_driver`, `dtM` 5e-4 s) | over 150–300 s, mode-1 lock-in at U 0.09–0.18 m/s: mid-span A/D within 0.2% of MoorDyn-F (0.017 against 0.018 at 0.06 m/s, below lock-in); mode 3 at 0.39–0.42 m/s within 1.4%; at 0.36 m/s MoorDyn-F settles in mode 2 and CableDyn in mode 3; frequency within one spectral bin wherever the modes agree; same response at `dtM` 5e-4 and 1e-2 s. At 0.21–0.33 m/s two branches coexist (a run ramped up from 0.18 m/s stays in mode 1, one ramped down from 0.30 m/s stays in mode 2): from rest CableDyn and MoorDyn-C settle in mode 2 (U 0.24 m/s: A/D 0.575 against 0.574 at x/L 0.24, same frequency); MoorDyn-F, whose phases start at zero (it does not carry its seed into its state), in mode 1, which `zero VIVphaseSeed` reproduces (0.699 against 0.699) | A/D <3%, frequency within one spectral bin; band: 3% (MoorDyn-C), 1% (MoorDyn-F) (`viv_lockin`) | Pass |
| **L2-VIV-riser** | Catenary riser of Thorsen et al. in a uniform 0.2 m/s current (MoorDyn-C's VIV test: D 0.024 m, EI 10.5 N m², 100 segments, `Cl` 0.7), deck written anchor first | measured cross-flow frequency 1.04 Hz; MoorDyn-C v2.7.2 (RK4, `dtM` 1e-4 s) | over 20–40 s at `dtM` 1e-3 s: mean fairlead tension 69.92 N against 69.93 N, range 3.73 N against 3.72 N, tension period 0.4853 s against the measured 0.4808 s and MoorDyn-C's 0.4811 s (0.4843 / 0.4829 s at `dtM` 5e-4 / 2.5e-4 s) | mean 0.2%, range 10%, period 1.5% (`viv_riser`) | Pass |
| **L2-VIV-EI** | Cross-flow VIV of a finite-EI cable: the L2-VIV line with EI = 1 N m², and a bending-stiff line (EA 5e9 N, EI 5e7 N m², β = π²EI/(TL²) ≈ 1, neutrally buoyant) against the EI = 0 string of equal first-mode frequency, U = 0.10–0.36 m/s | CableDyn `EI = 0` line (verification) | EI = 1: mid/quarter A/D 0.661/0.420 against 0.661/0.420, same frequency, at `dtM` 5e-4 to 1e-2 s; stiff line: mode-1 lock-in A/D within 2.5% of the string's at the same frequency for U ≤ 0.24 m/s; for U ≥ 0.27 m/s the string jumps to mode 2 while the stiff line stays in mode 1 (bending raises f₂/f₁ to 3.15) | EI = 1: A/D within 1% at `dtM` 0.01 and 0.002 s (5e-4 s run once over 200 s); stiff line at U 0.21 m/s: A/D within 3%; frequency within one spectral bin; at U 0.30 m/s stiff line A/D > 0.6, string < 0.15 (`viv_lockin`, `hermite_viv`) | Pass |
| **L2-VIV-long** | Long VIV runs, 400 cycles: (a) every node of a finite-EI cable moved across a 0.3 m/s flow at 5.5 rad/s (outside the synchronisation band) and inside it; (b) a taut 20 m line locked in, finite-EI and `EI = 0`, ρ∞ = 1, at 100 and 200 steps per cycle | (a) Adler's equation in closed form, `tan(ψ/2) = (b + s tan(θ/2))/a`; (b) the load powers against the change of the line's energy; a 2× finer step | (a) phase error 0.017 rad after 400 cycles at 100 steps per cycle, growing linearly (T/(T/2) 1.99) and second order (4.01 from 50 to 100 steps); inside the band the lag stays within 3.0e-5 rad of ψ*; (b) energy mismatch 2.0e-4 / 1.8e-4 of the VIV work, second order (3.98 / 3.67), A/D and VIV power of the run's two halves within 7.3e-4 and 1.8e-3, lock-in frequency within 1.9e-4 | (a) growth ratio 1.8–2.2, order 3.6–4.4, ≤0.05 rad; locked ≤1e-4 rad; (b) ≤3e-4, ratio 3–5; halves 2e-3 / 1e-2 / 2e-3 (`viv_long_run`) | Pass |
| **L3-1** | WD0050 static | OrcaFlex | 0.15 / 0.85% | <2% | Pass |
| **L3-2** | Regular-wave dynamic | OrcaFlex (pinned, dt-converged) | mean 0.30%, swing 8.4% | <2% / <15% | Pass |
| **L3-3** | Current-deflected static | OrcaFlex | 0.07–0.67% | <2% | Pass |
Expand Down
4 changes: 3 additions & 1 deletion doc/cli.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1125,7 +1125,9 @@ remaining cases.
* - ``--jobs``
- int
- ``1``
- Number of native processes run concurrently; must be positive.
- Number of native processes run concurrently; must be positive. Above 1, each process
runs with ``OMP_NUM_THREADS=1`` unless the environment sets it (measured batch scaling
and thread settings: :doc:`python`, Batch execution and study records).
* - ``--timeout``
- float, s
- none
Expand Down
65 changes: 65 additions & 0 deletions doc/python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -714,6 +714,71 @@ cases may run as separate native processes with ``jobs > 1``. Results are always
written in the original manifest order, not completion order. This is process-level concurrency;
it does not change CableDyn's numerical settings or make one solver instance multithreaded.

With ``jobs > 1`` and no ``OMP_NUM_THREADS`` in the environment, every case runs with
``OMP_NUM_THREADS=1``, and ``study.json`` records the value the cases ran with
(``omp_num_threads``; ``null`` when the environment was passed on without one). A set
``OMP_NUM_THREADS`` is passed on unchanged. The OpenMP regions of a GNU build (the tangent kernels
of a finite-EI cable of 32 elements or more, up to four threads, and the lines of a multi-line
system) pay off in a single run only, and many processes that each start a team oversubscribe the
cores. Measured on a 24-core, 48-thread workstation (gfortran Release build; the static Windows
release has no OpenMP):

.. list-table:: Batch wall time, 96 finite-EI VIV cases (100 elements, 2000 steps, 1.8 s each)
:header-rows: 1

* - ``jobs``
- wall, ``OMP_NUM_THREADS=1``
- speed-up
- mean case time
- wall, OpenMP default
* - 1
- 177.4 s
- 1.0
- 1.84 s
- 181.2 s
* - 2
- 91.2 s
- 1.9
- 1.89 s
- 91.5 s
* - 4
- 48.2 s
- 3.7
- 1.97 s
- 49.4 s
* - 8
- 27.1 s
- 6.5
- 2.18 s
- 28.7 s
* - 16
- 16.7 s
- 10.6
- 2.62 s
- 16.9 s
* - 24
- 13.4 s
- 13.3
- 3.15 s
- 14.1 s
* - 48
- 11.8 s
- 15.1
- 5.45 s
- 11.9 s

A case slows down as more run beside it (1.84 s alone, 3.15 s beside 23 others: shared memory
bandwidth and a lower all-core clock), so the batch gains less than ``jobs``; the second hardware
thread of each core adds 13 %. The VIV cases spend almost no time in OpenMP regions (a single run
takes 1.79 s with one thread and 1.76 s with the default), so the default costs them at most 5 %.
On a deck that uses them, the 1024-element lazy-wave cable of
``examples/lazy_wave_vessel_rao.dat``, a single run takes 11.4 s with one thread, 10.6 s with four
and 12.5 s with the default, and a batch of 24 such runs with ``jobs=24`` takes 16.7 s with one
thread per process, 17.9 s with four and 19.1 s with the default. Set ``jobs`` to the number of
physical cores (24 here), or to the number of hardware threads for the last 10-15 %, and leave
``OMP_NUM_THREADS`` unset for a batch; for a single long run of a large finite-EI cable,
``OMP_NUM_THREADS=4`` is the fastest setting.

One failed case does not cancel the remaining cases. The final status distinguishes:

* ``completed`` — native exit zero, which the driver reserves for a converged analysis;
Expand Down
35 changes: 31 additions & 4 deletions python/cabledyn/study.py
Original file line number Diff line number Diff line change
Expand Up @@ -314,6 +314,19 @@ def _case_dict(case: StudyCaseResult) -> dict[str, object]:
return result


def _case_environment(job_count: int) -> dict[str, str] | None:
"""The environment entries of every case process: one OpenMP thread each when several run at
once and the caller's environment does not choose a count, otherwise none.

Several CableDyn processes that each start an OpenMP team oversubscribe the cores; on a 24-core
workstation a batch of 24 finite-EI lazy-wave runs took 14 % longer with OpenMP left at its
default than with one thread per process.
"""
if job_count <= 1 or os.environ.get("OMP_NUM_THREADS", "").strip():
return None
return {"OMP_NUM_THREADS": "1"}


def run_study(
case_manifest: str | os.PathLike[str],
*,
Expand Down Expand Up @@ -354,7 +367,10 @@ def run_study(
Per-case time limit, in seconds; ``None`` for no limit.
jobs : int
Number of independent native processes run at once (not solver
threads within a process).
threads within a process). With ``jobs > 1`` and no
``OMP_NUM_THREADS`` in the environment, each process runs with
``OMP_NUM_THREADS=1``: the processes then share the cores without
oversubscribing them. A set ``OMP_NUM_THREADS`` is passed on unchanged.
overwrite : bool
Allow a non-empty output directory and replace existing case outputs.

Expand Down Expand Up @@ -446,6 +462,7 @@ def run_study(
solver_version = native.version()
destination.mkdir(parents=True, exist_ok=True)

case_env = _case_environment(job_count)
started = datetime.now(timezone.utc).isoformat()
summaries: dict[str, list[dict[str, object]]] = {}
summaries_lock = threading.Lock()
Expand All @@ -464,9 +481,14 @@ def execute(case: _Case) -> StudyCaseResult:
main_output: Path | None = None
static_output: Path | None = None
try:
native_result = native.run(
case.deck, output_root, timeout=timeout_value, overwrite=overwrite
)
if case_env is None:
native_result = native.run(
case.deck, output_root, timeout=timeout_value, overwrite=overwrite
)
else:
native_result = native.run(
case.deck, output_root, timeout=timeout_value, overwrite=overwrite, env=case_env
)
stdout, stderr = native_result.stdout, native_result.stderr
returncode = native_result.returncode
main_output = native_result.main_output
Expand Down Expand Up @@ -600,6 +622,11 @@ def execute(case: _Case) -> StudyCaseResult:
"started_at": started,
"finished_at": finished,
"jobs": job_count,
"omp_num_threads": (
case_env["OMP_NUM_THREADS"]
if case_env is not None
else os.environ.get("OMP_NUM_THREADS")
),
"timeout": timeout_value,
"period": {"start": start_value, "stop": stop_value},
"channels": list(selected) if selected is not None else None,
Expand Down
36 changes: 36 additions & 0 deletions python/tests/test_study.py
Original file line number Diff line number Diff line change
Expand Up @@ -315,3 +315,39 @@ def test_study_argument_validation(tmp_path, kwargs, message):
output_directory=tmp_path / "results",
**kwargs,
)


@pytest.mark.parametrize(
("jobs", "omp", "passed", "recorded"),
[
(2, None, "1", "1"), # parallel cases default to one OpenMP thread each
(2, "", "1", "1"), # an empty value counts as unset
(2, "3", None, "3"), # the caller's count is passed on unchanged
(1, None, None, None), # one case at a time keeps the environment
],
)
def test_study_gives_parallel_cases_one_openmp_thread(
tmp_path, monkeypatch, jobs, omp, passed, recorded
):
if omp is None:
monkeypatch.delenv("OMP_NUM_THREADS", raising=False)
else:
monkeypatch.setenv("OMP_NUM_THREADS", omp)
manifest = _case_manifest(tmp_path)
driver = _driver(tmp_path)
original_run = driver.run
seen: list[object] = []
lock = threading.Lock()

def recording_run(*args, **kwargs):
with lock:
seen.append(kwargs.get("env"))
return original_run(*args, **kwargs)

driver.run = recording_run # type: ignore[method-assign]
result = run_study(manifest, driver=driver, output_directory=tmp_path / "results", jobs=jobs)
assert result.passed
expected = None if passed is None else {"OMP_NUM_THREADS": passed}
assert seen == [expected, expected]
payload = json.loads(result.study_manifest.read_text(encoding="utf-8"))
assert payload["omp_num_threads"] == recorded
Loading
Loading