Structure-property roadmap¶
Status: planned, 2026-11-01. Tracker #778. These tasks have no assigned release or milestone and do not add a release gate. This plan turns the 20-paper structure-property review into bounded work; it does not claim that the proposed models or bulk-property workflows already exist.
The first useful result is a reproducible connection between a structure, a qualified calculation, and a precisely defined property. Build owned property records, descriptors and transparent baselines first. Add optional learned models only where a controlled comparison demonstrates useful accuracy or cost. A molecular orbital gap, a crystal band gap and an experimental optical gap are different targets. An accurate energy potential alone does not provide electronic, optical or transport observables.
Priorities and deliverables¶
“First”, “Next” and “Later” order this program, rather than overriding the
project’s bug priorities. First and Next use priority::P2; Later uses
priority::P3. The immediate implementation entry point is SPP-01.
Task |
Priority |
Bounded result |
Prerequisites |
Evidence to finish the task |
|---|---|---|---|---|
SPP-01 #779 |
First |
Typed property observations and provenance projected from existing results |
Existing output architecture |
Round-trip records; unit, state and missing-value refusals; molecular and periodic fixtures |
SPP-02 #780 |
First |
Native molecular descriptor export using composition, geometry and already available QC properties |
SPP-01; existing #693 |
Atom-order and rigid-motion checks; charge/origin conventions; feature-cost and leakage manifest |
SPP-03 #781 |
First |
Versioned QM9 and JARVIS benchmark manifests with grouped splits |
SPP-01 |
Reproducible IDs, hashes, license inventory and train/validation/calibration/test separation |
SPP-04 #782 |
Next |
Owned NumPy ridge baseline for QM9 isotropic polarizability |
SPP-02, SPP-03 |
Comparison with mean and composition baselines; held-out errors, interval coverage and domain limits |
SPP-05 #783 |
Later |
Small, owned descriptor-formula research spike for optical limiting |
SPP-03, SPP-04; lawful descriptor data |
Nested grouped validation, bounded expression search and an honest go/no-go report |
SPP-06 #784 |
Next |
Explicit predictor protocol and versioned model artifacts, native coefficients first |
SPP-01, SPP-04 |
Base install works offline without ML frameworks; invalid model/domain/license metadata fails closed |
SPP-07 #785 |
Later |
Owned image-resolved neighbor graph for scalar-property experiments |
SPP-01; reuse lattice utilities |
Permutation, rotation, wrapping and equivalent-cell tests; multiple-image and self-image fixtures |
SPP-08 #786 |
Later |
One owned MPNN/SchNet-style molecular polarizability pilot |
SPP-03, SPP-04, SPP-06, SPP-07 |
Same splits and cost accounting as the baseline; invariant scalar outputs; measured go/no-go |
SPP-09 #787 |
Later |
One owned CGCNN/MEGNet-style periodic band-gap pilot |
SPP-03, SPP-04, SPP-06, SPP-07 |
Fixed-fidelity JARVIS labels; composition/ridge comparison; cell invariance and domain report |
SPP-10 #788 |
Later |
Native power-factor and ZT algebra over explicit transport inputs |
SPP-01; qualified or referenced input coefficients |
Units, direction, temperature and carrier-state checks; analytic fixtures and uncertainty propagation |
Start with SPP-01, then SPP-02 and SPP-03, then SPP-04. SPP-06 makes successful native models reusable. The optical and graph pilots are independent research branches after their prerequisites; a negative result completes a research task and prevents unnecessary deployment. SPP-10 can use referenced input coefficients independently of model training. Automated transport prediction still waits for the existing physics work described below.
Reuse the existing physics and infrastructure¶
Property class |
Reusable foundation |
Remaining dependency or limitation |
|---|---|---|
Electronic |
Population analysis and dipoles in |
Keep orbital, fundamental and optical gaps separate. Metals, spin channels and occupation tolerances need explicit treatment. DFT, GW and experiment are separate fidelities. |
Optical and response |
TDDFT/TDA and UV/Vis output; static closed-shell RHF polarizability on CPHF |
UHF/KS polarizability is PR8; hyperpolarizability is PR9. Periodic Born-charge/dielectric work is PR16-PR18. A molecular polarizability is not a bulk dielectric constant without an additional physical model and state. |
Thermal |
Molecular frequencies and thermochemistry; existing Gamma-point phonon work |
Finite-temperature bulk properties need sampling or phonon dispersion and convergence. QHA1/QHA2 already cover quasi-harmonic and thermoelastic work. Molecular QM9 heat capacity is not lattice thermal conductivity. |
Mechanical |
Existing energy, gradients and route-specific stress |
Elastic constants remain PR19; piezo/photoelastic response is PR20-PR21. Derivative readiness and reference validation are route-specific, including #578/#637. No duplicate elasticity solver in this program. |
Transport |
Bands and the existing PROP17 BOLTZTRA plan |
PROP17 remains post-1.0; it is not implemented by SPP-10. Electronic relaxation time, carrier state and lattice/bipolar heat transport remain explicit inputs or separate future solvers. |
The main roadmap remains the authority for PR, PROP and QHA work. Experimental methods remain experimental when their outputs become training labels; fitting a model does not qualify the generating physics.
Reuse the existing parameter-opt provenance, protocol and
split conventions where appropriate. Fitting a property predictor is distinct
from fitting Hamiltonian parameters (#676). Reuse vibeqc.output and its band
edge and MLIP record conventions; coordinate any QVF schema addition in the
schema’s owning project before exporting it. SPP-01 starts with a native record
and supported output projection, not an independent QVF dialect.
The molecular spectral fingerprint (#693) is already available. Frame selection (#694), cell-independent periodic fingerprints (#695), and electronic spectral channels (#696) retain their existing issues. Spectral similarity can propose duplicate candidates; collisions mean it cannot prove molecular or crystal identity. SPP-07 is a local periodic graph, not a replacement for #695’s global spectral fingerprint. Reuse applicable lattice/image infrastructure and tests from #734 without assuming that a property graph changes cyclic physics.
The owned energy/force potential (#712) and MACE-CCM program (#732) retain their own architecture, label-generation, training-repository and weight decisions. Their checkpoints do not become electronic-property predictors. Property pilots may reuse provenance and data tooling, but have distinct target and model identities. This plan does not create another repository or change those programs’ scope.
Own the implementation, keep model dependencies optional¶
Implement record handling, geometry descriptors, dimensional checks, linear algebra baselines, graph construction and formula evaluation in vibe-qc using its existing numerical stack. Derive algorithms from the cited papers and equations; record departures and add citations alongside future code. Do not vendor a research repository simply to obtain an architecture.
SPP-05 implements a bounded, dimension-aware basis search and regularized fit in owned code. Symbolic formatting may have an optional adapter; a Mathematica runtime and copied CORRELATO SI code are not requirements. Start with explicit low-order products and powers, reject singular/nonphysical expressions, and bound complexity before fitting. This is an interpretable baseline study, not a claim to reproduce CORRELATO’s entire optimization procedure.
SPP-08/SPP-09 may use an optional PyTorch extra with lazy imports for owned
model layers. Extra names are implementation proposals, not a new public API
in this planning change. Preserve the existing [ml], [mace] and [skala]
extras and their meanings. Graph packages, model SDKs, reference-model code,
GPU drivers and downloaded weights must never become base-install requirements.
Training scripts and benchmark acquisition stay outside the importable runtime;
bounded pilot scripts can live under developer tooling. Deployment requires
the SPP-06 protocol, not an import of another QC engine.
Every adapter declares target definitions, supported elements/charge/spin/PBC, units, training domain and protocol, version, license and checkpoint hash. Record prediction provenance separately from calculated observables. Model selection and weight acquisition are explicit; no import-time network access, silent download, hidden fallback, or replacement of SCF. Native linear artifacts use a versioned data-only format with coefficients and preprocessing metadata. Reject incompatible dimensions and nonfinite values; never load arbitrary serialized Python objects to obtain a native baseline.
Code, datasets and weights have separate licenses. CGCNN, MEGNet, SchNet, PhysNet, SCANN and ALIGNN provide useful reference implementations, subject to their individual terms. Public DimeNet/GemNet code uses restricted Hippocratic terms in the reviewed versions; availability is not permission to bundle it. CORRELATO’s Mathematica SI is CC BY-NC 4.0. Implement from the publication’s mathematics, and review every actual code/data/weight artifact before reuse. An optional dependency does not remove its license obligations.
Data and scientific contracts¶
Each observation records structure identity and coordinates/cell/PBC, charge
and spin, property definition and tensor convention, units, intensive/extensive
normalization, source kind (computed, derived, predicted, experimental),
method/basis/ECP/functional/dispersion and convergence where relevant, generating
software identity, dataset version and lineage. Temperature, pressure, solvent,
frequency/wavelength, density, carrier concentration and relaxation-time
assumptions are required when the target depends on them. Unknown information
is explicit; unsupported or failed properties are not zero. Errors/uncertainty
and qualification status travel with the record.
SPP-01’s initial adapters cover existing molecular energies, dipoles and RHF polarizability, plus periodic band-edge/gap records. The contract can describe other targets without implementing their producers. Charged-system dipoles record their origin; atomic charges record the partitioning convention. A scalar invariant, a vector and a tensor have different transformation laws. The first models predict scalars; tensor learning remains later work.
SPP-02 separates composition/geometry features from QC-assisted features. Include available charges, bond-order summaries, dipole and orbital data only with their source and cost. A target or an algebraic reconstruction of it cannot also be an input. For polarizability prediction, exclude polarizability-derived features. Record whether a proposed speedup still requires the expensive QC calculation. Existing descriptors can be exported without waiting for PR8/PR9; new response descriptors wait for their qualified producers.
SPP-03 first supplies pinned manifests and small lawful fixtures for QM9 molecular isotropic polarizability and one documented JARVIS-DFT crystal gap field. Keep the source’s functional and geometry protocol; do not silently combine gap definitions. Materials Project is the next candidate, with access and redistribution terms checked separately. Public availability alone does not authorize redistributing a benchmark or releasing derived weights.
Source family |
Initial use |
Boundary |
|---|---|---|
QM9 |
Molecular scalar benchmark and descriptor ablations |
Fixed label definitions and exclusions; small organic domain; not a bulk-property or charged-system qualification |
JARVIS-DFT, later Materials Project |
Periodic scalar benchmark, later elastic/response tasks |
Preserve functional, units, per-atom conventions, structure version and field-specific missingness |
MD17, COLL, OC20 and PhysNet data |
Future geometry/domain stress tests |
Primarily energy/force evidence, not validation of unrelated electronic heads; energy/force work stays coordinated with #712 |
SCANN released examples |
Future controlled explanation checks |
Attention or site attribution must survive perturbation tests; it does not prove causality |
CORRELATO optical data |
Small-data research if lawful data use is established |
Experimental conditions are inputs; no bundled noncommercial SI/code or assumed reusable trained model |
New vibe-qc calculations |
Future owned property labels |
Submit through |
Group conformers, duplicate structures, alternative cell descriptions and paired fidelities before splitting. Store parent/group identities and split hashes; require source identities or validated equivalence rather than spectral similarity alone. Fit scaling, feature selection, expression search and hyperparameters on training/validation only. Keep calibration and final test groups separate. Freeze exclusions, search budgets and evaluation criteria before observing final test scores. Report composition/scaffold/domain holdouts as appropriate; random splits alone do not establish extrapolation.
For every pilot, compare a constant predictor, composition-only baseline, native descriptor baseline and the proposed model on identical data. Report MAE/RMSE in physical units, group/seed variability, sample count, failures, training and inference costs, and the cost of QC features. Predeclare useful error/cost criteria from the intended use on validation data; no universal accuracy number is promised here. Calibration intervals report coverage and width on held-out data under their stated assumptions; they are not guarantees on shifted chemistry. A model that fails the predeclared comparison stays a research result. Successful benchmark fits are not automatically released weights or scientifically qualified production methods.
Macroscopic property limits and formula path¶
The optical-limiting spike is motivated by CORRELATO’s explicit equations, not by its smallest reported cluster error. Its 24-dye study uses experimental absorption, thickness and beam waist as well as QC descriptors; it is not a structure-only mapping. The paper permits test error in model selection, and its three-dye result is explicitly a hypothesis. Use nested grouped validation with untouched outer folds and simple baselines. If an adequately independent test cannot be formed, report the study as exploratory. Recomputing the full descriptor set may depend on PR8/PR9; precomputed descriptors need provenance and lawful use. Do not copy the SI implementation or infer a bulk optical response from an orbital gap alone.
SPP-10 owns the deterministic scalar relations
PF = S^2 * sigma and ZT = PF * T / kappa_total.
For SI inputs these give PF in W m^-1 K^-2 and dimensionless ZT.
kappa_total must cover the declared electronic, lattice and, where distinct,
bipolar contributions without omission or double counting. Reject missing or
nonpositive denominators and mismatched temperature/carrier conditions.
Relaxation-time-normalized transport coefficients are not absolute conductivity
without an explicit relaxation time. Use scalar isotropic data or an explicitly
justified directional projection; never apply scalar multiplication blindly to
anisotropic tensors. Propagate supplied covariance (or label an independence
assumption) and keep model uncertainty separate from measurement uncertainty.
This algebra can consume referenced coefficients now; it does not generate
them or implement lattice thermal conductivity.
After the scalar pilots, consider angular/line-graph ablations, response tensors, multifidelity delta corrections, Hamiltonian/density learning and temperature-conditioned models only against a concrete unmet target. ALIGNN does not justify starting with every property head; DimeNet/GemNet complexity needs an equal-data ablation. Learned XC functionals and device-level inference are outside this program’s initial scope.
Literature-to-decision map¶
Numbers retain the requested review order. Links identify public sources; implementation tasks must consult the relevant equations and SI, record departures, and recheck artifact licenses at the version actually used.
Paper |
Roadmap decision |
|---|---|
SPP-07/SPP-09: periodic graph and scalar readout baseline; no universal property model claim |
|
SPP-01/SPP-09: state variables and extensive/intensive pooling; transfer learning only after a baseline |
|
SPP-08: owned bounded message-passing pilot |
|
SPP-07/SPP-08: distance-based continuous filters and invariant scalar tests |
|
Later angular-basis ablation; published formula does not make repository code permissively licensed |
|
Later geometric complexity only with measured benefit; force-learning remains coordinated with #712 |
|
SPP-03/SPP-09: JARVIS benchmark and later line-graph ablation; response targets need separate validation |
|
Charge, dipole and long-range conventions in SPP-01/SPP-02; potential accuracy does not certify electronic properties |
|
Explicit invariant descriptors are useful baselines; local atomic energies are not a closed formula for bulk response |
|
Controlled perturbation checks before interpreting attention as a scientific explanation |
|
SPP-07/SPP-09: equivalent-cell, wrapping and symmetry tests; scalar and tensor contracts differ |
|
12. Mishchenko et al., 2D electronic properties (online 2025, issue 2026) |
Later Hamiltonian/spectral targets; separate DFT/GW/experiment and 2D normalization |
SPP-03/SPP-04: realistic splits; its ADME/classification benchmark is not a quantum-property accuracy claim |
|
Conceptual motivation only: review ingestion obtained the abstract, not full text; no detailed implementation decision rests on it |
|
SPP-02/SPP-04: transparent descriptors and regression before a large learned model |
|
SPP-05: own small formula-search study using Eqs. (7)-(16) as motivation, with independent validation and explicit experimental inputs |
|
SPP-10: physical PF/ZT algebra. Body/equations were available; separate popup tables were not archived, so no table-derived benchmark claim |
|
18. Mengesha and Nagessar, electronic materials review (online 2025, issue 2026) |
Application inventory; use primary property papers for implementation and retain processing/environment variables |
Compact equal-data architecture comparisons, not a port of every reviewed model |
|
Separate scalar surrogates, potentials and learned functionals; paired-protocol delta learning is later work |