ariadne-router 0.3.6

Intelligent quantum simulator router with automatic backend selection

Ariadne

Intelligent Quantum Simulator Router

The Google Maps for quantum circuit simulation, automatically finding the fastest path for your quantum circuits.

---

Table of Contents

• What is Ariadne?
• Performance Highlights
• Perfect For Your Use Case
• Quick Start
• How Ariadne Works
• Real Performance Benchmarks
• Educational Examples
• Advanced Features
• Ariadne vs Other Tools
• Docker Usage
• Documentation & Learning
• Contributing
• Performance Tuning
• Troubleshooting
• Project Status
• Success Stories
• License

---

What is Ariadne?

Stop wasting hours choosing quantum simulators. Ariadne automatically routes your quantum circuits to the optimal backend, giving you maximum performance with zero configuration.

Think of it as Google Maps for quantum computing - you provide the destination (your quantum circuit), and Ariadne finds the fastest route (optimal backend).

One line of code. Up to 1000× speedup for specific circuit types.

from ariadne import simulate
result = simulate(quantum_circuit, shots=1000)  # That's it!

Before Ariadne:

• Spend hours researching which backend to use
• Deal with complex installation and configuration
• Manually optimize for each circuit type
• Circuits crash or run painfully slow
• Different setups for different platforms

After Ariadne:

• Write your circuit once
• Ariadne analyzes it in milliseconds
• Automatic routing to the optimal backend
• Consistent performance across platforms
• Zero configuration required

---

Performance Highlights

Real-world performance improvements from automatic backend selection:

Circuit Type	Traditional Approach	Ariadne	Speedup
50-qubit Clifford	Crashes or 45+ seconds	0.045s	~1000× faster*
Low-entanglement circuits	12.8s	0.26s	~50× faster*
Large Clifford circuits	Memory errors	0.045s	Succeeds where others fail*
General quantum algorithms	Manual backend tuning	Automatic	Zero configuration

*Benchmarks measured on Apple M3 Max (128GB RAM). Actual speedups vary by circuit type and hardware. Clifford circuits see the largest improvements via Stim backend. Your results may differ based on circuit characteristics and available backends.

---

🎯 Perfect For Your Use Case

🎓 Students & Educators

• Learn quantum computing without backend complexity
• Interactive tutorials and educational tools
• Cross-platform consistency (Windows, macOS, Linux)
• Start with our Quantum Computing Primer

🔬 Researchers

• Reproduce published results with automatic optimization
• Scale to circuits that crash other simulators
• Focus on science, not simulator configuration

⚙️ Developers & Engineers

• Integrate quantum simulation into existing workflows
• Production-ready with enterprise support
• Automatic scaling from your laptop to powerful multi-core servers

---

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]

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 1000× speedup

---

🧠 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:

Backend	Best For	Speedup	When It Works
Stim	Clifford circuits, error correction	1000×	Circuit contains only H, S, CNOT, Pauli gates
Tensor Networks	Low-entanglement circuits	50×	Entanglement grows slowly with qubit count
JAX-Metal	Apple Silicon acceleration	10×	Running on M1/M2/M3/M4 Macs
CUDA	NVIDIA GPU acceleration	20×	NVIDIA GPU with sufficient memory
Qiskit Aer	General-purpose, reliable fallback	1×	Universal fallback for any circuit

---

📊 Real 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.045s vs 45.2s with Qiskit (1000× speedup)

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

---

🎓 Educational Examples

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

Custom Routing Strategies

from ariadne import RoutingStrategy, ComprehensiveRoutingTree

# Optimize for specific constraints
router = ComprehensiveRoutingTree()

# Speed-first routing (default)
result = router.simulate(qc, strategy=RoutingStrategy.SPEED_FIRST)

# Memory-efficient for large circuits
result = router.simulate(qc, strategy=RoutingStrategy.MEMORY_EFFICIENT)

# Accuracy-first for critical applications
result = router.simulate(qc, strategy=RoutingStrategy.ACCURACY_FIRST)

Backend Comparison & Validation

from ariadne.enhanced_benchmarking import EnhancedBenchmarkSuite

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

# Validate results across backends
for backend, result in comparison.items():
    print(f"{backend}: {result.execution_time:.3f}s")
    print(f"  Fidelity: {result.fidelity:.4f}")
    print(f"  Memory used: {result.memory_usage_mb:.1f}MB")

---

🆚 Ariadne vs Other Tools

Feature	Ariadne	Qiskit Aer	Cirq	PennyLane	Stim (Direct)
Automatic Backend Selection	✅	❌	❌	❌	❌
Zero Configuration	✅	❌	❌	❌	❌
Educational Tools	✅	Limited	Limited	✅	❌
Hardware Acceleration	✅ Auto-detect	Manual setup	Manual setup	Manual setup	❌
Large Circuit Support	✅	❌ (crashes)	❌	❌	✅ (Clifford only)
Cross-Platform	✅	✅	✅	✅	✅
Performance	Optimal	Good	Good	Good	Excellent (Clifford only)

When to choose Ariadne:

• You want maximum performance without manual tuning
• You're teaching/learning quantum computing
• You need to simulate circuits that crash other tools
• You want consistent results across different hardware
• You're building production quantum applications

When NOT to choose Ariadne:

• You need fine-grained control over specific backend parameters
• You're doing research on simulator algorithms themselves
• You have very specific hardware requirements

---

🐳 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. User Guide → USER_GUIDE.md
3. Educational Examples → examples/education/
4. API Reference → docs/source/
5. Research Papers → docs/project/CITATIONS.bib
6. 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

---

📈 Performance Tuning

For Maximum Speed

# Ariadne automatically optimizes, but you can help:
from ariadne import analyze_circuit

# Check what Ariadne sees in your circuit
analysis = analyze_circuit(your_circuit)
print(f"Detected properties: {analysis.properties}")

# Force specific backend if you know better
result = simulate(your_circuit, backend='stim')  # For Clifford circuits

For Large Circuits

# Reduce memory usage for 30+ qubit circuits
from ariadne import RoutingStrategy

result = simulate(
    large_circuit,
    shots=100,  # Fewer shots
    strategy=RoutingStrategy.MEMORY_EFFICIENT
)

---

🛠️ 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

• ✅ Production Ready - All tests passing, security audited
• ✅ Cross-Platform - Windows, macOS, Linux support
• ✅ Hardware Acceleration - CUDA, Metal, Apple Silicon
• ✅ Educational Tools - 15+ algorithms, interactive tutorials
• ✅ Enterprise Support - Docker, CI/CD, monitoring
• 🔄 Active Development - New backends and features monthly

---

---

📄 License

Apache 2.0 - see LICENSE for details.

---

Built for the quantum computing community 🌟

⭐ Star us on GitHub • 📦 PyPI Package • 🐦 Follow Updates • 💼 Enterprise Support