Skip to content

feat: built-in default QRF k-point model with HuggingFace resolution#38

Merged
junwen94 merged 15 commits into
mainfrom
feat/default-modelspec
Jul 8, 2026
Merged

feat: built-in default QRF k-point model with HuggingFace resolution#38
junwen94 merged 15 commits into
mainfrom
feat/default-modelspec

Conversation

@junwen94

@junwen94 junwen94 commented Jul 7, 2026

Copy link
Copy Markdown
Collaborator

Part of #31 (and gates #30). Ships the functional core of a built-in default ML k-point model that resolves from Hugging Face, so ML k-point prediction works without the caller supplying a model.

What this delivers

  • HF model resolution — ml/models.load_model now supports source="huggingface" (location "<repo_id>::<filename>", download + local cache via huggingface_hub). Previously local-only.
  • Built-in default spec — DEFAULT_KPOINTS_MODEL = STFC QRF95 (STFC-SCD/kpoints-goldilocks-QRF::QRF95.pkl), target="k_distance", pinned + reproducible.
  • QRF post-prediction — predict_kdistance_quantiles (3 quantiles → median + calibrated interval), kdistance_to_selection (median → mesh, interval + confidence → Provenance, source="model").
  • Full feature stack ported from legacy main — the 483-dim vector the QRF was trained on:
    • ml/kdistance_features.py — matminer composition/structure + dscribe SOAP + lattice/symmetry (419-dim)
    • ml/cgcnn.py, ml/cgcnn_graph.py, ml/atom_features.py, ml/metallicity.py — CGCNN metallicity crystal representation (64-dim)
  • Advisor factory — qrf_kdistance_advisor loads QRF + CGCNN once; an explicit k_grid/k_spacing hint bypasses the model.

Verification

End-to-end validated: diamond Si → 10×10×10 mesh at 0.217 Å⁻¹, source="model", confidence 0.95 (QRF from HF + CGCNN metallicity). 93 tests pass; committed tests mock the models (no network / no checkpoint in CI).

Naming

Renamed kmesh_advisor → kindex_advisor and kspacing → kdistance for consistency with the aiida-quantumespresso "k-distance" term (contract rename tracked separately).

Deferred (follow-ups, not in this PR)

🤖 Generated with Claude Code

junwen94 and others added 9 commits July 6, 2026 13:38
@junwen94
Merge pull request #18 from stfc/refactor/staged-core-pipeline
705f841 
refactor(core): introduce staged pipeline
@junwen94
Merge pull request #11 from stfc/test/baseline-coverage
7670b65 
test: establish baseline coverage
@junwen94 @claude
feat(ml): support huggingface source in load_model
fbe11eb 
Implement `source="huggingface"` in `load_model`: parse the location as
`"<repo_id>::<filename>"`, download via `hf_hub_download` (honoring
`revision`), and joblib-load the artifact. First step toward a built-in
default ModelSpec resolved from the Hub.

Tests mock the download (no network).

Part of #31

Written by an agent on behalf of Junwen Yin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 @claude
feat(advisors): QRF k-spacing post-prediction logic + default ModelSpec
ad8875b 
Add the model-agnostic half of the default k-point advisor:
- DEFAULT_KPOINTS_MODEL: built-in ModelSpec for the STFC QRF95 on HuggingFace.
- predict_kspacing_quantiles: QRF output (lower, median, upper) k-spacing with
  the calibrated interval correction.
- kspacing_to_selection: median spacing -> mesh via k_distance_to_mesh, with
  source="model" provenance carrying the interval and confidence level.

Feature extraction (heavy deps) and advisor wiring come next.

Part of #31

Written by an agent on behalf of Junwen Yin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 @claude
refactor(advisors): rename kmesh_advisor -> kindex_advisor
63c43d1 
Name the k-index advisor for what it is (predicts a k-index into a mesh
table), pairing it with the new kspacing_advisor (predicts k-spacing). Renames
the module and its test; updates import paths. Public function names are
unchanged.

Part of #31

Written by an agent on behalf of Junwen Yin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 @claude
refactor(advisors): rename kspacing -> kdistance for naming consistency
77512b9 
Align the QRF advisor with the existing kmesh terminology (`k_distance_to_mesh`,
`k_distance`): rename the module, functions (`predict_kdistance_quantiles`,
`kdistance_to_selection`), and its test. The `CalculationHints.k_spacing`
contract field is unchanged.

Part of #31

Written by an agent on behalf of Junwen Yin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 @claude
feat(ml): port matminer/SOAP/lattice feature extractor for QRF
c70fa6f 
Reproduce the non-metallicity half of the QRF k-distance feature vector:
composition (matminer ElementProperty/Stoichiometry/ValenceOrbital), structure
(GlobalSymmetry/Density), SOAP (dscribe), and lattice/symmetry values, in the
trained order. Single-structure API `extract_structure_features` -> 419-dim
block; the CGCNN metallicity block (64) is appended separately to reach 483.

Part of #31

Written by an agent on behalf of Junwen Yin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 @claude
feat(ml): port CGCNN metallicity model for QRF metal features
b816f18 
Port the CGCNN model (PyG), radius graph builder, and atom embedding lookup
needed to compute the "metal" block of the QRF k-distance feature vector:
- cgcnn.py: CGCNN_PyG with extract_crystal_repr (64-dim pooled representation)
- cgcnn_graph.py: radius-based PyG graph builder
- atom_features.py: per-atom embedding lookup from atom_init JSON
- metallicity.py: load the pretrained CGCNN checkpoint + metal_features()

Verified against the recovered checkpoint: 419 (struct) + 64 (metal) = 483,
matching the trained QRF input. Committed tests use small/fake models (no
checkpoint, no network).

Part of #31

Written by an agent on behalf of Junwen Yin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 @claude
feat(advisors): assemble 483-dim QRF features + wire k-distance advisor
fa87d2d 
- extract_qrf_features: concat struct(419) + CGCNN metal(64) -> 483-dim vector.
- qrf_kdistance_advisor: Kmesh backend loading the QRF + metallicity model once,
  predicting k-distance and resolving a mesh; explicit k-grid/k-spacing hints
  bypass the model.

Verified end-to-end (QRF from HF + CGCNN from recovered checkpoint): diamond Si
-> 10x10x10 at 0.217 Å⁻¹, source="model", confidence 0.95. Committed tests mock
the models (no network/checkpoint).

Part of #31

Written by an agent on behalf of Junwen Yin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 junwen94 requested a review from susmitab July 7, 2026 14:05
junwen94 and others added 4 commits July 7, 2026 15:12
@junwen94 @claude
feat(advisors): heuristic fallback when the QRF k-point model is unav…
8f3f0ce 
…ailable

The default k-point advisor must never make the tool require network or hard-
fail. Guard both failure points: model/dependency load (torch/PyG/matminer
missing, HF download fails, bad checkpoint) and per-structure inference. On
failure, degrade to the heuristic k-point advice from the Advise stage.

The fallback mesh keeps its advice-derived provenance source (default/analysis,
never "model") — the result is a genuine heuristic recommendation, not a
placeholder — and appends a warning naming the reason the model was skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 @claude
feat: default pipeline uses the built-in QRF k-point model out of the…
ddb0c0a 
… box

Add default_kmesh_advisor() (QRF + heuristic fallback, metallicity checkpoint
env-overridable) and default_pipeline() wiring it into the Kmesh stage. The CLI
now runs the default QRF model when neither --model nor an explicit k-point hint
is given; an explicit hint resolves from advice without loading any model, and
--model still selects the local CSLR k-index backend.

The bare Pipeline() default stays the spacing heuristic so library callers never
trigger GB-scale model loads implicitly. Until the CGCNN metallicity checkpoint
is published to Hugging Face (#36), production environments without it fall back
to heuristic advice with a provenance warning.

Verified end-to-end via the CLI: with the checkpoint present, Si resolves to
source="model" (kpoints-goldilocks-QRF, confidence 0.95); with it missing, the
run degrades to source="default" and records the reason.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 @claude
build: promote the k-points ML stack to core dependencies (#32)
1acf064 
Decision on #32: the default QRF k-point model is a core capability, so its ML
stack ships in the base install rather than an optional extra. Add dscribe,
huggingface_hub, pandas, sklearn-quantile, torch, and torch-geometric to core
dependencies so `goldilocks-core recommend` predicts k-points out of the box
with no extra install step, at the cost of a GB-scale base install (accepted
trade-off).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 @claude
feat(advisors): resolve the CGCNN metallicity model from Hugging Face (…
21bd9da 
…#36)

The QRF k-distance features need a CGCNN metallicity checkpoint + atom-embedding
table. Now published at JunwenYin/metallicity-goldilocks-CGCNN, so the default
advisor resolves both from the Hub (cached) instead of a local path. Explicit
local paths still win, and GOLDILOCKS_METALLICITY_{CHECKPOINT,ATOM_INIT,REPO}
override for offline development. Resolution runs inside the guarded load, so a
download failure degrades to heuristic advice like any other load error.

With this, the default pipeline predicts k-points out of the box on a clean
machine with no local_data. Verified live: Si resolves QRF + metallicity from
HF and returns source="model" (confidence 0.95).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@sigilmakes sigilmakes marked this pull request as draft July 7, 2026 16:21
@sigilmakes

sigilmakes commented Jul 7, 2026

Copy link
Copy Markdown
Collaborator

(Marking as draft so its clear this branch is still WIP)

@sigilmakes

sigilmakes commented Jul 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Also are those goldilocks_output and site folders supposed to be in the repo? It looks like they should be gitignored

@junwen94

junwen94 commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator Author

Also are those goldilocks_output and site folders supposed to be in the repo? It looks like they should be gitignored

Yes you are correct I will fix it.

@junwen94 @claude
chore: ignore build artifacts (site/, goldilocks_output/, .DS_Store)
40b2e5c 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 junwen94 force-pushed the feat/default-modelspec branch from 50df872 to 40b2e5c Compare July 8, 2026 13:27
@junwen94 @claude
style: ruff format kdistance_advisor
f1c277b 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@junwen94 junwen94 marked this pull request as ready for review July 8, 2026 13:43
@junwen94 junwen94 merged commit b1ebad1 into main Jul 8, 2026
1 check passed
@sigilmakes sigilmakes mentioned this pull request Jul 8, 2026
Merged
@junwen94 junwen94 mentioned this pull request Jul 8, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@susmitab susmitab Awaiting requested review from susmitab

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@junwen94 @sigilmakes