QuantumForge 1.1

Open-source, laptop-first computational physics with explicit scientific provenance.

QuantumForge helps students and researchers move from a structure or model to a reproducible calculation plan, local teaching simulation, optional research-backend execution, auditable result record, and benchmark comparison.

QuantumForge does not turn every input into a trustworthy prediction automatically. It makes assumptions, limitations, review gates, convergence evidence, and result origin visible.

What is stable in 1.1

• Fourteen built-in teaching and reduced-model solvers.
• CIF, POSCAR, VASP, XYZ, and optional ASE structure parsing.
• Universal qforge study material.cif planning.
• Material Builder, DFT Studio, Monte Carlo Lab, and results UI.
• Explicit result classes: teaching, backend, calibrated, reference, pilot, and validated.
• Atomic run records with SHA-256 manifests.
• SQLite project, review, and durable workflow databases.
• Restartable local dependency-ordered workflows for built-in methods.
• Frozen validation specifications for H2O, Si, Fe, SrTiO3, and MnAs.
• Reproducible MnAs paper-study workflow with benchmark table, raw data, figures, and explicit claim boundaries.
• Environment diagnostics and backend capability preflight.

Installation

Core terminal toolkit

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
# .\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install quantumforge-laptop
qforge doctor

Web Studio and structure tools

python -m pip install "quantumforge-laptop[web,atoms]"
qforge-ui

From this repository

python -m pip install -e ".[dev,web,atoms]"
python -m pytest
qforge demo-ui

Periodic GPAW calculations are optional. On Windows, use a validated WSL2/Ubuntu environment for production GPAW work.

Quick start

Run a built-in model:

qforge run tight_binding_ssh

Inspect a structure and generate a review-gated plan:

qforge study examples/materials/SrTiO3.cif --goal full

Create a project and register runs:

qforge project-init SrTiO3 --root .
qforge run tight_binding_ssh --project-root .
qforge project-list --root .

Submit and run a durable workflow:

qforge workflow-submit examples/workflow_teaching.yml
qforge workflow-list
qforge workflow-run <WORKFLOW_ID>
qforge workflow-show <WORKFLOW_ID>

Verify a saved run:

qforge verify-run runs/<RUN_ID>
qforge env-export -o quantumforge-environment.json

Run the MnAs student paper-reproduction case study:

qforge benchmark-mnas-case-study --profile standard --seed 43

List the scientific validation registry:

qforge benchmarks-list
qforge benchmark-describe srtio3

Scientific result labels

Publication-ready status additionally requires resolved review gates and explicit human approval where needed.

Durable workflows

QuantumForge 1.0 runs local workflows in the foreground but commits task state to SQLite before and after each task. This gives deterministic interruption, inspection, cancellation between tasks, and retry/resume behavior without pretending to be a cluster scheduler.

External backend tasks are blocked unless the required capability passes preflight. The executor never silently substitutes a teaching model for a missing DFT backend.

Supported scope

Native Windows: UI, structure tools, study planning, teaching models, Monte Carlo, run verification.

Linux / WSL2: primary target for GPAW periodic DFT.

Optional backends: GPAW/ASE, PySCF, AkaiKKR, and TRIQS. Availability does not imply scientific readiness; qforge doctor checks usable capabilities.

Public development

• Read CONTRIBUTING.md before opening a pull request.
• Scientific-output changes must include benchmark evidence and explicit result classification.
• Report security issues according to SECURITY.md.
• Governance is described in GOVERNANCE.md.
• The stable public API is described in docs/PUBLIC_API.md.

Citation

Use the metadata in CITATION.cff. Archive releases should receive a DOI before publication claims are made.

License

QuantumForge is released under the GNU General Public License v3.0 or later. Optional scientific backends retain their own licenses and are not bundled unless explicitly stated.

Independent project name

QuantumForge Laptop is an independent computational-physics project and is not affiliated with other software projects using the QuantumForge name. The Python distribution name is quantumforge-laptop and the command-line entry point is qforge.