sync code from github@6f6c7d83845ee0307e16b2b9bb1b389c5bfc5007

README.md

@@ -194,9 +194,7 @@ You can render the API docs with [pdoc](https://pdoc.dev):
     pip install pdoc
     python build_api_docs.py
 
-Open `api_docs/index.html`. This documents the `magnet` package (`magnet.html` is the public
-API: `predict_shifts`, `predict_shieldings`, `implicit_solvent_correction`,
-`explicit_solvent_correction`) and every analysis module under `analysis/code`.
+Most people will only want to look at `api_docs/magnet.html` (the public API), though the other functions are documented as well.
 
 ### How to Cite
 
@@ -211,4 +209,4 @@ Adams, K.; Wagen, C.C.; Wolford, J.; Sak, M.H.; Saurí, J.; Feng, Z.; Bhadauria,
 - The original code, model weights, and datasets in this repository are released under the MIT License (see [`LICENSE`](LICENSE)).
 - Third-party literature data redistributed here remains subject to its original publications' terms and should be
 cited accordingly: CP3 (`data/cp3/`, Smith and Goodman), NS372
- (`data/ns372/`, Schattenberg and Kaupp), and DFT8K (`data/dft8k/`, Guan and Paton).
+ (`data/ns372/`, Schattenberg and Kaupp), DFT8K (`data/dft8k/`, Guan and Paton), and DELTA50 (`data/delta50/`, Cohen *et al.*).

analysis/code/delta50_residuals.py

@@ -0,0 +1,72 @@
+"""MagNET-Zero vs DFT residuals on the DELTA50 benchmark (50 common organics). No plotting.
+
+MagNET-Zero is compared against the DFT level it reproduces, on the same AIMNet2 geometries: protons
+vs WP04/pcSseg-2, carbons vs wB97X-D/pcSseg-2, gas phase; residual = DFT shielding minus MagNET.
+This is the comparison behind the paper's DELTA50 outlier observation (nitromethane, nitroethane, and
+2-methyl-2-nitropropane are the significant outliers). Read via data/delta50/decode_delta50.py.
+"""
+import numpy as np
+
+from stats import summarize_errors
+
+# the DFT level MagNET-Zero reproduces for each nucleus; MagNET-Zero is a single per-atom array
+NUCLEI = {
+    "H": {"atomic_number": 1, "dft": "shielding_wp04_pcSseg2", "nn": "nn_magnet_zero"},
+    "C": {"atomic_number": 6, "dft": "shielding_wb97xd_pcSseg2", "nn": "nn_magnet_zero"},
+}
+
+
+def load_shieldings(delta50_path):
+    """Flat per-atom arrays from the released reader: atomic_numbers, the MagNET predictions, the
+    DFT reference shieldings, and experimental_shift (all ppm, NaN where absent)."""
+    from decode_delta50 import Delta50
+    with Delta50(delta50_path) as ds:
+        return ds.all_atoms()
+
+
+def residuals(shieldings, nucleus):
+    """DFT-minus-MagNET-Zero shielding residuals (ppm) for one nucleus ("H" or "C"), over that
+    element's atoms where both values are present."""
+    spec = NUCLEI[nucleus]
+    z = np.asarray(shieldings["atomic_numbers"])
+    dft = np.asarray(shieldings[spec["dft"]], dtype=float)
+    nn = np.asarray(shieldings[spec["nn"]], dtype=float)
+    keep = (z == spec["atomic_number"]) & np.isfinite(dft) & np.isfinite(nn)
+    return dft[keep] - nn[keep]
+
+
+def residual_stats(errors):
+    """count / RMSE / MAE / median AE / max absolute error for a residual array."""
+    errors = np.asarray(errors, dtype=float)
+    if not errors.size:
+        return {"n": 0, "rmse": float("nan"), "mae": float("nan"), "median_ae": float("nan"),
+                "max_ae": float("nan")}
+    stats = summarize_errors(errors, np.zeros_like(errors))
+    stats["max_ae"] = float(np.abs(errors).max())
+    return stats
+
+
+def residual_summary(delta50_path):
+    """{nucleus: residual_stats} for both nuclei, from the released file."""
+    shieldings = load_shieldings(delta50_path)
+    return {nucleus: residual_stats(residuals(shieldings, nucleus)) for nucleus in NUCLEI}
+
+
+def per_molecule_max_residual(delta50_path):
+    """{molecule_name: {"H": max|residual|, "C": max|residual|}} - the DFT-vs-MagNET-Zero outlier
+    magnitudes per molecule (nitromethane, nitroethane, 2-methyl-2-nitropropane rank highest for C)."""
+    from decode_delta50 import Delta50
+    out = {}
+    with Delta50(delta50_path) as ds:
+        for i in range(len(ds)):
+            m = ds.molecule(i)
+            z = m["atomic_numbers"]
+            ref = np.where(z == 1, m["shielding_wp04_pcSseg2"],
+                          np.where(z == 6, m["shielding_wb97xd_pcSseg2"], np.nan))
+            r = ref - m["nn_magnet_zero"]
+            res = {}
+            for nucleus, zz in (("H", 1), ("C", 6)):
+                sel = (z == zz) & np.isfinite(r)
+                res[nucleus] = float(np.abs(r[sel]).max()) if sel.any() else float("nan")
+            out[m["name"]] = res
+    return out

analysis/code/test_delta50_residuals.py

@@ -0,0 +1,145 @@
+"""Tests for analysis/code/delta50_residuals.py.
+
+Synthetic tests check residual selection and statistics on a hand-built shieldings dict. Opt-in
+tests run against the real delta50.hdf5 and reproduce the paper's DELTA50 observation: MagNET-Zero
+tracks its DFT reference to well under 0.5 ppm (1H) and a few ppm (13C), with nitromethane,
+nitroethane, and 2-methyl-2-nitropropane the significant 13C outliers (up to ~7 ppm).
+"""
+import os
+import sys
+
+import numpy as np
+import pytest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "..", "..", "data", "delta50"))  # decode_delta50
+sys.path.insert(0, HERE)
+import paths  # noqa: E402
+
+import delta50_residuals as D  # noqa: E402
+
+
+def make_shieldings():
+    """Flat shieldings dict like the reader's all_atoms: H, C, C, H, N. MagNET-Zero is one array
+    (WP04 quality at H, wB97X-D quality at C); the DFT reference is split by nucleus."""
+    return {
+        "atomic_numbers": np.array([1, 6, 6, 1, 7]),
+        "shielding_wp04_pcSseg2": np.array([30.5, 150.5, 151.5, 31.5, 200.5]),
+        "shielding_wb97xd_pcSseg2": np.array([30.7, 150.7, 151.7, 31.7, 200.7]),
+        "nn_magnet_zero": np.array([30.6, 150.6, 151.6, 31.3, np.nan]),
+    }
+
+
+def test_residuals_select_nucleus_against_the_right_dft_level():
+    s = make_shieldings()
+    h = D.residuals(s, "H")  # DFT WP04 minus MagNET at the two H atoms (0, 3)
+    np.testing.assert_allclose(sorted(h), sorted([30.5 - 30.6, 31.5 - 31.3]))
+    c = D.residuals(s, "C")  # DFT wB97X-D minus MagNET at the two C atoms (1, 2)
+    np.testing.assert_allclose(sorted(c), sorted([150.7 - 150.6, 151.7 - 151.6]))
+    assert len(h) == 2 and len(c) == 2
+
+
+def test_residual_stats():
+    errors = np.array([-0.1, 0.2, 0.05, -0.05])
+    st = D.residual_stats(errors)
+    assert st["n"] == 4
+    assert st["rmse"] == pytest.approx(np.sqrt(np.mean(errors ** 2)))
+    assert st["mae"] == pytest.approx(np.mean(np.abs(errors)))
+    assert st["max_ae"] == pytest.approx(0.2)
+
+
+def test_residual_stats_empty():
+    st = D.residual_stats(np.array([]))
+    assert st["n"] == 0 and np.isnan(st["rmse"])
+
+
+# --- opt-in: reproduce the DELTA50 residual numbers from the released data -----------------------
+
+REAL = paths.dataset_file("delta50", file=__file__)
+
+
+@pytest.mark.skipif(not os.path.exists(REAL), reason="real delta50.hdf5 not present")
+def test_reproduces_delta50_magnet_zero_vs_dft_residuals():
+    summary = D.residual_summary(REAL)
+    # 1H: MagNET-Zero tracks WP04 to ~0.05 ppm RMSE, max residual ~0.47 ppm ("up to 0.4 ppm")
+    assert summary["H"]["rmse"] == pytest.approx(0.055, abs=0.01)
+    assert summary["H"]["max_ae"] == pytest.approx(0.469, abs=0.02)
+    # 13C: RMSE ~0.61 ppm, max residual ~6.65 ppm ("up to 7 ppm")
+    assert summary["C"]["rmse"] == pytest.approx(0.607, abs=0.03)
+    assert summary["C"]["max_ae"] == pytest.approx(6.654, abs=0.05)
+
+
+@pytest.mark.skipif(not os.path.exists(REAL), reason="real delta50.hdf5 not present")
+def test_named_13c_outliers_are_the_three_nitroalkanes():
+    per_mol = D.per_molecule_max_residual(REAL)
+    top3 = sorted(per_mol, key=lambda nm: -per_mol[nm]["C"])[:3]
+    assert set(top3) == {"nitromethane", "nitroethane", "2-methyl-2-nitropropane"}
+    # nitromethane is the single largest 13C outlier, ~6.65 ppm
+    assert per_mol["nitromethane"]["C"] == pytest.approx(6.654, abs=0.05)
+    # nitrobenzene, by contrast, is accurately predicted (paper's explicit contrast)
+    assert per_mol["nitrobenzene"]["C"] < 0.5
+
+
+# Golden experimental shifts (ppm) for the molecules whose atom order is most likely to be mismapped:
+# the three symmetry-fallback cases and the near-degenerate distinct environments (amide N-methyls,
+# diastereotopic methyls). Values are the published DELTA50 shifts; a mapping regression changes them.
+_GOLDEN_MULTISET = {
+    "cyclohexanone": {"C": [25.02, 27.03, 27.03, 42.0, 42.0, 212.15]},
+    "methyl acetate": {"C": [20.71, 51.62, 171.55]},
+    "2-methyl-2-nitropropane": {"C": [27.87, 27.87, 27.87, 85.06]},
+    "n,n-dimethylformamide": {"C": [31.44, 36.48, 162.52]},
+    "n,n-dimethylacetamide": {"C": [21.58, 35.2, 38.05, 170.66]},
+    "2-methyl-2-butene": {"C": [13.41, 17.32, 25.63, 118.44, 132.1]},
+}
+# (0-based carbon index -> shift): pins each shift to a specific atom, so a swap of two same-value-set
+# environments (e.g. the two DMF N-methyls) fails even though the multiset is unchanged.
+_GOLDEN_ATOM = {
+    "n,n-dimethylformamide": {0: 162.52, 3: 31.44, 4: 36.48},
+    "n,n-dimethylacetamide": {1: 170.66, 3: 35.2, 4: 38.05, 5: 21.58},
+    "2-methyl-2-butene": {0: 17.32, 1: 132.1, 2: 118.44, 3: 13.41, 4: 25.63},
+    "cyclohexanone": {1: 212.15, 2: 42.0, 3: 42.0, 4: 27.03, 5: 27.03, 6: 25.02},
+}
+
+
+@pytest.mark.skipif(not os.path.exists(REAL), reason="real delta50.hdf5 not present")
+def test_experimental_multiset_matches_published_delta50():
+    from decode_delta50 import Delta50
+    with Delta50(REAL) as ds:
+        for name, expected in _GOLDEN_MULTISET.items():
+            m = ds.molecule_by_name(name)
+            got = sorted(round(float(x), 2) for x in m["experimental_shift"][m["atomic_numbers"] == 6]
+                         if np.isfinite(x))
+            assert got == sorted(expected["C"]), name
+
+
+@pytest.mark.skipif(not os.path.exists(REAL), reason="real delta50.hdf5 not present")
+def test_experimental_swap_sensitive_carbons_pinned_to_atoms():
+    from decode_delta50 import Delta50
+    with Delta50(REAL) as ds:
+        for name, atoms in _GOLDEN_ATOM.items():
+            m = ds.molecule_by_name(name)
+            for idx, shift in atoms.items():
+                assert m["atomic_numbers"][idx] == 6, (name, idx)
+                assert m["experimental_shift"][idx] == pytest.approx(shift, abs=1e-3), (name, idx)
+
+
+@pytest.mark.skipif(not os.path.exists(REAL), reason="real delta50.hdf5 not present")
+def test_experimental_shift_present_and_agrees_with_dft():
+    from decode_delta50 import Delta50
+    with Delta50(REAL) as ds:
+        atoms = ds.all_atoms()
+    z = atoms["atomic_numbers"]
+    exp = atoms["experimental_shift"]
+    # experimental is present for every H and C atom, absent for heteroatoms
+    assert np.isfinite(exp[(z == 1) | (z == 6)]).all()
+    assert np.isnan(exp[(z != 1) & (z != 6)]).all()
+    # A correct atom mapping makes scaled DFT track experiment; a scrambled one would not. These
+    # tolerances are loose (our DFT is gas phase on AIMNet2 geometries, not DELTA50's PCM level) but
+    # far below the ppm-scale RMSE a wrong assignment would produce.
+    for zz, key, tol in ((1, "shielding_wp04_pcSseg2", 0.5), (6, "shielding_wb97xd_pcSseg2", 5.0)):
+        m = (z == zz) & np.isfinite(exp)
+        sigma = atoms[key][m]
+        A = np.vstack([sigma, np.ones(m.sum())]).T
+        coef, *_ = np.linalg.lstsq(A, exp[m], rcond=None)
+        rmse = np.sqrt(np.mean((A @ coef - exp[m]) ** 2))
+        assert rmse < tol, f"Z={zz} scaled-DFT-vs-exp RMSE {rmse:.3f} too large"

data/delta50/build_delta50.py

@@ -0,0 +1,299 @@
+"""Provenance/build script for delta50.hdf5.
+
+Regenerates the shipped delta50.hdf5 from three raw sources (none of which are shipped, exactly as
+for dft8k):
+
+  1. the previous delta50.hdf5, for the MagNET predictions already packaged into it
+     (nn_magnet_zero, nn_b3lyp, nn_b3lyp_pcm; these come from MagNET inference and are carried
+     forward unchanged), plus the atom order, geometries, and atomic numbers;
+  2. a directory of Gaussian NMR output files, one per molecule, each with two link jobs at the
+     MagNET-Zero reference levels (WP04 for 1H, wB97X-D for 13C; pcSseg-2; gas), computed on the
+     stored AIMNet2 geometries. Parsed with cctk. These become the per-atom DFT reference
+     shieldings shielding_wp04_pcSseg2 and shielding_wb97xd_pcSseg2, so the MagNET-Zero-vs-DFT
+     residual (Table S3/S4-style, the DELTA50 outlier check in the paper) reproduces from the file.
+  3. DELTA50_benchmark.xlsx from the DELTA50 Supporting Information (Cohen et al., Molecules 2023,
+     28, 2449; reference 47; CC BY 4.0), for the experimental 1H and 13C chemical shifts.
+
+The experimental shifts are mapped onto this file's own atom order and stored per atom as
+experimental_shift. DELTA50 numbers its atoms against independently built structures; those geometries
+were recomputed here, so the numbering only sometimes lines up. Each molecule is mapped by DELTA50's
+own atom numbering when that numbering is element-consistent and covers every H/C atom (47 of 50);
+the three whose atom order differs (cyclohexanone, methyl acetate, 2-methyl-2-nitropropane) are
+mapped by matching RDKit topological-symmetry classes to DELTA50 environments in order of the
+DFT-predicted shift. The mapping is validated: coverage is 100% of H and C atoms, and the large
+scaled-DFT-vs-experiment residuals are all chemically hard sp2 carbons (carbonyl, nitro, aromatic).
+
+Usage:
+    python3 build_delta50.py [SRC_HDF5] [OUT_DIR] [XLSX] [DST_HDF5]
+
+with the defaults below. Requires numpy, h5py, pandas, cctk, and rdkit.
+"""
+from __future__ import annotations
+import os
+import re
+import sys
+from collections import defaultdict
+
+import numpy as np
+import h5py
+
+SCALE = 1e-4
+MARKER = -2147483648
+
+_HOME = os.path.expanduser("~")
+_HERE = os.path.dirname(os.path.abspath(__file__))
+DEFAULT_SRC = os.path.join(_HERE, "delta50.hdf5")
+DEFAULT_OUT_DIR = os.path.join(_HOME, "research", "magnet", "delta50", "delta50",
+                               "output", "wp04_wb97xd_pcSseg2")
+DEFAULT_XLSX = os.path.join(_HOME, "research", "magnet", "delta50", "DELTA50_benchmark.xlsx")
+
+# Molecules whose canonical name here differs from the one in the previous file and the raw inputs.
+# DELTA50 (and the old file) mislabel 2-methyl-2-nitropropane, a C-nitro compound, as a nitrate ester.
+RENAMES = {"t-butyl nitrate": "2-methyl-2-nitropropane"}
+
+# DELTA50 spreadsheet compound names that differ from our molecule_names. "3,3-dimethyl-1-butene"
+# is split across two cells ("(3,3-Dimethyl-" then "1-butene)"), so both fragments are aliased.
+NAME_ALIASES = {
+    "dmf": "n,n-dimethylformamide", "thf": "tetrahydrofuran", "dmac": "n,n-dimethylacetamide",
+    "2cyanopropane": "isobutyronitrile", "mtbe": "methyl t-butyl ether",
+    "cyclopentenone": "cyclopent-2-en-1-one", "cyclohexenone": "cyclohex-2-en-1-one",
+    "pbenzoquinone": "1,4-benzoquinone", "thp": "tetrahydropyran",
+    "33dimethyl": "t-butylethylene", "1butene": "t-butylethylene",
+    "tbutylnitrate": "2-methyl-2-nitropropane",
+}
+
+
+def _norm(s):
+    return re.sub(r"[^a-z0-9]", "", str(s).lower())
+
+
+def _encode(values):
+    v = np.asarray(values, dtype=np.float64)
+    finite = np.isfinite(v)
+    out = np.full(v.shape, MARKER, dtype=np.int64)
+    out[finite] = np.round(v[finite] / SCALE).astype(np.int64)
+    return out.astype(np.int32)
+
+
+def _parse_atom_labels(s):
+    """DELTA50 atom-number strings: comma lists ("5,6,7"), ranges ("7-12"), singles, and mixtures."""
+    out = []
+    for tok in re.split(r"[,\s]+", str(s).strip()):
+        m = re.match(r"^(\d+)-(\d+)$", tok)
+        if m:
+            out += list(range(int(m.group(1)), int(m.group(2)) + 1))
+        elif tok.isdigit():
+            out.append(int(tok))
+    return out
+
+
+def load_predictions(src_hdf5):
+    with h5py.File(src_hdf5, "r") as f:
+        return {
+            "molecule_names": [str(n) for n in f["molecule_names"].asstr()[:]],
+            "n_atoms": f["n_atoms"][:].astype(np.int32),
+            "atomic_numbers": f["atomic_numbers"][:],
+            "coordinates": f["coordinates"][:],
+            "nn_magnet_zero": f["nn_magnet_zero"][:],
+            "nn_b3lyp": f["nn_b3lyp"][:],
+            "nn_b3lyp_pcm": f["nn_b3lyp_pcm"][:],
+        }
+
+
+def load_dft_reference(out_dir, file_names, out_names, atomic_numbers, starts):
+    """Per-atom WP04 and wB97X-D isotropic shieldings from the Gaussian outputs, aligned to the
+    stored atom order (checked). Files are matched by `file_names` (the raw-input naming) but the
+    returned per-molecule dict is keyed by `out_names` (the canonical output naming).
+    Returns (wp04, wb97xd, per_molecule_shieldings)."""
+    import cctk
+    files = {_norm(f[len("delta50-"):-len(".out")]): os.path.join(out_dir, f)
+             for f in os.listdir(out_dir) if f.endswith(".out")}
+    # the Gaussian files keep the pre-rename naming; fall back through RENAMES so re-running the
+    # build against its own (already-renamed) output still finds each file.
+    reverse = {v: k for k, v in RENAMES.items()}
+
+    def _find(name):
+        for candidate in (name, reverse.get(name, name)):
+            if _norm(candidate) in files:
+                return files[_norm(candidate)]
+        raise KeyError(f"no Gaussian output for {name!r} in {out_dir}")
+
+    wp04 = np.full(starts[-1], np.nan)
+    wb97xd = np.full(starts[-1], np.nan)
+    per_mol = {}
+    for i, (file_name, out_name) in enumerate(zip(file_names, out_names)):
+        objs = cctk.GaussianFile.read_file(_find(file_name))
+        by_level = {}
+        for g in objs:
+            ens = g.ensemble
+            iso = np.asarray(ens.get_properties_dict(ens.molecules[-1])["isotropic_shielding"],
+                             dtype=float)
+            z = np.asarray(ens.molecules[-1].atomic_numbers)
+            by_level["wb97xd" if "wb97xd" in g.route_card.lower() else "wp04"] = (z, iso)
+        sl = slice(int(starts[i]), int(starts[i + 1]))
+        z_ref = atomic_numbers[sl]
+        for level, (z, iso) in by_level.items():
+            if not np.array_equal(z, z_ref):
+                raise ValueError(f"{out_name}: {level} atom order does not match the stored geometry")
+        wp04[sl] = by_level["wp04"][1]
+        wb97xd[sl] = by_level["wb97xd"][1]
+        per_mol[out_name] = {"wp04": by_level["wp04"][1], "wb97xd": by_level["wb97xd"][1]}
+    return wp04, wb97xd, per_mol
+
+
+def _parse_experimental_sheets(xlsx, valid_names):
+    """{molecule_name: {"H": [(atoms, shift)], "C": [...]}} from the two DELTA50 functional sheets."""
+    import pandas as pd
+    valid = {_norm(n): n for n in valid_names}
+    out = {n: {"H": [], "C": []} for n in valid_names}
+    for sheet, nucleus in (("1H Functional", "H"), ("13C Functional", "C")):
+        df = pd.read_excel(xlsx, sheet_name=sheet, header=None)
+        hdr = next(r for r in range(df.shape[0]) if str(df.iat[r, 0]).strip() == "Compound")
+        current = None
+        for r in range(hdr + 1, df.shape[0]):
+            compound, label, shift = df.iat[r, 0], df.iat[r, 1], df.iat[r, 2]
+            if isinstance(compound, str) and compound.strip():
+                k = _norm(compound)
+                current = valid.get(_norm(NAME_ALIASES.get(k, compound)))
+            if current is None or pd.isna(label) or pd.isna(shift):
+                continue
+            out[current][nucleus].append((_parse_atom_labels(label), float(shift)))
+    return out
+
+
+def _symmetry_classes(atomic_numbers, coordinates):
+    """RDKit topological-symmetry classes for one molecule: {rank: [atom indices]}. Bonds are
+    perceived from the geometry."""
+    from rdkit import Chem
+    from rdkit.Chem import rdDetermineBonds
+    pt = Chem.GetPeriodicTable()
+    lines = [str(len(atomic_numbers)), ""]
+    for z, xyz in zip(atomic_numbers, coordinates):
+        lines.append(f"{pt.GetElementSymbol(int(z))} {xyz[0]:.6f} {xyz[1]:.6f} {xyz[2]:.6f}")
+    mol = Chem.MolFromXYZBlock("\n".join(lines))
+    rdDetermineBonds.DetermineBonds(mol, charge=0)
+    classes = defaultdict(list)
+    for atom_idx, rank in enumerate(Chem.CanonicalRankAtoms(mol, breakTies=False)):
+        classes[rank].append(atom_idx)
+    return classes
+
+
+def map_experimental(xlsx, molecule_names, atomic_numbers, coordinates, starts, dft_per_mol):
+    """Map DELTA50 experimental shifts onto our atom order; per-atom array (ppm, NaN where absent).
+
+    Direct: use DELTA50's atom numbering where it is element-consistent and covers every H/C atom.
+    Fallback: for molecules whose atom order differs, match RDKit symmetry classes to DELTA50
+    environments by DFT-predicted shift order. Asserts full H/C coverage."""
+    experimental = np.full(starts[-1], np.nan)
+    fallback = []
+    exp = _parse_experimental_sheets(xlsx, molecule_names)
+    for i, name in enumerate(molecule_names):
+        sl = slice(int(starts[i]), int(starts[i + 1]))
+        z = atomic_numbers[sl]
+        n = len(z)
+        envs = {1: exp[name]["H"], 6: exp[name]["C"]}
+        consistent = all(1 <= a <= n and z[a - 1] == zz
+                         for zz in (1, 6) for atoms, _ in envs[zz] for a in atoms)
+        # direct: use DELTA50's numbering. conflict = two environments claim one atom with different
+        # shifts (a numbering error, e.g. overlapping ranges); route those to the fallback rather
+        # than let a later write silently win.
+        direct = np.full(n, np.nan)
+        conflict = False
+        if consistent:
+            for zz in (1, 6):
+                for atoms, shift in envs[zz]:
+                    for a in atoms:
+                        if np.isfinite(direct[a - 1]) and direct[a - 1] != shift:
+                            conflict = True
+                        direct[a - 1] = shift
+        if consistent and not conflict and np.isfinite(direct[(z == 1) | (z == 6)]).all():
+            experimental[sl] = direct
+            continue
+        # fallback: RDKit symmetry classes matched to DELTA50 environments by DFT-shift order
+        fallback.append(name)
+        classes = _symmetry_classes(z, coordinates[sl])
+        assigned = np.full(n, np.nan)
+        sigma = {1: dft_per_mol[name]["wp04"], 6: dft_per_mol[name]["wb97xd"]}
+        for zz in (1, 6):
+            element_classes = [atoms for atoms in classes.values() if z[atoms[0]] == zz]
+            if len(element_classes) != len(envs[zz]):
+                raise ValueError(f"{name}: {len(element_classes)} symmetry classes vs "
+                                 f"{len(envs[zz])} DELTA50 environments for Z={zz}")
+            by_sigma = sorted(element_classes, key=lambda a: np.mean([sigma[zz][j] for j in a]))
+            by_shift = sorted(envs[zz], key=lambda e: -e[1])  # sigma ascending <-> shift descending
+            for atoms, (_, shift) in zip(by_sigma, by_shift):
+                for j in atoms:
+                    assigned[j] = shift
+        experimental[sl] = assigned
+
+    hc = (atomic_numbers == 1) | (atomic_numbers == 6)
+    missing = int((~np.isfinite(experimental[hc])).sum())
+    if missing:
+        raise ValueError(f"{missing} H/C atoms have no experimental shift")
+    return experimental, fallback
+
+
+def build(src_hdf5, out_dir, xlsx, dst_hdf5):
+    pred = load_predictions(src_hdf5)
+    file_names = pred["molecule_names"]                         # raw-input naming (files, sheets)
+    names = [RENAMES.get(n, n) for n in file_names]             # canonical output naming
+    starts = np.zeros(len(names) + 1, np.int64)
+    np.cumsum(pred["n_atoms"], out=starts[1:])
+
+    coords = pred["coordinates"].astype(np.float64) * SCALE  # int32 fixed point -> Angstrom
+    wp04, wb97xd, dft_per_mol = load_dft_reference(out_dir, file_names, names,
+                                                   pred["atomic_numbers"], starts)
+    experimental, fallback = map_experimental(xlsx, names, pred["atomic_numbers"], coords, starts,
+                                              dft_per_mol)
+    print(f"experimental mapped by symmetry fallback: {fallback}")
+
+    string_dt = h5py.string_dtype("utf-8")
+    opts = dict(compression="gzip", shuffle=True)
+    with h5py.File(dst_hdf5, "w") as f:
+        f.attrs["dataset"] = "delta50"
+        f.attrs["description"] = (
+            "The 50 small molecules of the DELTA50 benchmark (Cohen et al., Molecules 2023, 28, "
+            "2449; CC BY 4.0) on AIMNet2 geometries. Per-atom arrays: MagNET predictions, the DFT "
+            "reference shieldings MagNET-Zero targets (WP04 for 1H, wB97X-D for 13C, pcSseg-2, gas), "
+            "and the published experimental shifts mapped onto this atom order. The MagNET-Zero-vs-"
+            "DFT residual and the experiment comparison both reproduce from this file.")
+        f.attrs["n_molecules"] = len(names)
+        f.attrs["geometry"] = "AIMNet2"
+        f.attrs["scale"] = SCALE
+        f.attrs["missing_value_marker"] = MARKER
+        f.attrs["nn_magnet_zero"] = "MagNET-Zero: WP04 (1H) / wB97X-D (13C), pcSseg-2, 20-pass"
+        f.attrs["nn_b3lyp"] = "MagNET-PCM gas-phase component: B3LYP/pcSseg-2"
+        f.attrs["nn_b3lyp_pcm"] = "MagNET-PCM chloroform component: B3LYP/pcSseg-2 + chloroform PCM"
+        f.attrs["shielding_wp04_pcSseg2"] = "DFT reference: WP04/pcSseg-2 gas (the 1H MagNET-Zero level)"
+        f.attrs["shielding_wb97xd_pcSseg2"] = "DFT reference: wB97X-D/pcSseg-2 gas (the 13C MagNET-Zero level)"
+        f.attrs["experimental_shift"] = (
+            "Experimental 1H/13C shift (ppm, CDCl3, TMS reference) from DELTA50 (Cohen et al., "
+            "Molecules 2023, 28, 2449; CC BY 4.0), mapped onto this atom order. NaN at atoms with no "
+            "reported shift (heteroatoms).")
+
+        f.create_dataset("molecule_names", data=np.array(names, dtype=object), dtype=string_dt)
+        f.create_dataset("n_atoms", data=pred["n_atoms"], **opts)
+        f.create_dataset("atomic_numbers", data=pred["atomic_numbers"], **opts)
+        f.create_dataset("coordinates", data=pred["coordinates"], **opts)
+        f.create_dataset("nn_magnet_zero", data=pred["nn_magnet_zero"], **opts)
+        f.create_dataset("nn_b3lyp", data=pred["nn_b3lyp"], **opts)
+        f.create_dataset("nn_b3lyp_pcm", data=pred["nn_b3lyp_pcm"], **opts)
+        f.create_dataset("shielding_wp04_pcSseg2", data=_encode(wp04), **opts)
+        f.create_dataset("shielding_wb97xd_pcSseg2", data=_encode(wb97xd), **opts)
+        f.create_dataset("experimental_shift", data=_encode(experimental), **opts)
+
+    return dst_hdf5
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    src = args[0] if len(args) > 0 else DEFAULT_SRC
+    out_dir = args[1] if len(args) > 1 else DEFAULT_OUT_DIR
+    xlsx = args[2] if len(args) > 2 else DEFAULT_XLSX
+    dst = args[3] if len(args) > 3 else DEFAULT_SRC
+    print(f"src predictions : {src}")
+    print(f"DFT outputs     : {out_dir}")
+    print(f"experimental    : {xlsx}")
+    print(f"writing         : {dst}")
+    build(src, out_dir, xlsx, dst)
+    print("done.")

data/delta50/decode_delta50.py

@@ -2,23 +2,30 @@
 decode_delta50.py - reader/decoder for the delta50 HDF5 dataset.
 
 DELTA50 is a small benchmark of 50 common organic molecules (reference 47 in the paper). This
-file holds MagNET's predicted NMR shieldings for each molecule on its AIMNet2 geometry, at three
-model chemistries:
-
-  nn_magnet_zero  MagNET-Zero (WP04 for 1H, wB97X-D for 13C; pcSseg-2; 20-pass), the gas-phase
-                  triple-zeta-quality prediction
-  nn_b3lyp        the gas-phase component of the MagNET-PCM correction (B3LYP/pcSseg-2)
-  nn_b3lyp_pcm    the chloroform component of the MagNET-PCM correction (B3LYP/pcSseg-2 + PCM)
+file holds, per atom on each molecule's AIMNet2 geometry: MagNET's predicted shieldings, the DFT
+reference shieldings MagNET-Zero is trained to reproduce, and the published experimental shifts.
+
+  nn_magnet_zero          MagNET-Zero (WP04 for 1H, wB97X-D for 13C; pcSseg-2; 20-pass), the
+                          gas-phase triple-zeta-quality prediction
+  nn_b3lyp                the gas-phase component of the MagNET-PCM correction (B3LYP/pcSseg-2)
+  nn_b3lyp_pcm            the chloroform component of the MagNET-PCM correction (B3LYP/pcSseg-2 + PCM)
+  shielding_wp04_pcSseg2  DFT reference, WP04/pcSseg-2 gas (the level MagNET-Zero targets for 1H)
+  shielding_wb97xd_pcSseg2 DFT reference, wB97X-D/pcSseg-2 gas (the level MagNET-Zero targets for 13C)
+  experimental_shift      experimental 1H/13C shift (ppm, CDCl3, TMS ref) from DELTA50 (Cohen et
+                          al., Molecules 2023, 28, 2449; CC BY 4.0), mapped onto this atom order
 
 The MagNET-PCM implicit-solvent correction for a molecule is nn_b3lyp_pcm minus nn_b3lyp. The
-paper uses this set to probe outliers (nitromethane, nitroethane, and t-butyl nitrate are the
-notable ones).
+MagNET-Zero-vs-DFT residual (nn_magnet_zero minus shielding_wp04_pcSseg2 at 1H, minus
+shielding_wb97xd_pcSseg2 at 13C) is what the paper uses to probe outliers (nitromethane, nitroethane,
+and 2-methyl-2-nitropropane are the notable ones). experimental_shift is NaN at atoms with no
+reported shift (heteroatoms).
 
 Storage format:
   - Per-atom arrays are concatenated across molecules. Molecule i has `n_atoms[i]` atoms and owns
     the rows [start[i], start[i+1]) where start is the cumulative sum of `n_atoms`.
-  - coordinates and shieldings are int32 fixed point: physical = stored * 1e-4, so reconstruction
-    error is <= 5e-5 (Angstrom or ppm). A missing value would be the marker -2147483648 -> NaN.
+  - coordinates, shieldings, and shifts are int32 fixed point: physical = stored * 1e-4, so
+    reconstruction error is <= 5e-5 (Angstrom or ppm). A missing value is the marker
+    -2147483648 -> NaN.
   - molecules are identified by name (`molecule_names`).
 
 Requires: Python >= 3.7, numpy, h5py. No other dependencies.
@@ -67,8 +74,10 @@ class Delta50:
     def molecule(self, index: int) -> dict:
         """Return one molecule's data (physical units) by position.
 
-        Keys: name; atomic_numbers (n,); coordinates (n, 3 Angstrom); and the three predicted
-        shieldings (nn_magnet_zero, nn_b3lyp, nn_b3lyp_pcm), each (n,) ppm.
+        Keys: name; atomic_numbers (n,); coordinates (n, 3 Angstrom); the three predicted shieldings
+        (nn_magnet_zero, nn_b3lyp, nn_b3lyp_pcm); the two DFT reference shieldings
+        (shielding_wp04_pcSseg2, shielding_wb97xd_pcSseg2); and experimental_shift. Every per-atom
+        array is (n,) ppm; experimental_shift is NaN at atoms with no reported shift.
         """
         self._check(index)
         sl = slice(int(self._start[index]), int(self._start[index + 1]))
@@ -79,8 +88,24 @@ class Delta50:
             "nn_magnet_zero": _decode(self.f["nn_magnet_zero"][sl]),
             "nn_b3lyp": _decode(self.f["nn_b3lyp"][sl]),
             "nn_b3lyp_pcm": _decode(self.f["nn_b3lyp_pcm"][sl]),
+            "shielding_wp04_pcSseg2": _decode(self.f["shielding_wp04_pcSseg2"][sl]),
+            "shielding_wb97xd_pcSseg2": _decode(self.f["shielding_wb97xd_pcSseg2"][sl]),
+            "experimental_shift": _decode(self.f["experimental_shift"][sl]),
         }
 
+    def all_atoms(self) -> dict:
+        """Every atom in the dataset as flat arrays (physical units), for whole-dataset analyses
+        such as the MagNET-Zero-vs-DFT residual or DFT-vs-experiment comparisons.
+
+        Keys: atomic_numbers (n_total,); nn_magnet_zero, nn_b3lyp, nn_b3lyp_pcm,
+        shielding_wp04_pcSseg2, shielding_wb97xd_pcSseg2, experimental_shift, each (n_total,) ppm.
+        """
+        keys = ("nn_magnet_zero", "nn_b3lyp", "nn_b3lyp_pcm", "shielding_wp04_pcSseg2",
+                "shielding_wb97xd_pcSseg2", "experimental_shift")
+        out = {"atomic_numbers": self.f["atomic_numbers"][:]}
+        out.update({k: _decode(self.f[k][:]) for k in keys})
+        return out
+
     def molecule_by_name(self, name: str) -> dict:
         """Return one molecule's data (see `molecule`) by name."""
         return self.molecule(self.index_of(name))

data/delta50/delta50.hdf5

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:977bd7d46e5a81f5b1f0a19983a84ec3feb2bf26d2181c75bb25894d64e11c6f
-size 33248
+oid sha256:c4a4b5e42fdd2e1f07d0e98bddf4f22cdab7edd9d5d99c728e2a42f082671e2a
+size 47212

data/delta50/test_delta50.py

@@ -23,8 +23,9 @@ REAL = os.path.join(HERE, "delta50.hdf5")
 
 def _encode(values):
     v = np.asarray(values, dtype=np.float64)
-    out = np.round(v / SCALE).astype(np.int64)
-    out[~np.isfinite(v)] = MARKER
+    finite = np.isfinite(v)
+    out = np.full(v.shape, MARKER, dtype=np.int64)
+    out[finite] = np.round(v[finite] / SCALE).astype(np.int64)
     return out.astype(np.int32)
 
 
@@ -34,16 +35,21 @@ def _build_synthetic(path):
     names = ["alpha", "beta"]
     specs = [3, 5]  # n_atoms
     n_atoms = np.array(specs, dtype=np.int32)
-    an, coords, zero, b3, pcm, truth = [], [], [], [], [], []
+    an, coords, zero, b3, pcm, dwp, dwb, exp, truth = [], [], [], [], [], [], [], [], []
     for na in specs:
         a = rng.integers(1, 9, size=na).astype(np.uint8)
         c = rng.normal(0, 2, size=(na, 3))
         z = rng.normal(100, 30, size=na)
         g = rng.normal(100, 30, size=na)
         p = g + rng.normal(0, 0.2, size=na)
+        dw = z + rng.normal(0, 0.1, size=na)
+        db = z + rng.normal(0, 0.1, size=na)
+        e = rng.normal(5, 2, size=na)
+        e[a > 6] = np.nan  # heteroatoms have no experimental shift
         an.append(a); coords.append(_encode(c)); zero.append(_encode(z))
         b3.append(_encode(g)); pcm.append(_encode(p))
-        truth.append((a, c, z, g, p))
+        dwp.append(_encode(dw)); dwb.append(_encode(db)); exp.append(_encode(e))
+        truth.append((a, c, z, g, p, dw, db, e))
     opts = dict(compression="gzip", shuffle=True)
     with h5py.File(path, "w") as f:
         f.attrs["n_molecules"] = 2
@@ -57,6 +63,9 @@ def _build_synthetic(path):
         f.create_dataset("nn_magnet_zero", data=np.concatenate(zero), **opts)
         f.create_dataset("nn_b3lyp", data=np.concatenate(b3), **opts)
         f.create_dataset("nn_b3lyp_pcm", data=np.concatenate(pcm), **opts)
+        f.create_dataset("shielding_wp04_pcSseg2", data=np.concatenate(dwp), **opts)
+        f.create_dataset("shielding_wb97xd_pcSseg2", data=np.concatenate(dwb), **opts)
+        f.create_dataset("experimental_shift", data=np.concatenate(exp), **opts)
     return names, specs, truth
 
 
@@ -68,12 +77,17 @@ def test_reader_and_decode(tmp_path):
         assert ds.molecule_names == names
         for i, na in enumerate(specs):
             m = ds.molecule(i)
-            a, c, z, g, p = truth[i]
+            a, c, z, g, p, dw, db, e = truth[i]
             assert m["name"] == names[i]
             assert np.array_equal(m["atomic_numbers"], a)
             assert m["coordinates"].shape == (na, 3)
             assert np.abs(m["coordinates"] - c).max() <= 5e-5
             assert np.abs(m["nn_magnet_zero"] - z).max() <= 5e-5
+            assert np.abs(m["shielding_wp04_pcSseg2"] - dw).max() <= 5e-5
+            assert np.abs(m["shielding_wb97xd_pcSseg2"] - db).max() <= 5e-5
+            finite = np.isfinite(e)
+            assert np.abs(m["experimental_shift"][finite] - e[finite]).max() <= 5e-5
+            assert np.isnan(m["experimental_shift"][~finite]).all()
             assert np.allclose(ds.pcm_correction(i), p - g, atol=1e-4)
 
 
@@ -98,6 +112,16 @@ def test_real_file_smoke():
     with D.Delta50(REAL) as ds:
         assert len(ds) == 50
         assert "nitromethane" in ds.molecule_names
+        # the DELTA50 nitrate-ester misnomer is corrected to the C-nitro name here
+        assert "2-methyl-2-nitropropane" in ds.molecule_names
+        assert "t-butyl nitrate" not in ds.molecule_names
         m = ds.molecule_by_name("nitromethane")
         assert np.isfinite(m["nn_magnet_zero"]).all()
+        for key in ("shielding_wp04_pcSseg2", "shielding_wb97xd_pcSseg2", "experimental_shift"):
+            assert m[key].shape == m["atomic_numbers"].shape
+        # nitromethane: WP04 at H, wB97X-D at C, and an experimental shift on every H and C
+        z = m["atomic_numbers"]
+        assert np.isfinite(m["experimental_shift"][(z == 1) | (z == 6)]).all()
         assert ds.pcm_correction(ds.index_of("nitromethane")).shape == m["atomic_numbers"].shape
+        atoms = ds.all_atoms()
+        assert atoms["atomic_numbers"].shape == atoms["experimental_shift"].shape