pybmodes 1.8.0__py3-none-any.whl

pybmodes/__init__.py

@@ -0,0 +1,188 @@
+# Copyright 2024-2026 Jae Hoon Seo
+# Marine Structural Mechanics and Integrity Lab (SMI Lab), Inha University
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""pybmodes — Python finite-element library for wind turbine modal analysis.
+
+Public API
+==========
+
+The following subpackage entry points are the stable, semver-protected
+1.x surface (see the *Compatibility policy* section in the README).
+Anything else in the package tree is internal and may change between
+minor releases.
+
+    from pybmodes.models    import RotatingBlade, Tower, ModalResult
+    from pybmodes.elastodyn import (
+        compute_blade_params,
+        compute_tower_params,
+        compute_tower_params_report,
+        patch_dat,
+        validate_dat_coefficients,
+        BladeElastoDynParams,
+        TowerElastoDynParams,
+        ValidationResult,
+        CoeffBlockResult,           # tower blocks carry fa/ss/torsion
+                                    # participation + rejected_modes
+    )
+    from pybmodes.fitting   import PolyFitResult, fit_mode_shape
+    from pybmodes.campbell  import (
+        CampbellResult,             # save / load / to_csv
+        campbell_sweep,
+        plot_campbell,
+    )
+    from pybmodes.checks    import check_model, ModelWarning
+    from pybmodes.mac       import (
+        mac_matrix,
+        compare_modes,
+        ModeComparison,
+        plot_mac,
+        shape_to_vector,
+    )
+    from pybmodes.report    import generate_report
+    from pybmodes.mooring   import LineType, Point, Line, MooringSystem
+    from pybmodes.io        import (
+        HydroDynReader, WamitReader, WamitData,
+        PlatformSupport, TipMassProps,
+        read_out, BModeOutParseError,   # read_out(..., strict=True)
+    )
+    from pybmodes.coords    import DOF_NAMES, DOF_INDEX  # 6-DOF convention
+    from pybmodes.plots     import (
+        apply_style,
+        plot_mode_shapes,
+        plot_fit_quality,
+        bir_mode_shape_plot,
+        bir_mode_shape_subplot,
+        plot_environmental_spectra,   # wind/wave + 1P/3P vs tower
+        kaimal_spectrum,
+        jonswap_spectrum,
+    )
+
+    # On Tower:
+    #   Tower.from_bmi(bmi_path)
+    #   Tower.from_elastodyn(main_dat)
+    #   Tower.from_elastodyn_with_subdyn(main_dat, subdyn_dat)
+    #   Tower.from_elastodyn_with_mooring(main_dat, moordyn_dat,
+    #                                     hydrodyn_dat=None)
+    #   Tower.from_geometry(station_grid, outer_diameter,
+    #                       wall_thickness, *, flexible_length,
+    #                       E, rho, nu, outfitting_factor)
+    #   Tower.from_windio(yaml_path, *, component, thickness_interp,
+    #       hub_conn, tip_mass, n_nodes)
+    #     tip_mass: TipMassProps | float (RNA mass kg); n_nodes:
+    #     refine the FE mesh onto N even stations (issue #35)
+    #   Tower.from_windio_floating(yaml_path, *, water_depth,
+    #                              hydrodyn_dat, moordyn_dat,
+    #                              elastodyn_dat)  # coupled FOWT
+
+    # On RotatingBlade:
+    #   RotatingBlade.from_bmi(bmi_path)
+    #   RotatingBlade.from_elastodyn(main_dat)
+    #   RotatingBlade.from_windio(yaml_path, *, component, n_span,
+    #                             rot_rpm, elastic)
+    #     elastic="auto" (default) uses the WindIO *published*
+    #     distributed elastic properties when present — the full 6×6
+    #     decoupled at the elastic/shear centre + principal elastic
+    #     axes (issue #50; pybmodes.io._precomp.decouple), not the
+    #     raw diagonal — else the PreComp-class layup reduction;
+    #     "precomp" forces the reduction; "file" requires the
+    #     published properties.
+
+    from pybmodes.io.geometry import tubular_section_props
+    # WindIO .yaml input needs the optional [windio] extra (PyYAML);
+    # the runtime core stays numpy+scipy only — same stance as
+    # [plots]/[notebook]. Tower (tubular tower/monopile):
+    from pybmodes.io.windio  import read_windio_tubular, WindIOTubular
+    # Blade (composite layup -> PreComp-class thin-wall reduction):
+    from pybmodes.io.windio_blade import (
+        read_windio_blade,
+        windio_blade_section_props,
+        WindIOBlade,
+    )
+    # Floating substructure (member-Morison hydro + catenary mooring;
+    # used by Tower.from_windio_floating, yaml-first + deck-fallback):
+    from pybmodes.io.windio_floating import (
+        read_windio_floating,
+        hydrostatic_restoring,
+        added_mass,
+        rigid_body_inertia,
+        WindIOFloating,
+    )
+
+``ModalResult`` ships ``save(.npz)`` / ``load(.npz)`` /
+``to_json(.json)`` / ``from_json(.json)`` with metadata (pyBmodes
+version, source file, timestamp, git hash) and optional
+``participation`` + ``fit_residuals`` + ``mode_labels`` fields
+(``mode_labels`` names the floating-platform rigid-body modes —
+surge / sway / heave / roll / pitch / yaw — for a free-free model;
+``None`` otherwise). ``CampbellResult`` ships ``save(.npz)`` /
+``load(.npz)`` / ``to_csv(.csv)``.
+
+Known limitations of the 1.0 surface:
+
+- ``pybmodes.mooring`` is catenary-only quasi-static — no seabed
+  friction (``CB > 0``), no sloped seabed, no U-shape lines, no
+  time-domain dynamics, no line drag / added mass.
+- ``pybmodes.io.WamitReader`` extracts ``A_inf`` (infinite-frequency
+  added mass), ``A_0`` (zero-frequency), and ``C_hst`` (hydrostatic
+  restoring); finite-period frequency-dependent ``A(ω)`` / ``B(ω)``
+  are skipped.
+- ``Tower.from_elastodyn_with_mooring`` assembles a free-free floating
+  BMI for coupled-frequency prediction; ElastoDyn polynomial-
+  coefficient generation continues to use the cantilever
+  ``Tower.from_elastodyn`` regardless of platform configuration (see
+  ``cases/ECOSYSTEM_FINDING.md`` for the source-code citation).
+- ``BMIFile.support.distr_m`` (distributed hydrodynamic added mass
+  per unit tower length) is parsed by ``pybmodes.io.bmi.read_bmi``
+  but NOT wired into the FEM mass matrix; ``distr_k`` (distributed
+  soil stiffness) IS consumed. A ``UserWarning`` fires at parse time
+  if a deck specifies non-empty ``distr_m`` so the gap is not
+  silent.
+
+Internal modules (``pybmodes.fem.*``, the underscore-prefixed
+``pybmodes.models._pipeline``, and the private sub-package
+``pybmodes.io._elastodyn``) carry the implementation and should not
+be imported directly by user code; their signatures may change
+between minor releases. The per-format submodules under
+``pybmodes.io`` (``pybmodes.io.bmi``, ``elastodyn_reader``,
+``subdyn_reader``, ``wamit_reader``) are reachable directly but the
+public-freeze contract covers only the re-exports listed above.
+
+The CLI is exposed via ``pybmodes`` (see ``pybmodes --help``) and is
+declared in ``[project.scripts]``.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+# Numerical-options dataclasses (Phase 1 of the v1.x architecture
+# refactor) — centralised thresholds for the FEM solver, polynomial
+# fit, and pre-solve sanity checker. Defaults preserve every
+# previously-embedded magic number, so importing this module changes
+# no behaviour; the public-API value is that callers can now find
+# every numerical threshold in one place. Future PRs will accept
+# instances on ``Tower.run()`` / ``RotatingBlade.run()`` /
+# ``check_model()`` for per-call override.
+from pybmodes.options import CheckOptions, FitOptions, SolverOptions
+
+try:
+    __version__ = version("pybmodes")
+except PackageNotFoundError:
+    __version__ = "1.8.0-dev"
+
+__all__ = [
+    "__version__",
+    "CheckOptions",
+    "FitOptions",
+    "SolverOptions",
+]

pybmodes/_examples/__init__.py

@@ -0,0 +1,45 @@
+# Copyright 2024-2026 Jae Hoon Seo
+# Marine Structural Mechanics and Integrity Lab (SMI Lab), Inha University
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Bundled example inputs and reference decks.
+
+This sub-package vendors two trees that ship inside the wheel so a
+``pip install pybmodes`` user can copy them out to a working directory
+without keeping a full git clone of the repository.
+
+- ``sample_inputs/`` — pyBmodes-authored, Apache 2.0-licensed ``.bmi`` and
+  section-property ``.dat`` files. Four analytical-reference cases
+  (uniform blade, tower with top mass, rotating uniform blade,
+  pinned-free cable) plus seven reference-wind-turbine sub-cases under
+  ``reference_turbines/``. ``verify.py`` runs the four analytical
+  cases against closed-form references.
+- ``reference_decks/`` — six pre-patched ElastoDyn decks (three
+  land/monopile + three floating) whose polynomial blocks have been
+  regenerated from the structural inputs via ``Tower.from_elastodyn``.
+
+The trees are intentionally treated as opaque data; the ``.py``
+helpers inside them (``verify.py``, ``reference_turbines/build.py``)
+are intended to be run *after* vendoring out via
+``pybmodes examples --copy <dir>``, not imported.
+
+Users discover the bundles through three paths:
+
+- ``pybmodes examples --copy DIR`` — CLI that copies one or both
+  trees into a user-supplied directory.
+- Browsing the wheel install directly under
+  ``site-packages/pybmodes/_examples/``.
+- For developers working from a source checkout, the GitHub source
+  tree under the same path.
+"""

pybmodes/_examples/reference_decks/FLOATING_CASES.md

@@ -0,0 +1,144 @@
+<!-- markdownlint-disable MD013 -->
+# Floating cases — the correct ElastoDyn polynomial basis is *cantilever*
+
+For floating platforms, ElastoDyn polynomial coefficients
+(`TwFAM1Sh`, `TwFAM2Sh`, `TwSSM1Sh`, `TwSSM2Sh`) must be derived
+from a **cantilever** (`hub_conn = 1`) tower model with the RNA
+lumped at the tower top — **NOT** from a platform-coupled floating
+model.
+
+## Why
+
+ElastoDyn represents floating tower dynamics as a clamped-base
+cantilever **in the platform-attached frame**, with platform 6-DOF
+motion handled separately as independent generalised coordinates
+(`Sg / Sw / Hv / R / P / Y`). Three independent code-level evidences
+in OpenFAST `modules/elastodyn/src/ElastoDyn.f90` (main branch):
+
+1. The polynomial ansatz in `SHP` evaluates
+   `Σ_{i=1..PolyOrd-1} c_i · (h/H)^(i+1)` (lines 2486–2495). The
+   lowest power is `Fract²`, so `SHP(0) = SHP'(0) = 0`
+   *identically*. A free-free or pinned-pinned mode shape with
+   non-zero base slope cannot be represented in this format.
+2. The base node is hard-coded zero: `p%TwrFASF(:,0,0:1) = 0`,
+   `p%TwrSSSF(:,0,0:1) = 0` (lines 5147–5148).
+3. The internal tower modal eigenproblem (`Coeff` subroutine,
+   lines 5141–5267) integrates `MTFA = TwrTpMass + ∫ ρA φ² dh`
+   and `KTFA = ∫ EI φ'' φ'' dh + KTFAGrav`. **No** `PlatformMass`,
+   **no** `hydro_K`, **no** `mooring_K`, **no** `i_matrix` enter
+   this assembly. The only tip-end inertia is the scalar
+   `TwrTpMass` (lumped RNA mass).
+
+Platform 6-DOF motion enters the absolute tower kinematics via the
+**rigid-body sum** (lines 7485–7540):
+
+```text
+v_T(J) = v_Z + ω_X × rZT(J) + Σ_k φ_k(h_J) · q̇_k
+```
+
+`Sg/Sw/Hv/R/P/Y` and the tower modal coordinates `q_TFA1 / q_TFA2 /
+q_TSS1 / q_TSS2` are **independent** generalised coordinates;
+platform motion does NOT appear as forcing on `q_TFA1`. Feeding
+ElastoDyn polynomials that already encode platform-coupling
+**double-counts** the platform restoring forces because ElastoDyn
+re-derives those effects independently through the platform DOFs.
+
+Same BC for land and floating — only the runtime treatment of the
+clamp point differs (locked in Earth for land; rigidly attached to
+the moving platform for floating).
+
+## How
+
+Floating-platform polynomial coefficients are generated with the
+**existing** pyBmodes path — `Tower.from_elastodyn(...)` is
+*already* the cantilever path. It clamps at `TowerBsHt` with the RNA
+lumped at the top, ignores any platform / hydro / mooring matrices,
+and produces exactly the basis ElastoDyn assumes. No flag is needed.
+
+```python
+from pybmodes.models import Tower
+from pybmodes.elastodyn import compute_tower_params, patch_dat
+from pybmodes.io.elastodyn_reader import read_elastodyn_main
+
+main_path = "Floating_ElastoDyn.dat"
+tower = Tower.from_elastodyn(main_path)        # cantilever, RNA at top, no platform
+result = tower.run(n_modes=10)
+params = compute_tower_params(result)
+
+# patch_dat rewrites the *tower* .dat file (where the polynomial
+# blocks live), not the main ElastoDyn .dat.
+main = read_elastodyn_main(main_path)
+patch_dat(main_path.replace("ElastoDyn.dat", main.twr_file), params)
+```
+
+No WAMIT files, no HydroDyn parsing, and no MoorDyn parsing are
+required. The cantilever path is correct and self-contained — the
+ElastoDyn `.dat` (plus the tower file it references) carries every
+input needed.
+
+## What about `Tower.from_bmi()` with `hub_conn = 2`?
+
+`Tower.from_bmi("OC3Hywind.bmi")` and similar BModes-format decks
+with a populated `PlatformSupport` block solve the **coupled**
+tower-and-platform eigenproblem (free-free root, full 6×6 hydro /
+mooring / inertia matrices). That path:
+
+- **Correctly predicts coupled-system frequencies** for validation
+  against BModes JJ. pyBmodes matches BModes JJ to ~ 0.0003 % across
+  the first nine OC3 Hywind modes (`test_certtest_oc3hywind`). If
+  the goal is "what does the floating tower vibrate at when coupled
+  to its platform?", this is the right path.
+- **Produces eigenvectors that include platform rigid-body motion**
+  — i.e. the modes have non-zero base displacement and non-zero
+  base slope, which the ElastoDyn `SHP` ansatz cannot represent.
+  Feeding these eigenvectors into a polynomial fit produces
+  coefficients ElastoDyn cannot consume without double-counting the
+  platform.
+
+The two paths answer different questions; both are correct for
+their intended use:
+
+| Goal | Use | BC |
+| --- | --- | --- |
+| ElastoDyn polynomial coefficients (any floating deck) | `Tower.from_elastodyn(...)` | `hub_conn = 1`, RNA at top |
+| Coupled-system frequency validation against BModes JJ | `Tower.from_bmi("OC3Hywind.bmi")` | `hub_conn = 2`, full PlatformSupport |
+
+## Configurations included in `reference_decks/`
+
+This directory now ships pre-patched ElastoDyn decks for three
+floating configurations alongside the original three fixed-base
+decks:
+
+- [`nrel5mw_oc3spar/`](nrel5mw_oc3spar/) — *NREL 5MW* on the OC3
+  Hywind spar (Jonkman 2010). Source: OpenFAST `r-test`
+  `5MW_OC3Spar_DLL_WTurb_WavesIrr/`.
+- [`nrel5mw_oc4semi/`](nrel5mw_oc4semi/) — *NREL 5MW* on the OC4
+  DeepCwind semi-submersible (Robertson et al. 2014). Source:
+  OpenFAST `r-test` `5MW_OC4Semi_WSt_WavesWN/`.
+- [`iea15mw_umainesemi/`](iea15mw_umainesemi/) — *IEA-15-240-RWT*
+  on the UMaine VolturnUS-S semi (Allen et al. 2020). Source:
+  upstream `IEA-15-240-RWT/OpenFAST/IEA-15-240-RWT-UMaineSemi/`.
+
+Each deck is built by `scripts/build_reference_decks.py` using the
+cantilever path documented above; the validator passes on all four
+tower coefficient blocks after patching.
+
+## Citations
+
+- Jonkman, J., Butterfield, S., Musial, W., & Scott, G. (2009).
+  *Definition of a 5-MW Reference Wind Turbine for Offshore System
+  Development*. NREL/TP-500-38060.
+- Jonkman, J. (2010). *Definition of the Floating System for Phase
+  IV of OC3*. NREL/TP-500-47535.
+- Robertson, A., Jonkman, J., Masciola, M., Song, H., Goupee, A.,
+  Coulling, A., & Luan, C. (2014). *Definition of the
+  Semisubmersible Floating System for Phase II of OC4*.
+  NREL/TP-5000-60601.
+- Allen, C., Viselli, A., Dagher, H., Goupee, A., Gaertner, E.,
+  Abbas, N., Hall, M., & Barter, G. (2020). *Definition of the
+  UMaine VolturnUS-S Reference Platform Developed for the
+  IEA Wind 15-Megawatt Offshore Reference Wind Turbine*.
+  NREL/TP-5000-76773.
+- Gaertner, E., Rinker, J., Sethuraman, L., Zahle, F., Anderson, B.,
+  Barter, G., et al. (2020). *Definition of the IEA 15-Megawatt
+  Offshore Reference Wind Turbine*. NREL/TP-5000-75698.

pybmodes/_examples/reference_decks/README.md

@@ -0,0 +1,150 @@
+<!-- markdownlint-disable MD013 -->
+# Reference decks with corrected mode-shape polynomial coefficients
+
+## What is this?
+
+Copies of OpenFAST ElastoDyn input files with mode-shape polynomial
+coefficients (`TwFAM1Sh`, `TwFAM2Sh`, `TwSSM1Sh`, `TwSSM2Sh`,
+`BldFl1Sh`, `BldFl2Sh`, `BldEdgSh`) regenerated by pyBmodes from the
+structural-property blocks in the same files.
+
+Six turbine configurations are included — three fixed-base and three
+floating:
+
+- [`nrel5mw_land/`](nrel5mw_land/) — *NREL 5MW Reference Turbine*
+  (Jonkman et al. 2009), land-based.
+- [`nrel5mw_oc3monopile/`](nrel5mw_oc3monopile/) — *NREL 5MW* on the
+  OC3 Monopile (Jonkman & Musial 2010); rigid base, no soil flexibility,
+  SubDyn substructure included for provenance.
+- [`iea34_land/`](iea34_land/) — *IEA-3.4-130-RWT*
+  (Bortolotti et al. 2019, IEA Wind Task 37), land-based.
+- [`nrel5mw_oc3spar/`](nrel5mw_oc3spar/) — *NREL 5MW* on the OC3
+  Hywind floating spar (Jonkman 2010).
+- [`nrel5mw_oc4semi/`](nrel5mw_oc4semi/) — *NREL 5MW* on the OC4
+  DeepCwind semi-submersible (Robertson et al. 2014).
+- [`iea15mw_umainesemi/`](iea15mw_umainesemi/) — *IEA-15-240-RWT* on
+  the UMaine VolturnUS-S semi (Allen et al. 2020); the patched
+  TwSSM2Sh ends at WARN — the constrained 6th-order polynomial form
+  cannot represent this deck's 2nd-SS bending shape below the 1 %
+  PASS gate, a property of the IEA-15 tower's section-property
+  gradient, not a pyBmodes bug.
+
+The floating decks use the same cantilever (`hub_conn = 1`) modal
+basis as the fixed-base decks — see
+[`FLOATING_CASES.md`](FLOATING_CASES.md) for why this is the correct
+basis for ElastoDyn polynomial coefficients on any floating deck.
+
+## Why?
+
+The official upstream `.dat` files for these reference turbines contain
+polynomial coefficients that **do not represent the mode shapes
+produced by the same files' structural inputs**. The 2nd-mode tower
+coefficients (`TwFAM2Sh`, `TwSSM2Sh`) are the worst offenders, with
+RMS residuals 170×–2,500× higher than pyBmodes' own fits. See
+[`cases/ECOSYSTEM_FINDING.md`](https://github.com/SMI-Lab-Inha/pyBModes/blob/master/cases/ECOSYSTEM_FINDING.md)
+for the quantified evidence and the [`VALIDATION_SUMMARY.md`](VALIDATION_SUMMARY.md)
+in this directory for per-block before-and-after numbers across all
+three cases.
+
+The cause is upstream pipeline drift: the polynomial blocks were
+generated against an earlier revision of each turbine's structural
+model and have not been regenerated as the structural blocks were
+iteratively refined. OpenFAST accepts any coefficient set whose
+polynomial evaluates to 1 at the tip — there is no warning when the
+polynomials describe a different mode shape than the structural model
+in the same deck. This directory provides drop-in replacements where
+the polynomial block and the structural block describe the same modes.
+
+## Provenance
+
+| Source | Repository | Commit | Date |
+| --- | --- | --- | --- |
+| NREL 5MW (land + OC3 monopile) | OpenFAST `r-test` | `dd5feaaa` | 2026-03-12 |
+| IEA-3.4-130-RWT | IEA Wind Task 37 RWT repo | `824f8d6` | 2025-09-26 |
+| Regenerated with | pyBmodes | `0753ec2` | (current) |
+
+**Method**: pyBmodes solves the modal eigenvalue problem on the deck's
+structural inputs (15-DOF Bernoulli-Euler beam element, vectorised
+einsum core), then fits constrained 6th-order polynomials with the
+clamped-base + unit-tip constraints
+($\phi(0)=\phi'(0)=0$, $\phi(1)=1$). For tower modes, the rigid-body
+root component is removed before fitting (the **Improved Direct
+Method** described in BModes' Excel mode-shape worksheet,
+`external/BModes/docs/ModeShapePolyFitting.xls`). After regeneration
+every block is pyBmodes' best constrained fit and no block FAILs;
+all blocks reach PASS except one known WARN
+(`iea15mw_umainesemi/TwSSM2Sh` at 1.6 % RMS, an unavoidable
+representation limit of the constrained 6th-order polynomial form
+for that tower's section-property gradient — see
+[`FLOATING_CASES.md`](FLOATING_CASES.md) for the per-deck
+explanation). See [`VALIDATION_SUMMARY.md`](VALIDATION_SUMMARY.md)
+for the per-block before/after numbers.
+
+## How to use
+
+Drop the patched `.dat` files into your OpenFAST case directory,
+replacing the originals. Each case directory is self-contained — the
+ElastoDyn main file references only its sibling `_Tower.dat` and
+`_Blade.dat`, no external `..` traversal — so you can copy the whole
+directory or pick individual files.
+
+The structural-property blocks (mass density, EI, drag coefficients,
+geometric data) are **identical to the upstream files**; only the
+polynomial-coefficient lines are rewritten.
+
+## How to regenerate
+
+The reference decks here are produced by
+[`scripts/build_reference_decks.py`](https://github.com/SMI-Lab-Inha/pyBModes/blob/master/scripts/build_reference_decks.py),
+which copies the upstream sources, runs `pybmodes patch`, and re-runs
+the validator. To regenerate from scratch:
+
+```bash
+python scripts/build_reference_decks.py
+```
+
+To patch your own ElastoDyn deck:
+
+```bash
+pip install pybmodes
+pybmodes validate path/to/your_ElastoDyn.dat   # check consistency
+pybmodes patch path/to/your_ElastoDyn.dat --backup   # regenerate
+```
+
+Or programmatically:
+
+```python
+from pybmodes.elastodyn import compute_tower_params, compute_blade_params, patch_dat
+from pybmodes.models import Tower, RotatingBlade
+
+tower = Tower.from_elastodyn("path/to/MyTurbine_ElastoDyn.dat")
+patch_dat("path/to/MyTurbine_Tower.dat", compute_tower_params(tower.run(n_modes=10)))
+
+blade = RotatingBlade.from_elastodyn("path/to/MyTurbine_ElastoDyn.dat")
+patch_dat("path/to/MyTurbine_Blade.dat", compute_blade_params(blade.run(n_modes=10)))
+```
+
+## Floating configurations
+
+This directory ships three floating cases (OC3 Hywind spar, OC4
+DeepCwind semi, UMaine VolturnUS-S semi) generated via the same
+`Tower.from_elastodyn(...)` path as the fixed-base cases. ElastoDyn
+represents floating tower dynamics as a clamped-base cantilever in
+the platform-attached frame, with platform 6-DOF motion handled
+separately as independent generalised coordinates — so the correct
+modal basis for ElastoDyn polynomials is exactly the cantilever path
+this script already uses, regardless of land or floating. See
+[`FLOATING_CASES.md`](FLOATING_CASES.md) for the ElastoDyn-source-code
+justification and the contrast with `Tower.from_bmi()` (which solves
+the coupled tower + platform eigenproblem and is correct for
+frequency validation against BModes JJ but **not** for ElastoDyn
+polynomial generation — its eigenvectors include platform rigid-body
+motion that the ElastoDyn `SHP` ansatz cannot represent).
+
+## License
+
+The original upstream `.dat` files retain their respective licenses
+(see the `r-test` and IEA Wind Task 37 repositories). pyBmodes' patched
+versions are released under the same Apache 2.0 licence as pyBmodes itself —
+the structural content is unchanged from the upstream files; only the
+polynomial-coefficient lines were rewritten.

pybmodes/_examples/reference_decks/VALIDATION_SUMMARY.md

@@ -0,0 +1,63 @@
+<!-- markdownlint-disable MD013 -->
+# Reference-deck coefficient validation summary
+
+Per-block RMS residual of the polynomial coefficients shipped in each upstream deck (Before) and after pyBmodes regenerated them from the structural inputs in the same deck (After). The ratio column is the upstream `file_rms / pybmodes_rms` — values >> 1 indicate the upstream polynomial does not represent the mode shape produced by the deck's structural inputs.
+
+| Case | Block | Before RMS | After RMS | Ratio before | Status |
+| --- | --- | ---: | ---: | ---: | :---: |
+| nrel5mw_land | TwFAM1Sh | 0.0081 | 0.0000 | 313× | PASS |
+| nrel5mw_land | TwFAM2Sh | 5.0783 | 0.0024 | 2101× | PASS |
+| nrel5mw_land | TwSSM1Sh | 0.0075 | 0.0000 | 293× | PASS |
+| nrel5mw_land | TwSSM2Sh | 5.9009 | 0.0023 | 2529× | PASS |
+| nrel5mw_land | BldFl1Sh | 0.0022 | 0.0008 | 2.82× | PASS |
+| nrel5mw_land | BldFl2Sh | 0.0088 | 0.0035 | 2.48× | PASS |
+| nrel5mw_land | BldEdgSh | 0.0006 | 0.0002 | 3.17× | PASS |
+| nrel5mw_oc3monopile | TwFAM1Sh | 0.0037 | 0.0000 | 140× | PASS |
+| nrel5mw_oc3monopile | TwFAM2Sh | 5.7805 | 0.0032 | 1813× | PASS |
+| nrel5mw_oc3monopile | TwSSM1Sh | 0.0045 | 0.0000 | 173× | PASS |
+| nrel5mw_oc3monopile | TwSSM2Sh | 7.3266 | 0.0033 | 2220× | PASS |
+| nrel5mw_oc3monopile | BldFl1Sh | 0.0022 | 0.0008 | 2.82× | PASS |
+| nrel5mw_oc3monopile | BldFl2Sh | 0.0088 | 0.0035 | 2.48× | PASS |
+| nrel5mw_oc3monopile | BldEdgSh | 0.0006 | 0.0002 | 3.17× | PASS |
+| iea34_land | TwFAM1Sh | 0.0098 | 0.0002 | 56.9× | PASS |
+| iea34_land | TwFAM2Sh | 0.7230 | 0.0042 | 172× | PASS |
+| iea34_land | TwSSM1Sh | 0.0110 | 0.0002 | 64.0× | PASS |
+| iea34_land | TwSSM2Sh | 1.5494 | 0.0041 | 380× | PASS |
+| iea34_land | BldFl1Sh | 0.0106 | 0.0014 | 7.61× | PASS |
+| iea34_land | BldFl2Sh | 0.0051 | 0.0047 | 1.09× | PASS |
+| iea34_land | BldEdgSh | 0.0065 | 0.0014 | 4.62× | PASS |
+| nrel5mw_oc3spar | TwFAM1Sh | 0.0111 | 0.0000 | 350× | PASS |
+| nrel5mw_oc3spar | TwFAM2Sh | 10.6264 | 0.0024 | 4476× | PASS |
+| nrel5mw_oc3spar | TwSSM1Sh | 0.0165 | 0.0000 | 524× | PASS |
+| nrel5mw_oc3spar | TwSSM2Sh | 14.1050 | 0.0027 | 5311× | PASS |
+| nrel5mw_oc3spar | BldFl1Sh | 0.0022 | 0.0008 | 2.82× | PASS |
+| nrel5mw_oc3spar | BldFl2Sh | 0.0088 | 0.0035 | 2.48× | PASS |
+| nrel5mw_oc3spar | BldEdgSh | 0.0006 | 0.0002 | 3.17× | PASS |
+| nrel5mw_oc4semi | TwFAM1Sh | 0.0034 | 0.0000 | 106× | PASS |
+| nrel5mw_oc4semi | TwFAM2Sh | 8.2805 | 0.0024 | 3488× | PASS |
+| nrel5mw_oc4semi | TwSSM1Sh | 0.0048 | 0.0000 | 152× | PASS |
+| nrel5mw_oc4semi | TwSSM2Sh | 9.0396 | 0.0027 | 3404× | PASS |
+| nrel5mw_oc4semi | BldFl1Sh | 0.0033 | 0.0008 | 3.94× | PASS |
+| nrel5mw_oc4semi | BldFl2Sh | 0.0093 | 0.0036 | 2.59× | PASS |
+| nrel5mw_oc4semi | BldEdgSh | 0.0004 | 0.0002 | 2.29× | PASS |
+| iea15mw_umainesemi | TwFAM1Sh | 0.0078 | 0.0001 | 95.8× | PASS |
+| iea15mw_umainesemi | TwFAM2Sh | 0.7922 | 0.0013 | 619× | PASS |
+| iea15mw_umainesemi | TwSSM1Sh | 0.0088 | 0.0001 | 118× | PASS |
+| iea15mw_umainesemi | TwSSM2Sh | 102.4075 | 0.0163 | 6276× | WARN |
+| iea15mw_umainesemi | BldFl1Sh | 0.0048 | 0.0002 | 24.7× | PASS |
+| iea15mw_umainesemi | BldFl2Sh | 0.0021 | 0.0018 | 1.21× | PASS |
+| iea15mw_umainesemi | BldEdgSh | 0.0028 | 0.0008 | 3.73× | PASS |
+
+## Pattern
+
+- **2nd-mode tower coefficients** (`TwFAM2Sh`, `TwSSM2Sh`) show the largest inconsistency on every upstream deck: ratios from ~170× (IEA-3.4) to ~2,500× (NREL 5MW). The shipped polynomials do not represent the 2nd bending mode of the structural inputs by any reasonable metric.
+- **1st-mode tower coefficients** (`TwFAM1Sh`, `TwSSM1Sh`) and blade coefficients (`BldFl1Sh`, `BldFl2Sh`, `BldEdgSh`) show a smaller but non-zero inconsistency (typical ratio ~ 2–300×). Their absolute file RMS values still classify as PASS under the 1 % per-block gate, but they are still drift artefacts from the same generation pipeline.
+- **After patching every block is pyBmodes' best constrained fit and no block FAILs; most blocks reach PASS, one known WARN (`iea15mw_umainesemi / TwSSM2Sh` at 1.6 % RMS) reflects an ElastoDyn basis representation limit for that specific tower's section-property gradient, not a pyBmodes bug.** The After-RMS column matches the pyBmodes-RMS column from the Before report; the polynomials in the patched files are exactly pyBmodes' fits, so the file polynomial reproduces the pyBmodes mode shape modulo the writer's text-precision (~7 sig figs).
+
+## How to reproduce
+
+```bash
+python scripts/build_reference_decks.py
+```
+
+The script copies the upstream sources, runs `pybmodes patch`, and re-runs the validator. See `before_patch.txt` and `validation_report.txt` in each case directory for the raw CLI output.