ariadne-router 0.4.5

Intelligent quantum simulator router with automatic backend selection

Ariadne

Intelligent Quantum Simulator Router

Automatic backend selection for quantum circuit simulation based on circuit analysis.

Quick Start • Documentation • Examples • Contributing

---

What is Ariadne?

Ariadne automatically selects the optimal quantum simulation backend for your circuits. Instead of manually choosing between different simulators (Stim, Qiskit Aer, MPS, Tensor Networks, etc.), Ariadne analyzes your circuit and routes it to the most appropriate backend.

Simple usage:

from ariadne import simulate
from qiskit import QuantumCircuit

# Create any quantum circuit
qc = QuantumCircuit(3, 3)
qc.h(0)
qc.cx(0, 1)
qc.cx(1, 2)
qc.measure_all()

# Ariadne automatically selects the best backend
result = simulate(qc, shots=1000)

print(f"Backend used: {result.backend_used}")
print(f"Execution time: {result.execution_time:.3f}s")
print(f"Results: {dict(result.counts)}")

Key Features

• Automatic Backend Selection: Analyzes circuit properties and routes to optimal simulator
• Multiple Backend Support: Stim, Qiskit Aer, MPS, Tensor Networks, and more
• Educational Tools: Interactive circuit builder and algorithm library (15+ algorithms)
• Hardware Acceleration: Optional support for Apple Silicon (Metal) and NVIDIA GPUs (CUDA)
• Cross-Platform: Works on Windows, macOS, and Linux
• Transparent Routing: Understand why each backend was selected

---

Why Use Ariadne?

For Students & Educators

• Focus on learning quantum computing without worrying about simulator configuration
• Consistent interface across different simulation methods
• Interactive tutorials and educational tools included

For Researchers

• Automatic optimization for different circuit types
• Compare results across multiple backends easily
• Reproduce published results with minimal configuration

For Developers

• Single consistent API for quantum simulation
• Integrate quantum algorithms without backend expertise
• Production-ready with comprehensive testing

---

Quick Start

Installation

pip install ariadne-router

Optional Hardware Acceleration:

# Apple Silicon (M1/M2/M3/M4)
pip install ariadne-router[apple]

# NVIDIA GPUs
pip install ariadne-router[cuda]

# All quantum platform backends
pip install ariadne-router[quantum_platforms]

Note: The package installs as ariadne-router but imports as ariadne. This conflicts with the Ariadne GraphQL library at the import level. If you use both libraries, use separate virtual environments or consider importing as:

import ariadne_router as ariadne  # Alternative import style
# Or use separate venvs for each project

Basic Example

from ariadne import simulate, explain_routing
from qiskit import QuantumCircuit

# Create a 40-qubit GHZ state
qc = QuantumCircuit(40, 40)
qc.h(0)
for i in range(39):
    qc.cx(i, i + 1)
qc.measure_all()

# Simulate with automatic backend selection
result = simulate(qc, shots=1000)

print(f"Backend: {result.backend_used}")
print(f"Time: {result.execution_time:.3f}s")
print(f"Explanation: {explain_routing(qc)}")

Output:

Backend: stim
Time: 0.023s
Explanation: Clifford circuit detected → routed to Stim (stabilizer circuit optimization)

---

Common Pitfalls

✗ Import Name Confusion

Problem: The package is named ariadne-router but imports as ariadne

# ✗ Wrong
import ariadne-router  # This won't work

# ✓ Correct
import ariadne
from ariadne import simulate

Solution: Always use ariadne in imports, not ariadne-router.

✗ Conflict with Ariadne GraphQL

Problem: Both ariadne (GraphQL) and ariadne-router use the same import name

# ✗ This creates conflicts if both packages are installed
import ariadne  # Which package is this?

Solutions:

# ✓ Option 1: Use separate virtual environments (recommended)
pip install ariadne-router  # In quantum project venv

# ✓ Option 2: Qualified imports
import ariadne.router as quantum_router
result = quantum_router.simulate(circuit)

# ✓ Option 3: Direct function imports
from ariadne import simulate

✗ Wrong Backend Installation

Problem: Installing wrong packages for hardware acceleration

# ✗ Wrong - this tries to install GraphQL extras that don't exist
pip install ariadne[metal]

# ✓ Correct - this installs quantum router with hardware acceleration
pip install ariadne-router[apple]  # For Apple Silicon
pip install ariadne-router[cuda]   # For NVIDIA GPUs

✗ Missing Measurements

Problem: Forgetting to add measurements to circuits

# ✗ Circuit with no measurements
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
result = simulate(qc)  # This will give a warning

# ✓ Circuit with measurements
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()  # or qc.measure(0, 0), qc.measure(1, 1)
result = simulate(qc)

Note: Ariadne will automatically add measure_all() if no measurements are present, but it's better to be explicit.

✗ Manual Backend Selection Overuse

Problem: Always specifying backends manually defeats the purpose of Ariadne

# ✗ Misses the point - you're doing the routing manually
result = simulate(qc, backend_type='qiskit')

# ✓ Let Ariadne choose the optimal backend
result = simulate(qc)  # Ariadne will pick the best backend
print(f"Ariadne chose: {result.backend_used}")

When to manually specify backends:

• Debugging specific backend behavior
• Benchmarking backend performance
• Reproducing results that require a specific simulator

✗ Platform-Specific Issues

Problem: Installing Metal backend on non-Apple Silicon

# ✗ This will install but won't work on Intel/AMD
pip install ariadne-router[apple]  # On non-Apple Silicon

# Check your system first
ariadne doctor  # This shows what acceleration is available

Fix: Use ariadne doctor to see what backends work on your system.

---

How It Works

Ariadne analyzes your quantum circuit using:

1. Circuit Type Detection: Identifies Clifford circuits, parameterized circuits, etc.
2. Topology Analysis: Examines qubit connectivity patterns (chain, grid, heavy-hex, etc.)
3. Entanglement Analysis: Estimates entanglement growth using information theory
4. Resource Estimation: Considers circuit depth, width, and gate count
5. Hardware Detection: Checks for available accelerators (Apple Silicon, CUDA)

Routing Decision Tree

Here's how Ariadne's intelligent routing engine makes decisions:

graph TD
    A[Quantum Circuit] --> B{Circuit Type?};
    B --> C{Clifford?};
    B --> D{General?};

    C --> E{Stim available?};
    E -->|Yes| F[Stim Backend];
    E -->|No| G[Qiskit Backend];

    D --> H{Circuit Size?};
    H --> I{"Small (<= 20 qubits)"};
    H --> J{"Medium (21-35 qubits)"};
    H --> K{"Large (> 35 qubits)"};

    I --> L{Hardware?};
    L -->|Apple Silicon with JAX/Metal| M[JAX/Metal Backend];
    L -->|NVIDIA GPU with CUDA| N[CUDA Backend];
    L -->|CPU or other| O{Optional Backends?};
    O -->|Cirq| P[Cirq Backend];
    O -->|Qulacs| Q[Qulacs Backend];
    O -->|PennyLane| R[PennyLane Backend];
    O -->|None| G;

    J --> S{Entanglement?};
    S --> T{Low};
    S --> U{High};

    T --> V{MPS available?};
    V -->|Yes| W[MPS Backend];
    V -->|No| X{Tensor Network available?};
    X -->|Yes| Y[Tensor Network Backend];
    X -->|No| G;

    U --> Z{Hardware?};
    Z -->|NVIDIA GPU with CUDA| N;
    Z -->|Apple Silicon with JAX/Metal| M;
    Z -->|CPU or other| AA{Optional Backends?};
    AA -->|OpenCL| AB[OpenCL Backend];
    AA -->|Cirq| P;
    AA -->|Qulacs| Q;
    AA -->|None| G;

    K --> AC{Entanglement?};
    AC --> AD{Low};
    AC --> AE{High};

    AD --> AF{MPS available?};
    AF -->|Yes| W;
    AF -->|No| X;

    AE --> AG{Specialized Backends?};
    AG -->|Tensor Network| Y;
    AG -->|DDSIM| AH[DDSIM Backend];
    AG -->|Braket| AI[Braket Backend];
    AG -->|Q#| AJ[Q# Backend];
    AG -->|None| G;

Backend Selection Summary

Based on this analysis, Ariadne selects the optimal backend:

Circuit Type	Backend	When Used	Typical Performance
Clifford	Stim	H, S, CNOT, Pauli gates only	Fast for stabilizer circuits
Low Entanglement	MPS	Entanglement grows slowly	Efficient for χ < 100
Structured	Tensor Networks	Specific topology patterns	Varies by structure
General	Qiskit Aer	Universal fallback	Reliable baseline
Hardware Accelerated	JAX-Metal / CUDA	When available (experimental)	Platform dependent

Performance varies by hardware, circuit type, and available backends.

Supported Backends

Ariadne integrates with multiple quantum simulators:

• Stim: Fast stabilizer circuit simulator for Clifford circuits
• Qiskit Aer: General-purpose quantum circuit simulator
• Matrix Product States (MPS): Efficient for low-entanglement circuits
• Tensor Networks: For circuits with specific structural properties
• PennyLane: Differentiable quantum computing framework
• Optional: Cirq, Qulacs, DDSIM, Braket, Q#, and more

For detailed capabilities, see Backend Capabilities.

---

Educational Features

Interactive Circuit Builder

from ariadne import InteractiveCircuitBuilder, simulate

# Build circuits with step-by-step explanations
builder = InteractiveCircuitBuilder(2, "Bell State")
builder.add_hadamard(0, "Create superposition", "Apply H gate to qubit 0")
builder.add_cnot(0, 1, "Create entanglement", "Apply CNOT to entangle qubits")

circuit = builder.get_circuit()
result = simulate(circuit, shots=1000)
print(f"Bell state results: {dict(result.counts)}")

Algorithm Library

from ariadne import list_algorithms, get_algorithm

# Explore 15+ quantum algorithms
algorithms = list_algorithms()
print(f"Available: {algorithms}")
# ['bell', 'deutsch_jozsa', 'grover', 'qft', 'simon', 'vqe', ...]

# Get algorithm details
algo_info = get_algorithm('grover')
print(f"Description: {algo_info['metadata'].description}")

For more examples, see the examples directory and educational tutorials.

---

Advanced Usage

Manual Backend Selection

# Override automatic selection when needed
result = simulate(qc, backend='stim', shots=1000)

Routing Strategies

from ariadne import RoutingStrategy, ComprehensiveRoutingTree

router = ComprehensiveRoutingTree()

# Use specific routing strategies
result = router.simulate(qc, strategy=RoutingStrategy.SPEED_FIRST)

Backend Comparison

from ariadne.enhanced_benchmarking import EnhancedBenchmarkSuite

suite = EnhancedBenchmarkSuite()
comparison = suite.benchmark_backend_comparison(
    circuit=qc,
    backends=['auto', 'qiskit', 'stim'],
    shots=1000
)

for backend, result in comparison.items():
    print(f"{backend}: {result.execution_time:.3f}s")

For more advanced features, see the Advanced Guide.

---

Docker Support

# Pull and run
docker pull ghcr.io/hmbown/ariadne-router:latest
docker run --rm ghcr.io/hmbown/ariadne-router:latest \
  python -c "import ariadne; print('Ready!')"

# Full quantum environment (10+ backends)
docker build --target quantum-full -t ariadne-quantum-full .
docker run -it ariadne-quantum-full

---

Documentation

• Getting Started Guide - Comprehensive installation and first steps
• API Reference - Complete API documentation
• Performance Guide - Optimization tips and benchmarks
• Troubleshooting - Common issues and solutions
• Configuration Options - Advanced configuration
• Developer Guide - Contributing and extending Ariadne

For Specific Audiences

• Students: Educational Examples
• Researchers: Research Use Cases
• Educators: Instructor Guide
• DevOps: Deployment Guide

---

Reproducibility

Ariadne includes tools for reproducible quantum computing research:

# Validate circuits across backends
python -m ariadne repro --circuit ghz_20 \
  --backends qiskit,stim --shots 1024 \
  --output results.json --export-csv results.csv

# Manage benchmark datasets
python -m ariadne datasets list
python -m ariadne datasets generate --family all --sizes 10,20,30

See benchmarks/datasets/README.md for details.

---

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Bug reports and feature requests
• Adding new backends
• Improving documentation
• Performance improvements

Quick setup:

git clone https://github.com/Hmbown/ariadne.git
cd ariadne
pip install -e .[dev]
pre-commit install
pytest  # Run tests

---

Project Status

Current Version: 0.4.4 (Active Development)

• Test Coverage: 319 tests passing (32 skipped due to optional dependencies)
• Core Functionality: Stable routing with multiple backend support
• Platform Support: Windows, macOS, Linux
• Backend Support: Stim, Qiskit Aer, MPS, Tensor Networks, and more
• Experimental Features: JAX-Metal and CUDA acceleration (marked as experimental)

See CHANGELOG.md for detailed release notes.

---

When to Use Ariadne

Good fit:

• Learning quantum algorithms without simulator expertise
• Teaching quantum computing (consistent interface)
• Research requiring cross-backend validation
• Prototyping where "fast enough" matters more than maximum performance

Not recommended:

• Fine-grained simulator parameter control needed
• Researching simulator algorithms themselves
• Production workloads with strict latency requirements
• When you already have an optimal simulator setup

---

Troubleshooting

Problem	Solution
Import errors	Run pip install -e .[dev]
Backend not found	Check troubleshooting guide
Slow performance	See performance guide
Memory errors	Use RoutingStrategy.MEMORY_EFFICIENT

For detailed help, see our Troubleshooting Guide or open an issue.

---

License

Apache 2.0 - see LICENSE for details.

Trademarks

All product names, logos, and brands are property of their respective owners. This project is an independent open source effort and is not affiliated with or endorsed by any quantum computing company or framework mentioned in this documentation.

---

⭐ Star on GitHub • 📦 PyPI Package • 📖 Documentation

Made with ❤️ for the quantum computing community