appautomaton · benjipeng · Aug 26, 2026 · Aug 26, 2026
diff --git a/docs/benchmarks/dft-material-validation.md b/docs/benchmarks/dft-material-validation.md
@@ -17,6 +17,7 @@ calculation.
 | Diamond C, 8 atoms, PBE/GTH-q4, 40 Ha, 6×6×6, 7 volumes | `a₀ = 3.574441 Å`, `B₀ = 438.100 GPa`, Δ = `1.268 meV/atom` | All-electron PBE: lattice `0.075%` and bulk modulus `1.080%` relative error | Verified for the accepted 40 Ha workload. A 40→50 Ha central three-volume screen changed the curve by `0.438 meV/atom`; no full 50 Ha curve is required. |
 | Rock-salt MgO, 8 atoms, PBE, Mg-q2/O-q6, 70 Ha, 6×6×6, 7 volumes | `a₀ = 4.259503 Å`, `B₀ = 146.914 GPa`, Δ = `1.060 meV/atom` | All-electron PBE: lattice `0.123%` and bulk modulus `1.387%` relative error | Core EOS properties validated. The strict whole-report gate remains failed because `B₀′ = 3.39995` differs from `4.09093` by `16.89%`, above the locked `15%` threshold; this is retained as a likely Mg-q2 transferability limit. |
 | MgO periodic forces at the accepted EOS cell | 21 of 24 atom/axis comparisons pass `1e-4 Ha/bohr`; maximum deviation `2.246e-4 Ha/bohr` | Analytic force versus 48 reconverged ±0.01 bohr SCFs | Accepted with a known float32 total-energy precision limit. The three failures are O 6-x and O 7-y/z; the threshold was not weakened. |
+| Rock-salt MgO primitive Mg-q10/O-q6 feasibility, 2 atoms, 40 Ha, symmetry-reduced 4×4×4 | Complete wall `40.989 s`; peak temporary memory `57.2 MB`; 80 SCF iterations | Numerical admission only; no EOS reference claim | Failed: maximum orbital residual `4.329e-6` exceeded the locked `2e-6` gate. The conventional-cell precursor was stopped after more than five minutes. No full q10 EOS was run. |
 | fcc Al, 4 atoms, PBE/GTH-q3, Fermi-Dirac `0.00225 Ha`, 15 Ha, reduced 15×15×15, 11 bands, 7 volumes | `a₀ = 4.039885 Å`, `B₀ = 76.631 GPa`, `B₀′ = 4.58384`, Δ = `0.230 meV/atom` | All-electron PBE: lattice `0.024%`, bulk modulus `1.137%`, and `B₀′` `0.851%` relative error | Verified for this metallic EOS workload. The accepted mesh has 120 weighted representatives; the result does not establish broad Aluminum chemistry or metal transferability. |
 | bcc Fe primitive cell, spin-PBE/GTH-q16, Fermi-Dirac `0.01 Ha`, 150 Ha, exact unfolded 4×4×4, 10 bands | Unconstrained moment `2.41795 μB/atom`; the magnetic state is `0.023828 Ha/atom` below matched unpolarized Fe. The selected point took `10.727 s` in battery low-power mode. | Published PBE context `2.33 μB/atom`; 6×6×6 gave `2.33319`. The 200 Ha and 6×6×6 free-energy drifts were `0.000136` and `0.000812 Ha/atom`. | Current-verified on Apple M5 Max. All numerical, energy, moment, cutoff, k-point, checkpoint, and logical-memory gates pass. Historical-frozen Fe q8 evidence converged near `2.98 μB/atom` and remains a declared transferability failure. This verifies q16 bcc Fe, not broad d-block chemistry. |
 

diff --git a/docs/dft-gth-transferability.md b/docs/dft-gth-transferability.md
@@ -0,0 +1,108 @@
+# Periodic GTH Transferability
+
+This document is the scientific and engineering contract for Phase 7 of the
+[DFT roadmap](./dft-roadmap.md). It defines the production boundary of the
+periodic Goedecker-Teter-Hutter (GTH) path. Universal pseudopotential accuracy
+is not inferred from parser support, projector identities, or one material.
+
+## Runtime Boundary
+
+The product runtime remains element-agnostic. `PeriodicDFTSystem` supplies one
+`PseudopotentialData` value per ion, and the local potential, nonlocal
+projectors, forces, stress, and self-consistent field controller dispatch from
+that data. Phase 7 must not add element names, material names, or fitted
+corrections to the runtime path.
+
+The admitted GTH envelope supports real nonlocal channels through angular
+momentum `l = 2`. Parsed UPF input and GTH channels above this boundary remain
+proof-level and are not promoted by this phase.
+
+## Transferability Matrix
+
+The matrix is computed from locked observables, thresholds, and evidence
+identities. It must cover all of the following without selecting only passing
+metrics from a source report:
+
+- representative s-, p-, and d-block elements;
+- covalent, metallic, ionic, and magnetic solid environments;
+- homogeneous and mixed-species cells;
+- local and nonlocal energy and force execution;
+- insulating fixed occupations, metallic smearing, and collinear spin.
+
+Every material record binds the exact pseudopotential resource, reference
+bundle or protocol, calculation contract, and runtime identity used by its
+evidence. A missing or malformed SHA-256 identity fails closed. A
+historical-frozen or project-derived result stays labeled as such and cannot be
+reported as current verification.
+
+## Scientific Gates
+
+Equation-of-state cases retain the shared locked thresholds in `dft_eos.py`.
+Magnetic Iron retains its published-moment, magnetic-energy-ordering, cutoff,
+and k-point gates. Force coverage requires both:
+
+- deterministic local and nonlocal component derivatives across the admitted
+  `l = 0`, `l = 1`, and `l = 2` projector envelope;
+- at least one mixed-species self-consistent total-force comparison.
+
+The existing Mg-q2/O-q6 MgO case passes its locked lattice, bulk-modulus, and
+equation-of-state shape gates, but its bulk derivative remains outside the
+strict 15 percent gate and three finite-difference force components remain
+outside `1e-4 Ha/bohr`. Those values remain failures. Phase 7 may evaluate the
+already prepared Mg-q10 alternative, but only after one bounded feasibility
+point passes numerical, memory, and complete-wall controls. Thresholds are not
+changed after observing a result.
+
+## Report Semantics
+
+The matrix has three independent outcomes:
+
+- `coverage_complete`: every declared block, environment, occupation mode,
+  species mode, and force component has evidence;
+- `strict_science_passed`: every required locked scientific metric passes;
+- `production_envelope_verified`: coverage and strict science both pass with
+  source-bound current or accepted project-derived evidence.
+
+Known residuals are emitted as explicit blockers. Coverage never converts a
+scientific failure into a pass, and a single successful material never
+generalizes the entire GTH family.
+
+## Efficient Execution Policy
+
+Deterministic parser, identity, projector, and matrix tests run before any
+material calculation. Material work follows a fail-early ladder: one central
+feasibility point, then only the adjacent cutoff or k-point samples required to
+make a decision, and finally a full curve only for an admitted candidate.
+Existing source-bound evidence is reused when its fingerprints still match.
+No material run is repeated merely to reformat a report.
+
+## Current Matrix Result
+
+Run the deterministic report with:
+
+```bash
+uv run python -m mlx_atomistic.benchmarks.dft_gth_transferability --json
+```
+
+The committed contract currently reports:
+
+- `coverage_complete = true` across the declared block, environment, species,
+  occupation, and force axes;
+- `strict_science_passed = false` because the locked Mg-q2/O-q6 bulk-derivative
+  and total-force metrics remain outside their thresholds;
+- `identity_complete = false` because several older project-derived EOS
+  summaries do not retain exact calculation and runtime fingerprints;
+- `production_envelope_verified = false`.
+
+The one permitted Mg-q10/O-q6 feasibility point used the two-atom primitive
+cell, a 36-cubed FFT grid, eight occupied bands, and cubic k-point symmetry. It
+reduced complete wall time from an interrupted conventional-cell run exceeding
+five minutes to `40.989 s`, with `57,201,084` peak temporary bytes. It was not
+admitted: after 80 SCF iterations its maximum orbital residual was
+`4.329e-6`, above the locked `2e-6` limit. No seven-point q10 EOS was run.
+
+The primitive representation and reusable reciprocal-symmetry basis transform
+are retained because their deterministic geometry and quadrature gates pass.
+They improve future validation efficiency without adding a material branch to
+the product runtime. The failed q10 candidate remains in the matrix rather than
+being deleted or reclassified.
diff --git a/docs/dft-pseudopotentials.md b/docs/dft-pseudopotentials.md
@@ -54,7 +54,10 @@ translation invariance are deterministic gates. This implementation support
 does not by itself certify d-block material transferability. The bcc Iron
 PBE/GTH-q16 cutoff and k-point study now passes the Phase 5 material gate,
 while the matching q8 study retains a failed magnetic-moment gate. Phase 7
-must broaden this one-material result rather than generalizing from q16.
+now computes a multi-material coverage and science matrix rather than
+generalizing from q16. Coverage is complete, but the production GTH envelope
+remains unverified because locked MgO and older evidence-identity blockers are
+retained.
 
 ## Forces
 

diff --git a/docs/dft-roadmap.md b/docs/dft-roadmap.md
@@ -207,8 +207,9 @@ material workload was rerun merely to exercise these analysis contracts.
 
 ## Phase 7: Expand Pseudopotential Transferability
 
-Status: evidence expands incrementally with every earlier phase; the final
-matrix closes after spin support.
+Status: implementation complete; scientific exit blocked. The fail-closed
+matrix and efficient material decision policy are defined in
+[Periodic GTH Transferability](./dft-gth-transferability.md).
 
 - Strengthen periodic GTH convention fidelity instead of treating parser
   success as scientific validation. Existing UPF support retains its separate
@@ -221,6 +222,12 @@ matrix closes after spin support.
 Exit gate: a multi-material matrix passes locked energy, structural, and force
 thresholds without element-specific runtime branches.
 
+Current exit result: coverage is complete, but the gate remains blocked by the
+locked MgO q2 bulk-derivative and total-force residuals and incomplete exact
+calculation/runtime identities for older project-derived EOS summaries. A
+bounded primitive-cell Mg q10 screen improved runtime representation but failed
+its locked orbital-residual gate, so no full q10 EOS was run.
+
 ## Phase 8: Add Finite-Displacement Phonons
 
 Status: blocked on stable forces, ionic relaxation, cell geometry, and restart.

diff --git a/src/mlx_atomistic/benchmarks/data/dft_gth_transferability_contract.json b/src/mlx_atomistic/benchmarks/data/dft_gth_transferability_contract.json
@@ -0,0 +1,154 @@
+{
+  "schema_version": "mlx-atomistic.dft-gth-transferability.v1",
+  "coverage_requirements": {
+    "periodic_blocks": ["s", "p", "d"],
+    "environments": ["covalent", "metallic", "ionic", "magnetic"],
+    "species_modes": ["homogeneous", "mixed"],
+    "occupation_modes": ["fixed", "smeared", "collinear_spin"],
+    "force_components": ["local", "nonlocal", "total"]
+  },
+  "cases": [
+    {
+      "case_id": "diamond-silicon-q4",
+      "evidence_label": "project-derived",
+      "coverage": {
+        "periodic_blocks": ["p"],
+        "environments": ["covalent"],
+        "species_modes": ["homogeneous"],
+        "occupation_modes": ["fixed"],
+        "force_components": ["local", "nonlocal", "total"]
+      },
+      "identity": {
+        "pseudopotential_sha256": {
+          "Si GTH-PBE-q4": "da66fe0c10d015229e7ad88ea2c4204e6db54c4b9d39e05434d1c08df292d571"
+        },
+        "reference_protocol_sha256": "3cbf727f17d31ab7859acfc32d0bc313b5c02f7e870cd97411aa695c5986d53a",
+        "calculation_fingerprint": null,
+        "runtime_fingerprint": null
+      },
+      "metrics": [
+        {"name": "delta_mev_per_atom", "value": 1.942, "maximum": 3.0},
+        {"name": "lattice_relative", "value": 0.00166, "maximum": 0.005},
+        {"name": "bulk_modulus_relative", "value": 0.00232, "maximum": 0.1},
+        {"name": "bulk_derivative_relative", "value": 0.00153, "maximum": 0.15}
+      ]
+    },
+    {
+      "case_id": "diamond-carbon-q4",
+      "evidence_label": "project-derived",
+      "coverage": {
+        "periodic_blocks": ["p"],
+        "environments": ["covalent"],
+        "species_modes": ["homogeneous"],
+        "occupation_modes": ["fixed"],
+        "force_components": []
+      },
+      "identity": {
+        "pseudopotential_sha256": {
+          "C GTH-PBE-q4": "78e226aaa967b3c440cf427fa52d31552cab2dd4b8737abb69031b56cfba6e2a"
+        },
+        "reference_protocol_sha256": "8414886566bf47ed231d285293a586e0a7a6ee9f45cff44ce5944e1f502f76c6",
+        "calculation_fingerprint": null,
+        "runtime_fingerprint": null
+      },
+      "metrics": [
+        {"name": "delta_mev_per_atom", "value": 1.268, "maximum": 3.0},
+        {"name": "lattice_relative", "value": 0.00075, "maximum": 0.005},
+        {"name": "bulk_modulus_relative", "value": 0.0108, "maximum": 0.1}
+      ]
+    },
+    {
+      "case_id": "fcc-aluminum-q3",
+      "evidence_label": "project-derived",
+      "coverage": {
+        "periodic_blocks": ["p"],
+        "environments": ["metallic"],
+        "species_modes": ["homogeneous"],
+        "occupation_modes": ["smeared"],
+        "force_components": []
+      },
+      "identity": {
+        "pseudopotential_sha256": {
+          "Al GTH-PBE-q3": "06adc20c53ad6ff2eb7e1111c4b2437bd70ad520cdd6e5735dbb9cd09c1d381d"
+        },
+        "reference_protocol_sha256": "eebfe487557fcff52b1934ced8924844c307e0cfe30c739987e36734890a6788",
+        "calculation_fingerprint": "471b63703856b6b7ab5efe1369a2840dbff61d3340181cbfb385e17afad57f73",
+        "runtime_fingerprint": null
+      },
+      "metrics": [
+        {"name": "delta_mev_per_atom", "value": 0.22958746456278042, "maximum": 3.0},
+        {"name": "lattice_relative", "value": 0.00024152888409563096, "maximum": 0.005},
+        {"name": "bulk_modulus_relative", "value": 0.011368639861485518, "maximum": 0.1},
+        {"name": "bulk_derivative_relative", "value": 0.008508662077139715, "maximum": 0.15}
+      ]
+    },
+    {
+      "case_id": "rocksalt-mgo-q2-q6",
+      "evidence_label": "project-derived",
+      "coverage": {
+        "periodic_blocks": ["s", "p"],
+        "environments": ["ionic"],
+        "species_modes": ["mixed"],
+        "occupation_modes": ["fixed"],
+        "force_components": ["local", "nonlocal", "total"]
+      },
+      "identity": {
+        "pseudopotential_sha256": {
+          "Mg GTH-PBE-q2": "06b249c7c0940f4c03ac96d8a790be2cdebf82de6925e6b5d27cd22a4725dda6",
+          "O GTH-PBE-q6": "b1807a81468a4fae0b9ac298c63a550d8b95fbd126e9477c990436e6abe71333"
+        },
+        "reference_protocol_sha256": "ad4e262690181b6f009e5683eadb8402ee47c73acee32ca96873c95cf1c3e5ea",
+        "calculation_fingerprint": null,
+        "runtime_fingerprint": null
+      },
+      "metrics": [
+        {"name": "delta_mev_per_atom", "value": 1.060, "maximum": 3.0},
+        {"name": "lattice_relative", "value": 0.00123, "maximum": 0.005},
+        {"name": "bulk_modulus_relative", "value": 0.01387, "maximum": 0.1},
+        {"name": "bulk_derivative_relative", "value": 0.1689, "maximum": 0.15},
+        {"name": "force_max_abs_hartree_per_bohr", "value": 0.0002246, "maximum": 0.0001}
+      ]
+    },
+    {
+      "case_id": "bcc-iron-q16",
+      "evidence_label": "current-verified",
+      "coverage": {
+        "periodic_blocks": ["d"],
+        "environments": ["metallic", "magnetic"],
+        "species_modes": ["homogeneous"],
+        "occupation_modes": ["smeared", "collinear_spin"],
+        "force_components": []
+      },
+      "identity": {
+        "pseudopotential_sha256": {
+          "Fe GTH-PBE-q16": "b01c203a4837b7becf1b2f76b188bf6365ec5aec216dccf1ed4fda6b9d65fdcb"
+        },
+        "reference_protocol_sha256": "2264f8473237a1ae2c9dda90cc0dfdd3a60721a2b399d05ba70b72f7893f3756",
+        "calculation_fingerprint": "cbe945e5181c7c8c714ebcda1418c7d0375be4e754cd0035f33809eb026105e1",
+        "runtime_fingerprint": "f6689ca2da1f631a3ae0ee3e9c2e0d8b607e2a9fea8b45cd2318b2072f74f587"
+      },
+      "metrics": [
+        {"name": "moment_abs_error_bohr_magneton_per_atom", "value": 0.0879516, "maximum": 0.35},
+        {"name": "magnetic_minus_unpolarized_hartree_per_atom", "value": -0.02382830265, "maximum": 0.0},
+        {"name": "cutoff_moment_drift", "value": 0.000351, "maximum": 0.12},
+        {"name": "kpoint_moment_drift", "value": 0.084764, "maximum": 0.12},
+        {"name": "cutoff_free_energy_drift_hartree", "value": 0.000136428, "maximum": 0.01},
+        {"name": "kpoint_free_energy_drift_hartree", "value": 0.000812471, "maximum": 0.01}
+      ]
+    }
+  ],
+  "candidates": [
+    {
+      "candidate_id": "rocksalt-mgo-primitive-q10-q6-c40-k4",
+      "workload_fingerprint": "74453bf759a19229384de6bbd101c17921531c6d93d0e361e5366904a50d6cf1",
+      "calculation_fingerprint": "b730197a66ddc090265abcbd54069e5f354465ebd02b98346b3b11bea97fa498",
+      "implementation_fingerprint": "87837f9976860730d751639f9967700766913921b92b1cf087240c099179277e",
+      "elapsed_wall_seconds": 40.98934508301318,
+      "peak_temporary_bytes": 57201084,
+      "metrics": [
+        {"name": "orbital_residual", "value": 0.000004329048806539504, "maximum": 0.000002},
+        {"name": "scf_iterations", "value": 80.0, "maximum": 79.0}
+      ]
+    }
+  ]
+}