feat(foundations): introduce type/SSI split API + NREL 5MW OC3 dossier (PR #1/N)

Establishes the new foundation API that separates TYPE (monopile,
tripod, jacket, suction bucket) from SSI FIDELITY (fixed, 6x6, lumped
BNWF, physical BNWF, Craig-Bampton). v1.0 API frozen; legacy path
continues to work with a DeprecationWarning.

Context
-------
op3 v1.0 conflated two axes into one enum: ``FoundationMode.{FIXED,
STIFFNESS_6X6, DISTRIBUTED_BNWF, DISSIPATION_WEIGHTED}`` was described
as "four foundation modes" but actually encodes SSI fidelity levels,
not foundation topologies. There is no place for a Tripod or Jacket
to live its own geometry, mass, and coupling interface.

This PR scaffolds the clean split so model-by-model V&V&C work can
begin. The pattern is validated against the smallest published
monopile benchmark (NREL 5MW OC3 Phase I, Passon 2008). Tripod and
Jacket land in future PRs.

New API surface
---------------
- op3/foundations/base.py
  * FoundationType enum (MONOPILE, TRIPOD, JACKET, SUCTION_BUCKET, GBS)
  * FoundationProtocol (duck-typed contract)
  * BaseFoundation ABC with as_legacy_foundation() back-compat bridge
- op3/foundations/types/monopile.py
  * Monopile dataclass with diameter, wall thickness, embed length,
    stub length, soil profile, material properties
  * .from_oc3_spec() factory for NREL 5MW OC3 Phase I geometry
  * .from_yaml(model_dir) factory loading from dossier
  * .with_ssi(strategy) fluent API; .head_stiffness_6x6() queries it
- op3/ssi/base.py: SSIProtocol
- op3/ssi/stiffness_6x6.py: Stiffness6x6 strategy (pre-computed K,
  .rigid() fixed-base factory, .from_csv() loader)
- op3/ssi/pisa.py: PISA strategy wrapping pisa_pile_stiffness_6x6

Dossier pattern
---------------
op3/models/nrel_5mw_oc3_monopile/ becomes the template for every
future validated model:
- site.yaml: site metadata, references, DOIs
- geometry.yaml: foundation + tower + RNA geometry with provenance
- soil.yaml: layered soil profile (placeholder for OC3 Phase I, real
  profile comes from OC3 Phase II/III in PR #2)
- vvc.yaml: Verification / Validation / Calibration dossier with
  per-metric RED / YELLOW / GREEN status, acceptance tolerances,
  reference citations, and test module pointers
- build.py: build_monopile(ssi) and build_tower_model(ssi) entry
  points using the new API; bridges to op3.composer for eigen

A model is only cleared for use in dissertation results when every
vvc.yaml metric reads GREEN. PR #1 ships the nrel_5mw_oc3_monopile
dossier with one metric GREEN (f1_Hz_oc3_coupled within 5% of the
Passon 2008 benchmark: 0.2815 Hz vs 0.276 Hz published, 2% error)
and the rest NOT-STARTED / BLOCKED pending PR #2.

Back-compat
-----------
- op3/foundations.py is now a package (not a module); all legacy
  imports (``from op3.foundations import Foundation, FoundationMode,
  build_foundation, apply_scour_relief, foundation_from_pisa``) are
  preserved verbatim via ``op3/foundations/_legacy.py`` +
  ``op3/foundations/__init__.py`` re-export.
- build_foundation() now emits DeprecationWarning pointing at the
  new API. The Monopile back-compat bridge constructs Foundation()
  directly and is deprecation-silent.
- composer.py, opensees_foundations/*, openfast_coupling/*,
  standards/*, uq/*, anchors/*, and all existing tests are
  UNCHANGED. The 271-framework + 134-anchor regression suite
  remains green.

Tests (tests/test_model_nrel_5mw_oc3_monopile.py, 11 new)
---------------------------------------------------------
- Dossier files exist
- Monopile.from_oc3_spec / from_yaml contract
- head_stiffness_6x6 without SSI raises clearly
- with_ssi chaining, rigid K > 1e19 diagonal
- as_legacy_foundation returns STIFFNESS_6X6 with correct provenance
- Bridge emits no DeprecationWarning; direct build_foundation() does
- compose_tower_model accepts bridged Foundation
- f1 eigen matches OC3 Phase I within 5% (Passon 2008)

405 tests passing (271 framework + 134 anchors, 11 skipped).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Kyeong Sun Kim

op3/foundations/__init__.py

@@ -0,0 +1,66 @@
+"""
+Op^3 foundations package.
+
+Two coexisting APIs:
+
+1. **Legacy API (frozen at v1.0)** — re-exported from
+   :mod:`op3.foundations._legacy`. Emits :class:`DeprecationWarning`
+   when :func:`build_foundation` is called. Will be removed in v2.0.
+
+2. **New type/SSI API (v1.1+)** — :mod:`op3.foundations.types`
+   provides concrete foundation topologies (``Monopile``, ``Tripod``,
+   ``Jacket``, ``SuctionBucket``); :mod:`op3.ssi` provides SSI
+   fidelity strategies (``Fixed``, ``Stiffness6x6``, ``BNWFLumped``,
+   ``BNWFPhysical``, ``CraigBampton``). Each model under
+   :mod:`op3.models` is a validated-dossier instance that combines
+   the two.
+
+Import cheat sheet
+------------------
+>>> # Legacy (still works; DeprecationWarning)
+>>> from op3.foundations import build_foundation, FoundationMode
+>>>
+>>> # New types
+>>> from op3.foundations.types import Monopile
+>>> from op3.ssi import Stiffness6x6
+>>>
+>>> # Foundation protocol (for duck-typing / type hints)
+>>> from op3.foundations.base import FoundationProtocol
+
+The package import surface is intentionally thin: everything below is
+re-exported from either ``_legacy`` (with a deprecation trail) or
+``base`` (the new protocol). Concrete types are NOT re-exported here;
+import them explicitly from :mod:`op3.foundations.types`.
+"""
+from __future__ import annotations
+
+# Re-export the legacy API verbatim so ``from op3.foundations import
+# Foundation, FoundationMode, build_foundation, apply_scour_relief,
+# foundation_from_pisa`` continues to work for every v1.0 caller.
+from op3.foundations._legacy import (
+    Foundation,
+    FoundationMode,
+    apply_scour_relief,
+    build_foundation,
+    foundation_from_pisa,
+)
+
+# New-API surface (opt-in).
+from op3.foundations.base import (
+    BaseFoundation,
+    FoundationProtocol,
+    FoundationType,
+)
+
+__all__ = [
+    # Legacy (deprecated)
+    "Foundation",
+    "FoundationMode",
+    "apply_scour_relief",
+    "build_foundation",
+    "foundation_from_pisa",
+    # New
+    "BaseFoundation",
+    "FoundationProtocol",
+    "FoundationType",
+]

op3/foundations.py op3/foundations/_legacy.pyop3/foundations.py renamed to op3/foundations/_legacy.py

@@ -1,55 +1,32 @@
 """
-Op^3 foundation module factory.
-
-This module exposes the four OpenSeesPy foundation representations that
-differ in fidelity from "fixed base" (Mode A) to "dissipation-weighted
-generalized BNWF" (Mode D). All four modes share the same tower
-interface, so they can be swapped at runtime with a single flag.
-
-The OpenSeesPy code that actually builds the springs and zero-length
-elements lives in `op3.opensees_foundations.*`. This module is a thin
-factory that picks the right builder based on the mode name.
-
-The geotechnical/structural integration is the key contribution here:
-the CSV schema produced by OptumGX (bearing capacity envelopes, contact
-pressures, plastic dissipation fields) maps directly into the spring
-parameters consumed by OpenSeesPy. Each mode uses a different subset of
-this mapping.
-
-Mode A (fixed):
-    Does not use any OptumGX data. Fixes the tower base with `fix` on
-    all six DOF.
-
-Mode B (stiffness_6x6):
-    Reads a 6x6 stiffness matrix from CSV and attaches it as a single
-    zeroLength element at the tower base. The matrix is typically
-    derived from OpenSeesPy Mode C or D via static condensation.
-
-Mode C (distributed_bnwf):
-    Reads depth-resolved spring stiffness and ultimate resistance from
-    `opensees_spring_stiffness.csv` (produced by OptumGX) and builds
-    a chain of lateral p-y and vertical t-z springs along the bucket
-    skirt. Applies a stress-correction relief factor for scour.
-
-Mode D (dissipation_weighted):
-    Extends Mode C with a depth-dependent participation factor w(z)
-    derived from the plastic dissipation field at collapse. This is
-    the generalized cavity expansion framework of Appendix A of the
-    dissertation.
-
-Example
--------
-
->>> from op3 import build_foundation
->>> f = build_foundation(
-...     mode='distributed_bnwf',
-...     spring_profile='data/fem_results/opensees_spring_stiffness.csv',
-...     scour_depth=1.5,
-... )
->>> f.attach_to_opensees(base_node=1000)  # called by the composer
+LEGACY Op^3 foundation factory (frozen at v1.0).
+
+This module is the original ``op3.foundations`` module moved verbatim
+into a submodule of the new ``op3.foundations`` package. The public
+API (``Foundation``, ``FoundationMode``, ``build_foundation``,
+``apply_scour_relief``, ``foundation_from_pisa``) is preserved for
+backwards compatibility and re-exported by ``op3.foundations.__init__``.
+
+A :class:`DeprecationWarning` is emitted when ``build_foundation`` or
+``FoundationMode`` is used, pointing to the new
+:mod:`op3.foundations.types` API (``Monopile``, ``Tripod``, ``Jacket``,
+``SuctionBucket``) introduced in v1.1+. The legacy path will remain
+functional until the next major version bump.
+
+The four original modes (A/B/C/D) represent **SSI fidelity levels**
+(fixed / 6x6 / lumped-BNWF / dissipation-weighted BNWF) — they are
+NOT foundation types. The new API separates the axes:
+
+    FoundationType (Monopile, Tripod, Jacket, ...) x
+    SSIStrategy   (Fixed, Stiffness6x6, BNWFLumped, BNWFPhysical, CraigBampton)
+
+Concrete foundation topologies with their own mass, geometry, and
+coupling interface now live under :mod:`op3.foundations.types`; SSI
+strategies live under :mod:`op3.ssi`.
 """
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
@@ -60,12 +37,18 @@
 
 
 class FoundationMode(str, Enum):
-    """The five Op^3 foundation representations.
+    """The five Op^3 foundation representations (LEGACY, frozen at v1.0).
 
     The first four are the original v1.0 fidelity ladder (Modes A-D).
     ``distributed_bnwf_nonlinear`` (v1.1+) is the blueprint Q1(a) primary:
     a physically-distributed skirt column with per-depth PySimple1/
     TzSimple1 backbones.
+
+    **Deprecation notice (v1.1+):** these values represent SSI fidelity
+    levels, not foundation types. New code should use the type/SSI
+    split under :mod:`op3.foundations.types` and :mod:`op3.ssi`. The
+    legacy ``build_foundation(mode=...)`` path remains functional
+    throughout v1.x.
     """
     FIXED = "fixed"
     STIFFNESS_6X6 = "stiffness_6x6"
@@ -188,14 +171,24 @@ def build_foundation(
     skirt_length_m: Optional[float] = None,
     skirt_thickness_m: float = 0.025,
     physical: bool = False,
+    _suppress_deprecation_warning: bool = False,
 ) -> Foundation:
-    """Construct a Foundation handle ready for the composer.
+    """Construct a Foundation handle ready for the composer (LEGACY API).
+
+    **Deprecated (v1.1+):** use :mod:`op3.foundations.types` and
+    :mod:`op3.ssi` for new code. Example:
+
+    >>> from op3.foundations.types import Monopile
+    >>> from op3.ssi import Stiffness6x6
+    >>> mono = Monopile.from_oc3_spec(soil_profile=...)
+    >>> mono.with_ssi(Stiffness6x6(K=mono.head_stiffness_6x6()))
 
     Parameters
     ----------
     mode : str
         One of 'fixed', 'stiffness_6x6', 'distributed_bnwf',
-        'dissipation_weighted'. Case-insensitive.
+        'dissipation_weighted', 'distributed_bnwf_nonlinear'.
+        Case-insensitive.
     spring_profile : str or Path, optional
         Path to a CSV with columns (depth_m, k_ini_kN_per_m,
         p_ult_kN_per_m, spring_type). Required for Modes C and D.
@@ -211,12 +204,22 @@ def build_foundation(
         resistance scaling.
     scour_depth : float, default 0.0
         Scour depth in meters. Affects Modes B, C, D.
-
-    Returns
-    -------
-    Foundation
-        An opaque handle the composer can attach to an OpenSees model.
+    _suppress_deprecation_warning : bool
+        Internal flag used by ``op3.foundations.types`` adapters to
+        avoid spurious deprecation noise on the back-compat bridge.
     """
+    if not _suppress_deprecation_warning:
+        warnings.warn(
+            "op3.foundations.build_foundation (and FoundationMode) are "
+            "frozen at v1.0 and will be removed in v2.0. Use the new "
+            "type/SSI split: op3.foundations.types.{Monopile,Tripod,"
+            "Jacket,SuctionBucket} + op3.ssi.{Fixed,Stiffness6x6,"
+            "BNWFLumped,BNWFPhysical,CraigBampton}. See "
+            "op3/models/<name>/build.py for reference use.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
     try:
         mode_enum = FoundationMode(mode.lower())
     except ValueError:
@@ -358,4 +361,3 @@ def foundation_from_pisa(
         f"L={embed_length_m} m, {len(soil_profile)} soil layers"
     )
     return foundation
-