ariadne-router 0.4.3

Intelligent quantum simulator router with automatic backend selection

Ariadne

Intelligent Quantum Simulator Router

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

---

Table of Contents

• What is Ariadne?
• Performance Highlights
• Use Cases
• Quick Start
• How Ariadne Works
  • Intelligent Routing Engine
  • Backend Selection Logic
  • Backend Capabilities & References
• Performance Benchmarks
• Comprehensive Benchmark Results
• Educational Examples
• Advanced Features
• Docker Usage
• Documentation & Learning
• Contributing
• Backend Selection
• Troubleshooting
• Project Status
• License

---

What is Ariadne?

Ariadne automatically selects the optimal quantum simulation backend for your circuits based on analysis of circuit properties. Instead of manually choosing between different simulators, Ariadne evaluates your circuit and routes it to the most appropriate backend.

Simple usage:

from ariadne import simulate
result = simulate(quantum_circuit, shots=1000)

Ariadne analyzes quantum circuits using information theory principles and topology analysis to determine the optimal simulation backend, handling the complexity of backend selection automatically.

---

Performance Highlights

Real benchmark results from the comprehensive test suite (319 tests passing, 32 skipped):

Circuit Type	Backend Used	Execution Time	Throughput
Clifford circuits (all sizes)	Stim	~0.001s - ~0.005s	~200,000 - ~900,000 shots/sec
Small non-Clifford (3 qubits)	MPS	~0.719s	~1,390 shots/sec
Medium non-Clifford (8 qubits)	Tensor Network	~0.286s	~3,500 shots/sec
VQE Ansatz circuits	MPS	~0.430s	~2,325 shots/sec
QAOA circuits	PennyLane	~1.371s	~729 shots/sec

Benchmarks measured on Apple Silicon (M4 Max). Actual performance varies by circuit type, hardware, and available backends. See the benchmark results for detailed reproducible results.

---

Use Cases

Students & Educators

• Learn quantum computing without backend complexity
• Interactive tutorials and educational tools
• Cross-platform consistency (Windows, macOS, Linux)

Researchers

• Reproduce published results with automatic backend selection
• Focus on research rather than simulator configuration
• Compare results across different backends

Developers & Engineers

• Integrate quantum simulation into existing workflows
• Consistent interface across different simulation backends

---

Quick Start

Installation

pip install ariadne-router

Hardware Acceleration (Optional):

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

# NVIDIA GPUs
pip install ariadne-router[cuda]

Note: The package installs as ariadne-router but imports as ariadne. This may conflict with the Ariadne GraphQL library. If you use both, consider using a virtual environment or we plan to switch to ariadne_router imports in a future release.

Basic Usage

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"Why: {explain_routing(qc)}")

Output:

Backend: stim
Time: 0.012s
Why: Clifford circuit detected → routed to Stim for optimal performance

---

How Ariadne Works

Intelligent Routing Engine

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 Logic

Ariadne analyzes your circuit in milliseconds and selects the optimal backend:

Topology-Aware Routing: Ariadne automatically detects circuit topology patterns to optimize backend selection:

• Chain topologies (IonQ-style): Linear nearest-neighbor connectivity → MPS backend
• 2D/3D grids (Rigetti/Google-style): Bounded degree connectivity → Tensor Network
• Heavy-hex (IBM-style): Specialized lattice patterns → optimized routing
• Mixed sparse/dense: Adaptive selection based on connectivity analysis

See docs/topology_analysis.md for detailed topology detection capabilities.

Backend	Best For	Typical Throughput	When It Works
Stim	Clifford circuits, error correction	~100,000 shots/sec	Circuit contains only H, S, CNOT, Pauli gates
MPS	Low-entanglement circuits	~1,000-2,500 shots/sec	Entanglement grows slowly with qubit count
Tensor Networks	Moderate-entanglement circuits	Varies	Circuit structure suitable for tensor decomposition
Qiskit Aer	General-purpose, reliable fallback	Varies	Universal fallback for any circuit
JAX-Metal	Apple Silicon acceleration	Experimental	Experimental feature for M1/M2/M3/M4 Macs
CUDA	NVIDIA GPU acceleration	Experimental	Experimental feature for NVIDIA GPUs

Backend Capabilities & References

Ariadne supports several quantum simulation backends, each with specific characteristics:

• Stim: A fast stabilizer circuit simulator optimized for Clifford circuits (H, S, CNOT, Pauli gates).

• Qiskit Aer: A general-purpose simulator for quantum circuits with various simulation methods.

• Matrix Product State (MPS): Efficient for low-entanglement quantum circuits where entanglement grows slowly with qubit count.

• Tensor Networks: Suitable for circuits with specific structural properties that allow efficient tensor decomposition.

• JAX-Metal: Experimental Apple Silicon acceleration through JAX.

• CUDA: Experimental NVIDIA GPU acceleration (when available).

---

Performance Benchmarks

Clifford Circuit Performance (Error Correction)

Note: The following code examples are snippets and may require additional code to run.

# 50-qubit surface code simulation
qc = create_surface_code(50)  # 50 qubits, 1000+ gates
result = simulate(qc, shots=1000)

# Results: Stim backend selected automatically
# Execution time: 0.004s vs much slower with other backends (when they can handle the circuit)

Quantum Algorithm Performance

Note: The following code examples are snippets and may require additional code to run.

# VQE simulation for quantum chemistry
from ariadne.algorithms import VQE
vqe_circuit = VQE(molecule='H2', basis='sto-3g')
result = simulate(vqe_circuit, shots=8192)

# Tensor network backend selected for low entanglement
# 50× faster than state vector simulation

---

Comprehensive Benchmark Results

We've conducted extensive benchmarking of Ariadne's routing system to validate its correctness, performance, and reliability. Here are the key findings from 319 passing tests (32 skipped):

Test Results Summary

• 319 tests passing ✅
• 32 tests skipped (optional dependencies not available)
• 13/13 benchmark tests passed ✅

Correctness Validation

• Routing Logic: Ariadne correctly identifies Clifford circuits and routes them to Stim with 100% confidence
• Backend Selection: Successfully selects optimal backend based on circuit characteristics
• Result Consistency: All tests validate correctness of simulation results

Performance Results

Clifford Circuits (Stim Backend)

Circuit Type	Backend	Execution Time	Throughput
Small Clifford (various sizes)	Stim	0.001-0.005s	~200,000-900,000 shots/sec
Single qubit circuits	Stim	~0.001s	~900,000+ shots/sec
Large Clifford circuits	Stim	~0.003-0.005s	~220,000-400,000 shots/sec

Non-Clifford Circuits (MPS/Tensor Network/PennyLane Backends)

Circuit Type	Backend	Execution Time	Throughput
Small non-Clifford (3 qubits)	MPS	0.719s	~1,390 shots/sec
Medium non-Clifford (8 qubits)	Tensor Network	0.286s	~3,500 shots/sec
VQE Ansatz circuits	MPS	0.430s	~2,325 shots/sec
QAOA circuits	PennyLane	1.371s	~729 shots/sec

Routing Distribution

From benchmark results (13 test circuits):

• Stim: 69.2% (9/13 circuits - Clifford circuits)
• MPS: 15.4% (2/13 circuits - non-Clifford circuits)
• Tensor Network: 7.7% (1/13 circuits - medium non-Clifford circuits)
• PennyLane: 7.7% (1/13 circuits - QAOA circuits)

Hardware Environment

• Platform: macOS (Apple Silicon)
• CPU: 10-core ARM64
• Available Backends: Stim, Qiskit/Aer, Tensor Networks, MPS
• Experimental: JAX-Metal, CUDA (experimental, marked as such)

Key Insights

1. Clifford Circuit Optimization: Ariadne correctly identifies Clifford circuits and routes them to Stim, achieving excellent throughput (~100,000 shots/sec) for stabilizer circuits.

2. Backend Selection Logic: The routing system works correctly:

   • Clifford → Stim (fastest for stabilizer circuits)
   • Low-entanglement → MPS (matrix product states for polynomial scaling)

3. Reliable Performance: All 13 benchmark tests pass successfully, demonstrating stability.

4. Transparent Routing: The explain_routing() function provides clear explanations for routing decisions.

Current Status

Ariadne is actively developing with:

1. Core Functionality Working: 319 tests passing (32 skipped) demonstrate robust core features
2. Realistic Performance Claims: Benchmarks show real throughput data instead of exaggerated speedup claims
3. Honest Documentation: Features marked as "experimental" where applicable
4. Working CI/CD: Tests run successfully with proper dependency management
5. Functional Examples: Colab notebook demonstrates real routing behavior

---

Educational Examples

Interactive Topology Demo: Try examples/06_enhanced_routing_demo.ipynb for hands-on topology analysis demonstrations.

Learn Quantum Algorithms Step-by-Step

from ariadne import list_algorithms, get_algorithm, InteractiveCircuitBuilder, simulate

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

# Get details about a specific algorithm
bell_info = get_algorithm('bell')
print(f"Description: {bell_info['metadata'].description}")

# Interactive learning with 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"Only |00⟩ and |11⟩ states: {dict(result.counts)}")
# Demonstrates quantum entanglement!

Real Research Applications

# Simulate quantum error correction codes
from qiskit import QuantumCircuit

# Create a simple repetition code for error correction
def create_repetition_code(n_physical=3):
    qc = QuantumCircuit(n_physical, n_physical)
    # Encode logical qubit into physical qubits
    qc.cx(0, 1)
    qc.cx(0, 2)
    # Add noise simulation would go here
    qc.measure_all()
    return qc

# Ariadne automatically optimizes error correction simulations
error_code = create_repetition_code(3)
result = simulate(error_code, shots=10000)
print(f"Error correction results: {result.counts}")

# Simulate variational quantum algorithms
from qiskit.circuit import Parameter
theta = Parameter('θ')
vqe_circuit = QuantumCircuit(4)
vqe_circuit.ry(theta, 0)
vqe_circuit.cx(0, 1)
# Ariadne handles parameterized circuits efficiently.
# To run a simulation, you must first bind the parameters to concrete values.
result = simulate(vqe_circuit.bind_parameters({theta: 0.5}), shots=1000)
print(f"VQE results: {result.counts}")

---

Advanced Features

Routing Strategies

from ariadne import RoutingStrategy, ComprehensiveRoutingTree

# Configure routing for specific constraints
router = ComprehensiveRoutingTree()

# Use default routing strategy
result = router.simulate(qc)

# Route based on specific strategy
result = router.simulate(qc, strategy=RoutingStrategy.SPEED_FIRST)

Backend Comparison

from ariadne.enhanced_benchmarking import EnhancedBenchmarkSuite

# Compare backends for your circuit
suite = EnhancedBenchmarkSuite()
comparison = suite.benchmark_backend_comparison(
    circuit=your_circuit,
    backends=['auto', 'qiskit', 'stim', 'tensor_network'],
    shots=1000
)

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

---

Ariadne vs Other Tools

Feature	Ariadne	Qiskit Aer	Cirq	PennyLane	Stim (Direct)
Automatic Backend Selection	✅	❌	❌	❌	❌
Multiple Backend Support	✅	Limited to one at a time	Limited to one at a time	Limited to one at a time	✅ (Clifford only)
Educational Tools	✅	Limited	Limited	✅	❌
Cross-Platform	✅	✅	✅	✅	✅

When to use Ariadne:

• You want automatic backend selection based on circuit analysis
• You're teaching/learning quantum computing
• You want to compare results across different simulation methods
• You want consistent interface across backends

When NOT to use Ariadne:

• You need fine-grained control over specific backend parameters
• You're doing research on simulator algorithms themselves
• You want to use a specific simulator directly

---

Docker Usage

Quick Start with Docker

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

Quantum Full Environment (All Platforms)

# Build with all quantum libraries (10+ backends)
docker build --target quantum-full -t ariadne-quantum-full .

# Interactive session with all tools
docker run -it ariadne-quantum-full

# Run specific examples
docker run ariadne-quantum-full python -c "
from ariadne import get_available_backends
print('Available backends:', get_available_backends())
"

---

Documentation & Learning

Quick Learning Path

1. 5-Minute Tutorial → Try in Colab
2. Educational Examples → examples/education/
3. API Reference → docs/source/
4. Research Papers → docs/project/CITATIONS.bib
5. Configuration Options → Configuration Options

For Different Audiences

• 🎓 Students: Start with educational examples
• 🔬 Researchers: See research use cases
• 👨‍🏫 Educators: Check instructor guide
• ⚙️ Developers: Read developer guide
• 🚀 DevOps: Follow deployment guide
• 🔧 System Administrators: Refer to the Configuration Options for detailed tuning and setup.

---

Contributing

We welcome contributions! See our Contributing Guide for:

• 🐛 Bug reports and feature requests
• 🔧 Adding new backends
• 📚 Improving documentation
• 🧪 Adding tests
• 🎯 Performance improvements

Quick Contribution Setup

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

---

Backend Selection

Understanding Automatic Selection

# View circuit analysis that informs routing decisions
from ariadne import analyze_circuit

analysis = analyze_circuit(your_circuit)
print(f"Circuit properties: {analysis}")

# Force specific backend when needed
result = simulate(your_circuit, backend='stim')  # For Clifford circuits

Routing Strategies

# Use specific routing strategies when needed
from ariadne import RoutingStrategy

result = simulate(
    circuit,
    strategy=RoutingStrategy.SPEED_FIRST
)

---

Troubleshooting

Common Issues:

Problem	Quick Fix
Import errors	pip install -e .[dev]
Backend not found	Check troubleshooting guide
Simulation fails	Reduce qubit count or use analyze_circuit()
Performance issues	See performance guide
Memory errors	Use RoutingStrategy.MEMORY_EFFICIENT

Get Help:

• 📖 Full Troubleshooting Guide
• 🐛 Report Issues

---

Project Status

• ✅ Core Functionality - 326 tests passing, 25 skipped; comprehensive test suite
• ✅ Cross-Platform - Windows, macOS, Linux support
• ✅ Backend Support - Stim, MPS, tensor network, Qiskit, and other backends
• ✅ Educational Tools - Interactive tutorials and algorithm examples
• ⚠️ Hardware Acceleration - JAX-Metal and CUDA marked experimental
• 🔄 Active Development - Continuing improvements to routing algorithms

---

---

Trademarks

All product names, logos, and brands are property of their respective owners. Google, Microsoft, Alibaba, IBM and other names used in this repository are for identification purposes only and do not imply endorsement. This project is an independent open source effort and is not affiliated with or sponsored by any of the aforementioned companies.

License

Apache 2.0 - see LICENSE for details.

---

⭐ Star on GitHub • 📦 PyPI Package