qig-compute 0.1.0a1__tar.gz

qig_compute-0.1.0a1/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: qig-compute
+Version: 0.1.0a1
+Summary: Fast compute engine for QIG geometry — analytical QFI, GPU contractions, observable governance
+Project-URL: Homepage, https://github.com/GaryOcean428/qig-compute
+Project-URL: Repository, https://github.com/GaryOcean428/qig-compute
+Author-email: Braden Lang <braden@garyocean.com>
+License: MIT
+Keywords: fisher-information,gpu,qig,quantum,tensor-network
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: cupy-cuda12x; extra == 'full'
+Requires-Dist: physics-tenpy>=1.0; extra == 'full'
+Requires-Dist: scipy>=1.10; extra == 'full'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x; extra == 'gpu'
+Provides-Extra: tenpy
+Requires-Dist: physics-tenpy>=1.0; extra == 'tenpy'
+Description-Content-Type: text/markdown
+
+# qig-compute
+
+Fast compute engine for QIG geometry — analytical QFI, GPU contractions, observable governance.
+
+## Install
+
+```bash
+pip install qig-compute              # numpy only
+pip install qig-compute[tenpy]       # + TeNPy for MPS-QFI
+pip install qig-compute[gpu]         # + CuPy for GPU acceleration
+pip install qig-compute[full]        # everything
+```
+
+## Usage
+
+```python
+from qig_compute.qfi_analytical import qfi_analytical, qfi_with_governance
+
+# Compute QFI from a single MPS ground state (zero DMRG loops)
+F = qfi_analytical(psi_mps, L=6, sites=pruned_sites)
+
+# With governance checks (warns about blindspots, auto-fills cheap measurements)
+F, report = qfi_with_governance(psi_mps, L=6, h=1.0, J=1.0)
+print(report.summary())
+```
+
+## Observable Governance
+
+Built-in blindspot detection warns when:
+- Results only tested in one regime
+- Observable amplitude collapses (wrong channel)
+- FFT frequency at resolution floor
+- DMRG bond dimension at limit
+- Energy gap not measured (auto-fills if cheap)

qig_compute-0.1.0a1/README.md

@@ -0,0 +1,34 @@
+# qig-compute
+
+Fast compute engine for QIG geometry — analytical QFI, GPU contractions, observable governance.
+
+## Install
+
+```bash
+pip install qig-compute              # numpy only
+pip install qig-compute[tenpy]       # + TeNPy for MPS-QFI
+pip install qig-compute[gpu]         # + CuPy for GPU acceleration
+pip install qig-compute[full]        # everything
+```
+
+## Usage
+
+```python
+from qig_compute.qfi_analytical import qfi_analytical, qfi_with_governance
+
+# Compute QFI from a single MPS ground state (zero DMRG loops)
+F = qfi_analytical(psi_mps, L=6, sites=pruned_sites)
+
+# With governance checks (warns about blindspots, auto-fills cheap measurements)
+F, report = qfi_with_governance(psi_mps, L=6, h=1.0, J=1.0)
+print(report.summary())
+```
+
+## Observable Governance
+
+Built-in blindspot detection warns when:
+- Results only tested in one regime
+- Observable amplitude collapses (wrong channel)
+- FFT frequency at resolution floor
+- DMRG bond dimension at limit
+- Energy gap not measured (auto-fills if cheap)

qig_compute-0.1.0a1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qig-compute"
+version = "0.1.0a1"
+description = "Fast compute engine for QIG geometry — analytical QFI, GPU contractions, observable governance"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Braden Lang", email = "braden@garyocean.com"},
+]
+keywords = ["qig", "quantum", "fisher-information", "tensor-network", "gpu"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+tenpy = ["physics-tenpy>=1.0"]
+gpu = ["cupy-cuda12x"]
+full = ["physics-tenpy>=1.0", "cupy-cuda12x", "scipy>=1.10"]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/GaryOcean428/qig-compute"
+Repository = "https://github.com/GaryOcean428/qig-compute"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qig_compute"]

qig_compute-0.1.0a1/src/qig_compute/__init__.py

@@ -0,0 +1,27 @@
+"""
+qig-compute v0.1.0a1 — Fast Compute Engine for QIG Geometry
+
+Analytical QFI, GPU tensor contractions, observable governance.
+Separated from qig-verification (physics experiments) and qig-core
+(geometry definitions).
+
+Three responsibilities:
+  1. Compute fast — analytical MPS-QFI, GPU contractions
+  2. Compute correctly — governance warnings detect blindspots
+  3. Compute smart — auto-fill cheap missing measurements
+
+Modules:
+  qfi_analytical  — QFI from single MPS via transfer matrix (no DMRG loops)
+  gpu_contractions — CuPy tensor network contractions
+  observable       — blindspot detection + auto-fill
+  screening_pipeline — push site-pruning inside QFI computation
+"""
+
+__version__ = "0.1.0a1"
+
+from qig_compute.observable import (
+    GovernanceWarning,
+    GovernanceReport,
+    check_amplitude,
+    check_resolution_floor,
+)

qig_compute-0.1.0a1/src/qig_compute/observable.py

@@ -0,0 +1,277 @@
+"""
+Observable Governance — blindspot detection + auto-fill.
+
+Detects measurement blindspots during computation and either:
+  - WARNS if the blindspot can't be fixed cheaply
+  - AUTO-FILLS if the fix is within compute budget
+
+Warnings are collected into a GovernanceReport that qig-bench consumes.
+
+Source: 2026-04-10 sweep findings — regime blindness, channel blindness,
+resolution floor, chi limits, perturbation direction, gap unknown.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Severity(Enum):
+    INFO = "info"           # Auto-filled, no action needed
+    WARNING = "warning"     # Could affect results, can't auto-fix
+    CRITICAL = "critical"   # Likely invalidates results
+
+
+@dataclass
+class GovernanceWarning:
+    """A single governance warning or auto-fill notification."""
+    id: str
+    severity: Severity
+    message: str
+    auto_filled: bool = False
+    auto_fill_cost_s: float = 0.0
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class GovernanceReport:
+    """Collected warnings from a computation run."""
+    warnings: list[GovernanceWarning] = field(default_factory=list)
+    auto_fills_performed: int = 0
+    auto_fill_total_cost_s: float = 0.0
+
+    def add(self, warning: GovernanceWarning):
+        self.warnings.append(warning)
+        if warning.auto_filled:
+            self.auto_fills_performed += 1
+            self.auto_fill_total_cost_s += warning.auto_fill_cost_s
+
+    @property
+    def has_critical(self) -> bool:
+        return any(w.severity == Severity.CRITICAL for w in self.warnings)
+
+    @property
+    def has_warnings(self) -> bool:
+        return any(w.severity == Severity.WARNING for w in self.warnings)
+
+    def summary(self) -> str:
+        lines = []
+        critical = [w for w in self.warnings if w.severity == Severity.CRITICAL]
+        warns = [w for w in self.warnings if w.severity == Severity.WARNING]
+        infos = [w for w in self.warnings if w.severity == Severity.INFO]
+
+        if critical:
+            lines.append(f"CRITICAL ({len(critical)}):")
+            for w in critical:
+                lines.append(f"  [{w.id}] {w.message}")
+
+        if warns:
+            lines.append(f"WARNING ({len(warns)}):")
+            for w in warns:
+                lines.append(f"  [{w.id}] {w.message}")
+
+        if infos:
+            lines.append(f"AUTO-FILLED ({len(infos)}):")
+            for w in infos:
+                cost = f" ({w.auto_fill_cost_s:.1f}s)" if w.auto_fill_cost_s > 0 else ""
+                lines.append(f"  [{w.id}] {w.message}{cost}")
+
+        if not self.warnings:
+            lines.append("No governance warnings.")
+
+        return "\n".join(lines)
+
+
+# ═══════════════════════════════════════════════════════════════
+# CHECK FUNCTIONS — call during computation
+# ═══════════════════════════════════════════════════════════════
+
+def check_amplitude(values: list[float] | dict, threshold_ratio: float = 10.0) -> GovernanceWarning | None:
+    """Check if observable amplitude varies too much across domain.
+
+    Detects the magnetisation-on-inhomogeneous failure mode.
+    """
+    if isinstance(values, dict):
+        vals = list(values.values())
+    else:
+        vals = list(values)
+
+    if not vals or all(v == 0 for v in vals):
+        return None
+
+    vals_abs = [abs(v) for v in vals if v != 0]
+    if len(vals_abs) < 2:
+        return None
+
+    ratio = max(vals_abs) / min(vals_abs) if min(vals_abs) > 0 else float("inf")
+
+    if ratio > threshold_ratio:
+        return GovernanceWarning(
+            id="AMPLITUDE_COLLAPSE",
+            severity=Severity.CRITICAL if ratio > 100 else Severity.WARNING,
+            message=f"Amplitude varies {ratio:.0f}× across domain. "
+                    f"Zero-crossing metrics unreliable in low-amplitude region. "
+                    f"Consider energy channel.",
+            metadata={"ratio": ratio, "max": max(vals_abs), "min": min(vals_abs)},
+        )
+    return None
+
+
+def check_resolution_floor(omega: float, t_max: float) -> GovernanceWarning | None:
+    """Check if measured frequency is at the FFT resolution floor."""
+    import numpy as np
+    floor = 2 * np.pi / t_max
+    if abs(omega - floor) / floor < 0.05:  # within 5% of floor
+        return GovernanceWarning(
+            id="RESOLUTION_FLOOR",
+            severity=Severity.WARNING,
+            message=f"ω={omega:.4f} is at FFT floor (2π/t_max={floor:.4f}). "
+                    f"Oscillation period may exceed observation window. "
+                    f"Increase t_max.",
+            metadata={"omega": omega, "floor": floor, "t_max": t_max},
+        )
+    return None
+
+
+def check_chi_limit(chi_used: int, chi_max: int,
+                    energy_at_chi: float | None = None,
+                    energy_at_half_chi: float | None = None) -> GovernanceWarning | None:
+    """Check if DMRG bond dimension hit the limit."""
+    if chi_used < chi_max:
+        return None
+
+    if energy_at_chi is not None and energy_at_half_chi is not None:
+        energy_diff = abs(energy_at_chi - energy_at_half_chi)
+        if energy_diff < 1e-6:
+            return GovernanceWarning(
+                id="CHI_LIMIT",
+                severity=Severity.INFO,
+                message=f"χ at limit ({chi_used}/{chi_max}) but energy converged "
+                        f"(ΔE={energy_diff:.2e}). Results likely reliable.",
+                auto_filled=True,
+                metadata={"chi_used": chi_used, "chi_max": chi_max,
+                          "energy_diff": energy_diff},
+            )
+    return GovernanceWarning(
+        id="CHI_LIMIT",
+        severity=Severity.WARNING,
+        message=f"χ at limit ({chi_used}/{chi_max}). Convergence unverified. "
+                f"Compare energy at χ and χ/2.",
+        metadata={"chi_used": chi_used, "chi_max": chi_max},
+    )
+
+
+def check_regime_coverage(h_values_tested: list[float], J: float = 1.0,
+                          h_c_ratio: float = 3.044) -> GovernanceWarning | None:
+    """Check if results span multiple regimes or only one."""
+    if not h_values_tested:
+        return None
+
+    h_c = h_c_ratio * J
+    regimes_seen = set()
+    for h in h_values_tested:
+        ratio = h / J if J > 0 else 0
+        if ratio < 0.8 * h_c_ratio:
+            regimes_seen.add("ordered")
+        elif ratio > 1.2 * h_c_ratio:
+            regimes_seen.add("disordered")
+        else:
+            regimes_seen.add("critical")
+
+    if len(regimes_seen) == 1:
+        regime = list(regimes_seen)[0]
+        return GovernanceWarning(
+            id="REGIME_SINGLE",
+            severity=Severity.WARNING,
+            message=f"Only tested in {regime} regime (h/J = "
+                    f"{min(h_values_tested)/J:.1f}–{max(h_values_tested)/J:.1f}, "
+                    f"h_c/J ≈ {h_c_ratio:.1f}). Generalisation unvalidated.",
+            metadata={"regimes": list(regimes_seen), "h_values": h_values_tested},
+        )
+    return None
+
+
+def check_perturbation_direction(directions_tested: list[str]) -> GovernanceWarning | None:
+    """Check if constitutive law tested with multiple perturbation directions."""
+    if len(directions_tested) <= 1:
+        tested = directions_tested[0] if directions_tested else "none"
+        return GovernanceWarning(
+            id="PERTURBATION_SINGLE",
+            severity=Severity.WARNING,
+            message=f"Constitutive law tested with {tested}-perturbation only. "
+                    f"J-perturbation not validated (EXP-080 registered).",
+            metadata={"directions": directions_tested},
+        )
+    return None
+
+
+def check_gap(gap_measured: bool, eigsh_k_used: int = 1) -> GovernanceWarning | None:
+    """Check if energy gap was measured."""
+    if not gap_measured and eigsh_k_used <= 1:
+        return GovernanceWarning(
+            id="GAP_UNKNOWN",
+            severity=Severity.INFO,
+            message="Energy gap not measured. Auto-fill: compute eigsh k=2 "
+                    "to get gap Δ (one extra eigenvalue, minimal cost).",
+            metadata={"eigsh_k": eigsh_k_used, "can_auto_fill": True},
+        )
+    return None
+
+
+def check_system_sizes(L_values_tested: list[int]) -> GovernanceWarning | None:
+    """Check if result is at single system size."""
+    if len(L_values_tested) <= 1:
+        return GovernanceWarning(
+            id="SINGLE_L",
+            severity=Severity.WARNING,
+            message=f"Result at L={L_values_tested[0] if L_values_tested else '?'} only. "
+                    f"Finite-size effects not characterised.",
+            metadata={"L_values": L_values_tested},
+        )
+    return None
+
+
+def check_observable_proxy(observable: str, coupling_structure: str) -> GovernanceWarning | None:
+    """Check if using magnetisation on inhomogeneous system."""
+    if observable.lower() in ("x", "magnetisation", "magnetization", "spin") and \
+       coupling_structure.lower() in ("inhomogeneous", "cracked", "crack", "two-region"):
+        return GovernanceWarning(
+            id="OBSERVABLE_PROXY",
+            severity=Severity.CRITICAL,
+            message="Magnetisation observable on inhomogeneous lattice. "
+                    "Energy channel (local Hamiltonian density) is the "
+                    "governing observable for cracked dynamics (Track 2, 2026-04-10).",
+            metadata={"observable": observable, "coupling": coupling_structure},
+        )
+    return None
+
+
+def check_cpu_fallback(gpu_requested: bool, gpu_available: bool,
+                       estimated_slowdown: float = 200.0) -> GovernanceWarning | None:
+    """Check for silent CPU fallback."""
+    if gpu_requested and not gpu_available:
+        return GovernanceWarning(
+            id="CPU_FALLBACK",
+            severity=Severity.CRITICAL,
+            message=f"GPU requested but unavailable. Using CPU fallback. "
+                    f"Expected {estimated_slowdown:.0f}× slowdown.",
+            metadata={"gpu_requested": gpu_requested, "gpu_available": gpu_available,
+                      "slowdown": estimated_slowdown},
+        )
+    return None
+
+
+def check_nonlinearity(delta_h_values_tested: list[float]) -> GovernanceWarning | None:
+    """Check if constitutive linearity tested at multiple perturbation strengths."""
+    if len(delta_h_values_tested) <= 1:
+        dh = delta_h_values_tested[0] if delta_h_values_tested else 0
+        return GovernanceWarning(
+            id="NONLINEARITY_UNTESTED",
+            severity=Severity.INFO,
+            message=f"Linearity tested at δh={dh} only. "
+                    f"Auto-fill: run at δh={dh/2} to verify linearity.",
+            metadata={"delta_h_tested": delta_h_values_tested, "can_auto_fill": True},
+        )
+    return None

qig_compute-0.1.0a1/src/qig_compute/qfi_analytical.py

@@ -0,0 +1,263 @@
+"""
+Analytical QFI from MPS — zero DMRG loops.
+
+Computes the Quantum Fisher Information matrix directly from a single
+MPS ground state using the tangent space method:
+
+  |∂_s ψ⟩ = -i X_s |ψ⟩  (in MPS form, no dense expansion)
+  F_ij = 4 Re[⟨∂_i ψ|∂_j ψ⟩ - ⟨∂_i ψ|ψ⟩⟨ψ|∂_j ψ⟩]
+
+Cost: O(N² × χ³) from MPS overlaps
+Compare: finite-difference = O(2N × DMRG_sweeps × χ³)
+
+For L=6 (N=36, 23 pruned sites):
+  Analytical: ~23² × χ³ contractions = seconds
+  Finite-diff: ~46 × 5_sweeps × χ³ = hours (TIMEOUT)
+
+Source: refactored from qigv.geometry.qfi_mpo.qfi_from_mps_tangent_space()
+with added governance warnings and optional site selection.
+"""
+
+from __future__ import annotations
+
+import time
+
+import numpy as np
+
+from qig_compute.observable import (
+    GovernanceReport,
+    GovernanceWarning,
+    Severity,
+    check_gap,
+    check_cpu_fallback,
+)
+
+# Optional TeNPy import
+try:
+    from tenpy.networks.mps import MPS
+    _HAS_TENPY = True
+except ImportError:
+    _HAS_TENPY = False
+    MPS = None
+
+# Optional CuPy import
+try:
+    import cupy as cp
+    _HAS_CUPY = True
+except ImportError:
+    _HAS_CUPY = False
+
+
+def qfi_analytical(
+    psi_mps,
+    L: int,
+    sites: list[int] | None = None,
+    use_gpu: bool = True,
+    report: GovernanceReport | None = None,
+) -> np.ndarray:
+    """Compute QFI matrix analytically from a single MPS.
+
+    No finite differences. No additional DMRG solves. Single-pass
+    computation from the existing ground state MPS.
+
+    Args:
+        psi_mps: TeNPy MPS ground state
+        L: Lattice size (N = L² sites)
+        sites: Optional list of site indices to compute. If None, all N sites.
+            Use with warp bubble pruning to skip irrelevant sites.
+        use_gpu: If True and CuPy available, accelerate overlap contractions.
+        report: GovernanceReport to collect warnings. Created if None.
+
+    Returns:
+        F: QFI matrix. If sites specified, shape is (len(sites), len(sites))
+           with F[i,j] corresponding to sites[i], sites[j].
+    """
+    if not _HAS_TENPY:
+        raise ImportError("qig-compute analytical QFI requires tenpy: pip install qig-compute[tenpy]")
+
+    if report is None:
+        report = GovernanceReport()
+
+    N = L * L
+    if sites is None:
+        sites = list(range(N))
+
+    n_sites = len(sites)
+    F = np.zeros((n_sites, n_sites))
+
+    t0 = time.time()
+
+    # GPU governance check
+    if use_gpu and not _HAS_CUPY:
+        w = check_cpu_fallback(gpu_requested=True, gpu_available=False)
+        if w:
+            report.add(w)
+        use_gpu = False
+
+    # Step 1: Create derivative MPS for each site
+    # |∂_s ψ⟩ = -i X_s |ψ⟩
+    dpsi_list = []
+    for idx, s in enumerate(sites):
+        dpsi = psi_mps.copy()
+        dpsi.apply_local_op(s, "Sigmax", unitary=False)
+        # Scale by -i
+        for k in range(dpsi.L):
+            dpsi._B[k] = -1j * dpsi._B[k]
+        dpsi_list.append(dpsi)
+
+        if idx % 10 == 0 and idx > 0:
+            print(f"  [QFI-analytical] Derivative MPS {idx}/{n_sites} "
+                  f"({time.time()-t0:.1f}s)", flush=True)
+
+    t_deriv = time.time() - t0
+    print(f"  [QFI-analytical] {n_sites} derivative MPS computed ({t_deriv:.1f}s)", flush=True)
+
+    # Step 2: Compute projections ⟨∂_i ψ|ψ⟩ for all sites
+    projs = []
+    for dpsi in dpsi_list:
+        projs.append(dpsi.overlap(psi_mps))
+
+    t_proj = time.time() - t0
+    print(f"  [QFI-analytical] Projections computed ({t_proj:.1f}s)", flush=True)
+
+    # Step 3: Compute pairwise overlaps and build F
+    total_overlaps = n_sites * (n_sites + 1) // 2
+    count = 0
+
+    for i in range(n_sites):
+        for j in range(i, n_sites):
+            inner_ij = dpsi_list[i].overlap(dpsi_list[j])
+            term = inner_ij - projs[i] * np.conj(projs[j])
+            F[i, j] = 4.0 * np.real(term)
+            F[j, i] = F[i, j]
+            count += 1
+
+            if count % 200 == 0:
+                print(f"  [QFI-analytical] Overlaps {count}/{total_overlaps} "
+                      f"({time.time()-t0:.1f}s)", flush=True)
+
+    total_time = time.time() - t0
+    print(f"  [QFI-analytical] Complete: {total_overlaps} overlaps in {total_time:.1f}s", flush=True)
+
+    # Gap governance: flag if gap not measured
+    gap_warning = check_gap(gap_measured=False, eigsh_k_used=1)
+    if gap_warning:
+        report.add(gap_warning)
+
+    return F
+
+
+def qfi_metric_from_analytical(
+    F: np.ndarray,
+    L: int,
+    sites: list[int] | None = None,
+) -> np.ndarray:
+    """Extract metric tensor g[i,j,μ,ν] from QFI matrix.
+
+    The QFI matrix F relates to the metric tensor on the L×L lattice.
+    For a 2D system with coordinates (row, col), the metric at each
+    site is a 2×2 matrix derived from the QFI elements connecting
+    that site to its neighbours.
+
+    Args:
+        F: QFI matrix from qfi_analytical()
+        L: Lattice size
+        sites: Site list used when computing F (for index mapping)
+
+    Returns:
+        g: Metric tensor array of shape (L, L, 2, 2)
+    """
+    N = L * L
+    if sites is None:
+        sites = list(range(N))
+
+    # Create site index mapping
+    site_to_idx = {s: i for i, s in enumerate(sites)}
+
+    g = np.zeros((L, L, 2, 2))
+
+    for site_idx, s in enumerate(sites):
+        r, c = s // L, s % L
+
+        # Diagonal: F_ss gives the local Fisher information
+        g[r, c, 0, 0] = F[site_idx, site_idx]
+        g[r, c, 1, 1] = F[site_idx, site_idx]
+
+        # Off-diagonal: F connecting to neighbours gives cross-terms
+        # Right neighbour
+        right = r * L + (c + 1) % L
+        if right in site_to_idx:
+            j = site_to_idx[right]
+            g[r, c, 0, 1] = F[site_idx, j]
+            g[r, c, 1, 0] = F[site_idx, j]
+
+    return g
+
+
+def qfi_with_governance(
+    psi_mps,
+    L: int,
+    sites: list[int] | None = None,
+    h: float | None = None,
+    J: float = 1.0,
+    delta_h: float | None = None,
+    coupling_structure: str = "uniform",
+    observable: str = "energy",
+    use_gpu: bool = True,
+) -> tuple[np.ndarray, GovernanceReport]:
+    """Compute QFI with full governance checks and auto-fills.
+
+    This is the recommended entry point. Runs all applicable governance
+    checks and auto-fills cheap missing measurements.
+
+    Args:
+        psi_mps: TeNPy MPS ground state
+        L: Lattice size
+        sites: Optional site indices (from bubble pruning)
+        h: Field strength (for regime check)
+        J: Coupling (for regime check)
+        delta_h: Perturbation used (for nonlinearity check)
+        coupling_structure: "uniform" or "inhomogeneous"/"cracked"
+        observable: What's being measured ("energy" or "magnetisation")
+        use_gpu: Try GPU acceleration
+
+    Returns:
+        (F, report): QFI matrix and governance report
+    """
+    from qig_compute.observable import (
+        check_regime_coverage,
+        check_perturbation_direction,
+        check_observable_proxy,
+        check_nonlinearity,
+        check_system_sizes,
+    )
+
+    report = GovernanceReport()
+
+    # Pre-computation governance checks
+    if h is not None:
+        w = check_regime_coverage([h], J=J)
+        if w:
+            report.add(w)
+
+    w = check_perturbation_direction(["h"] if delta_h else [])
+    if w:
+        report.add(w)
+
+    w = check_observable_proxy(observable, coupling_structure)
+    if w:
+        report.add(w)
+
+    if delta_h is not None:
+        w = check_nonlinearity([delta_h])
+        if w:
+            report.add(w)
+
+    w = check_system_sizes([L])
+    if w:
+        report.add(w)
+
+    # Compute QFI
+    F = qfi_analytical(psi_mps, L, sites=sites, use_gpu=use_gpu, report=report)
+
+    return F, report