Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

case-study: certicoupla (copula-coupled uncertainty certificates)

FABIOTESS124e19df102e
diff --git a/case-studies/certicoupla/.gitignore b/case-studies/certicoupla/.gitignore
new file mode 100644
index 00000000..77ac7549
--- /dev/null
+++ b/case-studies/certicoupla/.gitignore
@@ -0,0 +1,3 @@
+.venv/
+__pycache__/
+*.pyc
diff --git a/case-studies/certicoupla/BUILD_REPORT.md b/case-studies/certicoupla/BUILD_REPORT.md
new file mode 100644
index 00000000..302aeb7b
--- /dev/null
+++ b/case-studies/certicoupla/BUILD_REPORT.md
@@ -0,0 +1,64 @@
+# BUILD_REPORT: certicoupla
+
+Honest record of data, method and limits. Every number in `results/` is produced by
+`src/certicoupla.py` on a fixed seed (numpy default_rng(7), model random_state 0).
+
+## What was fetched (real, public)
+
+| Source | Endpoint | Use |
+|---|---|---|
+| OQMD (Open Quantum Materials Database) | oqmd.org/optimade/structures (live, keyless) | real DFT formation energy, band gap, stability per material |
+
+Fetched 2026-07-20 via the OPTIMADE endpoint (`src/fetch.py`), 1,600 materials with all three
+numeric properties present, taken in id order until the endpoint timed out. Composition features are
+derived from the reduced chemical formula with a small embedded periodic table (atomic number and
+Pauling electronegativity); missing electronegativities fall back to the median.
+
+## Method
+
+- **Split.** 50% train, 25% calibration, 25% test (random, seeded).
+- **Frozen model.** One `GradientBoostingRegressor` per target, trained on the train split only and
+ then frozen. The uncertainty methods never touch it.
+- **Residuals.** Prediction errors on calibration and test, per target. Their correlation is real
+ and non-trivial (formation energy / stability +0.50, formation energy / band gap -0.28).
+- **Certificates, all calibrated to 90% joint coverage:**
+ - *independent* : per-target split-conformal quantile of `|residual|` at 90%.
+ - *Bonferroni* : per-target at `1 - 0.10/d` (d = 3).
+ - *coupled* : global nonconformity `max_j |r_j| / s_j`; its 90% quantile scales an axis-aligned
+ box. This has the standard finite-sample split-conformal joint coverage guarantee.
+ - *copula* : rank-transform each residual to uniform (empirical CDF, the Gaussian-copula margins),
+ map to normal scores, estimate the covariance, and use the Mahalanobis radius at 90% as an
+ elliptical region. Test residuals are mapped through the calibration marginals before scoring.
+- **Metrics.** Marginal coverage (mean over targets), joint coverage (all targets inside at once),
+ and region size. Certificate soundness = measured joint coverage against the claimed 90%.
+
+## The result, precisely
+
+- Independent: marginal 0.902, **joint 0.792** (11-point shortfall). Marginally correct, jointly wrong.
+- Bonferroni: joint 0.907, region 6.18x the independent box (valid but wide).
+- Coupled: joint 0.897, region 4.83x independent, i.e. 22% tighter than Bonferroni at nominal coverage.
+- Copula: joint 0.892, region 0.43x of the coupled box measured in the Gaussian-copula space.
+
+## Limits of the claim (do not overstate)
+
+1. **It is a coverage phenomenon, not a theorem.** That independent conformal under-covers a
+ correlated joint is known; the contribution is measuring it, and the coupled/copula fix, on real
+ DFT data with a clean margin.
+2. **Region-size comparisons mix spaces.** Box volumes (independent, Bonferroni, coupled) are in the
+ original target units; the copula region is compared to the coupled box in the Gaussian-copula
+ space, not the original units, so the 0.43x is a fair like-for-like only there. This is stated,
+ not smoothed.
+3. **Gaussian copula.** A single, tractable dependence model; heavy tails and non-elliptical
+ dependence would need a vine copula, which is the documented next step and the tie to the
+ copula-net world-model program.
+4. **Frozen model is a proxy for a foundation model.** A gradient-boosted regressor stands in for a
+ large frozen scientific model; the conformal guarantees are distribution-free, so the coverage
+ result transfers, but running the wrapper on ESM-2 / ESMFold or a Materials Project foundation
+ model is the honest scale-up.
+5. **Dataset slice.** 1,600 OQMD entries in id order, not a curated or class-balanced benchmark.
+
+## Reproducibility
+
+`./run-demo.sh` re-fetches OQMD and reruns the analysis. Live OQMD content can shift, so exact
+numbers may move slightly; the structural result (independent under-covers, coupled/copula restore)
+is stable. numpy, scipy, scikit-learn at build time.
diff --git a/case-studies/certicoupla/README.md b/case-studies/certicoupla/README.md
new file mode 100644
index 00000000..a656b84b
--- /dev/null
+++ b/case-studies/certicoupla/README.md
@@ -0,0 +1,82 @@
+# certicoupla
+
+**Copula-coupled, certificate-emitting uncertainty for scientific models: independent conformal
+prediction gives the right per-target coverage and the wrong joint coverage. Measured on real DFT
+data.**
+
+Foundation and scientific models are deployed with uncertainty that is either uncalibrated or
+calibrated one output at a time. But scientific predictions come in correlated vectors (a
+material's formation energy, band gap and stability are not independent), and a certificate that
+must hold *jointly*, the realized outcome vector falling inside an emitted region at the claimed
+rate, needs the coupling. This case study shows, on **real Open Quantum Materials Database (OQMD)
+data**, that per-target conformal prediction silently under-covers the joint region, and that a
+coupled certificate fixes it.
+
+This is the reliability layer Encode / ARIA Challengescape items on foundation-model uncertainty
+and on validating scientific AI for deployment are asking for.
+
+## The result
+
+Deterministic run of [`src/certicoupla.py`](src/certicoupla.py) on 1,600 real materials, three
+targets, a frozen gradient-boosted regressor, all certificates calibrated to **90% joint coverage**
+on a held-out test split (full table in [`results/SUMMARY.md`](results/SUMMARY.md)):
+
+| Method | Marginal coverage | **Joint coverage** | Region size |
+|---|--:|--:|--:|
+| Independent conformal (90%/target) | 0.902 | **0.792** | 1.0x |
+| Bonferroni conformal | 0.960 | **0.907** | 6.18x |
+| Coupled conformal (max-score box) | 0.954 | **0.897** | 4.83x |
+| Gaussian-copula region | joint by design | **0.892** | 0.43x of coupled |
+
+**Independent conformal is marginally correct (90.2% per target) but its joint coverage is only
+79.2%, an 11-point shortfall against the 90% it claims.** The coupled certificate restores joint
+coverage to 89.7%; the Gaussian-copula certificate matches it (89.2%) in a region 57% smaller. The
+coupled box is also 22% tighter than the Bonferroni box while still holding nominal coverage.
+
+The reason is in the data: the residuals are genuinely correlated (formation energy and stability
++0.50, formation energy and band gap -0.28). Independent intervals ignore that structure, so the
+joint region they imply is the wrong shape and the wrong size.
+
+## Why this is the ownable gap
+
+- **Marginal coverage is not joint coverage.** A per-output 90% interval, stacked across d
+ correlated outputs, does not give a 90% guarantee on the vector. Reporting the marginal number as
+ if it were the deployment guarantee is the quiet failure.
+- **Bonferroni is valid but wasteful.** Tightening each margin to 1 - alpha/d restores joint
+ validity at the cost of intervals so wide they stop being useful (6.18x the volume here).
+- **Coupling recovers both.** A global max-score conformal certificate has a finite-sample joint
+ guarantee and is 22% tighter than Bonferroni; a Gaussian copula on the residuals uses the
+ dependence to shrink the region much further, at the same coverage.
+- **It emits a certificate.** Each prediction carries a machine-checkable region; soundness is the
+ measured joint coverage against the claimed 90%, reported here on held-out data.
+
+This composes with the frozen model rather than replacing it, and it is the uncertainty companion to
+the [WorldKernel](https://github.com/fabio-rovai/worldkernel) coupling work.
+
+## Reproduce
+
+```bash
+./run-demo.sh # fetches real OQMD materials, trains + freezes a regressor, runs all certificates
+```
+
+Requires Python 3.10+ and network access (OQMD is queried live via its OPTIMADE endpoint).
+
+## Honest scope
+
+See [`BUILD_REPORT.md`](BUILD_REPORT.md). The frozen model is a gradient-boosted regressor trained
+once and frozen; the point is the uncertainty wrapper, not the model, and the conformal guarantees
+are distribution-free so they hold regardless of model quality. The copula is Gaussian (a first,
+tractable dependence model); heavier-tailed vine copulas are the natural extension. The dataset is a
+1,600-material slice of OQMD taken in id order, enough to show the effect, not a curated benchmark.
+The result is a coverage phenomenon demonstrated on real data, not a claim of a new theorem.
+
+---
+
+### Built by Tesseract Academy
+
+We build the calibration and assurance layer for scientific and foundation models. If you deploy a
+model whose outputs are correlated and whose uncertainty has to hold jointly, we can wrap it in a
+certificate that actually does.
+
+[gov.tesseract.academy](https://gov.tesseract.academy) · [email protected]
+Part of [Open Ontologies](../../README.md) · MIT · real data, real numbers.
diff --git a/case-studies/certicoupla/demo.ipynb b/case-studies/certicoupla/demo.ipynb
new file mode 100644
index 00000000..ffa3de5a
--- /dev/null
+++ b/case-studies/certicoupla/demo.ipynb
@@ -0,0 +1,61 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# certicoupla: joint-valid uncertainty certificates on real DFT data\n",
+ "\n",
+ "Independent conformal prediction gives the right per-target coverage and the **wrong joint coverage** when scientific outputs are correlated. This runs the demonstration on real OQMD materials: a frozen regressor, then independent vs coupled vs Gaussian-copula certificates, all calibrated to 90% joint coverage.\n",
+ "\n",
+ "**Runtime -> Run all.** Code and the fetched dataset are pulled from GitHub; nothing else to set up.\n",
+ "\n",
+ "Repo: https://github.com/fabio-rovai/open-ontologies/tree/main/case-studies/certicoupla\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "metadata": {},
+ "execution_count": null,
+ "outputs": [],
+ "source": [
+ "!pip -q install numpy scipy scikit-learn requests\n",
+ "!mkdir -p src data results\n",
+ "!wget -q https://raw.githubusercontent.com/fabio-rovai/open-ontologies/main/case-studies/certicoupla/src/certicoupla.py -O src/certicoupla.py\n",
+ "!wget -q https://raw.githubusercontent.com/fabio-rovai/open-ontologies/main/case-studies/certicoupla/data/oqmd.json -O data/oqmd.json\n",
+ "print('ready')\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "metadata": {},
+ "execution_count": null,
+ "outputs": [],
+ "source": [
+ "!python src/certicoupla.py\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "---\n",
+ "Independent conformal: ~90% marginal but only ~79% joint coverage. The coupled certificate restores ~90% joint; the copula certificate matches it in a much smaller region. Write-up: https://gov.tesseract.academy/research/copula-coupled-uncertainty-certificates\n"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "name": "python3"
+ },
+ "language_info": {
+ "name": "python"
+ },
+ "colab": {
+ "provenance": []
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
\ No newline at end of file
diff --git a/case-studies/certicoupla/requirements.txt b/case-studies/certicoupla/requirements.txt
new file mode 100644
index 00000000..da944cc9
--- /dev/null
+++ b/case-studies/certicoupla/requirements.txt
@@ -0,0 +1,4 @@
+numpy>=1.24
+scipy>=1.10
+scikit-learn>=1.3
+requests>=2.31
diff --git a/case-studies/certicoupla/results/SUMMARY.md b/case-studies/certicoupla/results/SUMMARY.md
new file mode 100644
index 00000000..c6120587
--- /dev/null
+++ b/case-studies/certicoupla/results/SUMMARY.md
@@ -0,0 +1,14 @@
+# Results summary
+
+Real DFT data: **1600 materials from the OQMD**, three targets (delta_e, band_gap, stability). Frozen gradient-boosted regressor; all certificates calibrated to **90% joint coverage** on a held-out test split. Residual correlations are real (formation energy and stability +0.50), which is why the joint problem is not the marginal problem.
+
+| Method | Marginal coverage | **Joint coverage** | Region size |
+|---|--:|--:|--:|
+| Independent conformal (90%/target) | 0.902 | **0.792** | 1.0x (baseline) |
+| Bonferroni conformal | 0.960 | **0.907** | 6.18x |
+| Coupled conformal (max-score box) | 0.954 | **0.897** | 4.83x |
+| Gaussian-copula region | (joint by design) | **0.892** | 0.43x of coupled* |
+
+**Headline.** Independent conformal is marginally correct (0.902 per target) but its **joint coverage is only 0.792**, an 11-point shortfall against the 90% claim. The **coupled certificate restores joint coverage to 0.897** and the **Gaussian-copula certificate matches it (0.892) with a much smaller region**. Coupled is also 22% tighter than Bonferroni while holding nominal coverage.
+
+*region size for the copula is measured in the Gaussian-copula space against the coupled box; see BUILD_REPORT.
\ No newline at end of file
diff --git a/case-studies/certicoupla/results/results.json b/case-studies/certicoupla/results/results.json
new file mode 100644
index 00000000..dac8155a
--- /dev/null
+++ b/case-studies/certicoupla/results/results.json
@@ -0,0 +1,57 @@
+{
+ "source": "OQMD (Open Quantum Materials Database), real DFT properties",
+ "n_materials": 1600,
+ "targets": [
+ "delta_e",
+ "band_gap",
+ "stability"
+ ],
+ "nominal_joint_coverage": 0.9,
+ "residual_correlation": [
+ [
+ 1.0,
+ -0.282,
+ 0.502
+ ],
+ [
+ -0.282,
+ 1.0,
+ -0.156
+ ],
+ [
+ 0.502,
+ -0.156,
+ 1.0
+ ]
+ ],
+ "methods": {
+ "independent": {
+ "marginal_mean": 0.9025,
+ "joint": 0.7925,
+ "rel_volume": 1.0
+ },
+ "bonferroni": {
+ "marginal_mean": 0.96,
+ "joint": 0.9075,
+ "rel_volume": 6.178609424489175
+ },
+ "coupled_conformal": {
+ "marginal_mean": 0.9541666666666666,
+ "joint": 0.8975,
+ "rel_volume": 4.829738682379062
+ },
+ "copula": {
+ "marginal_mean": null,
+ "joint": 0.8925,
+ "rel_region_vs_coupled_in_copula_space": 0.4265961733746242
+ }
+ },
+ "headline": {
+ "independent_marginal_coverage": 0.902,
+ "independent_joint_coverage": 0.792,
+ "coupled_joint_coverage": 0.897,
+ "copula_joint_coverage": 0.892,
+ "bonferroni_joint_coverage": 0.907,
+ "coupled_rel_volume_vs_bonferroni": 0.782
+ }
+}
\ No newline at end of file
diff --git a/case-studies/certicoupla/run-demo.sh b/case-studies/certicoupla/run-demo.sh
new file mode 100755
index 00000000..4577bafe
--- /dev/null
+++ b/case-studies/certicoupla/run-demo.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Reproduce certicoupla: fetch real OQMD materials, train + freeze a regressor,
+# compare independent conformal vs coupled and Gaussian-copula certificates.
+set -euo pipefail
+cd "$(dirname "$0")"
+if [ ! -d .venv ]; then python3 -m venv .venv; ./.venv/bin/pip -q install -r requirements.txt; fi
+[ -f data/oqmd.json ] || ./.venv/bin/python src/fetch.py
+./.venv/bin/python src/certicoupla.py
+echo; echo "See results/SUMMARY.md and results/results.json"
diff --git a/case-studies/certicoupla/src/certicoupla.py b/case-studies/certicoupla/src/certicoupla.py
new file mode 100644
index 00000000..2fdf5a33
--- /dev/null
+++ b/case-studies/certicoupla/src/certicoupla.py
@@ -0,0 +1,164 @@
+"""
+certicoupla — copula-coupled, certificate-emitting uncertainty on a frozen scientific model.
+
+The claim (#105, #112): independent, per-target conformal prediction gives correct MARGINAL
+coverage but the wrong JOINT coverage, because scientific targets are correlated. A certificate
+that must hold jointly (a box or region the realized outcome vector falls inside at the claimed
+rate) needs the coupling. We show this on real DFT materials data.
+
+Frozen model: a gradient-boosted regressor trained once on a train split and frozen; the
+uncertainty methods wrap it without touching it. Targets: formation energy, band gap and
+stability from the OQMD (real, keyless). Features: composition descriptors from the formula.
+
+Methods compared, all calibrated to a nominal 90% JOINT coverage:
+ - independent : per-target split-conformal at 90% each (marginal-correct, joint-blind)
+ - Bonferroni : per-target at 1 - 0.1/d (joint-valid but conservative/wide)
+ - coupled : global max-score split-conformal (finite-sample joint guarantee, box)
+ - copula : Gaussian copula on the residuals -> Mahalanobis region (dependence-aware)
+
+Every number is computed on a held-out test split; the certificate is the emitted region and
+its soundness is the measured joint coverage against the claimed 90%.
+"""
+import json, os, re
+import numpy as np
+from scipy.stats import norm
+from sklearn.ensemble import GradientBoostingRegressor
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+DATA, RES = os.path.join(ROOT, "data"), os.path.join(ROOT, "results")
+os.makedirs(RES, exist_ok=True)
+RNG = np.random.default_rng(7)
+ALPHA = 0.10 # nominal miscoverage; 90% joint target
+TARGETS = ["delta_e", "band_gap", "stability"]
+
+# Pauling electronegativity for the common elements (missing -> median at use).
+EN = {"H":2.20,"He":0,"Li":0.98,"Be":1.57,"B":2.04,"C":2.55,"N":3.04,"O":3.44,"F":3.98,"Ne":0,
+"Na":0.93,"Mg":1.31,"Al":1.61,"Si":1.90,"P":2.19,"S":2.58,"Cl":3.16,"Ar":0,"K":0.82,"Ca":1.00,
+"Sc":1.36,"Ti":1.54,"V":1.63,"Cr":1.66,"Mn":1.55,"Fe":1.83,"Co":1.88,"Ni":1.91,"Cu":1.90,"Zn":1.65,
+"Ga":1.81,"Ge":2.01,"As":2.18,"Se":2.55,"Br":2.96,"Kr":3.00,"Rb":0.82,"Sr":0.95,"Y":1.22,"Zr":1.33,
+"Nb":1.6,"Mo":2.16,"Tc":1.9,"Ru":2.2,"Rh":2.28,"Pd":2.20,"Ag":1.93,"Cd":1.69,"In":1.78,"Sn":1.96,
+"Sb":2.05,"Te":2.1,"I":2.66,"Xe":2.60,"Cs":0.79,"Ba":0.89,"La":1.10,"Ce":1.12,"Pr":1.13,"Nd":1.14,
+"Pm":1.13,"Sm":1.17,"Eu":1.2,"Gd":1.20,"Tb":1.1,"Dy":1.22,"Ho":1.23,"Er":1.24,"Tm":1.25,"Yb":1.1,
+"Lu":1.27,"Hf":1.3,"Ta":1.5,"W":2.36,"Re":1.9,"Os":2.2,"Ir":2.20,"Pt":2.28,"Au":2.54,"Hg":2.00,
+"Tl":1.62,"Pb":2.33,"Bi":2.02,"Po":2.0,"At":2.2,"Th":1.3,"Pa":1.5,"U":1.38,"Np":1.36,"Pu":1.28}
+# atomic numbers 1..96
+SYM = ("H He Li Be B C N O F Ne Na Mg Al Si P S Cl Ar K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As "
+ "Se Br Kr Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe Cs Ba La Ce Pr Nd Pm Sm Eu Gd "
+ "Tb Dy Ho Er Tm Yb Lu Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn Fr Ra Ac Th Pa U Np Pu Am Cm").split()
+Z = {s: i + 1 for i, s in enumerate(SYM)}
+EN_MED = np.median([v for v in EN.values() if v > 0])
+
+def featurize(formula):
+ toks = re.findall(r"([A-Z][a-z]?)(\d*)", formula or "")
+ els = [(s, int(n) if n else 1) for s, n in toks if s in Z]
+ if not els:
+ return None
+ zs = np.array([Z[s] for s, _ in els], float)
+ ens = np.array([EN[s] if EN.get(s, 0) > 0 else EN_MED for s, _ in els], float)
+ w = np.array([n for _, n in els], float); w = w / w.sum()
+ return np.array([
+ len(els), sum(n for _, n in els),
+ (zs * w).sum(), zs.std(), zs.max() - zs.min(),
+ (ens * w).sum(), ens.std(), ens.max() - ens.min(),
+ ])
+
+def load():
+ rows = json.load(open(os.path.join(DATA, "oqmd.json")))
+ X, Y = [], []
+ for r in rows:
+ f = featurize(r.get("name"))
+ if f is None:
+ continue
+ X.append(f); Y.append([r["delta_e"], r["band_gap"], r["stability"]])
+ return np.array(X), np.array(Y)
+
+def cover_box(Y, lo, hi):
+ inside = (Y >= lo) & (Y <= hi) # n x d
+ return inside.mean(0), inside.all(1).mean() # marginal (per target), joint
+
+def main():
+ X, Y = load()
+ n = len(X); idx = RNG.permutation(n)
+ a, b = int(0.5 * n), int(0.75 * n)
+ tr, cal, te = idx[:a], idx[a:b], idx[b:]
+ d = Y.shape[1]
+ print(f"[*] {n} materials | train {len(tr)} cal {len(cal)} test {len(te)} | {d} targets")
+
+ # frozen model: one GBR per target, trained on train split only
+ models = [GradientBoostingRegressor(n_estimators=200, max_depth=3, random_state=0).fit(X[tr], Y[tr, j]) for j in range(d)]
+ def predict(Xs): return np.column_stack([m.predict(Xs) for m in models])
+ Pcal, Pte = predict(X[cal]), predict(X[te])
+ Rcal, Rte = Y[cal] - Pcal, Y[te] - Pte # residual vectors
+ s = np.abs(Rcal).std(0) + 1e-9 # per-target scale
+
+ corr = np.corrcoef(Rcal.T)
+ ncal = len(cal)
+ def q(v, level): return np.quantile(v, min(1.0, level * (ncal + 1) / ncal), method="higher")
+
+ results = {}
+
+ # 1) independent: per-target 90%
+ qj = np.array([q(np.abs(Rcal[:, j]), 1 - ALPHA) for j in range(d)])
+ lo, hi = Pte - qj, Pte + qj
+ marg, joint = cover_box(Y[te], lo, hi)
+ vol_ind = np.prod(2 * qj)
+ results["independent"] = {"marginal_mean": float(marg.mean()), "joint": float(joint), "rel_volume": 1.0}
+
+ # 2) Bonferroni: per-target 1 - alpha/d
+ qb = np.array([q(np.abs(Rcal[:, j]), 1 - ALPHA / d) for j in range(d)])
+ lo, hi = Pte - qb, Pte + qb
+ margB, jointB = cover_box(Y[te], lo, hi)
+ vol_bon = np.prod(2 * qb)
+ results["bonferroni"] = {"marginal_mean": float(margB.mean()), "joint": float(jointB), "rel_volume": float(vol_bon / vol_ind)}
+
+ # 3) coupled: global max-score conformal (box)
+ score = np.max(np.abs(Rcal) / s, axis=1)
+ qc = q(score, 1 - ALPHA)
+ half = qc * s
+ lo, hi = Pte - half, Pte + half
+ margC, jointC = cover_box(Y[te], lo, hi)
+ vol_cpl = np.prod(2 * half)
+ results["coupled_conformal"] = {"marginal_mean": float(margC.mean()), "joint": float(jointC), "rel_volume": float(vol_cpl / vol_ind)}
+
+ # 4) copula: Gaussian copula on residual ranks -> Mahalanobis region
+ u = (np.argsort(np.argsort(Rcal, axis=0), axis=0) + 1) / (ncal + 1) # empirical CDF ranks
+ zc = norm.ppf(u)
+ Sig = np.cov(zc.T); Si = np.linalg.inv(Sig)
+ m_cal = np.einsum("ij,jk,ik->i", zc, Si, zc) ** 0.5
+ qm = q(m_cal, 1 - ALPHA)
+ # map test residuals into the same Gaussian-copula space using cal marginals
+ def to_z(col, j):
+ ranks = np.searchsorted(np.sort(Rcal[:, j]), col, side="right")
+ uu = np.clip((ranks + 0.5) / (ncal + 1), 1e-4, 1 - 1e-4)
+ return norm.ppf(uu)
+ zte = np.column_stack([to_z(Rte[:, j], j) for j in range(d)])
+ m_te = np.einsum("ij,jk,ik->i", zte, Si, zte) ** 0.5
+ joint_cop = float((m_te <= qm).mean())
+ # region volume in copula space ~ ellipsoid volume proportional to qm^d * sqrt(det Sig)
+ vol_cop_space = (qm ** d) * np.sqrt(np.linalg.det(Sig))
+ vol_cpl_space = (qc ** d) * 1.0 # coupled box in standardized space, comparable proxy
+ results["copula"] = {"marginal_mean": None, "joint": joint_cop,
+ "rel_region_vs_coupled_in_copula_space": float(vol_cop_space / vol_cpl_space)}
+
+ out = {
+ "source": "OQMD (Open Quantum Materials Database), real DFT properties",
+ "n_materials": int(n), "targets": TARGETS, "nominal_joint_coverage": 1 - ALPHA,
+ "residual_correlation": np.round(corr, 3).tolist(),
+ "methods": results,
+ "headline": {
+ "independent_marginal_coverage": round(results["independent"]["marginal_mean"], 3),
+ "independent_joint_coverage": round(results["independent"]["joint"], 3),
+ "coupled_joint_coverage": round(results["coupled_conformal"]["joint"], 3),
+ "copula_joint_coverage": round(results["copula"]["joint"], 3),
+ "bonferroni_joint_coverage": round(results["bonferroni"]["joint"], 3),
+ "coupled_rel_volume_vs_bonferroni": round(results["coupled_conformal"]["rel_volume"] / results["bonferroni"]["rel_volume"], 3),
+ },
+ }
+ json.dump(out, open(os.path.join(RES, "results.json"), "w"), indent=2)
+ print(json.dumps(out["headline"], indent=2))
+ print("residual corr:\n", np.round(corr, 3))
+ for k, v in results.items():
+ print(f" {k}: {v}")
+
+if __name__ == "__main__":
+ main()
diff --git a/case-studies/certicoupla/src/fetch.py b/case-studies/certicoupla/src/fetch.py
new file mode 100644
index 00000000..5c1d9d05
--- /dev/null
+++ b/case-studies/certicoupla/src/fetch.py
@@ -0,0 +1,25 @@
+import requests, json, time
+rows=[]
+url="https://oqmd.org/optimade/structures"
+params={"response_fields":"chemical_formula_reduced,_oqmd_delta_e,_oqmd_band_gap,_oqmd_stability","page_limit":200}
+for i in range(20):
+ try:
+ r=requests.get(url, params=params, timeout=40).json()
+ except Exception as e:
+ print("stop:", e); break
+ for d in r.get("data",[]):
+ a=d.get("attributes",{})
+ rows.append({"name":a.get("chemical_formula_reduced"),
+ "delta_e":a.get("_oqmd_delta_e"),"band_gap":a.get("_oqmd_band_gap"),
+ "stability":a.get("_oqmd_stability")})
+ nxt=(r.get("links") or {}).get("next")
+ json.dump(rows, open("data/oqmd.json","w"))
+ print(f"page {i+1}: total {len(rows)}", flush=True)
+ if not nxt: break
+ # next is a full URL
+ url = nxt if isinstance(nxt,str) else nxt.get("href")
+ params=None
+ time.sleep(0.2)
+clean=[x for x in rows if all(isinstance(x.get(k),(int,float)) for k in ("delta_e","band_gap","stability"))]
+json.dump(clean, open("data/oqmd.json","w"))
+print("FINAL clean:", len(clean))