From c42fd8ff04b127d746bc0262e63043ab5fbf2fc2 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Wed, 11 Nov 2026 18:56:09 +0900 Subject: [PATCH] feat: section-point stress and fatigue of biaxial bending The stress recovery for fatigue took the curvature magnitude at the two extreme fibres, T/A +/- E kappa r, so it did not follow the bending plane. Under combined cross-flow and in-line VIV the plane turns, and a whirling section, whose curvature magnitude stays constant, showed no cycles and no damage, although every point around it reverses once a revolution. section_stress takes the curvature vector on the section axes, the CurvX/CurvY channels of a finite-EI line (bending strain -(kx x + ky y)), and returns the stress at points around the section, sigma(theta) = T/A - E r (kappa_x cos theta + kappa_y sin theta). damage_along_arc(..., quantity="section", points=16) counts each point, keeps the largest damage and reports its angle (critical_angle on DamageProfile, None for the other quantities). The node-channel reader now knows the CurvX and CurvY prefixes. Checks: the stress of a known curvature vector point by point; in a fixed bending plane the extreme points are cable_stress's two fibres; a whirling section has no damage under "stress" and its point-by-point damage under "section"; missing or mismatched channels and a T-N curve are refused. pytest, ruff, mypy strict, Sphinx -W. Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 5 ++ doc/api_python.rst | 2 + doc/python_postprocessing.rst | 18 +++++ python/cabledyn/__init__.py | 2 + python/cabledyn/damage.py | 132 ++++++++++++++++++++++++++++++++-- python/cabledyn/ranges.py | 4 +- python/tests/test_damage.py | 80 +++++++++++++++++++++ 7 files changed, 236 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 51d7bb9e..4b854b84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,11 @@ All notable changes to CableDyn are recorded in this file. The format follows frequencies and `f D/U_n`, modal weights (taut-line sines or given shapes), the complex shape and its travelling-wave index (Feeny 2008), orbits and the in-line/cross-flow phase difference, with a CSV export and plots. +- `cabledyn.section_stress` and `damage_along_arc(..., quantity="section")`: the axial stress at + points around the section from the tension and the curvature vector on the section axes + (`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. ## [0.4.2] - 2026-11-09 diff --git a/doc/api_python.rst b/doc/api_python.rst index 4ea33930..19b11387 100644 --- a/doc/api_python.rst +++ b/doc/api_python.rst @@ -204,6 +204,8 @@ in each docstring and in :attr:`FatigueCurve.source`. :func:`channel_damage` and .. autofunction:: cabledyn.cable_stress +.. autofunction:: cabledyn.section_stress + .. autofunction:: cabledyn.damage_along_arc .. autoclass:: cabledyn.DamageProfile diff --git a/doc/python_postprocessing.rst b/doc/python_postprocessing.rst index 4548a784..e2358f8d 100644 --- a/doc/python_postprocessing.rst +++ b/doc/python_postprocessing.rst @@ -289,6 +289,24 @@ not follow the rotation of the bending plane. print(profile.critical_node, profile.maximum_damage) profile.plot() +On a finite-EI line, ``quantity="section"`` follows the bending plane. It recovers the stress at +``points`` points around the section (16 by default) with :func:`cabledyn.section_stress`, from +``TenN`` and the curvature vector on the section axes, ``CurvXN`` and +``CurvYN`` (:doc:`outputs`): ``T/A - E r (kappa_x cos theta + kappa_y sin theta)`` at the +angle ``theta`` from the section's x axis. It counts each point and keeps the largest damage, with +its angle in ``critical_angle``. This is the recovery for biaxial bending, combined cross-flow and +in-line VIV among them: a section whose curvature vector turns at a constant magnitude (a +whirling orbit) has no cycles in ``Curv`` and so no damage under ``"stress"``, while each point +around it passes through ``+/- E kappa r`` once a revolution. + +.. code-block:: python + + profile = damage_along_arc( + history, 1, armour, quantity="section", points=16, + area=2.4e-3, modulus=2.07e11, radius=0.09, arc_length=result.read_static(), + ) + print(profile.critical_node, profile.critical_angle[profile.node_ids.index(profile.critical_node)]) + Lifetime damage over sea states ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/python/cabledyn/__init__.py b/python/cabledyn/__init__.py index d238085d..d23b3cfb 100644 --- a/python/cabledyn/__init__.py +++ b/python/cabledyn/__init__.py @@ -54,6 +54,7 @@ damage_along_arc, lifetime_fatigue, miner_damage, + section_stress, study_sea_state_damage, ) from cabledyn.deck import DeckWriter @@ -281,6 +282,7 @@ "resample", "run_study", "seabed_clearance", + "section_stress", "segment_distance", "static_range_graph", "study_sea_state_damage", diff --git a/python/cabledyn/damage.py b/python/cabledyn/damage.py index 918e0f5f..e79e52f8 100644 --- a/python/cabledyn/damage.py +++ b/python/cabledyn/damage.py @@ -7,6 +7,10 @@ * :func:`channel_damage` does the same for one channel of a time history. * :func:`cable_stress` recovers the axial stress at the two extreme fibres of a cable, ``sigma = T/A +/- E kappa r``. +* :func:`section_stress` recovers it at points around the section from the + curvature vector on the section axes (the ``CurvX``/``CurvY`` channels), + ``sigma = T/A - E r (kappa_x cos theta + kappa_y sin theta)``, for biaxial + bending such as combined cross-flow and in-line VIV. * :func:`damage_along_arc` evaluates the damage at every output node of a line, from tension or from recovered stress. * :func:`study_sea_state_damage` and :func:`lifetime_fatigue` weight the @@ -50,6 +54,7 @@ "damage_along_arc", "lifetime_fatigue", "miner_damage", + "section_stress", "study_sea_state_damage", ] @@ -288,6 +293,78 @@ def cable_stress( return _readonly(axial + bending), _readonly(axial - bending) +def section_stress( + tension: npt.ArrayLike, + curvature_x: npt.ArrayLike, + curvature_y: npt.ArrayLike, + *, + area: float, + modulus: float, + radius: float, + points: int = 16, +) -> tuple[npt.NDArray[Any], npt.NDArray[Any]]: + """Return the axial stress at points around a section from its curvature vector. + + The point at angle ``theta`` from the section's x axis towards its y + axis, at distance ``radius`` from the neutral axis, has the bending strain + ``-(kappa_x x + kappa_y y)`` of the ``CurvX``/``CurvY`` channels (the + curvature vector on the section axes, pointing to the centre of + curvature), so + + ``sigma(theta) = T/A - E r (kappa_x cos theta + kappa_y sin theta)``. + + Unlike :func:`cable_stress` it follows the bending plane as it turns, so a + point sees the stress cycles of biaxial bending (cross-flow and in-line + VIV, a whirling orbit) that the two extreme fibres of a curvature + magnitude miss. + + Parameters + ---------- + tension : array_like + Effective tension, in newtons. + curvature_x, curvature_y : array_like + Curvature components on the section axes, in 1/m, broadcastable + against ``tension``. + area : float + Positive area that carries the tension, in m^2. + modulus : float + Positive Young's modulus of the component, in Pa. + radius : float + Non-negative distance of the points from the neutral axis, in metres. + points : int + Number of points, at ``theta = 360 k / points`` degrees. + + Returns + ------- + tuple[numpy.ndarray, numpy.ndarray] + Read-only stress with a last axis of length ``points``, in Pa, and the + ``(points,)`` angles in degrees. + + Raises + ------ + ValueError + If a section property or ``points`` is invalid or a value is not finite. + """ + section = _positive(area, "area") + elastic = _positive(modulus, "modulus") + if isinstance(radius, bool) or not math.isfinite(float(radius)) or float(radius) < 0.0: + raise ValueError("radius must be finite and non-negative") + if isinstance(points, bool) or int(points) != points or points < 1: + raise ValueError("points must be a positive integer") + axial, kx, ky = np.broadcast_arrays( + np.asarray(tension, dtype=np.float64) / section, + np.asarray(curvature_x, dtype=np.float64), + np.asarray(curvature_y, dtype=np.float64), + ) + if not (np.all(np.isfinite(axial)) and np.all(np.isfinite(kx)) and np.all(np.isfinite(ky))): + raise ValueError("tension and curvature must be finite") + angles = 2.0 * np.pi * np.arange(int(points)) / int(points) + bending = ( + elastic * float(radius) * (kx[..., None] * np.cos(angles) + ky[..., None] * np.sin(angles)) + ) + return _readonly(axial[..., None] - bending), _readonly(np.degrees(angles)) + + @dataclass(frozen=True) class DamageProfile: """Palmgren-Miner damage at every output node of one line. @@ -297,7 +374,7 @@ class DamageProfile: line_id : int Deck line identifier. quantity : str - ``"tension"`` or ``"stress"``. + ``"tension"``, ``"stress"`` or ``"section"``. curve : FatigueCurve Curve used. node_ids : tuple[int, ...] @@ -308,11 +385,15 @@ class DamageProfile: ``(n,)`` arc length in metres, or node number. damage : numpy.ndarray ``(n,)`` damage over the record; for ``"stress"`` the larger of the - two fibres. + two fibres, for ``"section"`` the largest of the points around the + section. duration : float Length of the analysed record, in seconds. source : pathlib.Path Result file. + critical_angle : numpy.ndarray | None + ``(n,)`` angle of the most damaged point from the section's x axis, in + degrees, for ``"section"``; ``None`` otherwise. """ line_id: int @@ -324,10 +405,13 @@ class DamageProfile: damage: npt.NDArray[Any] duration: float source: Path + critical_angle: npt.NDArray[Any] | None = None def __post_init__(self) -> None: object.__setattr__(self, "location", _readonly(self.location)) object.__setattr__(self, "damage", _readonly(self.damage)) + if self.critical_angle is not None: + object.__setattr__(self, "critical_angle", _readonly(self.critical_angle)) @property def critical_node(self) -> int: @@ -376,6 +460,7 @@ def damage_along_arc( arc_length: ArcSource = None, start: float | None = None, stop: float | None = None, + points: int = 16, ) -> DamageProfile: """Return the Miner damage at every output node of a line. @@ -389,6 +474,14 @@ def damage_along_arc( S-N); each fibre is counted separately and the larger damage is kept. Both channels must be written for the same nodes. + With ``quantity="section"`` the stress at ``points`` points around the + section is recovered from ``TenN``, ``CurvXN`` and + ``CurvYN`` by :func:`section_stress` (finite-EI lines; the same + section properties as ``"stress"``); each point is counted separately and + the largest damage is kept, with its angle in + :attr:`DamageProfile.critical_angle`. All three channels must be written + for the same nodes. + Parameters ---------- history : TimeHistory @@ -398,7 +491,7 @@ def damage_along_arc( curve : FatigueCurve S-N or T-N curve. quantity : str - ``"tension"`` or ``"stress"``. + ``"tension"``, ``"stress"`` or ``"section"``. area, breaking_strength, modulus, radius : float | None Section properties, in SI units, as described above. ultimate_strength : float | None @@ -407,6 +500,8 @@ def damage_along_arc( Node positions along the line (see :func:`cabledyn.node_range_graph`). start, stop : float | None Optional analysis window, in seconds. + points : int + Number of points around the section for ``"section"``. Returns ------- @@ -421,6 +516,7 @@ def damage_along_arc( If ``quantity`` is unknown, a section property is missing or invalid, or the tension and curvature channels cover different nodes. """ + angles: npt.NDArray[Any] | None = None view = _window(history, start, stop) tensions = node_channels(view, line_id, "Ten") data = node_matrix(view, tensions) @@ -440,10 +536,31 @@ def damage_along_arc( ) scale = 1.0e-6 histories = [outer, inner] + elif quantity == "section": + if curve.kind != "S-N": + raise ValueError("section-stress damage needs an S-N curve") + if area is None or modulus is None or radius is None or breaking_strength is not None: + raise ValueError("section-stress damage needs area, modulus, and radius only") + curvatures_x = node_channels(view, line_id, "CurvX") + curvatures_y = node_channels(view, line_id, "CurvY") + if tuple(curvatures_x) != tuple(tensions) or tuple(curvatures_y) != tuple(tensions): + raise ValueError("Ten, CurvX and CurvY channels must be written for the same nodes") + stresses, angles = section_stress( + data, + node_matrix(view, curvatures_x), + node_matrix(view, curvatures_y), + area=area, + modulus=modulus, + radius=radius, + points=points, + ) + scale = 1.0e-6 + histories = [stresses[:, :, k] for k in range(stresses.shape[2])] else: - raise ValueError("quantity must be 'tension' or 'stress'") + raise ValueError("quantity must be 'tension', 'stress' or 'section'") damage = np.zeros(data.shape[1]) - for series in histories: + worst = np.zeros(data.shape[1], dtype=np.int64) + for k, series in enumerate(histories): for index in range(data.shape[1]): value = miner_damage( rainflow_cycles(series[:, index]), @@ -451,7 +568,9 @@ def damage_along_arc( scale=scale, ultimate_strength=ultimate_strength, ) - damage[index] = max(damage[index], value) + if value > damage[index]: + damage[index] = value + worst[index] = k node_ids = tuple(tensions) kind, location = node_locations(int(line_id), node_ids, arc_length) return DamageProfile( @@ -464,6 +583,7 @@ def damage_along_arc( damage=damage, duration=float(view.time[-1] - view.time[0]), source=view.path, + critical_angle=None if angles is None else angles[worst], ) diff --git a/python/cabledyn/ranges.py b/python/cabledyn/ranges.py index be641e19..13dde176 100644 --- a/python/cabledyn/ranges.py +++ b/python/cabledyn/ranges.py @@ -57,7 +57,9 @@ "curvature": ("Curv", "Curvature", "1/m"), "bend_moment": ("BendMom", "BendMoment", "N-m"), } -_NODE_QUANTITY = re.compile(r"(Ten|Curv|BendMom)0*([1-9][0-9]{0,8})N0*([1-9][0-9]{0,8})", re.I) +_NODE_QUANTITY = re.compile( + r"(Ten|CurvX|CurvY|Curv|BendMom)0*([1-9][0-9]{0,8})N0*([1-9][0-9]{0,8})", re.I +) _NODE_POSITION = re.compile(r"L0*([1-9][0-9]{0,8})N0*([1-9][0-9]{0,8})p([xyz])", re.I) ArcSource = StaticProfile | Mapping[int, float] | None diff --git a/python/tests/test_damage.py b/python/tests/test_damage.py index 10c6978d..dccccb48 100644 --- a/python/tests/test_damage.py +++ b/python/tests/test_damage.py @@ -25,6 +25,7 @@ lifetime_fatigue, miner_damage, read_output, + section_stress, study_sea_state_damage, ) from cabledyn.damage import SECONDS_PER_YEAR @@ -323,3 +324,82 @@ def test_study_sea_state_damage_needs_a_time_history(tmp_path): study = _study(tmp_path, [_case(tmp_path, "s", static)]) with pytest.raises(StudyOutputError, match="not a time history"): study_sea_state_damage(study, {"s": 1.0}, lambda history: 0.0) + + +def test_section_stress_follows_the_curvature_vector(): + stress, angles = section_stress( + 1.0e5, 0.01, 0.0, area=0.01, modulus=2.0e11, radius=0.05, points=4 + ) + np.testing.assert_allclose(angles, [0.0, 90.0, 180.0, 270.0]) + # the strain at (x, y) is -(kx x + ky y): compression towards the centre of curvature (+x) + np.testing.assert_allclose(stress, [1.0e7 - 1.0e8, 1.0e7, 1.0e7 + 1.0e8, 1.0e7], atol=1.0) + assert not stress.flags.writeable + # in a fixed bending plane the extreme points are the two fibres of cable_stress + kx, ky = 0.006, -0.008 + many, _ = section_stress( + [2.0e5], [kx], [ky], area=0.01, modulus=2.0e11, radius=0.05, points=360 + ) + outer, inner = cable_stress(2.0e5, math.hypot(kx, ky), area=0.01, modulus=2.0e11, radius=0.05) + assert many.max() == pytest.approx(float(outer), rel=1.0e-4) + assert many.min() == pytest.approx(float(inner), rel=1.0e-4) + with pytest.raises(ValueError, match="points"): + section_stress(1.0, 0.0, 0.0, area=1.0, modulus=1.0, radius=1.0, points=0) + with pytest.raises(ValueError, match="points"): + section_stress(1.0, 0.0, 0.0, area=1.0, modulus=1.0, radius=1.0, points=True) # type: ignore[arg-type] + with pytest.raises(ValueError, match="finite"): + section_stress(1.0, math.nan, 0.0, area=1.0, modulus=1.0, radius=1.0) + + +def _whirl_columns(kappa: float = 0.01) -> dict[str, np.ndarray]: + """A section whose curvature vector turns at a constant magnitude (0.5 Hz).""" + omega = 2.0 * math.pi * 0.5 + columns: dict[str, np.ndarray] = {} + for node in (1, 3, 5): + columns[f"Ten1N{node}"] = np.full(TIME.shape, 1.0e6) + columns[f"Curv1N{node}"] = np.full(TIME.shape, kappa) + columns[f"CurvX1N{node}"] = kappa * np.cos(omega * TIME + 0.3 * node) + columns[f"CurvY1N{node}"] = kappa * np.sin(omega * TIME + 0.3 * node) + return columns + + +def test_section_damage_sees_a_whirl_the_two_fibres_miss(tmp_path): + history = read_output(write_main(tmp_path / "whirl.out", _whirl_columns())) + curve = dnv_rp_c203_curve("D") + section = {"area": 0.01, "modulus": 2.0e11, "radius": 0.05} + fibres = damage_along_arc(history, 1, curve, quantity="stress", **section) + assert np.all(fibres.damage == 0.0) and fibres.critical_angle is None + profile = damage_along_arc(history, 1, curve, quantity="section", points=8, **section) + assert profile.quantity == "section" + assert np.all(profile.damage > 0.0) + columns = _whirl_columns() + stress, angles = section_stress( + columns["Ten1N3"], columns["CurvX1N3"], columns["CurvY1N3"], points=8, **section + ) + damages = [ + channel_damage(_table(tmp_path, stress[:, k]), "S", curve, scale=1.0e-6).damage + for k in range(8) + ] + assert profile.damage[1] == _close(max(damages)) + assert profile.critical_angle is not None + # the critical angle is a point of the largest damage (opposite points of a whirl tie) + chosen = int(np.flatnonzero(angles == profile.critical_angle[1])[0]) + assert damages[chosen] == _close(max(damages)) + + +def test_section_damage_errors(tmp_path): + history = read_output(write_main(tmp_path / "whirl.out", _whirl_columns())) + curve = dnv_rp_c203_curve("D") + tn = FatigueCurve("tn", "T-N", 3.0, 3.0) + section = {"area": 0.01, "modulus": 2.0e11, "radius": 0.05} + with pytest.raises(ValueError, match="S-N curve"): + damage_along_arc(history, 1, tn, quantity="section", **section) + with pytest.raises(ValueError, match="area, modulus, and radius"): + damage_along_arc(history, 1, curve, quantity="section", area=1.0) + columns = _whirl_columns() + del columns["CurvY1N5"] + sparse = read_output(write_main(tmp_path / "sparse.out", columns)) + with pytest.raises(ValueError, match="same nodes"): + damage_along_arc(sparse, 1, curve, quantity="section", **section) + plain = read_output(write_main(tmp_path / "plain.out")) + with pytest.raises(KeyError, match="CurvX1N"): + damage_along_arc(plain, 1, curve, quantity="section", **section)