goldilocks-core

Goldilocks recommends settings for density functional theory (DFT) calculations and generates Quantum ESPRESSO self-consistent field (SCF) input files from a crystal structure.

Try it

Install uv, then clone the repository:

git clone https://github.com/stfc/goldilocks-core.git
cd goldilocks-core
uv sync

Start the Workbench

With Node.js 24 or newer installed, run:

uv sync --extra http
npm --prefix web ci
uv run goldilocks assets install workbench
uv run --extra http poe workbench

The asset step installs the models and pseudopotential tables. Open http://127.0.0.1:5173, upload a CIF or POSCAR, review the recommended settings, and download the generated inputs.

For a built frontend instead, stop the development servers and run:

uv run --extra http poe stage

Then open http://127.0.0.1:8000. See the Workbench guide for Docker and development checks.

Generate inputs from the command line

Download the prediction models and default pseudopotential table, then generate inputs for the bundled silicon structure:

uv run goldilocks assets install default
uv run goldilocks compute src/goldilocks_core/examples/structures/Si.cif --preset generate --out si-run

Open si-run/inputs/qe.in to see the input. The directory also contains the pseudopotentials, structures, and supporting data.

Treat the recommended settings as a starting point: review warnings and check convergence for your calculation. The quickstart explains the output and how to run it.

Guides and reference

• First calculation — generate, check, and run an input.
• Python API — use Goldilocks in a script.
• Recommendations — understand the choices and their limits.
• Pseudopotentials — choose a table or use your own files.
• CLI reference — commands and options.
• Scientific conventions — units and numerical definitions.
• Contributing — code layout and development checks.

Licence

Code: BSD 3-Clause. Documentation under docs/ and example structures: CC BY 4.0. Downloaded pseudopotentials retain their upstream licences.