Domain-aware input validation: guard naive inputs across naval / geotechnical / civil-structural / mechanical

[SMI-Lab-Inha]

Motivation

pyBmodes has strong software-engineering test coverage (closed-form references, round-trips, integration vs BModes), but until 1.11.0 it had thin domain-engineering input validation — it would accept physically implausible inputs from a non-specialist and faithfully compute a meaningless answer. 1.11.0 closed the naval-architecture / seakeeping dimension for the floating path (see below); this issue tracks extending the same rigor to the other disciplines so a geotechnical / civil-structural / mechanical mistake is caught at the door, not buried in the output.

Each turbine class needs a different expert lens:

• Floating → naval architecture / seakeeping
• Monopile → geotechnical + civil-structural
• Land-based → civil-structural + mechanical
• All → mechanical / units sanity

Shipped in 1.11.0 (naval architecture)

check_model floating-readiness gates (hub_conn=2): horizontal CM offset > yaw radius of gyration (WARN), zero added mass hydro_M (WARN), zero total restoring (WARN), non-physical platform inertia (ERROR). See #95.

Hard-won lesson: probe every threshold against the validated RWTs first

Domain heuristics are easy to get wrong because legitimate modelling conventions look "implausible" to a naive check. Concrete example found while scoping this: a longitudinal wave-speed guard √(EA/ρA) (catches the classic "forgot e9" unit error — steel should read ~5000 m/s) false-positives on every land/monopile reference deck, because ElastoDyn-convention towers are modelled axially rigid — axial_stff is a large placeholder (implied ~10⁷ m/s), not the physical E·A. Only the floating samples carry a real EA. So any material check must run on raw user inputs at the construction layer (from_geometry / from_windio*, where real E/rho/D/t are supplied), not on derived SectionProperties in check_model. Other convention traps to respect: unstable-spar negative hydrostatic restoring (legitimate), rank-deficient support matrices (legitimate).

Rule: no domain gate lands without verifying it stays silent on NREL 5MW, OC3/OC4, IEA-3.4/10/15/22, UPSCALE-25.

Candidate checks (by discipline + layer)

Mechanical / units — at the construction layer (from_geometry, from_windio*)

• Material modulus E in a plausible structural range (≈ [1e9, 1e12] Pa — catches GPa↔Pa unit errors). WARN.
• Material density ρ in [100, 25000] kg/m³ (catches kg/m³↔t/m³). WARN.
• These see the user's raw inputs, so they're safe from the axial-rigid placeholder problem above.

Civil-structural — land tower / shell

• Tube D/t ratio plausibility for shell buckling (real towers ≈ 80–250; monopiles ≈ 80–140). Cite DNV-ST-0126 / Eurocode EN 1993-1-6. Use a loose band (e.g. WARN outside [15, 400]) to avoid false positives on thin upper sections. Construction layer (needs D, t).
• Diameter taper sanity (outer diameter should be ~non-increasing base→top). INFO.
• 1st fore-aft frequency in a plausible band (~0.1–1.0 Hz, turbine-size dependent) — post-solve, INFO; catches gross unit/scale errors.

Geotechnical — monopile (largely depends on #97)

• When a monopile model is rigid-clamped at the mudline with no soil springs, INFO that the estimate is non-conservative (soil flexibility lowers the 1st frequency) — pairs with the soil-spring work in WindIO monopile: optional soil springs (soil_eq) for from_windio_with_monopile #97.
• Embedment-length / diameter ratio (L/D for driven monopiles ≈ 5–6) sanity once soil/embedment is modelled.

Naval architecture — floating (mostly done in 1.11.0)

• CM offset, added mass, restoring, platform inertia (1.11.0).
• Optional: per-DOF restoring presence (surge/sway/yaw vs heave/roll/pitch), carefully avoiding the legitimate negative-restoring spar case.

Proposed rollout

Land incrementally, one discipline per PR, each gate threshold confirmed with the maintainer (the domain expert) and RWT-verified silent before merge. WARN for "probably a mistake", ERROR only for strictly non-physical, INFO for "fidelity caveat". Target 1.12.0+.