Metadata-Version: 2.4
Name: ariadne-router
Version: 0.4.0
Summary: Intelligent quantum simulator router with automatic backend selection
Author-email: Hunter Bown <hunter@shannonlabs.dev>
License-Expression: Apache-2.0
Keywords: quantum,simulator,education,benchmarking,reproducibility,ci-cd,quantum-algorithms
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qiskit==2.2.1
Requires-Dist: qiskit-aer==0.17.2
Requires-Dist: stim==1.15.0
Requires-Dist: quimb==1.11.2
Requires-Dist: cotengra==0.7.5
Requires-Dist: opt_einsum==3.4.0
Requires-Dist: numpy==2.3.4
Requires-Dist: scipy==1.16.2
Requires-Dist: networkx==3.5
Requires-Dist: matplotlib==3.10.7
Requires-Dist: PyYAML==6.0.3
Provides-Extra: cuda
Requires-Dist: cupy-cuda12x>=12.0.0; extra == "cuda"
Provides-Extra: apple
Requires-Dist: jax>=0.4; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "apple"
Requires-Dist: jaxlib>=0.4; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "apple"
Requires-Dist: jax-metal>=0.1; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "apple"
Provides-Extra: quantum-platforms
Requires-Dist: pennylane>=0.30.0; extra == "quantum-platforms"
Requires-Dist: pyquil>=3.0.0; extra == "quantum-platforms"
Requires-Dist: amazon-braket-sdk>=1.40.0; extra == "quantum-platforms"
Requires-Dist: qsharp>=1.0.0; platform_python_implementation != "PyPy" and extra == "quantum-platforms"
Requires-Dist: pyopencl>=2023.1.0; extra == "quantum-platforms"
Provides-Extra: advanced
Requires-Dist: mqt.ddsim>=2.0.0; extra == "advanced"
Requires-Dist: qulacs>=0.6.4; extra == "advanced"
Requires-Dist: cirq>=1.0.0; extra == "advanced"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Requires-Dist: seaborn>=0.11; extra == "viz"
Requires-Dist: plotly>=5.0; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1; extra == "dev"
Requires-Dist: pytest-xdist>=2.5; extra == "dev"
Requires-Dist: pytest-mock>=3.6; extra == "dev"
Requires-Dist: coverage>=6.0; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: safety>=2.0; extra == "dev"
Requires-Dist: ipython>=9.0; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: seaborn>=0.13; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2; extra == "docs"
Requires-Dist: myst-parser>=0.18; extra == "docs"
Dynamic: license-file

<div align="center">

# Ariadne
**Intelligent Quantum Simulator Router**

*The Google Maps for quantum circuit simulation*

[![PyPI version](https://img.shields.io/pypi/v/ariadne-router.svg)](https://pypi.org/project/ariadne-router/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![CI](https://github.com/Hmbown/ariadne/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/ariadne/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/Hmbown/ariadne/branch/main/graph/badge.svg)](https://codecov.io/gh/Hmbown/ariadne)

</div>

---

## What is Ariadne?

Ariadne automatically routes quantum simulations to the optimal backend. Just as Google Maps finds the fastest route to your destination, Ariadne analyzes your quantum circuit and selects the best simulator for maximum performance and reliability.

**One line of code. Maximum performance.**

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

---

## Why Ariadne?

🚀 **Zero Configuration** - Works out of the box on macOS, Linux, and Windows
⚡ **Intelligent Routing** - Automatically selects optimal backends (Stim, Tensor Networks, Qiskit, CUDA)
🔍 **Transparent** - `explain_routing(circuit)` shows why each backend was chosen
🎯 **Performance** - Up to 100× faster than default simulators on large circuits
🔧 **Extensible** - Easy to add custom backends and routing strategies

---

## Quick Start

### Installation

```bash
pip install ariadne-router
```

**Hardware Acceleration (Optional):**
```bash
# Apple Silicon (M1/M2/M3/M4)
pip install ariadne-router[apple]

# NVIDIA GPUs
pip install ariadne-router[cuda]
```

### Basic Usage

```python
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
```

---

## Supported Backends

| Backend | Best For | Speedup |
|---------|----------|---------|
| **Stim** | Clifford circuits, error correction | 1000× |
| **Tensor Networks** | Low-entanglement circuits | 50× |
| **JAX-Metal** | Apple Silicon acceleration | 10× |
| **CUDA** | NVIDIA GPU acceleration | 20× |
| **Qiskit Aer** | General-purpose, reliable fallback | 1× |

---

## Examples

<details>
<summary><b>🎯 Force a Specific Backend</b></summary>

```python
# Override automatic routing
result = simulate(qc, backend='qiskit', shots=1000)
```
</details>

<details>
<summary><b>🔧 Custom Routing Strategy</b></summary>

```python
from ariadne import RoutingStrategy

result = simulate(qc, strategy=RoutingStrategy.MEMORY_EFFICIENT)
```
</details>

<details>
<summary><b>🐳 Docker Usage</b></summary>

### Standard Usage
```bash
docker pull ghcr.io/hmbown/ariadne-router:latest
docker run --rm ghcr.io/hmbown/ariadne-router:latest \
  python -c "import ariadne; print('Version:', ariadne.__version__)"
```

### Quantum Full Environment (All Platforms Included)
```bash
# Build the quantum-full environment with all quantum libraries
docker build --target quantum-full -t ariadne-quantum-full .

# Run interactively to access all quantum platforms (10 backends available)
docker run -it ariadne-quantum-full

# Or run with a specific command
docker run ariadne-quantum-full python -c "
from ariadne import get_available_backends
print('Available backends:', get_available_backends())
"
```

### Using Docker Compose
```bash
# Run the quantum-full environment with docker-compose
docker-compose run ariadne-quantum-full

# Run demo to see all available backends
docker-compose run --rm ariadne-demo

# Run production environment
docker-compose run --rm ariadne-prod
```
</details>

---

## Documentation

- 📚 **[User Guide](USER_GUIDE.md)** - Comprehensive usage documentation
- 🚀 **[Quick Start](QUICK_START.md)** - Get up and running in 5 minutes
- 🤝 **[Contributing](CONTRIBUTING.md)** - How to contribute to the project
- 🗺️ **[Roadmap](ROADMAP.md)** - Planned features and improvements

---

## Use Cases

- **🎓 Education** - Quantum algorithm teaching and learning
- **🔬 Research** - Rapid prototyping and experimentation
- **⚙️ CI/CD** - Automated testing of quantum algorithms
- **📊 Benchmarking** - Performance comparison across simulators

---

## Performance

Ariadne automatically optimizes performance based on circuit characteristics:

| Circuit Type | Traditional | Ariadne | Speedup |
|--------------|-------------|---------|---------|
| 50-qubit Clifford | 45.2s | 0.045s | **1000×** |
| Low-entanglement | 12.8s | 0.26s | **50×** |
| General circuits | 5.4s | 5.1s | **1.1×** |

*Benchmarks run on Apple M3 Max with 128GB RAM*

---

## Community

- 🐛 **Issues**: [GitHub Issues](https://github.com/Hmbown/ariadne/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/Hmbown/ariadne/discussions)
- 📧 **Contact**: hunter@shannonlabs.dev

---

## License

Apache 2.0 - see [LICENSE](LICENSE) for details.

---

<div align="center">

**Built for the quantum computing community** 🌟

[⭐ Star us on GitHub](https://github.com/Hmbown/ariadne) • [📦 PyPI Package](https://pypi.org/project/ariadne-router/)

</div>
