<div align="center">
# Ariadne
**Intelligent Quantum Simulator Router**
*The Google Maps for quantum circuit simulation*
[](https://pypi.org/project/ariadne-router/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/Hmbown/ariadne/actions/workflows/ci.yml)
[](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>
Raw data
{
"_id": null,
"home_page": null,
"name": "ariadne-router",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "quantum, simulator, education, benchmarking, reproducibility, ci-cd, quantum-algorithms",
"author": null,
"author_email": "Hunter Bown <hunter@shannonlabs.dev>",
"download_url": "https://files.pythonhosted.org/packages/aa/d1/f8b582df6f1dce0e2dfecfb3d064f399c1049eae45b3b09ead8728ac947c/ariadne_router-0.4.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# Ariadne\n**Intelligent Quantum Simulator Router**\n\n*The Google Maps for quantum circuit simulation*\n\n[](https://pypi.org/project/ariadne-router/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://github.com/Hmbown/ariadne/actions/workflows/ci.yml)\n[](https://codecov.io/gh/Hmbown/ariadne)\n\n</div>\n\n---\n\n## What is Ariadne?\n\nAriadne 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.\n\n**One line of code. Maximum performance.**\n\n```python\nfrom ariadne import simulate\nresult = simulate(quantum_circuit, shots=1000) # That's it!\n```\n\n---\n\n## Why Ariadne?\n\n\ud83d\ude80 **Zero Configuration** - Works out of the box on macOS, Linux, and Windows\n\u26a1 **Intelligent Routing** - Automatically selects optimal backends (Stim, Tensor Networks, Qiskit, CUDA)\n\ud83d\udd0d **Transparent** - `explain_routing(circuit)` shows why each backend was chosen\n\ud83c\udfaf **Performance** - Up to 100\u00d7 faster than default simulators on large circuits\n\ud83d\udd27 **Extensible** - Easy to add custom backends and routing strategies\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\npip install ariadne-router\n```\n\n**Hardware Acceleration (Optional):**\n```bash\n# Apple Silicon (M1/M2/M3/M4)\npip install ariadne-router[apple]\n\n# NVIDIA GPUs\npip install ariadne-router[cuda]\n```\n\n### Basic Usage\n\n```python\nfrom ariadne import simulate, explain_routing\nfrom qiskit import QuantumCircuit\n\n# Create a 40-qubit GHZ state\nqc = QuantumCircuit(40, 40)\nqc.h(0)\nfor i in range(39):\n qc.cx(i, i + 1)\nqc.measure_all()\n\n# Simulate with automatic backend selection\nresult = simulate(qc, shots=1000)\n\nprint(f\"Backend: {result.backend_used}\")\nprint(f\"Time: {result.execution_time:.3f}s\")\nprint(f\"Why: {explain_routing(qc)}\")\n```\n\n**Output:**\n```\nBackend: stim\nTime: 0.012s\nWhy: Clifford circuit detected \u2192 routed to Stim for 1000\u00d7 speedup\n```\n\n---\n\n## Supported Backends\n\n| Backend | Best For | Speedup |\n|---------|----------|---------|\n| **Stim** | Clifford circuits, error correction | 1000\u00d7 |\n| **Tensor Networks** | Low-entanglement circuits | 50\u00d7 |\n| **JAX-Metal** | Apple Silicon acceleration | 10\u00d7 |\n| **CUDA** | NVIDIA GPU acceleration | 20\u00d7 |\n| **Qiskit Aer** | General-purpose, reliable fallback | 1\u00d7 |\n\n---\n\n## Examples\n\n<details>\n<summary><b>\ud83c\udfaf Force a Specific Backend</b></summary>\n\n```python\n# Override automatic routing\nresult = simulate(qc, backend='qiskit', shots=1000)\n```\n</details>\n\n<details>\n<summary><b>\ud83d\udd27 Custom Routing Strategy</b></summary>\n\n```python\nfrom ariadne import RoutingStrategy\n\nresult = simulate(qc, strategy=RoutingStrategy.MEMORY_EFFICIENT)\n```\n</details>\n\n<details>\n<summary><b>\ud83d\udc33 Docker Usage</b></summary>\n\n### Standard Usage\n```bash\ndocker pull ghcr.io/hmbown/ariadne-router:latest\ndocker run --rm ghcr.io/hmbown/ariadne-router:latest \\\n python -c \"import ariadne; print('Version:', ariadne.__version__)\"\n```\n\n### Quantum Full Environment (All Platforms Included)\n```bash\n# Build the quantum-full environment with all quantum libraries\ndocker build --target quantum-full -t ariadne-quantum-full .\n\n# Run interactively to access all quantum platforms (10 backends available)\ndocker run -it ariadne-quantum-full\n\n# Or run with a specific command\ndocker run ariadne-quantum-full python -c \"\nfrom ariadne import get_available_backends\nprint('Available backends:', get_available_backends())\n\"\n```\n\n### Using Docker Compose\n```bash\n# Run the quantum-full environment with docker-compose\ndocker-compose run ariadne-quantum-full\n\n# Run demo to see all available backends\ndocker-compose run --rm ariadne-demo\n\n# Run production environment\ndocker-compose run --rm ariadne-prod\n```\n</details>\n\n---\n\n## Documentation\n\n- \ud83d\udcda **[User Guide](USER_GUIDE.md)** - Comprehensive usage documentation\n- \ud83d\ude80 **[Quick Start](QUICK_START.md)** - Get up and running in 5 minutes\n- \ud83e\udd1d **[Contributing](CONTRIBUTING.md)** - How to contribute to the project\n- \ud83d\uddfa\ufe0f **[Roadmap](ROADMAP.md)** - Planned features and improvements\n\n---\n\n## Use Cases\n\n- **\ud83c\udf93 Education** - Quantum algorithm teaching and learning\n- **\ud83d\udd2c Research** - Rapid prototyping and experimentation\n- **\u2699\ufe0f CI/CD** - Automated testing of quantum algorithms\n- **\ud83d\udcca Benchmarking** - Performance comparison across simulators\n\n---\n\n## Performance\n\nAriadne automatically optimizes performance based on circuit characteristics:\n\n| Circuit Type | Traditional | Ariadne | Speedup |\n|--------------|-------------|---------|---------|\n| 50-qubit Clifford | 45.2s | 0.045s | **1000\u00d7** |\n| Low-entanglement | 12.8s | 0.26s | **50\u00d7** |\n| General circuits | 5.4s | 5.1s | **1.1\u00d7** |\n\n*Benchmarks run on Apple M3 Max with 128GB RAM*\n\n---\n\n## Community\n\n- \ud83d\udc1b **Issues**: [GitHub Issues](https://github.com/Hmbown/ariadne/issues)\n- \ud83d\udcac **Discussions**: [GitHub Discussions](https://github.com/Hmbown/ariadne/discussions)\n- \ud83d\udce7 **Contact**: hunter@shannonlabs.dev\n\n---\n\n## License\n\nApache 2.0 - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n\n**Built for the quantum computing community** \ud83c\udf1f\n\n[\u2b50 Star us on GitHub](https://github.com/Hmbown/ariadne) \u2022 [\ud83d\udce6 PyPI Package](https://pypi.org/project/ariadne-router/)\n\n</div>\n",
"bugtrack_url": null,
"license": null,
"summary": "Intelligent quantum simulator router with automatic backend selection",
"version": "0.4.0",
"project_urls": null,
"split_keywords": [
"quantum",
" simulator",
" education",
" benchmarking",
" reproducibility",
" ci-cd",
" quantum-algorithms"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f04fd6722c369a62c6fcd04e9258f880a2ab876f6657f2c8ad98b3df0ea78014",
"md5": "c0c6577768058d1020ea8c4f5df721a9",
"sha256": "2519b4c91c645d03a4e8634ec9878a1f4c89ae70a6f0f63fd696f450a224a143"
},
"downloads": -1,
"filename": "ariadne_router-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c0c6577768058d1020ea8c4f5df721a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 301797,
"upload_time": "2025-10-26T22:11:54",
"upload_time_iso_8601": "2025-10-26T22:11:54.119838Z",
"url": "https://files.pythonhosted.org/packages/f0/4f/d6722c369a62c6fcd04e9258f880a2ab876f6657f2c8ad98b3df0ea78014/ariadne_router-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "aad1f8b582df6f1dce0e2dfecfb3d064f399c1049eae45b3b09ead8728ac947c",
"md5": "258fd63278c78a62b45a739beea73549",
"sha256": "ae0a70344c95c486e14cd68768fa8488246aaabd1e50cb9462b078e47ca84106"
},
"downloads": -1,
"filename": "ariadne_router-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "258fd63278c78a62b45a739beea73549",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 572392,
"upload_time": "2025-10-26T22:11:56",
"upload_time_iso_8601": "2025-10-26T22:11:56.351008Z",
"url": "https://files.pythonhosted.org/packages/aa/d1/f8b582df6f1dce0e2dfecfb3d064f399c1049eae45b3b09ead8728ac947c/ariadne_router-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 22:11:56",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ariadne-router"
}
JSON