Metadata-Version: 2.4
Name: quantaflow
Version: 0.0.1
Summary: Framework-neutral quantum computing library. Build once, run on PennyLane, Qiskit, and more.
Author-email: Northstar Corporation <opensource@northstarsindustries.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/NorthstarsIndustries/quantaflow
Project-URL: Documentation, https://github.com/NorthstarsIndustries/quantaflow#readme
Project-URL: Repository, https://github.com/NorthstarsIndustries/quantaflow
Project-URL: Issues, https://github.com/NorthstarsIndustries/quantaflow/issues
Project-URL: Changelog, https://github.com/NorthstarsIndustries/quantaflow/releases
Keywords: quantum,computing,pennylane,qiskit,circuit,simulator
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.35; extra == "pennylane"
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0; extra == "qiskit"
Requires-Dist: qiskit-aer>=0.13; extra == "qiskit"
Provides-Extra: all
Requires-Dist: pennylane>=0.35; extra == "all"
Requires-Dist: qiskit>=1.0; extra == "all"
Requires-Dist: qiskit-aer>=0.13; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pennylane>=0.35; extra == "dev"
Requires-Dist: qiskit>=1.0; extra == "dev"
Requires-Dist: qiskit-aer>=0.13; extra == "dev"
Dynamic: license-file

<p align="center">
  <h1 align="center">⚛️ Quantaflow</h1>
  <p align="center">
    <strong>Build quantum circuits once. Run them anywhere.</strong>
  </p>
  <p align="center">
    <a href="https://github.com/NorthstarsIndustries/quantaflow/actions/workflows/ci.yml"><img src="https://github.com/NorthstarsIndustries/quantaflow/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
    <a href="https://pypi.org/project/quantaflow/"><img src="https://img.shields.io/pypi/v/quantaflow.svg" alt="PyPI"></a>
    <a href="https://pypi.org/project/quantaflow/"><img src="https://img.shields.io/pypi/pyversions/quantaflow.svg" alt="Python"></a>
    <a href="https://github.com/NorthstarsIndustries/quantaflow/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
  </p>
</p>

---

**Quantaflow** is an open-source Python library for building and running quantum programs with a single, framework-neutral workflow. It gives you a simple circuit and program model that isn't tied to any one ecosystem, then lets you execute the same code on multiple backends — starting with **PennyLane** and **Qiskit** — while returning consistent, NumPy-friendly results.

Quantaflow is designed to remove the usual "plumbing" (rewriting circuits, swapping execution APIs, normalizing outputs, and managing run metadata) so you can **focus on experiments and algorithms, not framework glue**.

> **Status:** v0.0.1 — Alpha release. Core circuit builder and two simulator backends are stable and tested.

---

## Table of Contents

- [Why Quantaflow?](#why-quantaflow)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [The Bell Experiment](#the-bell-experiment)
- [API Reference](#api-reference)
  - [Circuit](#circuit)
  - [Backends](#backends)
  - [Result](#result)
- [Supported Gates](#supported-gates)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

---

## Why Quantaflow?

If you've ever worked with quantum computing frameworks, you know the pain:

| Problem | Without Quantaflow | With Quantaflow |
|---|---|---|
| **Framework lock-in** | Rewrite circuits for each backend | Write once, run anywhere |
| **Different result formats** | Parse each framework's output differently | Consistent `Result` object everywhere |
| **Setup boilerplate** | Device creation, transpilation, measurement setup | One-liner: `backend.run(circuit, shots=1000)` |
| **Comparing backends** | Separate scripts for each | Same circuit, swap one line |

Quantaflow sits between your algorithm and the execution layer, handling the translation so you don't have to.

---

## Features

### ✅ In v0.0.1 (Current)
- **Framework-neutral circuit builder** — `h`, `x`, `rx`, `ry`, `rz`, `cx`, `measure_all()`
- **PennyLane backend** — `default.qubit` simulator (configurable device)
- **Qiskit backend** — `AerSimulator` with automatic fallback
- **Consistent Result object** — `.counts`, `.probabilities`, `.metadata`
- **Fluent API** — chainable gate calls
- **Full test suite** — including cross-backend Bell state validation

### 🚧 Coming Soon
- More gates (y, z, s, t, swap, toffoli, parametric multi-qubit) — v0.0.2
- Circuit visualization — v0.0.2
- IBM Quantum hardware — v0.0.3
- Amazon Braket backend — v0.0.3
- VQE & QAOA algorithms — v0.0.4
- Transpiler passes — v0.0.5

See the full [Roadmap →](docs/roadmap.md)

---

## Installation

### Basic (no backends)
```bash
pip install quantaflow
```

### With PennyLane backend
```bash
pip install "quantaflow[pennylane]"
```

### With Qiskit backend
```bash
pip install "quantaflow[qiskit]"
```

### With all backends
```bash
pip install "quantaflow[all]"
```

### Development setup (with conda)
```bash
# Clone the repo
git clone https://github.com/NorthstarsIndustries/quantaflow.git
cd quantaflow

# Create conda environment
conda env create -f environment.yml
conda activate quantaflow-dev

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -q
```

### Requirements
- Python 3.10, 3.11, or 3.12
- NumPy ≥ 1.23
- PennyLane ≥ 0.35 (for PennyLane backend)
- Qiskit ≥ 1.0 + qiskit-aer ≥ 0.13 (for Qiskit backend)

---

## Quick Start

```python
from quantaflow import Circuit
from quantaflow.backends import PennyLaneBackend

# 1. Build a circuit
qc = Circuit(2)
qc.h(0)          # Hadamard on qubit 0
qc.cx(0, 1)      # CNOT: entangle qubits 0 and 1
qc.measure_all()  # Measure in computational basis

# 2. Run it
backend = PennyLaneBackend()
result = backend.run(qc, shots=1000)

# 3. Get results
print(result.counts)         # {'00': 503, '11': 497}
print(result.probabilities)  # {'00': 0.503, '11': 0.497}
print(result.metadata)       # {'backend': 'pennylane/default.qubit', 'shots': 1000, ...}
```

---

## The Bell Experiment

This is the **copy-paste example** that should just work. It creates a Bell state and runs it on *both* backends to show they produce equivalent results:

```python
from quantaflow import Circuit
from quantaflow.backends import PennyLaneBackend, QiskitBackend

# Build a Bell circuit: (|00⟩ + |11⟩) / √2
qc = Circuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# Run on PennyLane
pl_result = PennyLaneBackend().run(qc, shots=2000)
print(f"PennyLane: {pl_result.counts}")
print(f"  P(00) = {pl_result.probabilities['00']:.3f}")
print(f"  P(11) = {pl_result.probabilities['11']:.3f}")

print()

# Run on Qiskit — same circuit, no changes needed
qi_result = QiskitBackend().run(qc, shots=2000)
print(f"Qiskit:    {qi_result.counts}")
print(f"  P(00) = {qi_result.probabilities['00']:.3f}")
print(f"  P(11) = {qi_result.probabilities['11']:.3f}")

# Both backends produce ~50/50 split between |00⟩ and |11⟩
# Exactly what you'd expect from a Bell state!
```

**Expected output:**
```
PennyLane: {'00': 1012, '11': 988}
  P(00) = 0.506
  P(11) = 0.494

Qiskit:    {'00': 987, '11': 1013}
  P(00) = 0.494
  P(11) = 0.506
```

---

## API Reference

### Circuit

```python
from quantaflow import Circuit
```

#### `Circuit(num_qubits: int)`

Create a new quantum circuit.

| Property / Method | Description |
|---|---|
| `qc.num_qubits` | Number of qubits in the circuit |
| `qc.ops` | List of operations (read-only) |
| `qc.measured` | Whether `measure_all()` has been called |
| `len(qc)` | Number of gate operations |

#### Gate Methods

All gate methods return `self` for chaining:

```python
qc = Circuit(3)
qc.h(0).cx(0, 1).rx(2, 3.14)  # Fluent API
```

| Method | Description | Parameters |
|---|---|---|
| `qc.h(wire)` | Hadamard gate | — |
| `qc.x(wire)` | Pauli-X (NOT) gate | — |
| `qc.rx(wire, angle)` | X-rotation | `angle` in radians |
| `qc.ry(wire, angle)` | Y-rotation | `angle` in radians |
| `qc.rz(wire, angle)` | Z-rotation | `angle` in radians |
| `qc.cx(control, target)` | CNOT gate | Two distinct wires |
| `qc.measure_all()` | Measure all qubits | Locks circuit |

### Backends

```python
from quantaflow.backends import PennyLaneBackend, QiskitBackend
```

#### `PennyLaneBackend(device="default.qubit")`

| Method | Description |
|---|---|
| `backend.run(circuit, shots=1024)` | Execute circuit, return `Result` |
| `backend.name` | `"pennylane/default.qubit"` |

#### `QiskitBackend()`

Automatically selects `AerSimulator` if available, otherwise falls back.

| Method | Description |
|---|---|
| `backend.run(circuit, shots=1024)` | Execute circuit, return `Result` |
| `backend.name` | `"qiskit/AerSimulator"` |

### Result

```python
from quantaflow import Result
```

| Property | Type | Description |
|---|---|---|
| `result.counts` | `dict[str, int]` | Raw counts, e.g. `{"00": 503, "11": 497}` |
| `result.probabilities` | `dict[str, float]` | Normalized probabilities |
| `result.shots` | `int` | Total shots (sum of counts) |
| `result.metadata` | `dict` | Backend name, shots, quantaflow version |

---

## Supported Gates

| Gate | Type | Qubits | Parameters | Description |
|---|---|---|---|---|
| `h` | Clifford | 1 | — | Hadamard: creates superposition |
| `x` | Pauli | 1 | — | Bit flip (NOT gate) |
| `rx` | Rotation | 1 | `angle` | Rotation around X-axis |
| `ry` | Rotation | 1 | `angle` | Rotation around Y-axis |
| `rz` | Rotation | 1 | `angle` | Rotation around Z-axis |
| `cx` | Entangling | 2 | — | Controlled-NOT (CNOT) |

> 💡 **More gates coming in v0.0.2:** `y`, `z`, `s`, `t`, `swap`, `ccx` (Toffoli), and parametric multi-qubit gates.

---

## Roadmap

| Version | Codename | Highlights |
|---|---|---|
| **v0.0.1** ✅ | *Hello Quantum* | Circuit builder, PennyLane + Qiskit backends, Result object |
| **v0.0.2** | *More Gates* | 12+ new gates, parametric circuits, `.draw()` visualization |
| **v0.0.3** | *Real Hardware* | IBM Quantum, Amazon Braket, noise models |
| **v0.0.4** | *Algorithms* | VQE, QAOA, parameter sweeps, batching, caching |
| **v0.0.5** | *Production Ready* | Transpiler, plugins, benchmarking, full docs |

See the full [Roadmap →](docs/roadmap.md) for detailed feature plans.

---

## Contributing

We welcome contributions from the quantum computing community! Please read our:

- **[Contributing Guide](CONTRIBUTING.md)** — How to set up your dev environment, run tests, and submit PRs
- **[Code of Conduct](CODE_OF_CONDUCT.md)** — Our community standards
- **[Contributor License Agreement](CONTRIBUTOR_LICENSE_AGREEMENT.md)** — Required for all contributions

---

## License

Copyright (c) 2026 Northstar Corporation. All rights reserved.

Licensed under the [Apache License, Version 2.0](LICENSE).

---

<p align="center">
  Built with ❤️ by <a href="https://github.com/NorthstarsIndustries">Northstar Corporation</a>
</p>
