feat: add explicit angle_units override for WindIO rotor angles

The magnitude heuristic cannot resolve a degrees file whose cone and tilt
are both sub-half-degree (a zero-tilt turbine with a fractional-degree
precone reads as radians). Rejecting small values is not an option either,
since a legitimate radians file routinely has a small precone with zero
tilt. Add an explicit escape hatch instead: read_windio_rna gains
angle_units ('auto' | 'rad' | 'deg'), forwarded from Tower.from_windio and
from_windio_with_monopile as rna_angle_units. 'auto' (default) keeps the
pair heuristic for the common case; 'rad' / 'deg' take the file at its word
for the rare ambiguous one. Unknown values are rejected.

Author: SMI-Lab-Inha

src/pybmodes/io/windio.py

@@ -732,32 +732,45 @@ def _finite_float(value: Any, what: str) -> float:
     return f
 
 
-def _windio_rotor_angles(cone_value: Any, uptilt_value: Any) -> tuple[float, float]:
-    """Convert the WindIO precone and shaft tilt to radians, resolving the
-    rad/deg ambiguity once for the pair.
+def _windio_rotor_angles(
+    cone_value: Any, uptilt_value: Any, units: str = "auto"
+) -> tuple[float, float]:
+    """Convert the WindIO precone and shaft tilt to radians.
 
     The WindIO v2 turbine schema annotates ``hub.cone_angle`` and drivetrain
     ``uptilt`` as degrees, but the IEA reference ontologies store radians
-    (IEA-22 ``cone_angle`` 0.0698 = 4 deg, ``uptilt`` 0.1047 = 6 deg). A file
-    uses one convention throughout, so decide it once from the *larger* of the
-    two magnitudes rather than per value: a degrees file reliably carries a
-    several-degree shaft tilt (magnitude well above any radians precone /
-    tilt, which stay under ~0.3 rad), whereas judging each value alone would
-    misread a small schema-conforming degrees angle such as 0.25 deg as
-    0.25 rad. If the larger magnitude exceeds 0.5 the pair is degrees;
-    otherwise radians. Anything above 90 is non-physical either way and is
-    rejected (issue #130 review).
+    (IEA-22 ``cone_angle`` 0.0698 = 4 deg, ``uptilt`` 0.1047 = 6 deg).
+    ``units`` selects how to reconcile that:
+
+    - ``"rad"`` / ``"deg"`` — take the file at its word (no guessing).
+    - ``"auto"`` (default) — a file uses one convention throughout, so decide
+      it once from the *larger* of the two magnitudes: a degrees file reliably
+      carries a several-degree shaft tilt whose magnitude dwarfs any radians
+      precone / tilt (which stay under ~0.3 rad), so the larger angle
+      disambiguates the pair even when the cone is a fraction of a degree.
+      Larger magnitude over 0.5 means degrees, otherwise radians. The
+      residual blind spot is a degrees file whose angles are *both* below
+      ~0.5 deg (e.g. a zero-tilt turbine with a sub-degree precone); it reads
+      as radians. Pass ``units="deg"`` for such a file (issue #130 review).
+
+    Anything above 90 (in the resolved unit) is non-physical and rejected.
     """
     cone = _finite_float(cone_value, "hub cone_angle")
     uptilt = _finite_float(uptilt_value, "nacelle.drivetrain.uptilt")
-    biggest = max(abs(cone), abs(uptilt))
-    if biggest > 90.0:
+    if units not in ("auto", "rad", "deg"):
+        raise ValueError(
+            f"angle_units must be 'auto', 'rad' or 'deg'; got {units!r}."
+        )
+    if units == "auto":
+        biggest = max(abs(cone), abs(uptilt))
+        units = "deg" if biggest > 0.5 else "rad"
+    if max(abs(cone), abs(uptilt)) > 90.0:
         raise ValueError(
             f"rotor precone / shaft tilt (cone_angle={cone!r}, uptilt="
-            f"{uptilt!r}) is non-physical as either radians or degrees; "
-            f"expected values well under 90 deg."
+            f"{uptilt!r}) is non-physical in {units}; expected values well "
+            f"under 90 deg."
         )
-    if biggest > 0.5:  # degrees: a real shaft tilt dwarfs any radians angle
+    if units == "deg":
         return float(np.radians(cone)), float(np.radians(uptilt))
     return cone, uptilt
 
@@ -980,6 +993,7 @@ def read_windio_rna(
     component_hub: str = "hub",
     component_nacelle: str = "nacelle",
     component_blade: str = "blade",
+    angle_units: str = "auto",
 ) -> TipMassProps:
     """Lump the WindIO rotor-nacelle assembly into a tower-top ``TipMassProps``.
 
@@ -1024,6 +1038,12 @@ def read_windio_rna(
     goes beyond the ElastoDyn deck path's bare point-mass lumping, which the
     WindIO ontology's per-station blade mass makes possible.
 
+    ``angle_units`` selects how ``cone_angle`` / ``uptilt`` are read. The
+    WindIO v2 schema annotates them as degrees, but the IEA reference files
+    store radians; ``"auto"`` (default) disambiguates by magnitude (see
+    :func:`_windio_rotor_angles`), while ``"rad"`` / ``"deg"`` take the file
+    at its word for the rare all-sub-degree case ``"auto"`` cannot resolve.
+
     Requires the optional ``[windio]`` extra (PyYAML).
     """
     from pybmodes.io.bmi import TipMassProps
@@ -1112,7 +1132,9 @@ def _nac_geom(key: str) -> float:
     )
     if hub_r < 0.0:
         raise ValueError(f"hub diameter must be non-negative; got {hub_diam!r}.")
-    cone_ang, uptilt = _windio_rotor_angles(hub.get("cone_angle", 0.0), uptilt_raw)
+    cone_ang, uptilt = _windio_rotor_angles(
+        hub.get("cone_angle", 0.0), uptilt_raw, angle_units
+    )
     cone_cos = float(np.cos(cone_ang))
     cone_sin = float(np.sin(cone_ang))
 

src/pybmodes/models/tower.py

@@ -325,6 +325,7 @@ def from_windio(
         tip_mass: TipMassProps | float | None = None,
         n_nodes: int | None = None,
         lumped_rna_cal: bool = False,
+        rna_angle_units: str = "auto",
     ) -> Tower:
         """Build a tower (or monopile) model directly from a **WindIO**
         ontology ``.yaml`` (issue #35).
@@ -372,6 +373,11 @@ def from_windio(
             expressed at the tower top in the clamped-base convention, which
             a free-base / soil-flexible base interprets differently. Default
             ``False``.
+        rna_angle_units : how the auto-RNA reads ``cone_angle`` / ``uptilt``
+            when ``lumped_rna_cal=True``. ``"auto"`` (default) disambiguates
+            the WindIO rad/deg ambiguity by magnitude; pass ``"rad"`` or
+            ``"deg"`` to take the file at its word. Ignored unless
+            ``lumped_rna_cal`` is set.
 
         Notes
         -----
@@ -411,7 +417,7 @@ def from_windio(
                 )
             from pybmodes.io.windio import read_windio_rna
 
-            tip_mass = read_windio_rna(yaml_path)
+            tip_mass = read_windio_rna(yaml_path, angle_units=rna_angle_units)
 
         g = read_windio_tubular(
             yaml_path, component=component, thickness_interp=thickness_interp,
@@ -440,6 +446,7 @@ def from_windio_with_monopile(
         n_nodes: int | None = None,
         water_depth: float | None = None,
         lumped_rna_cal: bool = False,
+        rna_angle_units: str = "auto",
     ) -> Tower:
         """Build a combined **monopile + tower** fixed-bottom cantilever
         from a WindIO ontology ``.yaml`` (issue #92).
@@ -484,6 +491,9 @@ def from_windio_with_monopile(
             blocks via :func:`pybmodes.io.windio.read_windio_rna` and use
             it as ``tip_mass``. Requires an IEA-22-class ontology; mutually
             exclusive with ``tip_mass``. Default ``False``.
+        rna_angle_units : how the auto-RNA reads ``cone_angle`` / ``uptilt``
+            when ``lumped_rna_cal=True`` (``"auto"`` / ``"rad"`` / ``"deg"``);
+            see :meth:`from_windio`. Ignored unless ``lumped_rna_cal`` is set.
 
         Notes
         -----
@@ -509,7 +519,7 @@ def from_windio_with_monopile(
                 )
             from pybmodes.io.windio import read_windio_rna
 
-            tip_mass = read_windio_rna(yaml_path)
+            tip_mass = read_windio_rna(yaml_path, angle_units=rna_angle_units)
 
         mt = read_windio_monopile_tower(
             yaml_path,

tests/test_windio_rna.py

@@ -245,6 +245,42 @@ def _mk(cone: float, uptilt: float):
         assert getattr(deg, attr) == pytest.approx(getattr(rad, attr))
 
 
+def test_rna_explicit_deg_units_override(tmp_path: pathlib.Path) -> None:
+    """The all-sub-degree case auto cannot resolve: a zero-tilt degrees file
+    with a 0.3 deg cone. angle_units='deg' takes the file at its word, so it
+    reads as 0.3 deg, not 0.3 rad (Codex review on #130)."""
+    pytest.importorskip("yaml")
+    import numpy as np
+
+    from pybmodes.io.windio import read_windio_rna
+
+    o = _base_ontology()
+    o["components"]["hub"]["cone_angle"] = 0.3
+    o["components"]["nacelle"]["drivetrain"]["uptilt"] = 0.0
+    p = _write(o, tmp_path, "small_deg.yaml")
+
+    as_deg = read_windio_rna(p, angle_units="deg")
+    # equivalent radians file resolved by auto
+    o2 = _base_ontology()
+    o2["components"]["hub"]["cone_angle"] = float(np.radians(0.3))
+    o2["components"]["nacelle"]["drivetrain"]["uptilt"] = 0.0
+    as_rad = read_windio_rna(_write(o2, tmp_path, "small_rad.yaml"))
+    for attr in ("cm_axial", "ixx", "iyy", "izz"):
+        assert getattr(as_deg, attr) == pytest.approx(getattr(as_rad, attr))
+    # and auto (default) would misread the 0.3 as radians -> different result
+    as_auto = read_windio_rna(p)
+    assert as_auto.izz != pytest.approx(as_deg.izz)
+
+
+def test_rna_rejects_bad_angle_units(tmp_path: pathlib.Path) -> None:
+    """An unknown angle_units value is rejected."""
+    pytest.importorskip("yaml")
+    from pybmodes.io.windio import read_windio_rna
+
+    with pytest.raises(ValueError, match="angle_units"):
+        read_windio_rna(_write(_base_ontology(), tmp_path, "u.yaml"), angle_units="grad")
+
+
 def test_rna_rejects_nonphysical_angle(tmp_path: pathlib.Path) -> None:
     """A value non-physical as both radians and degrees (e.g. 200) is rejected
     rather than silently evaluated at a meaningless angle."""