quantumforge-laptop 1.0.0

Open-source laptop-first computational physics platform with auditable workflows, scientific provenance, and optional research backends

QuantumForge 1.0

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.0

• 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.
• 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

List the v1.0 scientific validation registry:

qforge benchmarks-list
qforge benchmark-describe srtio3

Scientific result labels

Label	Meaning
teaching_model	Transparent educational or reduced-model computation
backend_calculation	Result produced by a named external scientific backend
calibrated_model	Model contains fitted or literature-calibrated parameters
literature_reference	Value copied or digitized from a publication
experimental_reference	Measured reference value
unconverged_pilot	Executed calculation that has not passed convergence gates
validated_result	Converged result that passed the declared validation contract

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

Repository: https://github.com/chaabanetaha/quantumforge

• 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.