Metadata-Version: 2.4
Name: zuntenium
Version: 0.1.0
Summary: Enterprise-Grade Hybrid Quantum Computing SDK, Transpiler & Cloud Platform
Home-page: https://github.com/Vnnie-Mun/zuntenium
Author: Vnnie-Mun
Author-email: Vnnie-Mun <vinimun01@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Vnnie-Mun/zuntenium
Project-URL: Documentation, https://github.com/Vnnie-Mun/zuntenium#readme
Project-URL: Repository, https://github.com/Vnnie-Mun/zuntenium
Project-URL: Bug Tracker, https://github.com/Vnnie-Mun/zuntenium/issues
Project-URL: Changelog, https://github.com/Vnnie-Mun/zuntenium/releases
Keywords: quantum computing,quantum simulation,hybrid quantum classical,variational quantum eigensolver,QAOA,transpiler,stabilizer,matrix product state,gpu quantum,quantum cloud
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.11
Requires-Dist: typing-extensions>=4.8
Requires-Dist: dataclasses-json>=0.6
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.7; extra == "dev"
Requires-Dist: pybind11>=2.11; extra == "dev"
Requires-Dist: cmake>=3.27; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: hypothesis>=6.90; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Provides-Extra: ai
Requires-Dist: scikit-learn>=1.3; extra == "ai"
Requires-Dist: torch>=2.1; extra == "ai"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Requires-Dist: ipython>=8.17; extra == "viz"
Provides-Extra: hardware
Requires-Dist: qiskit-ibm-runtime>=0.15; extra == "hardware"
Requires-Dist: ionq-cirq>=0.4; extra == "hardware"
Requires-Dist: amazon-braket-sdk>=1.80; extra == "hardware"
Requires-Dist: boto3>=1.34; extra == "hardware"
Requires-Dist: aiohttp>=3.9; extra == "hardware"
Requires-Dist: qcs-sdk-python>=0.27; extra == "hardware"
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=12.0; extra == "gpu"
Provides-Extra: cloud
Requires-Dist: fastapi>=0.100.0; extra == "cloud"
Requires-Dist: uvicorn>=0.23.0; extra == "cloud"
Requires-Dist: pydantic>=2.0; extra == "cloud"
Requires-Dist: sqlalchemy>=2.0; extra == "cloud"
Requires-Dist: redis>=5.0; extra == "cloud"
Requires-Dist: rq>=1.15; extra == "cloud"
Provides-Extra: all
Requires-Dist: zuntenium[ai,cloud,dev,gpu,hardware,viz]; extra == "all"
Dynamic: license-file

# ZUNTENIUM

**Enterprise-Grade Hybrid Quantum Computing SDK, Transpiler & Cloud Platform**

[![PyPI version](https://img.shields.io/pypi/v/zuntenium.svg?color=blue)](https://pypi.org/project/zuntenium/)
[![Python 3.10 | 3.11 | 3.12](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://pypi.org/project/zuntenium/)
[![Tests Passing](https://img.shields.io/badge/tests-477%2F477%20passed-brightgreen.svg)](https://github.com/Vnnie-Mun/zuntenium/actions)
[![Code Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](https://github.com/Vnnie-Mun/zuntenium)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Docker Ready](https://img.shields.io/badge/docker-compose%20%26%20k8s-informational.svg)](https://github.com/Vnnie-Mun/zuntenium/tree/main/zuntenium_cloud)
[![Next.js Standalone](https://img.shields.io/badge/UI-Next.js%2015%20Standalone-black.svg)](https://github.com/Vnnie-Mun/zuntenium/tree/main/zuntenium-ui)

---

## Overview

**ZUNTENIUM** is a high-performance, full-stack quantum computing platform designed to scale seamlessly from interactive circuit design on laptops to distributed GPU simulation and physical Quantum Processing Unit (QPU) orchestration.

ZUNTENIUM converges advanced circuit compilation, simulation engines, multi-hardware orchestration, and self-hosted cloud microservices into a unified, production-ready ecosystem:

- 1. **Multi-Engine Quantum Simulation**:
  - **Aaronson-Gottesman Stabilizer Tableau**: Simulates Clifford circuits up to **10,000+ qubits** in $O(n^2)$ time with phase tracking.
  - **CuPy GPU Statevector Backend**: High-throughput GPU tensor contraction for dense unitary execution.
  - **Matrix Product State (MPS) Tensor Network**: Simulates 50–100+ weakly entangled qubits with SVD bond-dimension truncation.
  - **Exact Statevector Simulator**: Big-endian pure-state evolution with full Pauli expectation value contraction $\langle \psi | P | \psi \rangle$.
- 2. **Transpiler Engine v2**:
  - **`TranspilerCache`**: Structural template hashing with **$O(1)$ parameter rebinding**, cutting 95%+ transpilation latency in VQE and QAOA variational loops.
  - **SABRE Qubit Routing**: Lookahead distance heuristics, extended successor sets, and decay penalties for heavy-hex and grid topologies.
  - **Cartan KAK Lie Algebra Decomposition**: Canonical $SU(4)$ two-qubit decomposition minimizing two-qubit gate counts.
  - **Solovay-Kitaev $\epsilon$-Net Approximation**: Recursive group commutator approximation for arbitrary single-qubit rotations.
  - **Circuit Fingerprinting**: Parameter-invariant topological and DAG similarity hashing.
- 3. **Multi-Hardware Orchestration System (MHOS)**:
  - Unified adapter interface for physical execution on **IBM Quantum (Runtime)**, **IonQ Cloud**, **Amazon Braket**, and **Rigetti (QCS)** with automatic simulator fallback.
- 4. **Zero-Noise Extrapolation (ZNE) & Error Mitigation**:
  - Richardson, polynomial, and exponential noise scaling with randomized Pauli / readout mitigation.
- 5. **Self-Hostable Cloud Platform & Microservices**:
  - **FastAPI REST API**: Authentication, JWT tokens, API keys, quota management, and public backend discovery.
  - **RQ Distributed Worker Cluster**: High, default, low, and hardware queues with graceful job execution.
  - **Full Observability**: PostgreSQL 15 (UUID typed), Redis 7, Prometheus metrics, and Grafana dashboard provisioning.
- 6. **Next.js 15 Visual QCanvas Workspace**:
  - Standalone web interface with interactive quantum circuit builder, Bloch sphere visualizer, and live cloud job telemetry.

---

## Architecture

```
User Code / QCanvas UI  ───►  FastAPI Gateway (Port 8000)
                                     │
                  ┌──────────────────┴──────────────────┐
                  ▼                                     ▼
        Transpiler Engine v2                 Distributed Job Queue
   ├── TranspilerCache (O(1) Rebind)         ├── Redis Task Broker
   ├── SABRE Lookahead Router                ├── RQ Worker Cluster
   ├── Cartan KAK SU(4) Decomposition        └── PostgreSQL 15 (UUID)
   └── Solovay-Kitaev ε-Net
                  │
                  ▼
         Multi-Hardware Orchestrator (MHOS)
   ┌──────────────────────────────────────────────────────────┐
   │                     Execution Backends                   │
   ├────────────────────────────┬─────────────────────────────┤
   │ Local Simulation:          │ Cloud QPUs:                 │
   │ • Stabilizer (10,000+ q)   │ • IBM Quantum (Runtime)     │
   │ • CuPy GPU Statevector     │ • IonQ Cloud (Trapped Ion)  │
   │ • Tensor Network (MPS)     │ • Amazon Braket             │
   │ • C++ / NumPy Statevector  │ • Rigetti QCS (Supercond.)  │
   └────────────────────────────┴─────────────────────────────┘
```

---

## Competitive Capability Matrix

How ZUNTENIUM compares with established quantum frameworks:

| Capability Domain | Qiskit | PennyLane | TKET | CUDA-Q | **ZUNTENIUM** |
|---|---|---|---|---|---|
| **Primary Focus** | IBM ecosystem & general SDK | QML & hybrid gradients | High-performance routing | GPU-accelerated C++ | **Full-Stack Quantum SDK + Cloud + UI** |
| **Simulation Diversity** | High (Aer) | Via plugins | Via backends | CuQuantum | **High** (Statevector, Stabilizer $10^4$q, GPU, MPS) |
| **Clifford Stabilizer** | Included | External | External | Limited | **Top-Tier** ($10^4$+ qubits built-in) |
| **Transpiler Caching** | Basic pass manager | Tape caching | Structural passes | Compile-time | **Top-Tier** ($O(1)$ Template Rebinding) |
| **Multi-Hardware Portability** | IBM-centric | Provider plugins | Provider plugins | NVIDIA targets | **Native MHOS** (IBM, IonQ, Braket, Rigetti) |
| **Self-Hosted Cloud Stack** | Proprietary | None | None | None | **Built-in** (FastAPI, RQ, Postgres, Redis, Prometheus) |
| **Visual Canvas Web UI** | Web Composer | None | None | None | **Built-in** (Next.js 15 Standalone QCanvas) |
| **Test Verification** | Extensive | Extensive | Extensive | Extensive | **477 / 477 passing (100%)** |

---

## Quick Start & Code Examples

### 1. Massive Clifford Simulation (10,000 Qubits)

Simulate 10,000-qubit entangled states in seconds using the Aaronson-Gottesman binary stabilizer tableau:

```python
import zuntenium as zn

# Create a 10,000-qubit GHZ state circuit
qc = zn.QuantumCircuit(10000)
qc.h(0)
for i in range(9999):
    qc.cx(i, i + 1)
qc.measure_all()

# Execute on the stabilizer simulator
result = zn.execute(qc, backend="stabilizer", shots=1000)
print(result.counts)
# Output: {'00...0': 503, '11...1': 497}
```

---

### 2. $O(1)$ Variational Acceleration with `TranspilerCache`

Eliminate 95%+ transpilation overhead during VQE, QAOA, and QML parameter update loops:

```python
from zuntenium import QuantumCircuit
from zuntenium.transpiler import TranspilerCache

# Initialize structural template cache
cache = TranspilerCache(max_entries=1000)

# Build a parameterized variational ansatz
ansatz = QuantumCircuit(4)
ansatz.rx(0, theta=0.1).ry(1, theta=0.2).cx(0, 1).cx(2, 3)

# Hash topological structure invariant to parameter values
template_hash = cache.compute_template_hash(ansatz)

# In optimization loop: rebind in O(1) time without recompilation
for epoch in range(100):
    new_angles = [0.05 * epoch, 0.12 * epoch]
    fast_circuit = cache.rebind(template_hash, new_angles)
```

---

### 3. Hardware-Aware SABRE Routing

Map arbitrary quantum circuits onto physical chip coupling graphs with lookahead distance heuristics:

```python
from zuntenium.transpiler.passes.mapping.sabre_router import SABRERouter
from zuntenium.transpiler.coupling_map import CouplingMap
from zuntenium import QuantumCircuit

# Define a 3x3 grid hardware topology
coupling = CouplingMap.from_grid(3, 3)
router = SABRERouter(coupling_map=coupling, lookahead_weight=0.5, decay_rate=0.001)

# Route unmapped circuit onto physical architecture
routed_circuit, stats = router.run(unmapped_circuit)
print(f"Inserted SWAPs: {stats['swaps_added']}, Final Depth: {routed_circuit.depth()}")
```

---

### 4. Self-Hosted Cloud Client Execution

Submit circuits to your private Zuntenium Cloud cluster:

```python
from zuntenium.api.cloud import CloudClient
from zuntenium import QuantumCircuit

# Initialize client with API key
client = CloudClient(base_url="http://localhost:8000", api_key="zn_live_...")

# Discover available hardware and simulators
backends = client.list_backends()
print("Available:", [b["name"] for b in backends])

# Submit asynchronous job with error mitigation
job = client.submit(
    circuit=qc,
    backend="auto",
    shots=2048,
    mitigation=True,
    optimization_mode="rule",
)

result = job.wait_for_result(timeout=60)
print(result.counts)
```

---

## Installation

### From PyPI

```bash
pip install zuntenium
```

### With Optional Accelerators

```bash
# GPU acceleration (CuPy / CUDA)
pip install "zuntenium[gpu]"

# Cloud microservices stack (FastAPI, Redis, RQ, SQLAlchemy)
pip install "zuntenium[cloud]"

# Full installation with all extras
pip install "zuntenium[all]"
```

### From Source

```bash
git clone https://github.com/Vnnie-Mun/zuntenium.git
cd zuntenium
pip install -e ".[dev,cloud,gpu]"
```

---

## Deploying Zuntenium Cloud

Launch the full cloud infrastructure (API, multi-priority RQ workers, PostgreSQL, Redis, Prometheus, and Grafana):

```bash
cd zuntenium_cloud
docker compose up -d
```

- **API Gateway**: `http://localhost:8000` (Docs at `/docs`)
- **Prometheus Telemetry**: `http://localhost:9090`
- **Grafana Dashboard**: `http://localhost:3000`
- **RQ Worker Dashboard**: `http://localhost:9181`

### Running the QCanvas Web Workspace

```bash
cd zuntenium-ui
npm install
npm run build
npm run start
```
Interactive visual workspace available at `http://localhost:3000`.

---

## Test Suite & Verification

ZUNTENIUM is rigorously verified with **100% test pass rates**:

```bash
# Run complete test suite (477 tests)
pytest tests/

# Run unit tests only (279 tests)
pytest tests/unit/

# Run end-to-end integration verification (25 subsystems)
python debug_all.py
```

---

## License

ZUNTENIUM is licensed under the **Apache License 2.0**. See [`LICENSE`](LICENSE) for details.
