Merge pull request #126 from SMI-Lab-Inha/docs/document-water-depth-and-auto-rna

docs: document water_depth (#121) and auto-RNA (#82)

Author: SMI-Lab-Inha

docs/api_contract.rst

@@ -106,7 +106,10 @@ Model constructors
        moordyn_dat_path, hydrodyn_dat_path=None)``,
        ``from_geometry(...)``,
        ``from_windio(yaml_path, *, component='tower',
-       thickness_interp='linear')``,
+       thickness_interp='linear', hub_conn=1, tip_mass=None,
+       n_nodes=None, lumped_rna_cal=False)``,
+       ``from_windio_with_monopile(yaml_path, *, tip_mass=None,
+       n_nodes=None, water_depth=None, lumped_rna_cal=False)``,
        ``from_windio_floating(yaml_path, *, ...)``.
 
 Results + serialisation
@@ -312,6 +315,7 @@ I/O
 - :func:`pybmodes.io.out_parser.read_out` (with the
   ``strict=True`` option)
 - :func:`pybmodes.io.windio.read_windio_tubular`
+- :func:`pybmodes.io.windio.read_windio_rna`
 - :func:`pybmodes.io.windio_blade.read_windio_blade`
 - :func:`pybmodes.io.windio_floating.read_windio_floating`
 - :class:`pybmodes.io.errors.ParseError` — unified base class for

docs/quickstart.rst

@@ -148,10 +148,27 @@ without hand-building a ``PlatformSupport``:
 
    tower = Tower.from_windio_with_monopile(
        "IEA-15-240-RWT.yaml", tip_mass=991000.0,
+       water_depth=30.0,     # clamp at the seabed, not the embedded pile tip
    )
    tower.attach_mudline_foundation(f)        # mutates BMI to hub_conn = 3
    modal = tower.run(n_modes=4)
 
+.. note::
+
+   Pass ``water_depth`` whenever the monopile ``reference_axis.z`` runs
+   below the seabed (IEA-15: axis -75 -> +15 m, mudline at -30 m). It
+   clamps the cantilever at the mudline and drops the embedded pile; omit
+   it and that length is modelled as a free cantilever, dropping the
+   frequency well below reference (issue #121). It also auto-reads
+   ``environment.water_depth`` from the ontology when present.
+
+   On an IEA-22-class ontology that carries the hub and nacelle
+   ``elastic_properties_mb`` blocks, ``lumped_rna_cal=True`` derives the
+   tower-top RNA (hub + nacelle + blades) automatically instead of a
+   hand-supplied ``tip_mass`` (issue #82; requires ``hub_conn = 1``, the
+   clamped-base default) — the same flag works on
+   :meth:`~pybmodes.models.Tower.from_windio`.
+
 If you only need the 6 x 6 stiffness block to compose with an
 existing ``PlatformSupport`` you have already built (the
 ``CS_Monopile.bmi`` deck pattern, say), the raw matrix is also

src/pybmodes/__init__.py

@@ -84,13 +84,19 @@
     #                       wall_thickness, *, flexible_length,
     #                       E, rho, nu, outfitting_factor)
     #   Tower.from_windio(yaml_path, *, component, thickness_interp,
-    #       hub_conn, tip_mass, n_nodes)
+    #       hub_conn, tip_mass, n_nodes, lumped_rna_cal)
     #     tip_mass: TipMassProps | float (RNA mass kg); n_nodes:
-    #     refine the FE mesh onto N even stations (issue #35)
+    #     refine the FE mesh onto N even stations (issue #35);
+    #     lumped_rna_cal=True auto-derives the tower-top RNA from the
+    #     ontology's elastic_properties_mb blocks (issue #82; hub_conn=1
+    #     only)
     #   Tower.from_windio_with_monopile(yaml_path, *,
     #       component_tower, component_monopile, thickness_interp,
-    #       tip_mass, n_nodes)  # splice monopile + tower into one
-    #       fixed-bottom cantilever clamped at the mudline (issue #92)
+    #       tip_mass, n_nodes, water_depth, lumped_rna_cal)  # splice
+    #       monopile + tower into one fixed-bottom cantilever clamped at
+    #       the mudline (issue #92); water_depth clamps at the true
+    #       seabed, dropping the embedded pile (issue #121);
+    #       lumped_rna_cal auto-derives the RNA (issue #82)
     #   Tower.from_windio_floating(yaml_path, *, water_depth,
     #                              hydrodyn_dat, moordyn_dat,
     #                              elastodyn_dat)  # coupled FOWT
@@ -112,7 +118,14 @@
     # 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
+    # read_windio_rna: assemble the tower-top RNA lump (hub + nacelle +
+    # blades) from the elastic_properties_mb blocks (issue #82; also the
+    # engine behind ``lumped_rna_cal=True``).
+    from pybmodes.io.windio  import (
+        read_windio_rna,
+        read_windio_tubular,
+        WindIOTubular,
+    )
     # Blade (composite layup -> PreComp-class thin-wall reduction):
     from pybmodes.io.windio_blade import (
         read_windio_blade,