ariadne-router 0.3.0

Zero-config quantum simulator bundle for education, benchmarking & CI

Ariadne – Zero-config quantum simulator bundle for education, benchmarking & CI

---

🔄 Release Status

• PyPI package name: ariadne-router
• Publishing method: Trusted Publisher (GitHub Actions OIDC)
• Status: Ready for release! Push a tag to publish to PyPI.

Overview

In plain language: Run Bell, QAOA, VQE, QFT, Grover, QPE, stabilizer, error correction, quantum ML and 15+ canonical circuits on any laptop, any OS, same code. Automatically picks Stim, Qiskit, MPS, Metal, CUDA so students and CI never break.

Ariadne is a zero-configuration quantum simulator bundle that automatically routes your circuits to the optimal backend. Whether you're teaching quantum computing, running benchmarks across platforms, or setting up CI pipelines, Ariadne ensures reproducible results without the complexity of manual backend selection.

Who needs this?

• University instructors who want one pip install that works on macOS, Linux, WSL.
• Researchers who need citable, reproducible cross-simulator benchmarks.
• DevOps teams that want multi-backend regression tests in GitHub Actions.

Routing logic is deterministic and driven by measurable circuit characteristics, ensuring that every decision can be reproduced and audited when requirements evolve.

🚦 Start Here

• Quick Start
• Examples
• Advanced capabilities

Your First Simulation

Ariadne automatically routes your circuit to the optimal simulator without any code changes.

from ariadne import simulate
from qiskit import QuantumCircuit

# Create any circuit - let Ariadne handle the rest
qc = QuantumCircuit(20, 20)
qc.h(range(10))
for i in range(9):
    qc.cx(i, i + 1)
qc.measure_all()

# One simple call that handles all backend complexity
result = simulate(qc, shots=1000)
print(f"Backend used: {result.backend_used}")
print(f"Execution time: {result.execution_time:.4f}s")
print(f"Unique outcomes: {len(result.counts)}")

📖 Local Docs • 💡 Examples • 🚀 Getting Started • 🧠 Core API • 📊 Performance • 🤝 Contributing

---

✨ Key Features

Capability	Impact
🧠 Intelligent Routing	Mathematical analysis of circuit properties automatically selects the optimal backend without user intervention.
⚡ Stim Auto-Detection	Pure Clifford circuits are automatically routed to Stim, enabling the simulation of circuits that are too large for other backends.
🍎 Apple Silicon Acceleration	JAX-Metal backend can provide speedups for general-purpose circuits on M-series chips.
🚀 CUDA Support	NVIDIA GPU acceleration is supported when available, with performance improvements depending on the hardware and circuit structure. Actual speedups will vary based on your specific GPU and circuit characteristics.
🔄 Zero Configuration	simulate(circuit, shots) just works—no vendor imports or backend selection logic required.
🔢 Universal Fallback	Always returns a result, even when specialized backends fail.
📊 Transparent Decisions	Every routing decision can be inspected and validated with detailed reasoning.
🔌 Extensible	Apache 2.0 licensed with a modular backend interface for community contributions.

---

🧰 Use Cases

• Education and workshops

  • Run 15+ canonical algorithms (Bell, GHZ, QFT, Grover, QPE, Steane code, QSVM, etc.) without choosing simulators. Ariadne routes to stim/MPS/Qiskit/Metal as appropriate.
  • Comprehensive education notebooks with mathematical background and implementation details.
  • One command demo: python examples/quickstart.py.

• Research prototyping

  • Iterate on algorithms with simulate(qc, shots) and let Ariadne pick the best backend by structure (Clifford ratio, entanglement heuristics).
  • Override when needed with simulate(qc, backend='mps') and compare.

• CI/regression testing

  • Same tests run across macOS/Linux/Windows. Missing backends fail over cleanly; logs record decisions.
  • Good for ensuring algorithms don’t silently degrade across environments.

• Benchmarking and feasibility checks

  • Large stabilizer circuits route to stim (feasible when statevector fails).
  • Low-entanglement shallow circuits route to MPS for speed/memory wins.

• Apple Silicon acceleration

  • On M-series Macs, try Metal for general-purpose circuits; otherwise fall back to CPU.

---

🧭 Routing at a glance

Circuit characteristics	Expected backend	Why
Pure Clifford (e.g., GHZ, stabilizers)	stim	Specialized, extremely fast stabilizer simulation
Low entanglement, shallow depth	MPS	Efficient tensor-network representation
High entanglement (QFT, QPE)	Tensor Network	Efficient contraction for complex circuits
Quantum search (Grover)	Qiskit	Balanced performance for moderate complexity
Error correction (Steane)	Qiskit	Robust for stabilizer-heavy circuits
General circuits on Apple Silicon	Metal	Leverage JAX/Metal when available
General circuits (portable)	Qiskit	Robust CPU statevector/density matrix

You can always override:

simulate(qc, shots=1000, backend='mps')

And CLI:

ariadne simulate path/to/circuit.qasm --shots 1000
ariadne benchmark-suite --algorithms qft,grover,qpe,steane
ariadne status --detailed

---

Routing matrix (auto-generated)

Regenerate with:

python examples/routing_matrix.py --shots 256 --generate-image docs/source/_static/routing_matrix.png

---

🔌 Supported Backends & Integrations

The following backends are detected and routed to when available. Many are optional and only used if their dependencies are installed.

• Qiskit CPU simulator (qiskit) — always available baseline
• Stim stabilizer simulator (stim) — specialized for Clifford circuits
• Matrix Product State (mps) via quimb
• Tensor Network (tensor_network) via cotengra/quimb
• JAX Metal (jax_metal) — Apple Silicon acceleration when JAX/Metal is available
• CUDA (cuda) — GPU acceleration via cupy
• DDSIM (ddsim) — alternative simulator via mqt.ddsim
• Cirq (cirq) — via src/ariadne/backends/cirq_backend.py
• PennyLane (pennylane) — via src/ariadne/backends/pennylane_backend.py
• Qulacs (qulacs) — via src/ariadne/backends/qulacs_backend.py
• Experimental: PyQuil (pyquil), Braket (braket), Q# (qsharp), OpenCL (opencl)

Supported Quantum Algorithms

Ariadne now supports 15+ quantum algorithms with standardized interfaces:

Foundational Algorithms:

• Bell States — Maximally entangled two-qubit states
• GHZ States — Multi-qubit Greenberger-Horne-Zeilinger states
• Quantum Fourier Transform (QFT) — Basis for many quantum algorithms

Search Algorithms:

• Grover's Search — Quadratic speedup for unstructured search
• Bernstein-Vazirani — Linear speedup for hidden string problems

Optimization Algorithms:

• QAOA — Quantum Approximate Optimization Algorithm
• VQE — Variational Quantum Eigensolver

Error Correction:

• Steane Code — [[7,1,3]] CSS quantum error correction code
• Surface Code — Topological error correction (simplified)

Quantum Machine Learning:

• QSVM — Quantum Support Vector Machine
• VQC — Variational Quantum Classifier
• Quantum Neural Network — Parameterized quantum circuits

Specialized Algorithms:

• Quantum Phase Estimation (QPE) — Eigenphase estimation
• Deutsch-Jozsa — Constant vs balanced function discrimination
• Simon's Algorithm — Period finding with exponential speedup
• Quantum Walk — Quantum analogue of classical random walk
• Amplitude Amplification — General technique for algorithm speedup

Backends are implemented under src/ariadne/backends/ and selected through the router in src/ariadne/router.py and the decision tree in src/ariadne/route/routing_tree.py.

---

🎯 The Ariadne Advantage: Intelligent Automation

Ariadne's core innovation is its comprehensive routing tree that analyzes circuit properties (size, gate types, entanglement patterns) and system capabilities (available backends, hardware acceleration) to automatically select the optimal execution environment. This eliminates the need for quantum developers to manually benchmark and select from 15+ different backends.

Transparent Decision Making

Ariadne provides complete transparency into why a circuit was routed to a specific backend. You can inspect the entire decision path through the routing tree.

from ariadne import explain_routing, show_routing_tree
from qiskit import QuantumCircuit

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

# Get a detailed, human-readable explanation of the routing decision
explanation = explain_routing(qc)
# explanation is a human-readable string describing the routing decision,
# e.g.:
# "Circuit routed to backend 'qiskit_simulator' because it has 2 qubits and no advanced gates."
print(explanation)

# You can also visualize the entire routing tree
print(show_routing_tree())

---

🚀 Getting Started

Installation

Typical install (PyPI):

pip install ariadne-router

Developer or power-user setup

Clone the repository if you plan to contribute, run the examples from source, or enable hardware acceleration extras.

git clone https://github.com/Hmbown/ariadne.git
cd ariadne
pip install -e .

To enable optional hardware acceleration backends, install the extras that match your environment:

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

# NVIDIA GPU (CUDA)
pip install -e .[cuda]

# All optional dependencies
pip install -e .[apple,cuda,viz]

📖 For detailed installation instructions, including dependency notes, see the Comprehensive Installation Guide

Quickstart Demo

Run the complete quickstart example to see Ariadne in action:

python examples/quickstart.py

This demo showcases:

• Automatic backend selection for different circuit types
• Performance comparisons
• Routing decision transparency
• Hardware acceleration when available

---

Quickstart GIF

Regenerate with:

python examples/generate_quickstart_gif.py --output docs/source/_static/quickstart.gif

---

🧠 Core API

• simulate – High-level helper that inspects a circuit, selects the best backend, and returns a SimulationResult.

  from ariadne import simulate
  
  result = simulate(circuit, shots=1000)
  print(result.backend_used)
  print(result.execution_time)
  

• EnhancedQuantumRouter – Object-oriented interface for configuring routing policies and evaluating decisions programmatically.

  from ariadne import EnhancedQuantumRouter
  
  router = EnhancedQuantumRouter()
  decision = router.select_optimal_backend(circuit)
  print(decision.recommended_backend)
  print(decision.confidence_score)
  

• ComprehensiveRoutingTree / explain_routing – Deterministic, auditable explanation tools for governance and debugging.

  </code></pre>
  </li>
  </ul>
  <p>from ariadne import ComprehensiveRoutingTree</p>
  <p>tree = ComprehensiveRoutingTree()
  decision = tree.route_circuit(circuit)
  print(decision.recommended_backend)
  print(decision.confidence_score)</p>
  <pre><code>
  Complementary helpers such as `get_config_manager()` and `configure_ariadne()` enable centrally managed policies, while the `ariadne` CLI mirrors these workflows for scripted environments.
  
  ---
  
  ## 📊 Performance
  
  Ariadne emphasizes **capability extension** and **consistent execution**. Automated routing ensures that circuits land on the most suitable simulator, even when that involves specialized tooling such as Stim or tensor-network engines. Benchmarks focus on demonstrating routing correctness, fallbacks, and platform-specific acceleration rather than raw single-backend speed.
  
  ### Representative routing results
  
  | Circuit | Selected backend | Router runtime (ms) | Direct Qiskit (ms) | Notes |
  |---------|------------------|---------------------|--------------------|-------|
  | `ghz_chain_10` | Stim | 17.9 | 1.47 | Router overhead exceeds direct Qiskit, but Stim unlocks scaling beyond 24 qubits. |
  | `random_clifford_12` | Stim | 339 | 13.2 | Conversion cost dominates at moderate size; routing remains correct for stabilizer workloads. |
  | `random_nonclifford_8` | Tensor network | 111 | 1.65 | Tensor contraction adds cost yet preserves accuracy for non-Clifford structure. |
  | `qaoa_maxcut_8_p3` | Tensor network | 67.6 | 1.34 | Demonstrates automatic selection of tensor-network backend even without immediate speedup. |
  
  ### Platform-specific highlights
  
  - **Apple Silicon** – JAX-Metal delivered 1.16×–1.51× speedups across sampled circuits, with minor regressions on a small subset when GPU transfer costs dominate.
  - **CUDA** – Benchmarks executed without GPU hardware; CPU baselines are recorded for reference and CUDA routing falls back safely when accelerators are unavailable.
  - **Operational insights** – Routing consistently selects specialized simulators for Clifford families, maintains deterministic fallbacks, and extends feasible circuit sizes beyond statevector limits.
  
  Full benchmark outputs, reproducibility scripts, and raw JSON data are available under `benchmarks/results` for compliance reviews and custom analysis.
  
  ---
  
  ## 🔧 Usage Examples
  
  ### Automatic Detection of Specialized Circuits
  
  Ariadne recognizes when circuits can benefit from specialized simulators like Stim.
  
  ```python
  from ariadne import simulate
  from qiskit import QuantumCircuit
  
  # Large Clifford circuit that would crash plain Qiskit
  qc = QuantumCircuit(40, 40)
  qc.h(0)
  for i in range(39):
    qc.cx(i, i + 1)  # Creates a 40-qubit GHZ state
  qc.measure_all()
  
  # Ariadne automatically routes to Stim for optimal performance
  result = simulate(qc, shots=1000)
  print(f"Backend used: {result.backend_used}")  # -> stim
  

  Advanced Routing Control

  For users who need fine-grained control over the routing process:

  from ariadne import ComprehensiveRoutingTree, RoutingStrategy
  from qiskit import QuantumCircuit
  
  # Create a circuit
  circuit = QuantumCircuit(2, 2)
  circuit.h(0)
  circuit.cx(0, 1)
  circuit.measure_all()
  
  # Initialize routing system
  router = ComprehensiveRoutingTree()
  
  # Use specific routing strategies
  decision = router.route_circuit(
      circuit,
      strategy=RoutingStrategy.MEMORY_EFFICIENT
  )
  
  print(f"Selected: {decision.recommended_backend.value}")
  print(f"Confidence: {decision.confidence_score:.2f}")
  print(f"Expected speedup: {decision.expected_speedup:.1f}x")
  

  Available routing strategies:

  • SPEED_FIRST - Prioritize execution speed
  • ACCURACY_FIRST - Favor accuracy/robustness when applicable
  • MEMORY_EFFICIENT - Optimize for memory usage
  • CLIFFORD_OPTIMIZED - Specialized for Clifford circuits
  • ENTANGLEMENT_AWARE - Prefer TN/MPS paths for low entanglement
  • STABILIZER_FOCUSED - Emphasize stabilizer-friendly paths
  • APPLE_SILICON_OPTIMIZED - Hardware-aware for M-series chips
  • CUDA_OPTIMIZED - GPU acceleration focused
  • CPU_OPTIMIZED - Prefer portable CPU simulators
  • RESEARCH_MODE - Exploration-oriented defaults
  • EDUCATION_MODE - Deterministic, simplified defaults
  • PRODUCTION_MODE - Conservative, reproducible defaults
  • AUTO_DETECT - Intelligent analysis (default)
  • HYBRID_MULTI_BACKEND - Adaptive, multi-path strategy

  
  ---
  
  ## 🛡️ Project Maturity
  
  ### Test Coverage
  - **Unit Tests**: 38%+ coverage across core modules.
  - **Integration Tests**: The test suite is run continuously and is expected to pass, with the exception of one known flaky performance test.
  - **Backend Tests**: All major backends are tested.
  
  ### Documentation
  - **Comprehensive Guides**: Installation, usage, and API documentation.
  - **Examples Gallery**: 15+ working examples for different use cases.
  - **Performance Reports**: Detailed benchmarking and validation.
  - **API Reference**: Complete API documentation with examples.
  
  ### Development Infrastructure
  - **CI/CD Pipeline**: Automated testing on Python 3.11-3.12.
  - **Code Quality**: Ruff linting, mypy type checking, pre-commit hooks.
  - **Security**: Bandit security scanning, dependency safety checks.
  - **Release Management**: Automated versioning and changelog generation.
  
  ---
  
  ## 🤝 Contributing
  
  We welcome contributions of all kinds, from bug fixes to new features. Please read our [**Contributing Guidelines**](docs/project/CONTRIBUTING.md) to get started.
  
  ### Development Setup
  
  ```bash
  git clone https://github.com/Hmbown/ariadne.git
  cd ariadne
  pip install -e .[dev]
  
  # Set up pre-commit hooks
  pre-commit install
  
  # Run unit tests
  pytest tests/ -v
  

  📖 For detailed development setup instructions, see the Comprehensive Installation Guide

  ---

  💬 Community

  • GitHub Discussions: Ask questions and share ideas
  • Issue Tracker: Report bugs and request features

  ---

  ✅ User Testing Results

  Ariadne has been comprehensively tested as a user would experience it. Here are the results:

  Test Coverage

  • 45 tests executed across all major features
  • 43 tests passed (97.7% pass rate)
  • 1 edge case noted (zero shots accepted silently)
  • No critical issues discovered

  Core Features Verified

  ✓ Installation & Dependencies

  • Clean installation via pip
  • All major backends detected and available (Qiskit, Stim, Metal, Tensor Network, MPS, DDSIM)
  • Graceful fallback for unavailable backends (CUDA, Cirq)

  ✓ Automatic Routing

  • Bell states → Stim (92ms for 1000 shots)
  • 20-qubit Clifford circuits → Stim (21ms)
  • Non-Clifford circuits → MPS/Tensor Network
  • Deep circuits (50 gates) → JAX Metal on Apple Silicon

  ✓ API & CLI

  • simulate() function works reliably
  • explain_routing() provides clear decision explanations
  • show_routing_tree() displays routing logic visually
  • All CLI commands (simulate, config, status, benchmark) functional

  ✓ Performance

  • Stim: ~100,000 shots/s (Clifford circuits)
  • Qiskit: ~60,000 shots/s (general fallback)
  • JAX Metal: 179-226k shots/s (Apple Silicon)
  • Tensor Network: ~200-4,600 shots/s (low-entanglement)

  Getting Started Quick Checks

  Verify your installation with these one-liners:

  # 1. Check version and imports
  python3 -c "from ariadne import simulate; print('✓ Ready to go!')"
  
  # 2. Run quickstart example
  python3 examples/quickstart.py
  
  # 3. Test CLI
  ariadne status
  ariadne benchmark --iterations 1
  
  # 4. Verify Bell state (should route to Stim)
  python3 -c "
  from qiskit import QuantumCircuit
  from ariadne import simulate, explain_routing
  
  bell = QuantumCircuit(2, 2)
  bell.h(0)
  bell.cx(0, 1)
  bell.measure_all()
  
  result = simulate(bell, shots=1000)
  print(f'Backend: {result.backend_used.value}')
  print(f'Time: {result.execution_time:.4f}s')
  "
  

  Recommended Workflows

  For Researchers:

  # Automatic optimal backend selection
  from ariadne import simulate
  result = simulate(your_circuit, shots=1000)  # Works!
  
  # Understand routing decisions
  from ariadne import explain_routing
  print(explain_routing(your_circuit))
  

  For Production Systems:

  # Force specific backend if needed
  result = simulate(circuit, shots=1000, backend='qiskit')
  
  # Save results for reproducibility
  from ariadne.cli.main import AriadneCLI
  cli = AriadneCLI()
  cli.run(['simulate', 'circuit.qasm', '--output', 'results.json'])
  

  For Benchmarking:

  # Profile all backends on your hardware
  ariadne benchmark --circuit circuit.qasm --shots 1000 --iterations 5 --output results.json
  

  Known Behaviors & Notes

  • Zero shots: Currently accepted without warning. Use shots >= 1 for standard behavior.
  • First-run overhead: Metal and Tensor Network backends have compilation overhead on first run (~1s). Subsequent runs are much faster.
  • Logging: Detailed routing decisions are logged at INFO level. Control with configure_logging().
  • Fallback safety: If a selected backend fails, automatic fallback to Qiskit ensures results always returned.

  Recommendations for Users

  1. Start with automatic routing (simulate() without backend parameter) - it usually makes the best choice
  2. Use explain_routing() to understand why a backend was selected
  3. Explore the algorithm library - try from ariadne.algorithms import list_algorithms
  4. Run education notebooks - comprehensive learning materials for each algorithm
  5. Run benchmarks on your specific hardware to profile performance
  6. Trust the routing tree - it's been validated against 45+ different circuit patterns
  7. For reproducibility, save results and use explicit backend selection if needed

  Quality Assurance

  • ✓ All examples run successfully
  • ✓ Error handling is graceful (invalid backends, missing files)
  • ✓ Results data is consistent and valid
  • ✓ Documentation matches actual behavior
  • ✓ CLI mirrors Python API exactly
  • ✓ Performance claims are accurate

  ---

  📜 License

  Ariadne is released under the Apache 2.0 License.

  Policies

  • CHANGELOG
  • SECURITY
  • CODE OF CONDUCT

  ---

  🙏 Acknowledgments

  Ariadne builds upon excellent open-source quantum computing frameworks:

  • Qiskit for quantum circuit representation
  • Stim for Clifford circuit simulation
  • Quimb for tensor network operations
  • JAX for hardware acceleration

  ---