Metadata-Version: 2.1
Name: quantum-pipeline
Version: 2.4.0
Summary: Framework for running, monitoring and analysing quantum algorithms.
Author-Email: Piotr Krzysztof <piotr@codextechnologies.org>
Maintainer-Email: Piotr Krzysztof <piotr@codextechnologies.org>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Project-URL: Homepage, https://github.com/straightchlorine/quantum-pipeline
Project-URL: Documentation, https://docs.qp.piotrkrzysztof.dev/
Project-URL: Source, https://github.com/straightchlorine/quantum-pipeline
Project-URL: Issues, https://github.com/straightchlorine/quantum-pipeline/issues
Project-URL: Changelog, https://docs.qp.piotrkrzysztof.dev/changelog/
Project-URL: Author, https://piotrkrzysztof.dev
Requires-Python: <3.13,>=3.12
Requires-Dist: qiskit>=1.4.2
Requires-Dist: qiskit-ibm-runtime>=0.37.0
Requires-Dist: qiskit-aer>=0.15.1
Requires-Dist: qiskit-nature>=0.7.2
Requires-Dist: qiskit-qasm3-import>=0.6.0
Requires-Dist: pyscf>=2.8.0
Requires-Dist: qiskit-algorithms>=0.4.0
Requires-Dist: reportlab>=4.3.1
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: pylatexenc>=2.10
Requires-Dist: scipy>=1.15.2
Requires-Dist: numpy>=2.2.3
Requires-Dist: psutil>=7.1.2
Requires-Dist: avro>=1.12.0
Requires-Dist: kafka-python-ng>=2.2.3
Requires-Dist: cryptography>=44.0.1
Requires-Dist: Jinja2>=3.1.6
Requires-Dist: Requests>=2.32.3
Provides-Extra: dev
Requires-Dist: pytest>=8.3.4; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: debugpy>=1.8.12; extra == "dev"
Requires-Dist: ruff>=0.16.10; extra == "dev"
Requires-Dist: mypy>=2.4.0; extra == "dev"
Requires-Dist: testcontainers>=4.13.3; extra == "dev"
Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
Requires-Dist: pytest-randomly>=4.0.1; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.1; extra == "dev"
Requires-Dist: pytest-randomly>=3.16.0; extra == "dev"
Requires-Dist: pytest-watch>=4.2.0; extra == "dev"
Requires-Dist: pyspark>=3.5.5; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.3; extra == "docs"
Requires-Dist: mkdocs-material[imaging]>=9.5.3; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.2; extra == "docs"
Requires-Dist: mkdocs-panzoom-plugin>=0.5.2; extra == "docs"
Requires-Dist: pymdown-extensions>=10.7; extra == "docs"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.8.0; extra == "ml"
Requires-Dist: xgboost>=3.2.0; extra == "ml"
Requires-Dist: seaborn>=0.13.2; extra == "ml"
Requires-Dist: jupyterlab>=4.5.6; extra == "ml"
Requires-Dist: mlflow>=3.10.1; extra == "ml"
Requires-Dist: pyspark>=3.5.5; extra == "ml"
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://qp-docs.codextechnologies.org/mkdocs/banner.svg" alt="Quantum Pipeline" width="350">
</p>

<div align="center">

[Documentation](https://docs.qp.piotrkrzysztof.dev) &middot; [Quick Start](https://docs.qp.piotrkrzysztof.dev/getting-started/quick-start/) &middot; [Examples](https://docs.qp.piotrkrzysztof.dev/usage/examples/)

[![PyPI version](https://badge.fury.io/py/quantum-pipeline.svg)](https://pypi.org/project/quantum-pipeline/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/quantum-pipeline)](https://pypi.org/project/quantum-pipeline/)
[![Docker Pulls](https://img.shields.io/docker/pulls/straightchlorine/quantum-pipeline.svg)](https://hub.docker.com/r/straightchlorine/quantum-pipeline)
[![ghcr.io](https://img.shields.io/badge/ghcr.io-cpu%20%7C%20gpu-blue?logo=github)](https://github.com/straightchlorine/quantum-pipeline/pkgs/container/quantum-pipeline)

Ground-state energies of molecules with the Variational Quantum Eigensolver - and the infrastructure
to keep every iteration it takes to get there.

</div>

## Architecture

```mermaid
graph LR
    M[molecules.json] --> HF

    subgraph sim["quantum-pipeline (pip install)"]
        HF[PySCF<br/>Hartree-Fock reference] --> VQE[VQE loop<br/>Qiskit ansatz, scipy optimizer<br/>Aer on CPU or GPU]
    end

    VQE --> Out[PDF report +<br/>convergence plots]

    subgraph platform["data platform (docker compose, optional)"]
        K[Kafka<br/>one Avro message per finished run] --> S[Spark jobs<br/>scheduled by Airflow] --> I[(Iceberg tables<br/>on Garage)]
        I --> ML["ML module<br/>predict convergence from the first K steps"]
    end

    VQE -->|result with all iterations| K
    VQE -->|metrics| G[Prometheus + Grafana]
```

Point `quantum-pipeline` at a JSON file of molecules and it runs VQE for each one. PySCF supplies the Hartree-Fock starting point, Qiskit builds the ansatz, a scipy optimizer drives it, and Aer simulates the circuit on CPU or on an NVIDIA GPU. A run ends with a PDF report and a convergence plot per molecule.

Everything to the right of the solver is optional. With Kafka on, the finished result of each molecule, with every iteration in it, leaves the solver as one Avro message, and Spark jobs scheduled by Airflow land those messages in Iceberg tables.

Prometheus metrics and a Grafana dashboard with alert rules watch the run. The ML module, which reads the tables to predict from the first iterations whether a run will converge, is in progress and not part of a normal run.

## What it does

- Runs VQE for every molecule in a JSON file, in `sto3g`, `6-31g` or `cc-pvdz`
- Simulates with Qiskit Aer on CPU, or on a GPU through the CUDA Thrust backend with the `:gpu` image ([Docker Hub](https://hub.docker.com/r/straightchlorine/quantum-pipeline/tags?name=gpu) &middot; [GHCR](https://github.com/straightchlorine/quantum-pipeline/pkgs/container/quantum-pipeline))
- Lets you pick the classical optimizer (L-BFGS-B, COBYLA, SLSQP, Nelder-Mead, Powell, BFGS, CG, TNC, Newton-CG, trust-constr), the ansatz depth, the iteration cap and the convergence threshold
- Writes a PDF report and PNG convergence plots to `gen/`
- Streams each finished run, with all its iterations, to Kafka as Avro, with a schema registry
- Turns the stream into Iceberg tables with Spark and Airflow
- Exports Prometheus metrics and ships a Grafana dashboard
- Work in progress: models that predict convergence and final energy from the first iterations of a run

## Quick Start

```bash
pip install quantum-pipeline
quantum-pipeline -f data/molecules.json -b sto3g --max-iterations 100 --optimizer L-BFGS-B --report
```

Or with Docker:

```bash
docker pull straightchlorine/quantum-pipeline:cpu
docker run --rm straightchlorine/quantum-pipeline:cpu -f data/molecules.json -b sto3g --max-iterations 100
```

Both images are on [Docker Hub](https://hub.docker.com/r/straightchlorine/quantum-pipeline/tags) as `straightchlorine/quantum-pipeline:cpu` and `:gpu`, and on [GHCR](https://github.com/straightchlorine/quantum-pipeline/pkgs/container/quantum-pipeline) as `ghcr.io/straightchlorine/quantum-pipeline` with the same tags.

The GPU image is built for compute capabilities 6.1, 7.0, 8.0 and 9.0 (plus PTX), so it targets NVIDIA GPUs with compute capability 6.1 or newer. To build for one GPU only, rebuild it with the `CUDA_ARCH` build argument - see the [GPU acceleration page](https://docs.qp.piotrkrzysztof.dev/deployment/gpu-acceleration/).

The [installation guide](https://docs.qp.piotrkrzysztof.dev/getting-started/installation/) covers GPU acceleration; the [deployment guide](https://docs.qp.piotrkrzysztof.dev/deployment/) brings up the full platform with `docker compose`.

## Documentation

Full docs at <https://docs.qp.piotrkrzysztof.dev>. Build them locally with:

```bash
pdm run mkdocs serve
```

Started as an engineering thesis, continued through a master's. Source on [GitHub](https://github.com/straightchlorine/quantum-pipeline), mirrored on [Codeberg](https://codeberg.org/piotrkrzysztof/quantum-pipeline).

## License

MIT License. See [LICENSE](LICENSE) for details.

---

<div align="center">

To the only God, be honour and glory for ever and ever.

</div>
