# Nativ3 — Topology-Aware Quantum Compiler

**24 theorems. 42,000+ tests. Zero failures.**

Quantum circuit topology and classical network topology are the same mathematical object, connected by a universal 4×4 transfer matrix with bond dimension 4 = 2⊗2.

## Install

```bash
pip install nativ3
pip install nativ3[qiskit]  # with Qiskit integration
```

## Quick Start

```python
from nativ3 import compile_circuit

# Define your circuit as (control, target) pairs
circuit = [(0,1), (0,2), (0,3), (1,2), (2,3)]

# Define hardware connectivity
hardware = {0:[1], 1:[0,2,4], 2:[1,3], 3:[2,4], 4:[1,3]}

# Calibration data (from IBM Quantum)
calibration = {
    "qubits": {q: {"gate_fidelity": 0.998} for q in range(5)},
    "edges": {(i,j): {"cx_fidelity": 0.97} for i in range(5) for j in hardware.get(i,[])}
}

# Compile: finds optimal qubit mapping maximizing topology cost Z
mapping, Z, swaps = compile_circuit(circuit, hardware, calibration)
print(f"Optimal mapping: {mapping}")
print(f"Topology cost Z: {Z:.4f}")
print(f"SWAP gates needed: {swaps}")
```

## What Z Captures That SWAP Count Doesn't

- Per-qubit fidelity (not all qubits are equal)
- Per-edge CX fidelity (not all connections are equal)  
- Chain length effects (longer chains decay nonlinearly)
- Hub structure (star circuits prefer high-connectivity nodes)
- Multi-gate optimization (different transfer matrix per gate type)

Among mappings with the same SWAP count, Z discriminates by up to **35%**.

## Key Results

| Theorem | Result |
|---------|--------|
| T1-T2 | Non-transitivity of CU topology, F = cos⁴(α) |
| T15-T16 | Universal 4×4 transfer matrix, bond dimension 4 |
| T17 | Projector angle: det(M) = 0, classical stochastic matrix |
| T19 | Relay = eigenvector of gate at projector |
| T22 | Self-referential: M is itself a CU gate |
| T23 | Novelty formula with conservation law |
| T24 | Deflection D² = 1-Z², breathing ratchet |

## Links

- **Paper**: [doi.org/10.5281/zenodo.19302455](https://doi.org/10.5281/zenodo.19302455)
- **IDE**: [nativ3.shift8.space](https://nativ3.shift8.space)
- **Breathing Mode**: [breathing.shift8.space](https://breathing.shift8.space)
