Metadata-Version: 2.4
Name: iqs-qec
Version: 0.1.0
Summary: Automated discovery of Decoherence-Free Subspaces with built-in IBM Quantum hardware validation.
Home-page: https://github.com/yourusername/iqs-qec
Author: IQS-EQS Project
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: qiskit>=1.0.0
Requires-Dist: qiskit-ibm-runtime>=0.23.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# IQS-QEC: Rigorous Quantum Architecture Verification & Hardware Validation

`iqs_qec` is an enterprise-grade mathematical verification engine for quantum architectures with **built-in automated IBM Quantum hardware validation**.

Instead of relying on heuristic noise suppression, `iqs_qec` uses Functional Analysis (Compressions, Bifurcations, and Stratified Contractions) to mathematically prove whether a proposed quantum hardware topology admits a stable **Decoherence-Free Subspace (DFS)**, and then automatically synthesizes and runs validation circuits on real quantum hardware.

## Why IQS-QEC?

The quantum computing industry spends billions trying to suppress environmental noise. Standard tools optimize control pulses to fight this noise. `iqs_qec` solves the problem at the root: it proves mathematically whether the causal ($E$-channel) and memory ($M$-channel) noises perfectly cancel each other out in your hardware design ($\kappa_E + \mu_0 = 0$).

More importantly, it provides the bridge from abstract mathematics to real quantum execution. It discovers the protected subspaces, auto-generates the necessary unitaries via exact subspace projection (Part 251 Lemma 1), transpiles the circuits, and submits them to an IBM Quantum Processor to empirically prove the cancellation holds.

## Features

- **Host Discovery (`host_discovery.py`)**: Automatically scans the full joint eigenspaces of your noise operators to discover protected DFS hosts. Scales up to $N=9$ qubits (6,400 protected hosts discovered in ~228s).
- **Absolute Stability Verification (`bootstrap_verifier.py`)**: Computes exact Kraus operators to verify if the discovered host is an absolute, non-leaking fixed point of the Heisenberg dual.
- **Circuit Synthesis (`circuit_synthesis.py`)**: Automatically projects the full system Hamiltonian onto the discovered host subspace and generates exact `qiskit.QuantumCircuit` objects for validation.
- **IBM Hardware Execution (`hardware_runner.py`)**: Seamlessly connects to your IBM Quantum account, automatically finds the lowest-error physical qubit pair, transpiles, and submits validation circuits.
- **Statistical Analysis (`statistics.py`)**: Performs automated chi-squared goodness-of-fit testing and computes null/control separation ratios directly from the QPU result data.

## Proven on Real Quantum Hardware

This framework's predictions have been rigorously verified on IBM Quantum processors (e.g., `ibm_marrakesh`, `ibm_fez`). 

In live null-tests of the D4 cancellation symmetry:
- **Null Arm (Symmetry Exists):** Residuals drop to statistical noise floors (consistent with $\Delta = 0$, $p > 0.5$).
- **Control Arm (No Symmetry):** Produces massive separation signals (up to 24x above the noise floor) perfectly tracking the theoretical curves.

## Quick Start

### Installation

```bash
pip install iqs-qec
```

### End-to-End Pipeline Demo

```python
import numpy as np
from iqs_qec import find_protected_hosts
from iqs_qec.circuit_synthesis import build_null_test_circuits
from iqs_qec.hardware_runner import submit_circuits
from iqs_qec.statistics import analyze_null_test

# 1. Define your system and noise Hamiltonians (N=2 example)
I2, sx, sy, sz = np.eye(2), np.array([[0,1],[1,0]]), np.array([[0,-1j],[1j,0]]), np.diag([1,-1])
H_S = np.kron(sx, sx) + np.kron(sy, sy)
noise = np.kron(sz, I2) + np.kron(I2, sz)

# 2. Discover protected DFS hosts
hosts = find_protected_hosts(H_S, [noise], strict_only=True)
host = hosts[0]

# 3. Auto-generate the actual and counterfactual test circuits
circuits, meta, exact = build_null_test_circuits(
    host, H_S, 
    t_values=[0.3, 0.5, 0.7], 
    g_values=[1.5],
    eps=0.5
)

# 4. Submit to IBM Hardware (Requires QISKIT_IBM_TOKEN env var)
# res_file, out_data = submit_circuits(circuits, meta, shots=20000)

# 5. Analyze the real QPU results
# result = analyze_null_test(null_residuals, control_residuals, shots=20000)
```
