From a14243564dd90aa0fa2c5379fd3358a11881c908 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Mon, 9 Nov 2026 00:41:19 +0900 Subject: [PATCH 1/2] fix(modal): note a mode with omega^2 < 0 and document its signed frequency A modal analysis about an unstable static state (a planar equilibrium unstable out of its plane on a coarse mesh, a compressed strut) finds eigenvalues omega^2 < 0. modes.out wrote them as a negative frequency and omega with a period of 0, a convention neither the run nor the manual stated. The run now prints a note naming the line and the number of such modes, and the Outputs page and the theory manual document the signed values (Omega = -sqrt(|omega^2|), Frequency = Omega/2 pi, Period 0). The new modal_negative_note test runs a 27-element cable whose planar state is unstable out of its plane (one negative mode, noted) and the same cable on 108 elements (all frequencies positive, no note). Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 4 ++ CMakeLists.txt | 8 +++ doc/outputs.rst | 6 +- doc/theory.rst | 4 +- src/CableDyn_DeckDriver.f90 | 13 +++- tests/test_modal_negative_note.py | 104 ++++++++++++++++++++++++++++++ 6 files changed, 136 insertions(+), 3 deletions(-) create mode 100644 tests/test_modal_negative_note.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e3549554..2017e148 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ 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. +- Modal analysis about an unstable static state: a mode with omega^2 < 0 was written to + `modes.out` as a negative frequency with period 0 without a word in the run or the manual. + The run now notes the line and the number of such modes, and the Outputs page documents the + signed values (`Omega` = -sqrt(|omega^2|), `Frequency` = `Omega`/2 pi). ## [0.4.1] - 2026-11-08 diff --git a/CMakeLists.txt b/CMakeLists.txt index 96dcf84c..07ae1fba 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -3091,6 +3091,14 @@ if(Python3_Interpreter_FOUND) --source ${CMAKE_CURRENT_SOURCE_DIR} --output ${CMAKE_CURRENT_BINARY_DIR}/modal_torsion_deck) set_tests_properties(modal_torsion_deck PROPERTIES LABELS "python;driver;integration;validation") + # A modal analysis about an unstable static state writes its negative omega^2 as a negative + # frequency of period 0 and notes it; the stable state of a finer mesh does neither. + add_test( + NAME modal_negative_note + COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_modal_negative_note.py + --exe $ + --output ${CMAKE_CURRENT_BINARY_DIR}/modal_negative_note) + set_tests_properties(modal_negative_note PROPERTIES LABELS "python;driver;modal" TIMEOUT 300) # Static-initialization robustness matrix: a deterministic sample of EI=0 mooring regimes # (catenary, semi-taut, taut, suspended, composite, slack/vertical, anchors off the seabed, # sloped seabed, fine mesh, soft seabed, current, one/two segments, Free/Connect points) diff --git a/doc/outputs.rst b/doc/outputs.rst index ac7e6fb7..1fd0325e 100644 --- a/doc/outputs.rst +++ b/doc/outputs.rst @@ -459,7 +459,11 @@ holds two tab-separated tables, each introduced by a ``#`` comment line, a heade row: * ``# Natural frequencies``: ``LineID Mode Frequency Period Omega`` (Hz, s, rad/s), the - ``nModes`` lowest modes of every line in ascending order; + ``nModes`` lowest modes of every line in ascending order of :math:`\omega^2`. A mode with + :math:`\omega^2 < 0`, an instability of the static state (a planar equilibrium that is + unstable out of its plane, a compressed strut), is written with the signed values + ``Omega`` :math:`= -\sqrt{|\omega^2|}` and ``Frequency`` :math:`= -\sqrt{|\omega^2|}/2\pi` and + ``Period`` 0, and the run prints a note naming the line and the number of such modes; * ``# Mode shapes``: ``LineID Mode Node X Y Z dX dY dZ``, one row per mode and node. ``X Y Z`` is the static node position and ``dX dY dZ`` the nodal translation of the mode, scaled so that the largest nodal displacement of the mode is 1. Nodes are numbered End A first, diff --git a/doc/theory.rst b/doc/theory.rst index 18d5f2a1..32f6766f 100644 --- a/doc/theory.rst +++ b/doc/theory.rst @@ -2030,7 +2030,9 @@ positive; where two components are equally large to round-off (the mirrored node symmetric line), the first of them in the solver's node order is. Memory grows linearly with the line length. The frequencies :math:`f = \omega/2\pi` and the nodal translations of each mode (scaled to a unit largest -nodal displacement) are written to ``.modes.out``. For a taut string of tension +nodal displacement) are written to ``.modes.out``; an eigenvalue :math:`\omega^2 < 0`, an +instability of the static state, is written as the negative frequency +:math:`-\sqrt{|\omega^2|}/2\pi` and noted. For a taut string of tension :math:`T` the transverse frequencies are :math:`f_n = (n/2L)\sqrt{T/m}`; for a shallow sagging cable the out-of-plane and antisymmetric in-plane modes follow the string with the horizontal tension :math:`H`, and the symmetric in-plane modes satisfy diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index ed2473df..9d7ad227 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -33016,7 +33016,7 @@ SUBROUTINE write_modes_file(out_root, lines, res, ErrStat, ErrMsg) TYPE(ModalLineResult), INTENT(IN) :: res(:) INTEGER, INTENT(OUT) :: ErrStat CHARACTER(*), INTENT(OUT) :: ErrMsg - INTEGER :: unit, ios, li, part, nn, k, dpn, src, dst + INTEGER :: unit, ios, li, part, nn, k, dpn, src, dst, n_neg REAL(wp), ALLOCATABLE :: q_a(:), shapes_a(:, :), polar(:) CHARACTER(1) :: tb LOGICAL :: twist @@ -33077,6 +33077,17 @@ SUBROUTINE write_modes_file(out_root, lines, res, ErrStat, ErrMsg) END DO END DO CLOSE (unit) + ! A mode with omega^2 < 0 is an instability of the static state: it is written with a + ! negative frequency, and the run says so. + DO li = 1, SIZE(lines) + n_neg = 0 + IF (ALLOCATED(res(li)%omega2) .AND. res(li)%n_found > 0) & + n_neg = COUNT(res(li)%omega2(1:res(li)%n_found) < CD_ZERO) + IF (n_neg > 0) CALL print_note(output_unit, ' ', 'line '//TRIM(int_to_str(lines(li)%id))//': '// & + TRIM(int_to_str(n_neg))//' of its modes have omega^2 < 0, so its static state '// & + 'is unstable in them; '//TRIM(out_root)//'.modes.out gives each a negative '// & + 'frequency, -sqrt(|omega^2|)/(2 pi), and a period of 0') + END DO END SUBROUTINE write_modes_file SUBROUTINE resolve_deck_friction(opts, ErrStat, ErrMsg) diff --git a/tests/test_modal_negative_note.py b/tests/test_modal_negative_note.py new file mode 100644 index 00000000..ec11e45c --- /dev/null +++ b/tests/test_modal_negative_note.py @@ -0,0 +1,104 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: Apache-2.0 +# Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University +"""A modal analysis about an unstable static state reports its negative omega^2. + +A short finite-EI cable on a coarse mesh (27 elements) is solved in its vertical plane, where +it is unstable out of the plane: its lowest eigenvalue omega^2 is negative. modes.out must +write that mode with a negative frequency and omega and a period of 0, and the run must print +a note naming the line. On a mesh refined 4x the planar state is stable: every frequency is +positive and the note is absent. + +usage: test_modal_negative_note.py --exe --output +""" + +from __future__ import annotations + +import argparse +import os +import subprocess +import sys +from pathlib import Path + +DECK = """--------------------- CableDyn Input File ------------------------------------ +Finite-EI cable whose planar static state is unstable out of its plane on a coarse mesh +--------------------- LINE TYPES --------------------------------------- +TypeName Diam Mass EA BA EI Cd_n Cd_t Ca_n Ca_t +(-) (m) (kg/m) (N) (N-s) (N-m2) (-) (-) (-) (-) +cab 0.167 45.5 5.72e8 -0.5 9250.0 1.2 0.01 1.0 0.0 +--------------------- POINTS ------------------------------------------- +ID Type X Y Z +(-) (-) (m) (m) (m) +1 Coupled 0.0 0.0 -0.24 +2 Fixed 77.65 0.0 -21.06 +--------------------- LINES -------------------------------------------- +ID NodeA NodeB Outputs +(-) (-) (-) (-) +1 1 2 - +--------------------- SECTIONS ----------------------------------------- +LineID LineType Length NumSegs +(-) (-) (m) (-) +1 cab 90.56 {n} +--------------------- OPTIONS ------------------------------------------ +21.06 WtrDpth +1.5e5 kBot +0.01 dtM +0.0 TMax +4 nModes +--------------------- OUTPUTS ------------------------------------------ +FairTen1 +--------------------- need this line ----------------------------------- +""" + +NOTE = "of its modes have omega^2 < 0" + + +def run(exe: str, out: Path, n: int) -> tuple: + deck = out / ("cable_%d.dat" % n) + deck.write_text(DECK.format(n=n), encoding="utf-8", newline="\n") + root = out / ("cable_%d" % n) + 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("run with %d elements failed: %s" % (n, (p.stdout + p.stderr)[-400:])) + rows = [] + for ln in Path(str(root) + ".modes.out").read_text(encoding="utf-8").splitlines(): + if ln.startswith("# Mode shapes"): + break + t = ln.split() + if len(t) == 5 and t[0].isdigit(): + rows.append([float(v) for v in t[2:]]) + return rows, 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 = [] + rows, log = run(a.exe, out, 27) + neg = [r for r in rows if r[0] < 0.0] + if not neg: + failures.append("coarse mesh: no negative frequency (%s)" % rows) + for f, per, om in neg: + if per != 0.0 or om >= 0.0: + failures.append("coarse mesh: negative mode with period %g, omega %g" % (per, om)) + if "line 1: %d %s" % (len(neg), NOTE) not in log: + failures.append("coarse mesh: the run does not note the %d negative mode(s)" % len(neg)) + rows, log = run(a.exe, out, 108) + if any(r[0] <= 0.0 for r in rows): + failures.append("refined mesh: a non-positive frequency (%s)" % rows) + if NOTE in log: + failures.append("refined mesh: the run notes a negative mode") + print("modal negative-mode note: %d failures" % len(failures)) + for f in failures: + print("FAIL:", f) + return 1 if failures else 0 + + +if __name__ == "__main__": + sys.exit(main()) From c42b271e72e25477a5017bf9a4eb9e0d3bf7661a Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Mon, 9 Nov 2026 01:53:47 +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 | 4 ---- 1 file changed, 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2017e148..e3549554 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,10 +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. -- Modal analysis about an unstable static state: a mode with omega^2 < 0 was written to - `modes.out` as a negative frequency with period 0 without a word in the run or the manual. - The run now notes the line and the number of such modes, and the Outputs page documents the - signed values (`Omega` = -sqrt(|omega^2|), `Frequency` = `Omega`/2 pi). ## [0.4.1] - 2026-11-08