vibe-qcDocumentation

Pinned structure-property benchmarks¶

SPP-03 (#781) supplies owned, offline QM9 and JARVIS parsers, source and row hashes, explicit exclusions, grouped splits and a training-only preprocessing contract. It performs no model fitting or new quantum-chemistry calculation. The implementation needs only Python’s standard library; dataset SDKs, RDKit, ASE and model frameworks are not required. Imports never fetch data.

Source and target contracts¶

Profile	Pinned source	Target and units	Geometry and property protocol
`qm9-alpha`	Original QM9 archive, Figshare file 3195389, article 1057646 v2	XYZ property 7, `alpha`, molecular isotropic static dipole polarizability in bohr cubed	Neutral small organic molecules; B3LYP/6-31G(2df,p) relaxed geometry and property
`jarvis-opt-gap`	JARVIS-DFT 2021-08-18, Figshare file 29204826, article 6815699 v9	Exactly `optb88vdw_bandgap`, an intensive Kohn-Sham gap in eV	VASP PAW optB88-vdW relaxed periodic structure and electronic calculation

QM9 coordinates are angstroms. JARVIS lattice vectors are rows in angstroms; the parser respects its explicit Cartesian/fractional flag. Unknown JARVIS charge and multiplicity remain unknown. Per-record settings such as plane-wave cutoff and k-point length remain recoverable from the pinned raw record, whose canonical JSON hash is retained. A fixed profile does not imply identical numerical settings for every material. No MBJ gap, optical gap, experimental gap or quasiparticle gap is substituted for the selected field.

The QM9 mapping follows the dataset’s README, Format and Notes sections, and Ramakrishnan et al., Data Records. The JARVIS mapping follows Choudhary and DeCost, Model performance and Table 3, and the versioned source. This archive has 55,723 rows, while the paper reports 55,722. The parser records the archive’s actual population rather than adjusting it to the paper.

Explicit local acquisition¶

Download these public files into a data directory outside the source checkout. No credentials are needed for these pinned releases. Any future authenticated source must keep credentials outside manifests and source control.

export BENCHMARK_DIR="$HOME/.cache/vibe-qc/property-benchmarks"
mkdir -p "$BENCHMARK_DIR"
curl --fail --location https://ndownloader.figshare.com/files/3195389 \
  --output "$BENCHMARK_DIR/dsgdb9nsd.xyz.tar.bz2"
curl --fail --location https://ndownloader.figshare.com/files/3195404 \
  --output "$BENCHMARK_DIR/uncharacterized.txt"
curl --fail --location https://ndownloader.figshare.com/files/3195392 \
  --output "$BENCHMARK_DIR/readme.txt"
curl --fail --location https://ndownloader.figshare.com/files/29204826 \
  --output "$BENCHMARK_DIR/jdft_3d-8-18-2021.json.zip"

The loaders verify size, SHA256 and publisher MD5 against constants in vibeqc.property_benchmarks before parsing those same bytes. Tar/ZIP members are read in memory, never extracted onto the filesystem. A newer release or modified exclusion file fails the pin; changing a pin is a new benchmark version, not an automatic refresh. Full archive loading uses memory for the decompressed records; this is a bounded local benchmark loader, not a streaming database service.

Artifact	SHA256
QM9 XYZ archive	`3a63848ac80691bdb8d41834b575afad345b9300d7a2db0c38adb7f6eaa8360c`
QM9 consistency exclusions	`3aa5115d540b356de94791d4a74c3bf1ed91c469ecf52a4f5d7cc0506fe02e24`
QM9 README	`0ee83fc21faa9527ebe89fad0ce8f2bd2da1cbd35a3c7edc199f4ad21d31d97a`
JARVIS ZIP	`03e5af365067117d97c73b83fc74b86f79cdba4cc592b346f5aa2209a24c3925`

The individual QM9 file records declare CC0, and the selected JARVIS release declares CC BY 4.0. See the licensing inventory for the precise metadata endpoints and attribution. These terms concern data; they do not license external code or model weights. No database, label subset, SDK code or weights are bundled. Tests generate synthetic fixtures.

Exclusions and lineage¶

Every source row remains in the manifest, including excluded rows. Missing or invalid targets are null with a reason, never zero-imputed. Real zero JARVIS gaps are retained. QM9’s 3,054 geometry-consistency failures and the 11 difficult geometries enumerated in the pinned README are excluded, including any overlap. The latter is a deliberately stricter policy than consistency exclusions alone. Malformed identities/record layouts abort the load; invalid labels or geometry receive explicit exclusion reasons.

Five JARVIS jid families occur repeatedly in this archive. All 16 rows in those families are excluded as duplicate_source_id, including differing records under one ID. Each is retained with a raw-record hash and occurrence suffix. They still share the original jid parent. Nothing selects an arbitrary preferred version or silently increases its statistical weight.

Rows contain typed SPP-01 StructureIdentity objects, target scalars, fidelity labels, parent links and raw hashes. Exported manifests retain structure hashes and composition rather than full coordinates. QM9 scalar alpha is not expanded into a fabricated polarizability tensor. Synthetic BenchmarkDataset objects are explicitly labelled synthetic and do not claim verified source artifacts.

Freeze random groups and a chemistry holdout¶

import os
from pathlib import Path
from vibeqc.property_benchmarks import load_qm9, load_jarvis, grouped_split
from vibeqc.output import write_property_benchmark, read_property_benchmark

data_dir = Path(os.environ["BENCHMARK_DIR"])
qm9 = load_qm9(data_dir / "dsgdb9nsd.xyz.tar.bz2",
              data_dir / "uncharacterized.txt", data_dir / "readme.txt")
random_groups = grouped_split(qm9, seed=781)
fluorine_holdout = grouped_split(qm9, seed=781, holdout_elements=(9,))
path = data_dir / "qm9-alpha-splits.json"
write_property_benchmark(path, qm9, (random_groups, fluorine_holdout))
assert read_property_benchmark(path, qm9) == (random_groups, fluorine_holdout)

jarvis = load_jarvis(data_dir / "jdft_3d-8-18-2021.json.zip")
write_property_benchmark(data_dir / "jarvis-opt-gap-splits.json", jarvis,
    (grouped_split(jarvis, seed=781),
     grouped_split(jarvis, seed=781, holdout_elements=(8,))))

The default fractions are 70/10/10/10 for training, validation, calibration and test. SHA256 of the seed and sorted component IDs selects the partition, independently of labels and input order. These are expected shares of groups, not exact row counts. Small populations can have empty partitions; a training fit on an empty partition is refused. Save the manifest before fitting models.

Grouping conservatively joins full molecular compositions or reduced crystal compositions, then unions all source-parent and validated-equivalence links transitively. This keeps conformers, duplicates, supercells and paired fidelities together. It also overgroups distinct isomers and polymorphs; it is a leakage-control policy, not a chemical equivalence detector. Spectral similarity is never an identity. Additional GroupLink evidence must come from source identities or independently validated equivalence. Excluded rows retain their grouping links, so removing a bad label cannot break a connecting path.

An element holdout assigns every component containing any selected element to test, including linked partner rows. The other three fractions are then renormalized over the remaining groups; no additional random test rows are selected. A holdout that leaves no eligible test or no eligible non-test rows is refused. Fluorine for QM9 and oxygen for JARVIS are explicit example domain choices, not universal benchmark standards.

These splits deliberately differ from published random row splits, including ALIGNN’s 80/10/10 protocol. Their scores cannot be presented as reproductions of that paper’s tables. Parent evidence is caller supplied; the library cannot certify an invented source relationship or discover arbitrary unreported ones.

Training-only preprocessing¶

split.fit_rows(dataset) returns only training rows after verifying the snapshot and recomputing memberships. An explicit ID subset is allowed only if it is nonempty, unique and entirely in training. Validation, calibration, test, unknown and excluded IDs are refused.

split.preprocessing_contract(dataset, feature_manifest_sha256=...) freezes that population with the SPP-02 feature-manifest hash and split hash. Scaling, imputation and feature-selection fits must use these rows. Validation selects hyperparameters; calibration fits uncertainty intervals after model selection; test is reserved for final evaluation. No preprocessing or model is fitted by SPP-03. Callers can still misuse externally accessed data; this contract is the required entry point for the forthcoming SPP-04 baseline, not a sandbox.

Manifest replay verifies the full snapshot hash, split hash, configuration, exclusions and memberships. Changing a source, target, row, grouping or seed requires a new manifest. No QVF schema is changed.