Goldilocks QRF95 k-mesh recommendation model

QRF95 is a quantile random forest used by Goldilocks to recommend a Gamma-centred k-point mesh for a three-dimensional periodic inorganic crystal. The artifact predicts k_distance, the maximum spacing between adjacent k-points in reciprocal space, in inverse angstroms, following the convention used by AiiDA-QuantumESPRESSO. It does not directly predict the three integer mesh values.

This is not a standalone estimator: inference must reproduce the complete feature vector and feature ordering described below, including the learned representation from the companion Goldilocks CGCNN metallicity model.

Input and feature contract

The input is a periodic crystal structure. Goldilocks constructs the qrf_comp_struct_soap_lattice_metal feature vector in this order:

  1. Composition descriptors: Magpie ElementProperty, Stoichiometry, and ValenceOrbital features from matminer.
  2. Structure descriptors: GlobalSymmetryFeatures and DensityFeatures from matminer.
  3. SOAP descriptors: all species replaced by X, periodic boundaries, r_cut=10.0 angstrom, n_max=8, l_max=6, sigma=1.0, followed by a mean over atoms.
  4. Direct- and reciprocal-lattice lengths and angles, crystal-system and Bravais-lattice encodings, and space-group number.
  5. The pooled crystal representation produced by the companion CGCNN metallicity model. This is the learned representation before its classification head, not the predicted metal/non-metal class.

Changing a featurizer, parameter, feature order, atomic embedding, or companion checkpoint changes the model input contract.

Output and conversion to a k-mesh

model.predict(features) returns the 0.05, 0.5, and 0.95 quantiles in that order. The 0.5 quantile is the median recommendation. The interval from the 0.05 to the 0.95 quantile has nominal central coverage of 90%; the artifact name QRF95 must not be interpreted as a 95% central prediction interval.

For reciprocal-lattice vectors b_i, Goldilocks converts a selected k_distance to the integer mesh with

N_i = ceil(|b_i| / k_distance)

The k-distance definition and mesh conversion follow the convention used by AiiDA-QuantumESPRESSO. The legacy Goldilocks application applies an additional application-level conformal correction of -0.0016 inverse angstroms to the QRF95 bounds. That correction is not embedded in this pickle and should be versioned separately by consuming software.

Training target

The target was generated from Quantum ESPRESSO single-point SCF total-energy calculations for 20,187 structures sampled from MC3D PBEsol-v1 without further structural relaxation. The calculation protocol used:

  • SSSP 1.3 PBEsol efficiency pseudopotentials and their recommended cutoffs;
  • Marzari-Vanderbilt cold smearing of 0.01 Ry;
  • spin-averaged calculations without magnetic configurations;
  • Gamma-centred meshes generated by scanning k-distance from 1.0 inverse angstroms in steps of 0.005 inverse angstroms.

The first of three consecutive meshes whose energy differences were below 1 meV per atom was selected as the converged target. The associated training data are available from the PSDI Data Collections record.

Loading it

This record holds everything the model needs:

  • QRF95.pkl: the fitted forest.
  • is_metal.ckpt, atom_init.json: the metallicity network whose learned representation makes up 64 of the 483 input columns, and the atomic embedding table its graphs are built from. They are the same files as in record ptc95-vbq12, and model.json still pins them there by digest, so the copies here are verified against the originals on load.
  • model.json: the artifact in machine-readable form — the serving runtime, the feature contract and its 483 columns in order, the target contract, and the digests of everything above.

Download this record and nothing else. With goldilocks-ml installed:

from goldilocks_ml.inference import load_model

model = load_model("path/to/this/record")
prediction = model.predict(structure)  # prediction.value is a k-distance

That record was written after the fact rather than by the run that fitted this forest, and says so in record_origin. It declares no calibration, because the -0.0016 correction described above was fitted under a different rule than current software applies; the median is unaffected by it, so the point prediction stands and the interval is returned with no coverage claimed.

Runtime and safe loading

  • Artifact: QRF95.pkl, a trusted joblib/pickle file.
  • Embedded scikit-learn version: 1.7.2.
  • Required sklearn-quantile version: 0.1.1.

Verify the byte size and SHA-256 value in manifest.json before loading. Pickle files can execute code during deserialization; load this artifact only from a trusted PSDI record and in a controlled environment.

Scope and limitations

The model recommends inputs consistent with the training protocol; it does not prove k-point convergence for a new calculation protocol or target property. The convergence procedure does not guarantee that the globally optimal mesh is selected, that every Fermi-surface pocket is resolved, or that total energies are correctly resolved for compounds with band gaps below 0.14 eV. Predictions for structures or chemistries outside the training distribution require independent convergence testing.

The surviving artifact record does not identify an immutable training-dataset snapshot or training-code commit. No evaluation values are reported here because the surviving notebook outputs do not unambiguously bind them to this specific QRF95 artifact.