Merge pull request #99 from SMI-Lab-Inha/fix-95-platform-cm-offset-guard

feat(checks): platform CM-offset guard + release 1.11.0 (#95)

Author: SMI-Lab-Inha

CHANGELOG.md

@@ -8,8 +8,31 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.11.0] — 2026-05-23
+
+A minor feature release: a WindIO monopile + tower constructor (#92) and a
+`check_model` guard that catches the implausible-platform-CM-offset input
+error behind #95. Additive and backward-compatible; no numerical change to
+any existing model.
+
 ### Added
 
+- **`check_model` gate for an implausibly large horizontal platform CM offset
+  (#95).** `cm_pform_x` / `cm_pform_y` on a `PlatformSupport` are the CM offset
+  *from the tower axis*; a value comparable to the platform's own size is
+  almost always a coordinate-origin offset leaking into the field, which
+  injects spurious surge/sway↔yaw coupling, shifts the rigid-body frequencies,
+  and mislabels the modes. The new check warns (WARN) when the horizontal
+  offset magnitude exceeds the platform's yaw radius of gyration `√(I_yaw/m)`,
+  turning a previously silent input error into an actionable message at the
+  call site. New `CheckOptions.platform_cm_offset_gyradius_factor` (default
+  `1.0`) tunes the threshold; the `PlatformSupport.cm_pform_x` / `cm_pform_y`
+  docs now state explicitly that they are tower-axis-relative (not a global
+  coordinate). Surfaced the diagnosis on #95: the reported "yaw on the first
+  mode" was this input error (a ~39 m CM offset on the IEA-15 VolturnUS-S),
+  not a classifier regression — with `cm_pform_x ≈ 0` the rigid-body modes
+  label cleanly.
+
 - **`Tower.from_windio_with_monopile(yaml, …)` — WindIO monopile + tower
   splice (#92).** `from_windio` reduces a *single* tube; there was no WindIO
   path that joined a monopile and tower into one fixed-bottom system. The new

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pybmodes"
-version = "1.10.1"
+version = "1.11.0"
 description = "Python finite-element library for wind turbine blade and tower modal analysis (OpenFAST/ElastoDyn)"
 readme = "README.md"
 license = { file = "LICENSE" }

src/pybmodes/__init__.py

@@ -182,7 +182,7 @@
 try:
     __version__ = version("pybmodes")
 except PackageNotFoundError:
-    __version__ = "1.10.1"
+    __version__ = "1.11.0"
 
 __all__ = [
     "CheckOptions",

src/pybmodes/checks.py

@@ -49,8 +49,13 @@
    ``1e-6 · max|A|``). Rank deficiency is **not** flagged — surge /
    sway / yaw hydrostatic restoring is legitimately zero on most
    floaters and mooring layouts can be low-rank by design.
-7. The requested ``n_modes`` does not exceed the model's DOF count.
-8. The polynomial-fit design matrix on the mesh stations is not
+7. The horizontal platform CM offset (``cm_pform_x`` / ``cm_pform_y``)
+   does not exceed the platform's yaw radius of gyration
+   ``√(I_yaw / m)`` — a larger value is almost always a coordinate-
+   origin offset leaking into a field that means "CM offset from the
+   tower axis", which mislabels the rigid-body modes (issue #95).
+8. The requested ``n_modes`` does not exceed the model's DOF count.
+9. The polynomial-fit design matrix on the mesh stations is not
    ill-conditioned (cond > 1e4 ⇒ WARN, > 1e6 ⇒ ERROR).
 """
 
@@ -146,6 +151,7 @@ def check_model(
     _check_ei_ratio(sp, out)
     _check_rna_vs_tower_mass(bmi, sp, out)
     _check_support_conditioning(bmi, out)
+    _check_platform_cm_offset(bmi, out)
     if n_modes is not None:
         _check_n_modes_vs_dof(bmi, n_modes, out)
     _check_polyfit_conditioning(bmi, out)
@@ -385,6 +391,62 @@ def _check_support_conditioning(bmi, out: list[ModelWarning]) -> None:
             ))
 
 
+def _check_platform_cm_offset(bmi, out: list[ModelWarning]) -> None:
+    """Flag an implausibly large horizontal platform CM offset.
+
+    ``cm_pform_x`` / ``cm_pform_y`` are the platform CM offset *from the
+    tower axis* — for a standard floater the tower sits at or near the
+    platform centroid, so these are small. A horizontal offset that
+    rivals the platform's own size (its yaw radius of gyration
+    ``√(I_yaw / m)``) is almost always a coordinate-origin value leaking
+    into the field; it injects spurious surge/sway↔yaw coupling through
+    the rigid-arm transform, shifts the rigid-body frequencies, and
+    mislabels the modes (issue #95). Emitted as WARN, not ERROR — a
+    genuinely large offset is physically representable, just unusual.
+    """
+    from pybmodes.io.bmi import PlatformSupport
+
+    if not isinstance(bmi.support, PlatformSupport):
+        return
+    sup = bmi.support
+    cm_x = float(getattr(sup, "cm_pform_x", 0.0) or 0.0)
+    cm_y = float(getattr(sup, "cm_pform_y", 0.0) or 0.0)
+    offset = float(np.hypot(cm_x, cm_y))
+    if offset == 0.0:
+        return
+
+    # Yaw radius of gyration r_g = √(I_yaw / m). Use the platform mass
+    # and the 6×6 inertia's yaw (5,5) term; bail quietly if either is
+    # unavailable / non-positive (can't form a meaningful scale).
+    mass = float(getattr(sup, "mass_pform", 0.0) or 0.0)
+    i_mat = np.asarray(sup.i_matrix, dtype=float)
+    if mass <= 0.0 and i_mat.shape == (6, 6) and np.isfinite(i_mat[0, 0]):
+        mass = float(i_mat[0, 0])      # i_matrix[0,0] is the platform mass
+    if mass <= 0.0 or i_mat.shape != (6, 6):
+        return
+    i_yaw = float(i_mat[5, 5])
+    if not np.isfinite(i_yaw) or i_yaw <= 0.0:
+        return
+    r_g = float(np.sqrt(i_yaw / mass))
+    if r_g <= 0.0:
+        return
+
+    if offset > _CHECK_OPTIONS.platform_cm_offset_gyradius_factor * r_g:
+        out.append(ModelWarning(
+            "WARN",
+            f"Horizontal platform CM offset (cm_pform_x={cm_x:.3g} m, "
+            f"cm_pform_y={cm_y:.3g} m, magnitude {offset:.3g} m) exceeds the "
+            f"platform's yaw radius of gyration √(I_yaw/m) = {r_g:.3g} m. "
+            f"cm_pform_x / cm_pform_y are the CM offset FROM THE TOWER AXIS — "
+            f"a value this large is usually a coordinate-origin offset leaking "
+            f"into the field; it injects spurious surge/sway↔yaw coupling that "
+            f"shifts the rigid-body frequencies and mislabels the modes. Set "
+            f"them to the CM offset relative to the tower axis (≈0 for a tower "
+            f"on the platform centroid).",
+            "bmi.support.cm_pform_x",
+        ))
+
+
 def _check_n_modes_vs_dof(
     bmi, n_modes: int, out: list[ModelWarning]
 ) -> None:

src/pybmodes/io/bmi.py

@@ -93,14 +93,21 @@ class PlatformSupport:
     distr_k_z: np.ndarray
     distr_k: np.ndarray
     wires: TensionWireSupport | None = None
-    # Horizontal offset of the platform centre of mass from the tower
-    # axis, in the tower-base frame (x = downwind / surge-aligned,
-    # y = lateral / sway-aligned), metres. Non-zero only for an
-    # asymmetric floating substructure; both default to 0.0 so every
-    # existing deck / sample (axisymmetric spars, symmetric semis) is
-    # byte-identical. Consumed by ``pybmodes.fem.nondim.nondim_platform``
-    # as the horizontal components of the CM → tower-base rigid arm
-    # (the vertical component stays ``cm_pform``). Added 1.2.0.
+    # Horizontal offset of the platform centre of mass from the TOWER
+    # AXIS, in the tower-base frame (x = downwind / surge-aligned,
+    # y = lateral / sway-aligned), metres. This is a *local* offset of
+    # the CM relative to the tower centreline — NOT a position in any
+    # global / OpenFAST / WAMIT coordinate frame. For a standard floater
+    # the tower sits on the platform centroid, so these are ≈ 0 (every
+    # axisymmetric spar / symmetric semi: exactly 0). A value comparable
+    # to the platform's own size (its yaw radius of gyration) is almost
+    # always a coordinate-origin offset leaking in; it injects spurious
+    # surge/sway↔yaw coupling and mislabels the rigid-body modes — the
+    # ``check_model`` platform-CM-offset gate warns on it (issue #95).
+    # Both default to 0.0 so every existing deck / sample is byte-
+    # identical. Consumed by ``pybmodes.fem.nondim.nondim_platform`` as
+    # the horizontal components of the CM → tower-base rigid arm (the
+    # vertical component stays ``cm_pform``). Added 1.2.0.
     cm_pform_x: float = 0.0
     cm_pform_y: float = 0.0
 

src/pybmodes/options.py

@@ -144,6 +144,15 @@ class CheckOptions:
     fit_cond_fail : float, default 1e6
         Polynomial-fit design-matrix condition above which check_model
         emits a FAIL. Mirrors :class:`FitOptions.fit_cond_fail`.
+    platform_cm_offset_gyradius_factor : float, default 1.0
+        The horizontal platform CM offset (``cm_pform_x`` / ``cm_pform_y``
+        on a ``PlatformSupport``) is flagged when its magnitude exceeds
+        this factor times the platform's yaw radius of gyration
+        ``√(I_yaw / m)``. ``cm_pform_x`` / ``cm_pform_y`` are the CM
+        offset *from the tower axis*; a value comparable to the
+        platform's own size is almost always a coordinate-origin error
+        leaking into the field, which injects spurious surge/sway↔yaw
+        coupling and mislabels the rigid-body modes (issue #95).
     """
 
     stiffness_jump_factor: float = 5.0
@@ -152,6 +161,7 @@ class CheckOptions:
     support_asymmetry_rtol: float = 1.0e-6
     fit_cond_warn: float = 1.0e4
     fit_cond_fail: float = 1.0e6
+    platform_cm_offset_gyradius_factor: float = 1.0
 
 
 # Module-level default instances. Internal call sites that don't (yet)

tests/test_checks.py

@@ -291,6 +291,72 @@ def test_polyfit_cond_number_warn(self, tmp_path: pathlib.Path) -> None:
         assert hits[0].severity in ("WARN", "ERROR")
         assert "polynomial-fit design matrix" in hits[0].message
 
+    # --- platform CM offset (issue #95) ---------------------------------
+    def _build_cm_offset_tower(self, cm_x: float, cm_y: float = 0.0) -> Tower:
+        """A hub_conn=2 PlatformSupport tower with a full 6×6 inertia and
+        a configurable horizontal CM offset. Yaw radius of gyration is
+        √(I_yaw/m) = √(2.0e10 / 1.8e7) ≈ 33.3 m."""
+        n = 5
+        span = np.linspace(0.0, 1.0, n)
+        sp = SectionProperties(
+            title="t", n_secs=n,
+            span_loc=span, str_tw=np.zeros(n), tw_iner=np.zeros(n),
+            mass_den=np.full(n, 100.0),
+            flp_iner=np.full(n, 10.0), edge_iner=np.full(n, 10.0),
+            flp_stff=np.full(n, 1.0e9), edge_stff=np.full(n, 1.0e9),
+            tor_stff=np.full(n, 1.0e8), axial_stff=np.full(n, 1.0e10),
+            cg_offst=np.zeros(n), sc_offst=np.zeros(n), tc_offst=np.zeros(n),
+        )
+        m = 1.8e7
+        i6 = np.zeros((6, 6))
+        i6[0, 0] = i6[1, 1] = i6[2, 2] = m
+        i6[3, 3] = i6[4, 4] = 1.3e10
+        i6[5, 5] = 2.0e10                       # I_yaw → r_g ≈ 33.3 m
+        platform = PlatformSupport(
+            draft=10.0, cm_pform=0.0, mass_pform=m, i_matrix=i6, ref_msl=0.0,
+            hydro_M=np.eye(6) * 1.0e6, hydro_K=np.eye(6) * 1.0e7,
+            mooring_K=np.diag([1.0e6] * 6),
+            distr_m_z=np.array([]), distr_m=np.array([]),
+            distr_k_z=np.array([]), distr_k=np.array([]), wires=None,
+            cm_pform_x=cm_x, cm_pform_y=cm_y,
+        )
+        bmi = BMIFile(
+            title="t", echo=False, beam_type=2, rot_rpm=0.0, rpm_mult=1.0,
+            radius=90.0, hub_rad=0.0, precone=0.0, bl_thp=0.0, hub_conn=2,
+            n_modes_print=20, tab_delim=True, mid_node_tw=False,
+            tip_mass=TipMassProps(
+                mass=100_000.0, cm_offset=0.0, cm_axial=0.0,
+                ixx=0.0, iyy=0.0, izz=0.0, ixy=0.0, izx=0.0, iyz=0.0,
+            ),
+            id_mat=1, sec_props_file="", scaling=ScalingFactors(),
+            n_elements=10, el_loc=np.linspace(0.0, 1.0, 11),
+            tow_support=1, support=platform, source_file=None,
+        )
+        tower = Tower.__new__(Tower)
+        tower._bmi = bmi
+        tower._sp = sp
+        return tower
+
+    def test_large_horizontal_cm_offset_warns(self) -> None:
+        """A horizontal CM offset exceeding the platform's yaw radius of
+        gyration (the issue #95 input error) flags WARN."""
+        tower = self._build_cm_offset_tower(cm_x=-39.0)   # > r_g ≈ 33.3 m
+        hits = _filter(check_model(tower), "cm_pform_x")
+        assert len(hits) == 1 and hits[0].severity == "WARN"
+        assert "radius of gyration" in hits[0].message
+        assert "tower axis" in hits[0].message.lower()
+
+    def test_small_horizontal_cm_offset_is_silent(self) -> None:
+        """A modest CM offset (well under the gyration radius) is a
+        legitimate asymmetric floater and must not warn."""
+        tower = self._build_cm_offset_tower(cm_x=-4.0)     # < r_g ≈ 33.3 m
+        assert _filter(check_model(tower), "cm_pform_x") == []
+
+    def test_zero_cm_offset_is_silent(self) -> None:
+        """The axisymmetric / symmetric default (offset 0) never warns."""
+        tower = self._build_cm_offset_tower(cm_x=0.0, cm_y=0.0)
+        assert _filter(check_model(tower), "cm_pform_x") == []
+
 
 # ---------------------------------------------------------------------------
 # Auto-run integration on Tower.run / RotatingBlade.run