quantaflow 0.0.1

Framework-neutral quantum computing library. Build once, run on PennyLane, Qiskit, and more.

⚛️ Quantaflow

Build quantum circuits once. Run them anywhere.

---

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?
• Features
• Installation
• Quick Start
• The Bell Experiment
• API Reference
  • Circuit
  • Backends
  • Result
• Supported Gates
• Roadmap
• Contributing
• 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 →

---

Installation

Basic (no backends)

pip install quantaflow

With PennyLane backend

pip install "quantaflow[pennylane]"

With Qiskit backend

pip install "quantaflow[qiskit]"

With all backends

pip install "quantaflow[all]"

Development setup (with conda)

# 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

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:

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

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:

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

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

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 → for detailed feature plans.

---

Contributing

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

• Contributing Guide — How to set up your dev environment, run tests, and submit PRs
• Code of Conduct — Our community standards
• Contributor License Agreement — Required for all contributions

---

License

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

Licensed under the Apache License, Version 2.0.

---

Built with ❤️ by Northstar Corporation