Metadata-Version: 2.4
Name: quantumforge-laptop
Version: 1.1.0
Summary: Open-source laptop-first computational physics platform with auditable workflows, scientific provenance, and optional research backends
Author: Taha Chaabane
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/chaabanetaha/quantumforge
Project-URL: Repository, https://github.com/chaabanetaha/quantumforge
Project-URL: Issues, https://github.com/chaabanetaha/quantumforge/issues
Project-URL: Changelog, https://github.com/chaabanetaha/quantumforge/blob/main/CHANGELOG.md
Keywords: computational physics,materials science,DFT,Monte Carlo,education
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: numpy<3,>=1.26
Requires-Dist: scipy<2,>=1.11
Requires-Dist: matplotlib<4,>=3.8
Requires-Dist: PyYAML<7,>=6.0
Requires-Dist: typer<1,>=0.12
Requires-Dist: rich<16,>=13.7
Requires-Dist: threadpoolctl<4,>=3.5
Provides-Extra: web
Requires-Dist: streamlit<2,>=1.40; extra == "web"
Provides-Extra: chemistry
Requires-Dist: pyscf<4,>=2.8; extra == "chemistry"
Provides-Extra: atoms
Requires-Dist: ase<4,>=3.23; extra == "atoms"
Provides-Extra: perovskite
Requires-Dist: ase<4,>=3.29; extra == "perovskite"
Requires-Dist: gpaw<27,>=26.7; extra == "perovskite"
Provides-Extra: magnetism
Requires-Dist: ase<4,>=3.29; extra == "magnetism"
Requires-Dist: gpaw<27,>=26.7; extra == "magnetism"
Provides-Extra: dev
Requires-Dist: pytest<10,>=8.0; extra == "dev"
Requires-Dist: ruff<1,>=0.9; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
Provides-Extra: diagnostics
Dynamic: license-file

<p align="center">
  <img src="docs/assets/quantumforge_pixel_logo.png" alt="QuantumForge logo" width="220">
</p>

# 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

```bash
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

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

### From this repository

```bash
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:

```bash
qforge run tight_binding_ssh
```

Inspect a structure and generate a review-gated plan:

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

Create a project and register runs:

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

Submit and run a durable workflow:

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

Verify a saved run:

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

Run the MnAs student paper-reproduction case study:

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

List the scientific validation registry:

```bash
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

- Read [CONTRIBUTING.md](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](SECURITY.md).
- Governance is described in [GOVERNANCE.md](GOVERNANCE.md).
- The stable public API is described in [docs/PUBLIC_API.md](docs/PUBLIC_API.md).

## Citation

Use the metadata in [CITATION.cff](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`.
