physmap 0.2.0__py3-none-any.whl

physmap/__init__.py

@@ -0,0 +1,61 @@
+"""PhysMAP — physics-aware credibility checks for AI surrogates.
+
+Two distinct methods live here, and they are deliberately kept apart:
+
+**Closure validity and surrogate observability.** A surrogate trained on (Re, Pr) is
+blind to x/D, so it fails silently in a pipe entrance region -- and so do input-space
+novelty detectors, because they see only (Re, Pr) too. This path reads the bound
+variable from the test coordinates, checks it against the closure's validated range,
+and knows at fit time whether that variable is structurally observable to the
+surrogate. Where it is observable, the guard defers to the statistical baselines.
+
+**Causal materiality.** A mechanism outside its calibration range only matters if it
+materially reaches the requested quantity of interest. This path flags a prediction
+only when a mechanism is both out of range AND material to that QoI.
+
+These are different claims with different evidence. Nothing in this package attributes
+the results of one to the other. See `physmap.release` for what this build may claim.
+
+No LLM is in any path. Explanations are deterministic rendered templates.
+"""
+
+from __future__ import annotations
+
+from physmap.release import (
+    CURRENT_RELEASE_STATE,
+    EvidenceState,
+    ReleaseState,
+)
+
+__version__ = "0.2.0"
+
+
+# The CredibilityGuardrail public surface is re-exported LAZILY (PEP 562). A bare
+# `import physmap` must stay free of numpy, sklearn, scipy and joblib -- a test
+# asserts it -- while `from physmap import CredibilityGuardrail` pulls the
+# guardrail and its scientific stack, which is fair because you are about to use
+# the guard. Adding an eager import here breaks that guarantee silently.
+_GUARDRAIL_EXPORTS = frozenset({
+    "CredibilityGuardrail",
+    "Regime", "DetectorKind", "DensityMethod", "AggregatorKind", "Device",
+    "Observability", "Verdict", "Disposition",
+    "NoveltyDetectorConfig", "DistanceDetectorConfig", "GPVarianceDetectorConfig",
+    "ClosureValidityDetectorConfig", "ColumnMap", "DetectorResult", "Assessment",
+})
+
+_RELEASE_EXPORTS = frozenset({
+    "CURRENT_RELEASE_STATE", "ReleaseState", "EvidenceState",
+})
+
+__all__ = ["__version__", *sorted(_RELEASE_EXPORTS), *sorted(_GUARDRAIL_EXPORTS)]
+
+
+def __getattr__(name: str):
+    if name in _GUARDRAIL_EXPORTS:
+        import physmap.guardrail as _g
+        return getattr(_g, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | _GUARDRAIL_EXPORTS)

physmap/_paths.py

@@ -0,0 +1,69 @@
+"""Repo-checkout paths, resolved once and failing loudly.
+
+Several artifacts in this project live in the CHECKOUT, not in the installed
+package: the digitised NACA fixture, the regime/observability mapping, the
+registry-expansion table, and the benchmark substrate CSVs. They are deliberately
+outside the wheel -- see the note on redistribution in LICENSE-CORPUS, and the
+README's warning that the benchmark requires an editable install.
+
+The trap this module exists to close: code that derives such a path with
+``Path(__file__).parents[n]`` silently produces a WRONG path under the src/
+layout rather than an error, and a caller that catches FileNotFoundError then
+degrades quietly. A missing corpus becomes an empty corpus, and an empty corpus
+still runs -- it just answers nothing. Every resolver here raises instead.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = ["repo_root", "checkout_path", "have_checkout", "CheckoutRequired"]
+
+_MARKERS = ("pyproject.toml", ".git")
+REPO_URL = "https://github.com/cloudronin/physmap"
+
+
+class CheckoutRequired(FileNotFoundError):
+    """Checkout-only data was needed from an installed wheel.
+
+    A FileNotFoundError, so every existing handler still catches it. The CLI catches it by
+    name and prints this one sentence instead of a traceback.
+    """
+
+    def __init__(self, what: str):
+        self.what = what
+        super().__init__(
+            f"this needs {what} from the repository checkout, and a pip-installed wheel "
+            f"does not include that data. Clone {REPO_URL} and run `pip install -e .` inside "
+            f"the clone to use it."
+        )
+
+
+def repo_root() -> Path | None:
+    """The checkout root, or None when running from an installed wheel."""
+    for parent in Path(__file__).resolve().parents:
+        if any((parent / m).exists() for m in _MARKERS):
+            return parent
+    return None
+
+
+def have_checkout() -> bool:
+    return repo_root() is not None
+
+
+def checkout_path(*parts: str, what: str) -> Path:
+    """A path inside the checkout. Raises unless it exists.
+
+    `what` names the artifact in the error, so a failure says which file is
+    missing and why it is not in the wheel.
+    """
+    root = repo_root()
+    if root is None:
+        raise CheckoutRequired(what)
+    p = root.joinpath(*parts)
+    if not p.exists():
+        raise FileNotFoundError(
+            f"{what} not found at {p}. Expected it in the checkout at "
+            f"{'/'.join(parts)}."
+        )
+    return p

physmap/applicability/fixtures.py

@@ -0,0 +1,83 @@
+"""Declarative screening fixtures. Stated cases, not measured ones.
+
+Two cases were screened out of the original study. They are reproduced here as
+DECLARATIVE fixtures: their preconditions are asserted from the case description, not
+read from data, because the evidence inputs and provenance for them are not available.
+
+What they demonstrate is the refusal logic and its reason codes. What they are not is
+executable evidence-backed cases, and nothing in the output lets them read as such --
+every result carries `evidence_state = DECLARATIVE`, and the CLI prints it.
+
+They become measured cases only when their evidence inputs and provenance arrive. Until
+then a fixture that claimed otherwise would be the exact error this project is about:
+a stated thing wearing the clothes of a measured one.
+"""
+
+from __future__ import annotations
+
+from physmap.applicability.screen import ScreenResult, screen_case
+from physmap.release import EvidenceState
+
+__all__ = ["FIXTURE_IDS", "conjugate_heat_transfer", "fda_blood_pump", "get_fixture"]
+
+FIXTURE_IDS = ("conjugate-heat-transfer", "fda-blood-pump")
+
+
+def conjugate_heat_transfer() -> ScreenResult:
+    """Solid-fluid conjugate heat transfer, QoI = peak solid temperature.
+
+    Screened out because the QoI does not decompose over fluid-side mechanisms. Peak
+    solid temperature is set by conduction through the solid coupled to the fluid-side
+    heat flux; removing a fluid-side convection mechanism changes the coupled boundary
+    condition rather than subtracting a term. There is no "the same case with buoyancy
+    off" whose peak temperature differs only by the buoyancy contribution.
+    """
+    return screen_case(
+        "conjugate-heat-transfer", "peak_solid_temperature",
+        qoi_decomposes=False,
+        mechanisms_separable=False,
+        has_calibration_window=True,
+        ablation_available=None,
+        evidence_state=EvidenceState.DECLARATIVE,
+        notes=(
+            "Preconditions are asserted from the case description, not measured.",
+            "Reported to demonstrate refusal logic only.",
+        ),
+    )
+
+
+def fda_blood_pump() -> ScreenResult:
+    """FDA benchmark centrifugal blood pump, QoI = haemolysis index.
+
+    Screened out because the mechanisms are not separable. The haemolysis index
+    integrates a damage model along pathlines through a rotating machine; shear
+    generation, turbulence and residence time are coupled through the same flow field.
+    Switching one off does not hold the others fixed -- it produces a different flow.
+    """
+    return screen_case(
+        "fda-blood-pump", "haemolysis_index",
+        qoi_decomposes=True,
+        mechanisms_separable=False,
+        has_calibration_window=True,
+        ablation_available=None,
+        evidence_state=EvidenceState.DECLARATIVE,
+        notes=(
+            "Preconditions are asserted from the case description, not measured.",
+            "Reported to demonstrate refusal logic only.",
+        ),
+    )
+
+
+_FIXTURES = {
+    "conjugate-heat-transfer": conjugate_heat_transfer,
+    "fda-blood-pump": fda_blood_pump,
+}
+
+
+def get_fixture(case_id: str) -> ScreenResult:
+    try:
+        return _FIXTURES[case_id]()
+    except KeyError:
+        raise KeyError(
+            f"unknown screening fixture {case_id!r}; available: {list(FIXTURE_IDS)}"
+        ) from None

physmap/applicability/screen.py

@@ -0,0 +1,99 @@
+"""The applicability screen: is the causal method even the right tool here?
+
+Cheap, and deliberately run first. The causal method needs three things to be true of a
+case: the quantity of interest must decompose, the mechanism must be separable enough to
+remove on its own, and an ablation must be obtainable. Where any of those fails, the right
+answer is a refusal with a reason code -- not a confident number produced by machinery
+operating outside the conditions it assumes.
+
+A refusal here is a result. It is also the cheapest honest output the method has.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from physmap.release import EvidenceState
+
+__all__ = ["Applicability", "ReasonCode", "ScreenResult", "screen_case"]
+
+
+class Applicability(str, Enum):
+    APPLICABLE = "applicable"
+    NOT_APPLICABLE = "not_applicable"
+    INSUFFICIENT_EVIDENCE = "insufficient_evidence"
+
+
+class ReasonCode(str, Enum):
+    #: The QoI is not a sum or blend over mechanisms, so removing one is undefined.
+    QOI_DOES_NOT_DECOMPOSE = "qoi_does_not_decompose"
+    #: The mechanisms are coupled: you cannot switch one off and hold the rest fixed.
+    MECHANISMS_NOT_SEPARABLE = "mechanisms_not_separable"
+    #: No calibration window is recorded, so "outside calibration" has no meaning.
+    NO_CALIBRATION_WINDOW = "no_calibration_window"
+    #: No matched ablation is obtainable for this case.
+    NO_ABLATION_AVAILABLE = "no_ablation_available"
+    #: Everything needed is present.
+    SATISFIED = "satisfied"
+
+
+@dataclass(frozen=True)
+class ScreenResult:
+    case_id: str
+    qoi: str
+    applicability: Applicability
+    reason_code: ReasonCode
+    rationale: str
+    evidence_state: EvidenceState
+    notes: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def is_declarative(self) -> bool:
+        return self.evidence_state is EvidenceState.DECLARATIVE
+
+
+def screen_case(
+    case_id: str,
+    qoi: str,
+    *,
+    qoi_decomposes: bool | None,
+    mechanisms_separable: bool | None,
+    has_calibration_window: bool | None,
+    ablation_available: bool | None,
+    evidence_state: EvidenceState,
+    notes: tuple[str, ...] = (),
+) -> ScreenResult:
+    """Screen a case. `None` for any precondition means "not established", which is
+    INSUFFICIENT_EVIDENCE -- distinct from establishing that it is false."""
+
+    def _r(app: Applicability, code: ReasonCode, why: str) -> ScreenResult:
+        return ScreenResult(
+            case_id=case_id, qoi=qoi, applicability=app, reason_code=code,
+            rationale=why, evidence_state=evidence_state, notes=tuple(notes),
+        )
+
+    checks = (
+        (qoi_decomposes, ReasonCode.QOI_DOES_NOT_DECOMPOSE,
+         f"the quantity of interest ({qoi}) does not decompose over mechanisms, so "
+         f"removing one is not defined"),
+        (mechanisms_separable, ReasonCode.MECHANISMS_NOT_SEPARABLE,
+         "the mechanisms are coupled: one cannot be switched off while the others are "
+         "held fixed, so an ablation would change more than the mechanism under test"),
+        (has_calibration_window, ReasonCode.NO_CALIBRATION_WINDOW,
+         "no calibration window is recorded, so 'outside calibration' has no meaning "
+         "for this case"),
+        (ablation_available, ReasonCode.NO_ABLATION_AVAILABLE,
+         "no matched ablation is obtainable, so the counterfactual cannot be formed"),
+    )
+
+    for value, code, why in checks:
+        if value is None:
+            return _r(Applicability.INSUFFICIENT_EVIDENCE, code,
+                      f"not established whether {why.split(',')[0]}")
+        if value is False:
+            return _r(Applicability.NOT_APPLICABLE, code, why)
+
+    return _r(Applicability.APPLICABLE, ReasonCode.SATISFIED,
+              "quantity of interest decomposes, mechanisms are separable, a calibration "
+              "window is recorded, and a matched ablation is obtainable")