vibe-qc/Documentation

QM9 polarizability ridge baseline

SPP-04 (#782) is an inspectable structure-only regression experiment for QM9 isotropic static molecular polarizability in bohr^3. It compares a training-mean predictor, composition ridge, composition plus geometry ridge, and composition plus geometry plus spectral ridge on identical SPP-03 frozen splits. NumPy is the only numerical dependency. No estimator framework, dataset SDK, new QC calculation or download is needed at inference. Model weights are not bundled or released.

The training tool is scripts/property_ridge_baseline.py, outside the importable runtime. vibeqc.polarizability_ridge owns only the validated coefficient artifact and prediction. This bounded scalar artifact is not the general predictor interface planned under SPP-06.

Fit and selection

For each feature column, the tool computes its mean and population standard deviation using only training rows. Numerically constant columns receive scale one and coefficient zero. The centered design is solved by float64 SVD:

Z = (X - training_mean) / training_scale
Z = U diag(s) V^T
beta = V diag(s / (s^2 + n_train * lambda)) U^T (y - mean_train(y))
prediction = mean_train(y) + Z beta

This minimizes mean squared error plus lambda * ||beta||^2, with an unpenalized intercept. At zero lambda, singular values at or below eps * max(n_train, n_features) * s_max are discarded, yielding a truncated minimum-norm least-squares solution. The artifact records singular values, rank, cutoff, constant columns and full-column conditioning. Rank deficiency is reported explicitly; an undefined full-column condition is null. The implementation does not form or invert a normal-equation matrix. See Hoerl and Kennard (1970) for ridge regularization; the displayed SVD form specifies our implementation.

The default fixed grid is 0, 1e-6, 1e-4, 0.01, 1, 100. Validation MAE chooses lambda; exact ties prefer the smaller lambda. All transforms and coefficients remain fitted on training only. There is no train-plus-validation refit. Calibration and test labels cannot enter the selection function. Feature failures abort the study instead of changing the frozen population. No missing feature is imputed. Target-derived and QC-assisted columns are refused in this initial structure-only experiment.

This follows the separation of descriptors, fitting and external evaluation discussed in Le et al. (2012), sections 2-6. Gilmer et al. (2017), section 4 provides QM9 task context; no message-passing code or reported score is reused. SPP-03’s original source definition of isotropic alpha is authoritative.

Declare the study before scoring test data

First create a plan, then run it against an already frozen SPP-03 manifest:

python scripts/property_ridge_baseline.py plan --output "$BENCHMARK_DIR/alpha-plan.json"
python scripts/property_ridge_baseline.py run \
  --archive "$BENCHMARK_DIR/dsgdb9nsd.xyz.tar.bz2" \
  --uncharacterized "$BENCHMARK_DIR/uncharacterized.txt" \
  --readme "$BENCHMARK_DIR/readme.txt" \
  --splits "$BENCHMARK_DIR/qm9-alpha-splits.json" \
  --plan "$BENCHMARK_DIR/alpha-plan.json" \
  --output "$BENCHMARK_DIR/alpha-study"

The default pilot criterion requires the validation-selected geometry or spectral model to improve validation MAE by at least 5% over both the training mean and composition ridge. It also requires average feature construction below 50 ms/molecule and validation prediction below 1 ms/molecule on the measured runtime. These are declared research comparison budgets, not application-specific accuracy requirements or hardware-independent promises.

The plan, selected coefficients and validation decision are hashed before calibration and test scoring. A NO-GO is a completed comparison. GO-research does not release a model or establish production accuracy. Test errors are reported after selection and cannot change its verdict. Run a new, explicitly versioned study for new criteria; do not tune against previously scored test labels or change memberships to improve a result.

Outputs include all four coefficient artifacts per split and a JSON report with dataset/split/feature/artifact/plan hashes, seeds, row and group counts, validation/test MAE and RMSE, mean/std/max group MAE, interval widths and coverage, failures, rank diagnostics and measured costs. Feature costs include construction and column-manifest validation. Composition uses the same cheap geometry table, so its recorded feature cost is a conservative upper bound. The shared geometry and spectral preparation costs are counted once in the study total. Fitting, selection, calibration and test inference are separately reported. Input loading is reported separately; downloads are outside the study. No new QC calculations are performed. The original B3LYP geometry generation cost is unknown and excluded; these supplied optimized geometries do not establish a speedup for an end-to-end geometry-to-property workflow. Changing BLAS implementations can alter the last bits of coefficients and therefore their hashes; hashes identify actual fits, not a cross-platform bitwise promise.

Group calibration and limits

Each calibration component contributes the maximum absolute residual over its eligible molecules. With G calibration groups and miscoverage a, the radius is the ceil((G + 1) * (1 - a))-th smallest group residual maximum. Too few groups for a finite order statistic is an error, not a clipped quantile. Every prediction receives the interval [prediction - radius, prediction + radius]. Negative predictions or lower endpoints are preserved rather than clipped.

The finite-sample rank follows Angelopoulos and Bates, section 1.1. Our nonconformity score is a whole composition-group maximum, not an individual molecule residual. Coverage would require exchangeable groups under the stated calibration construction. Neither chemistry holdouts nor arbitrary deployment satisfy that assumption automatically. Reports therefore include both empirical molecule coverage and the fraction of test groups whose entire population is covered. Large intervals can cover well while being unhelpful.

The supported structural domain is neutral singlet, nonperiodic H/C/N/O/F molecules with at most nine heavy atoms and 29 total atoms. Descriptor-based prediction refuses structures outside it and flags unseen training elements or selected features outside their observed training ranges. A flag is a diagnostic, not a calibrated out-of-domain probability. The fluorine holdout is a deliberate chemistry shift. Single-seed reports describe group variation, not seed uncertainty or universal model performance.

Inspect and reuse a local artifact

from vibeqc.output import read_polarizability_ridge
from vibeqc.molecular_descriptors import DescriptorConfig, molecular_descriptors

model = read_polarizability_ridge("local-research-model.json")
config = DescriptorConfig(**dict(model.descriptor_manifest["settings"]))
features = molecular_descriptors(structure_identity, config=config)
prediction = model.predict(features)
print(prediction["value"], prediction["unit"], prediction["domain_flags"])

structure_identity must explicitly provide charge zero and multiplicity one. The artifact contains coefficients, scaling, selected feature order, descriptor manifest, training ranges, source/split provenance and calibration metadata. Loading verifies its content hash and refuses unknown schemas, fields, units or nonfinite values. It deserializes data only, never executable objects. The lower-level matrix API requires the exact feature order and descriptor hash, but cannot check molecular charge/spin/size from a matrix alone. All user-facing files go through vibeqc.output; no QVF schema is changed.