From b3a05c1405b09f061a17c7b854dc0c0897928424 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Mon, 9 Nov 2026 00:55:45 +0900 Subject: [PATCH 1/2] fix(statics): note a Point3 buoy that starts off balance The static solve does not place a Point3 buoy: it starts at its deck position (theory.rst). Under the default bodyIC static every other free object starts balanced, so a buoy given off its balance started there without a word: a 112 t, 259 m^3 buoy on one slack leg started with 1.5 MN of net buoyancy unbalanced and surfaced within 2 s. Under bodyIC static the point initial condition now evaluates the buoy as a Free point (the core static solve with the Free/Connect points held where it put them) and, when the net force on it at its deck position exceeds 1e-4 of its net weight plus 1 N, notes that force and the distance to its static balance, with the remedies (its balanced deck position, or bodyIC deck). The solve and the march are unchanged; bodyIC deck prints nothing. The core solve returns the starting net force of each moving point for it (point_force_start). The new point3_balance_note test runs the buoy under bodyIC static (the noted force must equal the line force on it plus its net buoyancy to 1e-3) and under bodyIC deck (no note). Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 5 ++ CMakeLists.txt | 10 +++ doc/driver_format.md | 5 +- doc/theory.rst | 4 +- src/CableDyn_DeckDriver.f90 | 82 ++++++++++++++++++++++- tests/test_point3_balance_note.py | 107 ++++++++++++++++++++++++++++++ 6 files changed, 209 insertions(+), 4 deletions(-) create mode 100644 tests/test_point3_balance_note.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e3549554..4967ede7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,11 @@ All notable changes to CableDyn are recorded in this file. The format follows The touchdown element now takes the reaction of its grounded stretch, from the grounded node to the touchdown point located from the two nodes' clearances: the error falls at the second order (2.1, 0.7, 0.2 N) and the outputs vary continuously. +- `Point3` buoys under the default `bodyIC static`: the static solve does not place a `Point3` + buoy, so it started at its deck position off balance without a word while every other free + object started balanced (a 112 t, 259 m^3 buoy started with 1.5 MN unbalanced and surfaced in + 2 s). The run now notes the unbalanced force and the distance to the buoy's static balance as + a `Free` point. ## [0.4.1] - 2026-11-08 diff --git a/CMakeLists.txt b/CMakeLists.txt index dc729c4f..a1baaaf1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1838,6 +1838,16 @@ if(Python3_Interpreter_FOUND) TIMEOUT 300 ENVIRONMENT "${_cabledyn_python_test_environment}") + # A Point3 buoy that starts off balance under bodyIC static is noted with its unbalanced force. + add_test(NAME point3_balance_note + COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_point3_balance_note.py + --exe $ + --output ${CMAKE_BINARY_DIR}/point3_balance_note) + set_tests_properties(point3_balance_note PROPERTIES + LABELS "python;bodies;static" + TIMEOUT 300 + ENVIRONMENT "${_cabledyn_python_test_environment}") + # The note on grounded lines that a current moves over a seabed without friction: once per run # on every standalone route, and never without a grounded node, a current, or a march, or # with friction. diff --git a/doc/driver_format.md b/doc/driver_format.md index eb2d0104..fb85fcce 100644 --- a/doc/driver_format.md +++ b/doc/driver_format.md @@ -527,7 +527,10 @@ A line's End A attaches to a body through a `Body` point; the point's positi fairlead offset in the body frame. - A `Point3` body supports exactly one attachment point, which becomes a dynamic point with the - body's `Mass`/`Vol`/`CdA`/`Ca`. + body's `Mass`/`Vol`/`CdA`/`Ca`. The static solve does not place it: it starts at its deck + position. Under `bodyIC static` (the default) a run whose buoy is not balanced there notes the + unbalanced force and the distance to its static balance as a `Free` point; give the deck + position of that balance, or set `bodyIC deck` to start it off balance on purpose. - A `Rigid6` body transfers structural force and moment through rigid attachment kinematics, plus lumped translational current and wave hydrodynamics from `CdA`/`Ca`. Rotational body hydrodynamics are not modelled. diff --git a/doc/theory.rst b/doc/theory.rst index 0e1e8f15..8d0d4a43 100644 --- a/doc/theory.rst +++ b/doc/theory.rst @@ -1591,7 +1591,9 @@ hang it from the seabed. The contact acts along the surface normal of a sloped o bathymetry, in the point static equilibrium and in the monolithic and staggered point steps alike (in the staggered step its stiffness and damping are linearly implicit, like the end blocks of the attached lines), so a grounded point starts at rest. A ``Point3`` buoy is not -placed by the static solve (it starts at its deck position) but carries the same contact in +placed by the static solve (it starts at its deck position; under ``bodyIC static`` the run notes +the force its line, weight, buoyancy, drag and contact leave on it there and the distance to its +balance as a ``Free`` point) but carries the same contact in every march, the monolithic and staggered steps and the coupled point step of the OpenFAST aggregate and the C API. The contact is frictionless: the point routes reject ``frictionMu``. A point clear of the seabed sees exactly no contact load, and its results are unchanged. diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index 4a765731..ff7839f7 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -12177,7 +12177,10 @@ SUBROUTINE solve_point_equilibrium(types, points, lines, sections, opts, ErrStat DO i = 1, SIZE(points) IF (point_moves(i)) np = np + 1 END DO - IF (np == 0) RETURN + IF (np == 0) THEN + CALL point3_balance_note() + RETURN + END IF ALLOCATE (pidx(np)) np = 0 DO i = 1, SIZE(points) @@ -12205,9 +12208,74 @@ SUBROUTINE solve_point_equilibrium(types, points, lines, sections, opts, ErrStat END DO CALL solve_body_equilibrium(types, no_bodies, no_rod_types, no_rods, points, lines, sections, opts, ErrStat, & ErrMsg, bathymetry, points_only=.TRUE.) + IF (ErrStat == CD_DECKDRV_OK) CALL point3_balance_note() CONTAINS + SUBROUTINE point3_balance_note() + !! A Point3 buoy is not placed by the static solve: it starts at its deck position. Under + !! bodyIC static, where every other free object starts balanced, note the force its line, + !! weight, buoyancy, current drag and seabed contact leave on it there, and how far its + !! static equilibrium (the balance of the buoy as a Free point, with the Free/Connect + !! points held where the static solve put them) lies from it. + TYPE(DeckPoint), ALLOCATABLE :: pc(:) + REAL(wp), ALLOCATABLE :: f0(:) + REAL(wp) :: w_net + INTEGER :: ip, es_n + LOGICAL :: any3, skp + CHARACTER(1024) :: em_n + CHARACTER(32) :: fbuf, dbuf + IF (.NOT. opts%body_ic_static) RETURN + any3 = .FALSE. + DO ip = 1, SIZE(points) + IF (points(ip)%point3 .AND. point_has_line(ip)) any3 = .TRUE. + END DO + IF (.NOT. any3) RETURN + pc = points + DO ip = 1, SIZE(pc) + IF (pc(ip)%point3 .AND. point_has_line(ip)) THEN + pc(ip)%ptype = 'free' + ELSE IF (TRIM(pc(ip)%ptype) == 'free' .OR. TRIM(pc(ip)%ptype) == 'connect') THEN + pc(ip)%ptype = 'fixed' + END IF + END DO + ALLOCATE (f0(SIZE(pc))) + f0 = CD_ZERO + skp = .FALSE. + CALL solve_body_equilibrium_core(types, no_bodies, no_rod_types, no_rods, pc, lines, sections, opts, es_n, & + em_n, bathymetry, points_only=.TRUE., quiet=.TRUE., skipped=skp, & + point_force_start=f0) + IF (skp) RETURN + DO ip = 1, SIZE(points) + IF (.NOT. (points(ip)%point3 .AND. point_has_line(ip))) CYCLE + w_net = ABS(opts%rhoW*points(ip)%vol - points(ip)%mass)*opts%g + IF (.NOT. (f0(ip) > 1.0e-4_wp*w_net + CD_ONE)) CYCLE + WRITE (fbuf, '(ES10.3)') f0(ip) + IF (es_n == CD_DECKDRV_OK) THEN + WRITE (dbuf, '(ES10.3)') NORM2(pc(ip)%pos - points(ip)%pos) + CALL print_note(output_unit, ' ', 'BODY '//TRIM(int_to_str(points(ip)%body_id))//' (Point3) starts '// & + 'at its deck position, which the static solve does not change, with an unbalanced '// & + 'force of '//TRIM(ADJUSTL(fbuf))//' N there; its static equilibrium lies '// & + TRIM(ADJUSTL(dbuf))//' m away. Give the deck position of its equilibrium, or set '// & + 'OPTION bodyIC deck to start it from its deck position on purpose') + ELSE + CALL print_note(output_unit, ' ', 'BODY '//TRIM(int_to_str(points(ip)%body_id))//' (Point3) starts '// & + 'at its deck position, which the static solve does not change, with an unbalanced '// & + 'force of '//TRIM(ADJUSTL(fbuf))//' N there. Give the deck position of its '// & + 'equilibrium, or set OPTION bodyIC deck to start it from its deck position on purpose') + END IF + END DO + END SUBROUTINE point3_balance_note + + LOGICAL FUNCTION point_has_line(ip) RESULT(has) + INTEGER, INTENT(IN) :: ip + INTEGER :: jl + has = .FALSE. + DO jl = 1, SIZE(lines) + IF (lines(jl)%nodeA == points(ip)%id .OR. lines(jl)%nodeB == points(ip)%id) has = .TRUE. + END DO + END FUNCTION point_has_line + LOGICAL FUNCTION point_moves(ip) RESULT(mv) INTEGER, INTENT(IN) :: ip INTEGER :: jl @@ -27044,7 +27112,8 @@ END SUBROUTINE rigid6_rod_loads SUBROUTINE solve_body_equilibrium_core(types, bodies, rod_types, rods, points, lines, sections, opts, ErrStat, & ErrMsg, bathymetry, points_only, jac_check_err, ext_pt, ext_fm, & - end_force_a, quiet, skipped, ext_km, ext_rot, end_force_b, res_left) + end_force_a, quiet, skipped, ext_km, ext_rot, end_force_b, res_left, & + point_force_start) !! Static equilibrium of the free objects of a deck: free Rigid6 bodies (six DOFs: position !! and a rotation-vector increment on SO(3); a CoupledPinned body holds its position at its !! host node and balances its moment about it), free rods (position and the two rotations @@ -27131,6 +27200,9 @@ SUBROUTINE solve_body_equilibrium_core(types, bodies, rod_types, rods, points, l ! [N m] of an object at the returned poses (zero when nothing was balanced): the resolution of ! the balance, which the passes of solve_body_equilibrium cannot refine REAL(wp), INTENT(OUT), OPTIONAL :: res_left + ! point_force_start: the magnitude of the net force on every moving point at its starting + ! position (per entry of points; zero for a point that does not move) + REAL(wp), INTENT(OUT), OPTIONAL :: point_force_start(:) TYPE :: LineStaticCache !! A moving line's mesh and loads (fixed) and its last converged shape (the warm seed). @@ -27179,6 +27251,7 @@ SUBROUTINE solve_body_equilibrium_core(types, bodies, rod_types, rods, points, l IF (PRESENT(quiet)) silent = quiet IF (PRESENT(skipped)) skipped = .FALSE. IF (PRESENT(res_left)) res_left = CD_ZERO + IF (PRESENT(point_force_start)) point_force_start = CD_ZERO IF (.NOT. (only_points .OR. opts%body_ic_static)) RETURN ! the objects that move: free Rigid6 bodies and free rods with a line, then Free/Connect points ALLOCATE (okind(SIZE(bodies) + SIZE(rods) + SIZE(points)), idx(SIZE(bodies) + SIZE(rods) + SIZE(points))) @@ -27366,6 +27439,11 @@ SUBROUTINE solve_body_equilibrium_core(types, bodies, rod_types, rods, points, l DO CALL residual(x, r, sc, ok, .TRUE.) IF (.NOT. ok) RETURN + IF (phase == 1 .AND. PRESENT(point_force_start)) THEN + DO k = 1, nobj + IF (okind(k) == OBJ_POINT) point_force_start(idx(k)) = NORM2(r(off(k) + 1:off(k) + 3)) + END DO + END IF rnorm = NORM2(r) mu = 1.0e-8_wp trust = -CD_ONE diff --git a/tests/test_point3_balance_note.py b/tests/test_point3_balance_note.py new file mode 100644 index 00000000..e69bca0e --- /dev/null +++ b/tests/test_point3_balance_note.py @@ -0,0 +1,107 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: Apache-2.0 +# Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University +"""A Point3 buoy that starts off balance under bodyIC static is noted with its unbalanced force. + +The static solve does not place a Point3 buoy: it starts at its deck position. A 112 t buoy of +259 m^3 on one slack wire leg, 11 m below the surface, starts with about 1.5 MN of net buoyancy +unbalanced. Under the default bodyIC static the run must note it, with the force equal to the +line force on the buoy (Point1F at t = 0) plus its net buoyancy (rhoW Vol - Mass) g to 1e-3, and +with bodyIC deck (an off-balance start on purpose) it must not. + +usage: test_point3_balance_note.py --exe --output +""" + +from __future__ import annotations + +import argparse +import math +import os +import re +import subprocess +import sys +from pathlib import Path + +DECK = """--------------------- CableDyn Input File ------------------------------------ +Point3 buoy on one wire leg, off balance at its deck position +--------------------- LINE TYPES --------------------------------------- +TypeName Diam Mass EA BA EI Cd_n Cd_t Ca_n Ca_t +(-) (m) (kg/m) (N) (N-s) (N-m2) (-) (-) (-) (-) +leg 0.0631 19.93 3.588e8 -0.5 0.0 1.2 0.008 1.0 0.0 +--------------------- BODIES ------------------------------------------- +ID Type X Y Z Roll Pitch Yaw Mass Vol C33 C44 C55 CdA Ca Ixx Iyy Izz +(-) (-) (m) (m) (m) (deg) (deg) (deg) (kg) (m3) (N/m) (Nm/rad) (Nm/rad) (m2) (-) (kgm2) (kgm2) (kgm2) +1 Point3 27.92 -29.39 -11.07 0.0 0.0 0.0 111760.0 258.6 0.0 0.0 0.0 5.56 0.5 683510.0 683510.0 683510.0 +--------------------- POINTS ------------------------------------------- +ID Type X Y Z +(-) (-) (m) (m) (m) +1 Body1 0.0 0.0 0.0 +2 Fixed 166.94 -51.95 -56.85 +--------------------- LINES -------------------------------------------- +ID NodeA NodeB Outputs +(-) (-) (-) (-) +1 1 2 - +--------------------- SECTIONS ----------------------------------------- +LineID LineType Length NumSegs +(-) (-) (m) (-) +1 leg 178.39 23 +--------------------- OPTIONS ------------------------------------------ +56.85 WtrDpth +1.8e5 kBot +0.01 dtM +0.02 TMax +{ic} bodyIC +--------------------- OUTPUTS ------------------------------------------ +Point1Fx +Point1Fy +Point1Fz +--------------------- need this line ----------------------------------- +""" + +NOTE = re.compile(r"BODY 1 \(Point3\) starts at its deck position, which the static solve does not change, " + r"with an unbalanced force of\s+(\S+) N there") +G, RHO = 9.80665, 1025.0 + + +def run(exe: str, out: Path, ic: str) -> tuple: + deck = out / ("buoy_%s.dat" % ic) + deck.write_text(DECK.format(ic=ic), encoding="utf-8", newline="\n") + root = out / ("buoy_%s" % ic) + env = dict(os.environ) + env.setdefault("OPENBLAS_NUM_THREADS", "1") + p = subprocess.run([exe, str(deck), str(root)], capture_output=True, text=True, env=env, cwd=str(out)) + if p.returncode != 0: + raise RuntimeError("bodyIC %s run failed: %s" % (ic, (p.stdout + p.stderr)[-400:])) + rows = Path(str(root) + ".out").read_text(encoding="utf-8").splitlines() + return [float(v) for v in rows[2].split()[1:4]], p.stdout + p.stderr + + +def main() -> int: + ap = argparse.ArgumentParser() + ap.add_argument("--exe", required=True) + ap.add_argument("--output", required=True) + a = ap.parse_args() + out = Path(a.output) + out.mkdir(parents=True, exist_ok=True) + failures = [] + f, log = run(a.exe, out, "static") + m = NOTE.search(log) + if not m: + failures.append("bodyIC static: no note of the unbalanced Point3 buoy") + else: + net = (f[0], f[1], f[2] + (RHO * 258.6 - 111760.0) * G) + expect = math.sqrt(sum(c * c for c in net)) + got = float(m.group(1)) + if abs(got - expect) > 1.0e-3 * expect: + failures.append("bodyIC static: noted force %.4e N, expected %.4e N" % (got, expect)) + _, log = run(a.exe, out, "deck") + if NOTE.search(log): + failures.append("bodyIC deck: the off-balance start is noted") + print("Point3 balance note: %d failures" % len(failures)) + for x in failures: + print("FAIL:", x) + return 1 if failures else 0 + + +if __name__ == "__main__": + sys.exit(main()) From 6f21fabf67860c17f9858623ed3f6f1b71b2c890 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Mon, 9 Nov 2026 01:55:17 +0900 Subject: [PATCH 2/2] chore(changelog): the entry moves to the batch changelog change The [Unreleased] entries of the open changes are added together in one change, so that they do not conflict with each other. Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4967ede7..e3549554 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,11 +18,6 @@ All notable changes to CableDyn are recorded in this file. The format follows The touchdown element now takes the reaction of its grounded stretch, from the grounded node to the touchdown point located from the two nodes' clearances: the error falls at the second order (2.1, 0.7, 0.2 N) and the outputs vary continuously. -- `Point3` buoys under the default `bodyIC static`: the static solve does not place a `Point3` - buoy, so it started at its deck position off balance without a word while every other free - object started balanced (a 112 t, 259 m^3 buoy started with 1.5 MN unbalanced and surfaced in - 2 s). The run now notes the unbalanced force and the distance to the buoy's static balance as - a `Free` point. ## [0.4.1] - 2026-11-08