goldilocks-ml

Train and publish the models that choose DFT settings for you.

Setting up a DFT calculation means guessing things that are hard to guess: how dense the k-point mesh needs to be, whether the material is a metal and needs smearing. Goldilocks answers those from models trained on past calculations. This package is where those models are trained, evaluated and published.

Want the answers rather than the models? Goldilocks Core takes a structure and writes your input files.

📖 Documentation

Use a published model

from goldilocks_ml.inference import load_model

model = load_model("path/to/a/psdi/record")
prediction = model.predict(structure)

prediction.value  # e.g. 0.2134
prediction.quantity  # 'k_distance'

Train one

A training job is one TOML file, not a notebook. This runs offline in a clean checkout:

uv sync
uv run goldilocks-ml train run protocols/synthetic/regression.toml \
  --dataset tests/fixtures/kdist --output local_runs/first

You get one folder holding the predictions, the split, the scores against a baseline, the environment, and a SHA-256 for every file involved.

The real scientific models need the optional dependency set:

uv sync --extra models

See Train a model.

Publish one

uv run goldilocks-ml publish validate deposits/k_points/k_distance/qrf \
  --artifact-directory local_data/models/k_points/k_distance/qrf

Everything is checked locally first, and nothing is ever submitted for review without you doing it yourself. See Publish a model.

Development

uv sync --group dev --extra models
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mkdocs build --strict
uv build

The lint and format checks cover the whole tree, including Python inside fenced blocks in the documentation. Narrowing them to src tests passes locally and fails in CI.

The GitHub Pages workflow builds documentation on every pull request and deploys it after changes reach main. A repository administrator must select GitHub Actions as the Pages source once before the first deployment.

Licence

This package is released under the BSD 3-Clause Licence, matching Goldilocks Core.

Published models are a separate matter. Trained weights and the datasets behind them are released through PSDI under CC BY 4.0, which is stated in each deposit's record rather than here — a licence for code and a licence for data answer different questions.

Two modules under src/goldilocks_ml/models/ are adapted from stfc/goldilocks_kpoints, which is CC BY 4.0, and carry attribution in their headers. CC BY 4.0 permits adapted material under other terms provided attribution is kept, so they are redistributed under the licence above.