physmap 0.2.0__py3-none-any.whl

physmap/closures/index.py

@@ -0,0 +1,393 @@
+"""Open closure INDEX — public coverage, no verdicts.
+
+The closure *index* is the open-core "coverage is public, bounds are paid" map:
+metadata for every closure PhysMAP knows about, carrying NO ranges, NO provenance,
+NO contested/confirmation/disposition content of any kind. It ships in the core
+wheel so a seed-only install can resolve a regime or a free-text closure name to a
+`closure_id`, report what is covered, and tell the three "no bounds here" cases
+apart — without shipping the moat.
+
+This is DISTINCT from `physmap.closures.registry.REGISTRY`, the executable formula
+bridge (carries `fn` + cached `re_range`/`ra_range` that the substrate engine reads
+at runtime). The registry stays internal; the index is the public surface.
+
+Data lives in the bundled `physmap/closures/data/closure_index.json` (generated by
+`build_index_json()` from the canonical corpus + registry geometry + the alias map;
+regenerate with `python -m physmap.closures.index --rebuild`). The runtime only
+READS the JSON via importlib.resources — it never needs the premium corpus.
+
+Resolution semantics (consumed by the guardrail) distinguish, for a requested
+closure_id:
+  * in the active corpus            → case 1  (bounds available now)
+  * in premium_coverage, not active → case 2a (bounds in premium, not the seed)
+  * in the index, no bounds anywhere → case 2b (registered, not yet curated)
+  * not in the index                → case 3  (nothing registered)
+Cases 2b/3 embed a pre-filled GitHub issue URL — inert text, no telemetry.
+"""
+
+from __future__ import annotations
+
+import importlib.resources as _ir
+import json
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from urllib.parse import quote
+
+_INDEX_PACKAGE = "physmap.closures.data"
+_INDEX_FILENAME = "closure_index.json"
+_COVERAGE_PACKAGE = "physmap.corpus.data"
+_COVERAGE_FILENAME = "premium_coverage.json"
+
+# Repo that receives closure-request issues (cases 2b/3). The URL is inert text in
+# an error message; the user clicking it is the entire (zero-telemetry) signal.
+ISSUE_REPO = "cloudronin/physmap"
+
+
+@dataclass(frozen=True)
+class ClosureMeta:
+    """Public, verdict-free metadata for one known closure."""
+    closure_id: str
+    closure_name: str
+    closure_family: str
+    geometry_class: str
+    physics_coordinates: tuple[str, ...]
+    citation: str
+    aliases: tuple[str, ...] = field(default_factory=tuple)
+
+
+# ── load the bundled index (runtime; no premium corpus required) ──────────────
+def _load_index_json() -> dict:
+    # Tolerant of a missing file so the module imports during its own --rebuild
+    # bootstrap; at runtime the JSON is always present as bundled package data.
+    try:
+        return json.loads((_ir.files(_INDEX_PACKAGE) / _INDEX_FILENAME).read_text("utf-8"))
+    except (FileNotFoundError, ModuleNotFoundError):
+        return {"closures": []}
+
+
+def _build_runtime_index() -> dict[str, ClosureMeta]:
+    out: dict[str, ClosureMeta] = {}
+    for d in _load_index_json().get("closures", []):
+        out[d["closure_id"]] = ClosureMeta(
+            closure_id=d["closure_id"],
+            closure_name=d.get("closure_name", ""),
+            closure_family=d.get("closure_family", ""),
+            geometry_class=d.get("geometry_class", ""),
+            physics_coordinates=tuple(d.get("physics_coordinates", [])),
+            citation=d.get("citation", ""),
+            aliases=tuple(d.get("aliases", [])),
+        )
+    return out
+
+
+CLOSURE_INDEX: dict[str, ClosureMeta] = _build_runtime_index()
+
+
+#: Size of the committed index. The packaging test asserts this, because an index
+#: that fails to load does not raise -- it comes back empty, and an empty index
+#: reports every closure as unregistered while every import still succeeds.
+EXPECTED_INDEX_SIZE = 201
+
+
+def verify_index_loaded() -> int:
+    """Raise unless the bundled closure index actually loaded. Returns its size."""
+    n = len(CLOSURE_INDEX)
+    if n == 0:
+        raise RuntimeError(
+            "the bundled closure index loaded as EMPTY. This almost always means "
+            "package data did not ship: check that pyproject.toml still sets "
+            "`where = [\"src\"]` under [tool.setuptools.packages.find] and that "
+            "closures/data/*.json is listed in [tool.setuptools.package-data]."
+        )
+    return n
+
+
+def premium_coverage_ids() -> set[str]:
+    """closure_ids that have curated bounds in the PREMIUM corpus (ids only — the
+    bundled coverage map carries no bound values)."""
+    data = json.loads((_ir.files(_COVERAGE_PACKAGE) / _COVERAGE_FILENAME).read_text("utf-8"))
+    return set(data.get("closure_ids", []))
+
+
+# ── free-text closure matching (direct naming = the high-fidelity demand signal)
+def _norm(s: str) -> str:
+    return re.sub(r"[^a-z0-9]+", " ", s.lower()).strip()
+
+
+def match_closure(text: str) -> str | None:
+    """Resolve a free-text closure name to a closure_id via id/name/alias match.
+
+    Exact (normalized) match on closure_id, closure_name, or any alias wins; failing
+    that, a unique substring match against an alias/name is accepted. Ambiguous or
+    no match → None (the caller raises case 3)."""
+    if not text:
+        return None
+    q = _norm(text)
+    # 1. exact id
+    for cid, meta in CLOSURE_INDEX.items():
+        if q == _norm(cid):
+            return cid
+    # 2. exact name or alias
+    for cid, meta in CLOSURE_INDEX.items():
+        if q == _norm(meta.closure_name) or any(q == _norm(a) for a in meta.aliases):
+            return cid
+    # 3. unique substring of an alias/name (e.g. "sst" → menter-sst-1994)
+    hits = {cid for cid, meta in CLOSURE_INDEX.items()
+            if any(q in _norm(a) or _norm(a) in q for a in (meta.aliases + (meta.closure_name,)))}
+    return hits.pop() if len(hits) == 1 else None
+
+
+class ClosureResolutionError(ValueError):
+    """Raised by CredibilityGuardrail.fit when a requested closure resolves but its
+    validated bounds are not available in the active corpus (cases 2a/2b/3).
+
+    Subclasses ValueError so existing `except ValueError` paths still catch it,
+    while tests can target the resolution case specifically."""
+    def __init__(self, message: str, *, case: "ResolutionCase | None" = None):
+        super().__init__(message)
+        self.case = case
+
+
+class ResolutionCase(str, Enum):
+    """How a requested closure resolves against the active corpus / coverage / index."""
+    ACTIVE = "1"          # bounds present in the ACTIVE corpus → normal operation
+    PREMIUM_ONLY = "2a"   # bounds in premium coverage but not the active (seed) corpus
+    NO_BOUNDS = "2b"      # registered in the index, but no bounds curated in any tier
+    UNREGISTERED = "3"    # not in the index at all
+
+
+def classify_closure(closure_id: str, active_ids: set[str]) -> ResolutionCase:
+    """Classify a resolved closure_id into the resolution-semantics case."""
+    if closure_id in active_ids:
+        return ResolutionCase.ACTIVE
+    if closure_id in premium_coverage_ids():
+        return ResolutionCase.PREMIUM_ONLY
+    if closure_id in CLOSURE_INDEX:
+        return ResolutionCase.NO_BOUNDS
+    return ResolutionCase.UNREGISTERED
+
+
+def resolution_message(name: str, case: ResolutionCase, *, facets: dict | None = None) -> str:
+    """The factual, one-line error text for a non-active case (no upsell prose).
+
+    `name` is the closure_id (2a/2b) or the regime/free-text the user asked for (3).
+    Cases 2b and 3 embed a pre-filled GitHub issue URL — inert text, no telemetry."""
+    if case is ResolutionCase.PREMIUM_ONLY:
+        return (f"closure {name} resolved for this regime; validated bounds are not in "
+                f"the seed corpus (available in the premium corpus).")
+    if case is ResolutionCase.NO_BOUNDS:
+        return (f"closure {name} is registered; validated bounds are not yet curated. "
+                f"To prioritize, file an issue: {issue_url(name, facets)}")
+    if case is ResolutionCase.UNREGISTERED:
+        return (f"no closure registered for {name}. If this closure should be covered, "
+                f"file an issue: {issue_url(name, facets)}")
+    return ""  # ACTIVE has no error
+
+
+def issue_url(name: str, facets: dict | None = None) -> str:
+    """Pre-filled GitHub closure-request issue URL (inert text; no network)."""
+    title = quote(f"closure-request: {name}")
+    body_lines = [f"Closure requested: {name}", ""]
+    if facets:
+        body_lines.append("Regime facets:")
+        body_lines += [f"- {k}: {v}" for k, v in facets.items()]
+    body = quote("\n".join(body_lines))
+    return f"https://github.com/{ISSUE_REPO}/issues/new?title={title}&body={body}"
+
+
+# ── dev-only: regenerate the bundled index from corpus + registry ─────────────
+# Common alternate names for free-text matching. Keyed by closure_id; merged with
+# auto-derived tokens at build time. Author-extend as the index grows.
+ALIASES: dict[str, tuple[str, ...]] = {
+    "gnielinski-1976": ("Gnielinski", "Gnielinski 1976", "Gnielinski correlation"),
+    "dittus-boelter-1930": ("Dittus-Boelter", "Dittus Boelter", "DB correlation"),
+    "sieder-tate-1936": ("Sieder-Tate", "Sieder Tate"),
+    "petukhov-1970": ("Petukhov", "Petukhov-Kirillov"),
+    "blasius-pohlhausen-flat-plate-forced-1921": ("Pohlhausen", "Blasius-Pohlhausen", "flat plate laminar"),
+    "mcadams-vertical-plate-natural-1954": ("McAdams", "McAdams vertical plate"),
+    "modified-sparrow-cur-asym-narrow-rect-channel-2014": ("Forrest", "Sparrow-Cur", "modified Sparrow-Cur"),
+    "menter-sst-1994": ("SST", "Menter SST", "k-omega SST", "SST k-omega"),
+    "wilcox-k-omega-2006": ("k-omega", "Wilcox k-omega", "komega"),
+    "launder-spalding-k-epsilon-1974": ("k-epsilon", "standard k-epsilon", "Launder-Spalding"),
+    "spalart-allmaras-1992": ("Spalart-Allmaras", "SA model", "S-A"),
+    "aung-worku-mixed-convection-1986": ("Aung-Worku", "mixed convection tube"),
+    "rohsenow-pool-boiling-1952": ("Rohsenow", "Rohsenow pool boiling"),
+    "zuber-chf-1959": ("Zuber", "Zuber CHF", "critical heat flux"),
+}
+
+
+# Approved closure-index expansion (docs/PhysMAP_Registry_Expansion_Candidates_v0_1.md).
+# The markdown table is the human-readable source of truth; build_index_json() parses
+# it at rebuild time and merges the candidates (metadata-only, case-2b) with the
+# corpus-derived entries. Family is taken from the section the row sits under.
+from pathlib import Path as _Path
+
+from physmap._paths import checkout_path as _checkout_path
+
+_CANDIDATES_MD_PARTS = ("docs", "PhysMAP_Registry_Expansion_Candidates_v0_1.md")
+
+
+def _candidates_md() -> _Path:
+    """The approved candidate table. Checkout-only; raises if absent.
+
+    Resolved lazily and loudly on purpose. This file supplies 147 of the 201
+    indexed closures. An earlier version skipped it when missing, which turned a
+    broken path into a quietly three-quarters-empty index that still imported,
+    still ran, and answered "unregistered" for closures that are registered.
+    """
+    return _checkout_path(*_CANDIDATES_MD_PARTS, what="the approved closure-index candidate table")
+
+# Section number/letter -> closure_family. Sections not listed (Summary, Decisions,
+# §15 coords, §16 excluded, the §7 parent) carry no candidates and map to None.
+_SECTION_FAMILY: dict[str, str] = {
+    "1": "condensation", "2": "external-convection", "3": "natural-convection",
+    "4": "rans-turbulence", "5": "interfacial-force", "6": "radiation",
+    "7a": "single-phase-convection", "7b": "hydraulic-friction",
+    "7c": "transfer-analogy", "7d": "surface-enhancement", "7e": "packed-porous",
+    "8": "cardio", "9": "aero", "10": "combustion-kinetics",
+    "11": "species-diffusion", "12": "non-newtonian-rheology", "13": "rarefied-gas",
+}
+# Per-entry family overrides where a section is heterogeneous (§4 wall treatments
+# belong to the corpus `wall-function` family, not the RANS default).
+_FAMILY_OVERRIDE: dict[str, str] = {
+    "spalding-law-of-the-wall-1961": "wall-function",
+    "van-driest-damping-1956": "wall-function",
+    "kader-temperature-wall-1981": "wall-function",
+    "jayatilleke-p-function-1969": "wall-function",
+}
+
+_SECTION_RE = re.compile(r"^#{2,3}\s+(\d+[a-e]?)\.")
+_SLUG_RE = re.compile(r"[a-z0-9][a-z0-9-]+$")
+
+
+def parse_candidate_rows(md_text: str) -> list[dict]:
+    """Parse the approved candidate table into metadata-only index entries.
+
+    Tracks the current family section; emits one entry per 5-column candidate row
+    (id | name | coordinates | citation | aliases). Non-family tables (Summary,
+    the §14 corrections table) sit under family=None and are skipped."""
+    out: list[dict] = []
+    family: str | None = None
+    for line in md_text.splitlines():
+        m = _SECTION_RE.match(line)
+        if m:
+            family = _SECTION_FAMILY.get(m.group(1))
+            continue
+        if not family or not line.lstrip().startswith("|") or line.count("|") < 6:
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) < 5 or not _SLUG_RE.fullmatch(cells[0]):
+            continue  # skips the "closure_id" header (underscore) and "---" separators
+        cid, name, coords, citation, aliases = cells[:5]
+        out.append({
+            "closure_id": cid,
+            "closure_name": name,
+            "closure_family": _FAMILY_OVERRIDE.get(cid, family),
+            "geometry_class": "",
+            "physics_coordinates": [c.strip() for c in coords.split(",") if c.strip()],
+            "citation": citation,
+            "aliases": sorted({a.strip() for a in aliases.split(",") if a.strip()}),
+        })
+    return out
+
+
+def build_index_json() -> dict:
+    """Build the index payload from the CANONICAL corpus + registry + the approved
+    expansion candidates (dev-only; needs the premium tree). Metadata only —
+    names/families/coords/citations/aliases. No bounds, no provenance, no disposition."""
+    from physmap.corpus import calibration as cc
+    from physmap.closures.registry import REGISTRY
+
+    entries = cc.load_corpus(cc.DEFAULT_PATH)
+    by_geom = {cid: e.geometry_class for cid, e in REGISTRY.items()}
+
+    def primary_citation(entry) -> str:
+        for b in entry.validated_range:
+            c = (b.provenance or {}).get("citation")
+            if c:
+                # first sentence/clause — concise, still public bibliographic
+                return c.split(". Restated")[0].split(". Modified")[0].strip()
+        return ""
+
+    closures = []
+    seen = set()
+    for e in entries:
+        seen.add(e.closure_id)
+        auto = tuple(w for w in _norm(e.closure_id).split() if len(w) > 2)
+        closures.append({
+            "closure_id": e.closure_id,
+            "closure_name": e.closure_name,
+            "closure_family": e.closure_family,
+            "geometry_class": by_geom.get(e.closure_id, ""),
+            "physics_coordinates": list(e.physics_coordinates),
+            "citation": primary_citation(e),
+            "aliases": sorted(set(ALIASES.get(e.closure_id, ())) | set(auto)),
+        })
+
+    # Registry closures with NO corpus entry (e.g. churchill) — case-2b by
+    # construction; include so they are nameable/coverable.
+    for cid, reg in REGISTRY.items():
+        if cid in seen:
+            continue
+        name = cid.replace("-", " ").title()
+        closures.append({
+            "closure_id": cid,
+            "closure_name": name,
+            "closure_family": "",
+            "geometry_class": reg.geometry_class,
+            "physics_coordinates": list(reg.required_inputs),
+            "citation": (reg.note or "").split(".")[0],
+            "aliases": sorted(set(ALIASES.get(cid, ()))),
+        })
+
+    # Approved expansion candidates (metadata-only, case-2b by construction).
+    n_corpus = len(closures)
+    if True:
+        for cand in parse_candidate_rows(_candidates_md().read_text(encoding="utf-8")):
+            if cand["closure_id"] in seen:
+                continue
+            seen.add(cand["closure_id"])
+            closures.append(cand)
+    n_candidates = len(closures) - n_corpus
+
+    closures.sort(key=lambda d: d["closure_id"])
+    return {
+        "_comment": "Open closure INDEX — public coverage metadata ONLY (id, name, "
+                    "family, geometry, coordinates, citation, aliases). Verdict-free: "
+                    "carries no bounds and no curation status. Generated by "
+                    "physmap.closures.index.build_index_json() from the corpus + registry "
+                    f"+ the approved expansion table ({n_corpus} curated + {n_candidates} "
+                    "case-2b candidates).",
+        "version": cc_version(),
+        "n_closures": len(closures),
+        "closures": closures,
+    }
+
+
+def cc_version() -> str:
+    try:
+        from physmap.guardrail.corpus_regimes import CALIBRATION_CORPUS_VERSION
+        return CALIBRATION_CORPUS_VERSION
+    except Exception:
+        return "unknown"
+
+
+def _rebuild_to_disk() -> None:
+    from pathlib import Path
+    payload = build_index_json()
+    out = Path(__file__).resolve().parent / "data" / _INDEX_FILENAME
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(payload, ensure_ascii=True, indent=2) + "\n", encoding="utf-8")
+    print(f"wrote {out} ({payload['n_closures']} closures)")
+
+
+if __name__ == "__main__":
+    import argparse
+    ap = argparse.ArgumentParser(description="closure index — rebuild the bundled JSON")
+    ap.add_argument("--rebuild", action="store_true", help="regenerate closure_index.json from the canonical corpus")
+    if ap.parse_args().rebuild:
+        _rebuild_to_disk()
+    else:
+        print(f"{len(CLOSURE_INDEX)} closures in the bundled index "
+              f"(run with --rebuild to regenerate from the corpus)")