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: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ All notable changes to CableDyn are recorded in this file. The format follows
(`CurvX`/`CurvY`), `T/A - E r (kappa_x cos theta + kappa_y sin theta)`, counted point by point
for the fatigue of biaxial bending; a whirling section, which the two-fibre recovery from the
curvature magnitude sees as constant, now accumulates its damage.
- `cabledyn.current_steps`: a stepped-current schedule for a VIV study in one run (each speed
held, then ramped to the next), written as the deck's MoorDyn-C `Currents 2` file, with the
VIV response of every hold.

## [0.4.2] - 2026-11-09

Expand Down
5 changes: 5 additions & 0 deletions doc/api_python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -346,6 +346,11 @@ the solver's own curvature, tension, and angle channels, where written, are auth
.. autoclass:: cabledyn.ModalAmplitudes
:members:

.. autofunction:: cabledyn.current_steps

.. autoclass:: cabledyn.CurrentSteps
:members:

Deck editing and case generation
--------------------------------

Expand Down
26 changes: 26 additions & 0 deletions doc/python_postprocessing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -495,6 +495,32 @@ is 0.05, a standing wave between the pinned ends.
viv.plot_orbit(13)
viv.export("results/line1_viv.csv")

A stepped-current study holds the current at a sequence of speeds in one run, so each step
starts from the state the previous one left: the response follows a branch as the current goes
up and comes back down, where separate runs would each start from rest.
:func:`cabledyn.current_steps` builds the schedule (each speed held ``hold`` seconds, ramped
linearly over ``ramp`` seconds to the next, along one direction); its ``write`` puts the deck's
MoorDyn-C ``Currents 2`` file ``current_profile_dynamic.txt`` (:doc:`options`) in the deck
folder, its ``duration`` is the ``TMax`` to give, and its ``responses`` returns the
:func:`~cabledyn.viv_response` of every hold from ``settle`` seconds into it. The file's
smallest time interval is the ramp, the step the current table is resampled to, so a hold must
be a whole number of ramps; the static start takes the first speed. The file holds the last
speed for two ramps past ``duration``, because the resampled table returns to its first sample
over its last interval; the run therefore keeps the last speed up to ``TMax``.

.. code-block:: python

from cabledyn import current_steps

speeds = [0.10, 0.14, 0.18, 0.22, 0.26, 0.22, 0.18, 0.14, 0.10]
steps = current_steps(speeds, hold=60.0, ramp=5.0, direction=(0.0, 1.0, 0.0))
steps.write("cases/stepped") # next to the deck, which sets "2 Currents" and TMax
print(steps.duration)
# ... run the deck, then:
for speed, viv in zip(steps.speeds, steps.responses(
result.read_line_positions(1), diameter=0.1, settle=30.0)):
print(speed, viv.amplitude_over_diameter("cross_flow").max(), viv.frequency("cross_flow"))

Parameter grids
---------------

Expand Down
10 changes: 9 additions & 1 deletion python/cabledyn/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,13 @@
)
from cabledyn.sweep import parameter_grid
from cabledyn.touchdown import TouchdownHistory, touchdown_history
from cabledyn.viv import ModalAmplitudes, VIVResponse, viv_response
from cabledyn.viv import (
CurrentSteps,
ModalAmplitudes,
VIVResponse,
current_steps,
viv_response,
)

if TYPE_CHECKING:
from cabledyn._lib import abi_minor as abi_minor
Expand All @@ -177,6 +183,7 @@
"CoherenceResult",
"ConvergenceError",
"CoupledRun",
"CurrentSteps",
"DamageProfile",
"DeckFile",
"DeckFormatError",
Expand Down Expand Up @@ -243,6 +250,7 @@
"channel_summary",
"clearance_matrix",
"compare_histories",
"current_steps",
"cycle_histogram",
"damage_along_arc",
"damage_equivalent_range",
Expand Down
170 changes: 169 additions & 1 deletion python/cabledyn/viv.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
from cabledyn.spectra import _sampling
from cabledyn.touchdown import _positions

__all__ = ["ModalAmplitudes", "VIVResponse", "viv_response"]
__all__ = ["CurrentSteps", "ModalAmplitudes", "VIVResponse", "current_steps", "viv_response"]

_DIRECTIONS = ("cross_flow", "in_line")

Expand Down Expand Up @@ -596,3 +596,171 @@ def viv_response(
whole_line=whole_line,
node_numbers=numbers,
)


@dataclass(frozen=True)
class CurrentSteps:
"""A uniform current held at a sequence of speeds, for a stepped-current VIV study.

Created by :func:`current_steps`. The current is held at ``speeds[k]`` for
``hold`` seconds, then ramps linearly over ``ramp`` seconds to the next
speed, so one run continues each step from the state the previous one
left (the response branch an up-and-down sweep follows). :meth:`write`
gives the deck its MoorDyn-C ``Currents 2`` file.

Attributes
----------
speeds : numpy.ndarray
Read-only ``(n_steps,)`` current speeds, m/s.
hold, ramp : float
Hold time of each speed and ramp time between speeds, s.
direction : numpy.ndarray
Read-only ``(3,)`` unit direction of the current.
"""

speeds: npt.NDArray[Any]
hold: float
ramp: float
direction: npt.NDArray[Any]

@property
def starts(self) -> npt.NDArray[Any]:
"""Read-only ``(n_steps,)`` start time of each hold, s."""
return _readonly(np.arange(self.speeds.size) * (self.hold + self.ramp))

@property
def duration(self) -> float:
"""End of the last hold, s: the deck's ``TMax``.

The file holds the last speed for two ramps beyond it (:meth:`write`); a
longer run then repeats the record.
"""
return float(self.starts[-1] + self.hold)

def windows(self, settle: float) -> tuple[tuple[float, float], ...]:
"""Return the analysis window of every hold, from ``settle`` seconds into it to its end."""
if not (math.isfinite(float(settle)) and 0.0 <= float(settle) < self.hold):
raise ValueError("settle must be finite, non-negative and shorter than the hold")
return tuple((float(t) + float(settle), float(t) + self.hold) for t in self.starts)

def write(
self,
folder: str | os.PathLike[str],
*,
depths: tuple[float, float] = (-1.0e4, 0.0),
overwrite: bool = False,
) -> Path:
"""Write ``current_profile_dynamic.txt``, the deck's ``Currents 2`` file, into ``folder``.

The current is uniform between the two ``depths`` (z, m, increasing) and
held beyond them. The file's smallest time interval is the ramp, the time
step MoorDyn-C and CableDyn resample it to, so the holds stay exact.

The resampled table has ``floor(t_last/dt) + 1`` samples and takes its
first sample over its last interval (where a longer run starts to repeat
it), and a rounded ``dt`` can drop the last sample by one step. The file
therefore ends two ramps after :attr:`duration`, still at the last speed,
so the run up to ``TMax`` never returns to the first speed.

Raises
------
FileExistsError
If the file exists and ``overwrite`` is false.
ValueError
If the depths are not two finite, increasing elevations.
"""
low, high = (float(z) for z in depths)
if not (math.isfinite(low) and math.isfinite(high) and low < high):
raise ValueError("depths must be two finite, increasing elevations")
target = Path(folder).expanduser().resolve() / "current_profile_dynamic.txt"
if target.exists() and not overwrite:
raise FileExistsError(f"output already exists: {target}")
rows: list[str] = []
for k, (start, speed) in enumerate(zip(self.starts, self.speeds, strict=True)):
velocity = float(speed) * self.direction
values = " ".join(f"{number(v)} {number(v)}" for v in velocity)
times = (float(start), float(start) + self.hold) if k else (0.0, self.hold)
rows.extend(f"{number(t)} {values}" for t in times)
Comment thread
SMI-Lab-Inha marked this conversation as resolved.
Resolved
# the guard: the last speed held two ramps past TMax (see above)
rows.append(f"{number(self.duration + 2.0 * self.ramp)} {values}")
lines = [
"--------------------- MoorDyn dynamic currents File -------------------------",
"a uniform current held at a sequence of speeds (cabledyn.current_steps)",
"line 5 lists the depths (m); each later row is t ux(z1 z2) uy(z1 z2) uz(z1 z2)",
"------------------------------------------------------------------------------",
f"{number(low)} {number(high)}",
"time ux... uy... uz...",
*rows,
]
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text("\n".join(lines) + "\n", encoding="ascii")
return target

def responses(
self,
history: TimeHistory,
*,
diameter: float,
settle: float,
line_id: int | None = None,
) -> tuple[VIVResponse, ...]:
"""Return the :func:`viv_response` of every hold, from ``settle`` seconds into it."""
return tuple(
viv_response(
history,
flow=float(speed) * self.direction,
diameter=diameter,
start=start,
stop=stop,
line_id=line_id,
)
for speed, (start, stop) in zip(self.speeds, self.windows(settle), strict=True)
)


def current_steps(
speeds: npt.ArrayLike,
*,
hold: float,
ramp: float,
direction: npt.ArrayLike = (0.0, 1.0, 0.0),
) -> CurrentSteps:
"""Return a stepped current schedule.

Parameters
----------
speeds : array_like
Positive current speeds, m/s, in the order they are held; an
up-and-down sweep lists them up and back.
hold : float
Hold time of each speed, s; a whole number of ramps.
ramp : float
Positive ramp time between speeds, s.
direction : array_like
``(3,)`` direction of the current (normalised), default ``+y``.

Raises
------
ValueError
If a speed is not finite and positive, the times are invalid, the hold
is not a whole number of ramps, or the direction is not a finite,
non-zero 3-vector.
"""
values = np.array(speeds, dtype=np.float64).reshape(-1)
if values.size < 1 or not np.all(np.isfinite(values)) or np.any(values <= 0.0):
raise ValueError("speeds must be one or more finite, positive values")
hold_s, ramp_s = float(hold), float(ramp)
if not (math.isfinite(hold_s) and hold_s > 0.0 and math.isfinite(ramp_s) and ramp_s > 0.0):
raise ValueError("hold and ramp must be finite and positive")
ratio = hold_s / ramp_s
if abs(ratio - round(ratio)) > 1.0e-9 * ratio:
raise ValueError("hold must be a whole number of ramps (the file's resampling step)")
unit = np.array(direction, dtype=np.float64)
if unit.shape != (3,) or not np.all(np.isfinite(unit)) or not np.any(unit):
raise ValueError("direction must be a finite, non-zero 3-vector")
return CurrentSteps(
speeds=_readonly(values),
hold=hold_s,
ramp=ramp_s,
direction=_readonly(unit / np.linalg.norm(unit)),
)
27 changes: 27 additions & 0 deletions python/tests/test_end_to_end.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
DriverExecutionError,
StaticProfile,
compare_histories,
current_steps,
fft_filter,
generate_deck_cases,
line_geometry,
Expand Down Expand Up @@ -305,3 +306,29 @@ def test_viv_response_of_the_inline_example(driver, tmp_path):
assert response.modal_amplitudes("cross_flow").dominant_mode == 1
assert response.modal_amplitudes("in_line").dominant_mode == 2
assert response.travelling_wave_index("cross_flow") < 0.2


def test_stepped_current_continues_the_response(driver, tmp_path):
# the in-line VIV example under a current stepped 0.10 -> 0.18 -> 0.10 m/s in one run
steps = current_steps([0.10, 0.18, 0.10], hold=60.0, ramp=5.0)
text = (EXAMPLES / "viv_taut_cable_inline.dat").read_text(encoding="utf-8")
text = text.replace("1 1 2 V", "1 1 2 p")
lines = []
for line in text.splitlines():
if line.startswith("uniform 0.0 0.15 0.0 current"):
line = "2 Currents"
elif line.startswith("90.0 TMax"):
line = f"{steps.duration} TMax"
lines.append(line)
deck = tmp_path / "stepped.dat"
deck.write_text("\n".join(lines) + "\n", encoding="utf-8")
steps.write(tmp_path)
result = driver.run(deck, "out/stepped", timeout=600)
first, middle, last = steps.responses(result.read_line_positions(1), diameter=0.1, settle=30.0)
# the lock-in frequency follows the current up and comes back with it
assert middle.frequency("cross_flow") > first.frequency("cross_flow") + 0.03
assert last.frequency("cross_flow") == pytest.approx(first.frequency("cross_flow"), abs=0.01)
assert (
middle.amplitude_over_diameter("cross_flow").max()
> first.amplitude_over_diameter("cross_flow").max()
)
79 changes: 78 additions & 1 deletion python/tests/test_viv.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
import numpy as np
import pytest

from cabledyn import LineNodeHistory, VIVResponse, viv_response
from cabledyn import LineNodeHistory, VIVResponse, current_steps, viv_response
from cabledyn.results import TimeHistory

L = 100.0
Expand Down Expand Up @@ -272,3 +272,80 @@ def test_methods_validate_direction_and_node():
response.modal_amplitudes(n_modes=0)
with pytest.raises(ValueError, match="shapes must have shape"):
response.modal_amplitudes(shapes=np.ones((2, 3)))


def test_current_steps_schedule_and_file(tmp_path):
steps = current_steps([0.1, 0.2, 0.1], hold=20.0, ramp=5.0, direction=(0.0, 2.0, 0.0))
np.testing.assert_allclose(steps.starts, [0.0, 25.0, 50.0])
assert steps.duration == pytest.approx(70.0)
np.testing.assert_allclose(steps.direction, [0.0, 1.0, 0.0])
assert steps.windows(15.0) == ((15.0, 20.0), (40.0, 45.0), (65.0, 70.0))
path = steps.write(tmp_path, depths=(-100.0, 0.0))
assert path.name == "current_profile_dynamic.txt"
lines = path.read_text(encoding="ascii").splitlines()
assert lines[4].split() == ["-100", "0"]
rows = np.array([[float(v) for v in line.split()] for line in lines[6:]])
# t ux(z1 z2) uy(z1 z2) uz(z1 z2): held, ramped over 5 s, held, and the last speed two
# ramps past TMax
np.testing.assert_allclose(rows[:, 0], [0.0, 20.0, 25.0, 45.0, 50.0, 70.0, 80.0])
np.testing.assert_allclose(rows[:, 3], [0.1, 0.1, 0.2, 0.2, 0.1, 0.1, 0.1])
assert np.all(rows[:, [1, 2, 5, 6]] == 0.0) and np.all(rows[:, 3] == rows[:, 4])
with pytest.raises(FileExistsError):
steps.write(tmp_path)
with pytest.raises(ValueError, match="settle"):
steps.windows(20.0)


@pytest.mark.parametrize(
("kwargs", "message"),
[
({"speeds": []}, "speeds must be"),
({"speeds": [0.1, 0.0]}, "speeds must be"),
({"ramp": 0.0}, "hold and ramp"),
({"hold": 22.0}, "whole number of ramps"),
({"direction": (0.0, 0.0, 0.0)}, "direction must be"),
],
)
def test_current_steps_validation(kwargs, message):
arguments = {"speeds": [0.1, 0.2], "hold": 20.0, "ramp": 5.0, **kwargs}
with pytest.raises(ValueError, match=message):
current_steps(**arguments)


def _resampled_speed(times, speeds, t):
# the native rule (CD_Current_Grid_Resample, CD_Current_Grid_Velocity): dt the smallest
# interval, floor(t_last/dt) + 1 samples at k dt, the upper index modulo the sample count
# and both indices the first sample over the last interval
dt = np.diff(times).min()
samples = np.interp(np.arange(int(np.floor(times[-1] / dt)) + 1) * dt, times, speeds)
q = t / dt
n = np.floor(q).astype(int)
upper = (n + 1) % samples.size
lower = np.maximum(upper - 1, 0)
return samples[lower] * (1.0 - (q - n)) + samples[upper] * (q - n)


@pytest.mark.parametrize(
("speeds", "hold", "ramp"),
[([0.5, 1.0], 0.3, 0.1), ([0.1, 0.2, 0.3], 20.0, 5.0), ([0.4], 1.2, 0.4)],
)
def test_current_steps_file_holds_the_last_speed_to_tmax(tmp_path, speeds, hold, ramp):
steps = current_steps(speeds, hold=hold, ramp=ramp)
lines = steps.write(tmp_path).read_text(encoding="ascii").splitlines()
rows = np.array([[float(v) for v in line.split()] for line in lines[6:]])
t = np.linspace(steps.windows(0.0)[-1][0], steps.duration, 401)
np.testing.assert_allclose(_resampled_speed(rows[:, 0], rows[:, 3], t), speeds[-1])
if speeds[0] != speeds[-1]:
# without the guard row the table would return to the first speed within the last hold
old = _resampled_speed(rows[:-1, 0], rows[:-1, 3], t)
assert old[-1] == pytest.approx(speeds[0])


def test_current_steps_responses_take_each_hold():
steps = current_steps([0.5, 0.25], hold=15.0, ramp=5.0)
responses = steps.responses(_history(_standing), diameter=D, settle=5.0)
assert len(responses) == 2
assert responses[1].time[0] == pytest.approx(25.0)
assert np.allclose(responses[0].normal_speed, 0.5) and np.allclose(
responses[1].normal_speed, 0.25
)
Loading