autoq-qec 0.2.1__tar.gz

autoq_qec-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ronaldo Rodrigues
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

autoq_qec-0.2.1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: autoq-qec
+Version: 0.2.1
+Summary: Multi-code QEC resource estimator for arbitrary Qiskit circuits
+Author-email: Ronaldo Rodrigues <Ronaldoengenhariadacomputacao@hotmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/Ronaldoengenhariadacomputacao/autoq-qec
+Project-URL: Issues, https://github.com/Ronaldoengenhariadacomputacao/autoq-qec/issues
+Project-URL: ORCID, https://orcid.org/0009-0006-7449-1190
+Keywords: quantum,qec,surface-code,fault-tolerant,qiskit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: qiskit>=1.0.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: ibm
+Requires-Dist: qiskit-ibm-runtime>=0.20; extra == "ibm"
+Provides-Extra: sim
+Requires-Dist: qiskit-aer>=0.14; extra == "sim"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# AutoQ QEC Estimator
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21327566.svg)](https://doi.org/10.5281/zenodo.21327566)
+
+**Multi-code fault-tolerant quantum error correction estimator for arbitrary Qiskit circuits.**
+
+Given any Qiskit circuit and a set of hardware profiles, AutoQ QEC returns a ranked comparison of QEC codes (Surface Code, Floquet Code, Bacon-Shor, Steane [[7,1,3]]) with physically grounded resource estimates: physical qubit count, execution time, and circuit fidelity.
+
+## What this does that nothing else does
+
+| Tool | Multi-code | Arbitrary circuit | Analytic model | Hardware-agnostic |
+|---|---|---|---|---|
+| Azure Resource Estimator | ❌ Surface Code only | ✅ | ✅ | ❌ Azure only |
+| stim | ✅ | ❌ needs rewrite | ❌ simulation | ❌ |
+| qiskit-qec | ✅ | ❌ no estimator | ❌ | ✅ |
+| **AutoQ QEC** | ✅ | ✅ | ✅ | ✅ |
+
+## Install
+
+```bash
+pip install autoq-qec
+# With IBM Quantum integration:
+pip install "autoq-qec[ibm,sim]"
+```
+
+## Quickstart
+
+```python
+from qiskit import QuantumCircuit
+from autoq_qec import compare, rank
+from autoq_qec import HARDWARE_PROFILES, CalibratedHardware, HardwareProfile
+
+# Any Qiskit circuit
+circuit = QuantumCircuit(4)
+circuit.h(0); circuit.cx(0,1); circuit.cx(1,2); circuit.cx(2,3)
+
+# Hardware profiles (built-in or custom)
+hardwares = [
+    HardwareProfile("IBM_Eagle",     t_gate_ns=391,   p_phys=0.0062, topology="heavy-hex"),
+    HardwareProfile("IBM_Heron",     t_gate_ns=100,   p_phys=0.003,  topology="heavy-hex"),
+    HardwareProfile("Quantinuum_H2", t_gate_ns=100e3, p_phys=0.00029,topology="all-to-all"),
+]
+
+# One call — returns all codes × all hardwares
+result = compare(circuit, hardwares, fidelity_target=0.99)
+
+# Pass hardware_calibrations to exclude combinations that violate T1
+# (t_circuit >= 0.5×T1) — matches by name or by (t_gate_ns, p_phys)
+recommendations = rank(result, hardware_calibrations=HARDWARE_PROFILES)
+
+for r in recommendations[:3]:
+    print(f"#{r.rank} {r.hardware} + {r.code}: "
+          f"{r.total_physical_qubits}q, {r.execution_time_us:.1f}µs, "
+          f"fidelity={r.fidelity_circuit:.4f}")
+```
+
+## With real IBM calibration data
+
+```python
+from autoq_qec.real_hardware import from_ibm_backend, noise_model_from_ibm
+
+# Pulls today's calibration — T1, T2, CX error per qubit pair
+hw = from_ibm_backend("ibm_brisbane", token="YOUR_IBM_TOKEN")
+
+# Simulate locally with real noise model (no queue, no cost)
+sim = noise_model_from_ibm("ibm_brisbane", token="YOUR_IBM_TOKEN")
+```
+
+## Physical models
+
+| Code | Model | Reference |
+|---|---|---|
+| Surface Code | $p_L \approx A(p/p_{th})^{(d+1)/2}$, $q=2d^2-1$, overhead $=d^3$ | Fowler et al., PRA 86, 032324 (2012) |
+| Floquet Code | $p_L \approx 0.07(p/p_{th})^{(d+1)/2}$, $q=4d^2+8(d-1)$, overhead $=\lfloor d/2\rfloor$ | Gidney & Fowler, arXiv:2202.11829 |
+| Bacon-Shor | $p_L \approx (p/p_{th})^d$, $q=d^2$ | Aliferis & Cross (2007) |
+| Steane [[7,1,3]] | $p_L \approx 21p^2$, $q=13$ | Steane, PRL 77, 793 (1996) |
+
+Thresholds are enforced: `p ≥ p_th` raises `ValueError` — no silent wrong results.
+
+## Algorithm Estimator
+
+Order-of-magnitude T-count estimates for known algorithms, without building the full circuit:
+
+```python
+from autoq_qec import AlgorithmEstimator
+
+est = AlgorithmEstimator.shor(2048)
+print(est.t_count_estimate, est.t_count_uncertainty)  # ±5x — build the real circuit for precise numbers
+```
+
+Covers `shor`, `grover`, `qft`, `vqe`. These are rough estimates (±2×–±10× depending on the algorithm) — use `extract_circuit_profile()` on a real circuit whenever possible.
+
+## Test
+
+```bash
+pytest tests/ -v   # 49 tests, all verify physics not arithmetic
+```
+
+## What the tests check (unlike most QEC tools)
+
+- `p ≥ threshold` raises `ValueError`, not wrong overhead
+- `d` is always odd for Surface Code (rotated lattice requirement)
+- `p_L ≤ p_L_target` guaranteed after distance selection
+- Noisier hardware requires larger `d` (monotonicity)
+- Circuit with 0 gates raises `ValueError` (destroyed by transpiler)
+- Fidelity scales correctly with `t_gate`
+
+## Author
+
+Ronaldo Rodrigues — ORCID: [0009-0006-7449-1190](https://orcid.org/0009-0006-7449-1190)

autoq_qec-0.2.1/README.md

@@ -0,0 +1,110 @@
+# AutoQ QEC Estimator
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21327566.svg)](https://doi.org/10.5281/zenodo.21327566)
+
+**Multi-code fault-tolerant quantum error correction estimator for arbitrary Qiskit circuits.**
+
+Given any Qiskit circuit and a set of hardware profiles, AutoQ QEC returns a ranked comparison of QEC codes (Surface Code, Floquet Code, Bacon-Shor, Steane [[7,1,3]]) with physically grounded resource estimates: physical qubit count, execution time, and circuit fidelity.
+
+## What this does that nothing else does
+
+| Tool | Multi-code | Arbitrary circuit | Analytic model | Hardware-agnostic |
+|---|---|---|---|---|
+| Azure Resource Estimator | ❌ Surface Code only | ✅ | ✅ | ❌ Azure only |
+| stim | ✅ | ❌ needs rewrite | ❌ simulation | ❌ |
+| qiskit-qec | ✅ | ❌ no estimator | ❌ | ✅ |
+| **AutoQ QEC** | ✅ | ✅ | ✅ | ✅ |
+
+## Install
+
+```bash
+pip install autoq-qec
+# With IBM Quantum integration:
+pip install "autoq-qec[ibm,sim]"
+```
+
+## Quickstart
+
+```python
+from qiskit import QuantumCircuit
+from autoq_qec import compare, rank
+from autoq_qec import HARDWARE_PROFILES, CalibratedHardware, HardwareProfile
+
+# Any Qiskit circuit
+circuit = QuantumCircuit(4)
+circuit.h(0); circuit.cx(0,1); circuit.cx(1,2); circuit.cx(2,3)
+
+# Hardware profiles (built-in or custom)
+hardwares = [
+    HardwareProfile("IBM_Eagle",     t_gate_ns=391,   p_phys=0.0062, topology="heavy-hex"),
+    HardwareProfile("IBM_Heron",     t_gate_ns=100,   p_phys=0.003,  topology="heavy-hex"),
+    HardwareProfile("Quantinuum_H2", t_gate_ns=100e3, p_phys=0.00029,topology="all-to-all"),
+]
+
+# One call — returns all codes × all hardwares
+result = compare(circuit, hardwares, fidelity_target=0.99)
+
+# Pass hardware_calibrations to exclude combinations that violate T1
+# (t_circuit >= 0.5×T1) — matches by name or by (t_gate_ns, p_phys)
+recommendations = rank(result, hardware_calibrations=HARDWARE_PROFILES)
+
+for r in recommendations[:3]:
+    print(f"#{r.rank} {r.hardware} + {r.code}: "
+          f"{r.total_physical_qubits}q, {r.execution_time_us:.1f}µs, "
+          f"fidelity={r.fidelity_circuit:.4f}")
+```
+
+## With real IBM calibration data
+
+```python
+from autoq_qec.real_hardware import from_ibm_backend, noise_model_from_ibm
+
+# Pulls today's calibration — T1, T2, CX error per qubit pair
+hw = from_ibm_backend("ibm_brisbane", token="YOUR_IBM_TOKEN")
+
+# Simulate locally with real noise model (no queue, no cost)
+sim = noise_model_from_ibm("ibm_brisbane", token="YOUR_IBM_TOKEN")
+```
+
+## Physical models
+
+| Code | Model | Reference |
+|---|---|---|
+| Surface Code | $p_L \approx A(p/p_{th})^{(d+1)/2}$, $q=2d^2-1$, overhead $=d^3$ | Fowler et al., PRA 86, 032324 (2012) |
+| Floquet Code | $p_L \approx 0.07(p/p_{th})^{(d+1)/2}$, $q=4d^2+8(d-1)$, overhead $=\lfloor d/2\rfloor$ | Gidney & Fowler, arXiv:2202.11829 |
+| Bacon-Shor | $p_L \approx (p/p_{th})^d$, $q=d^2$ | Aliferis & Cross (2007) |
+| Steane [[7,1,3]] | $p_L \approx 21p^2$, $q=13$ | Steane, PRL 77, 793 (1996) |
+
+Thresholds are enforced: `p ≥ p_th` raises `ValueError` — no silent wrong results.
+
+## Algorithm Estimator
+
+Order-of-magnitude T-count estimates for known algorithms, without building the full circuit:
+
+```python
+from autoq_qec import AlgorithmEstimator
+
+est = AlgorithmEstimator.shor(2048)
+print(est.t_count_estimate, est.t_count_uncertainty)  # ±5x — build the real circuit for precise numbers
+```
+
+Covers `shor`, `grover`, `qft`, `vqe`. These are rough estimates (±2×–±10× depending on the algorithm) — use `extract_circuit_profile()` on a real circuit whenever possible.
+
+## Test
+
+```bash
+pytest tests/ -v   # 49 tests, all verify physics not arithmetic
+```
+
+## What the tests check (unlike most QEC tools)
+
+- `p ≥ threshold` raises `ValueError`, not wrong overhead
+- `d` is always odd for Surface Code (rotated lattice requirement)
+- `p_L ≤ p_L_target` guaranteed after distance selection
+- Noisier hardware requires larger `d` (monotonicity)
+- Circuit with 0 gates raises `ValueError` (destroyed by transpiler)
+- Fidelity scales correctly with `t_gate`
+
+## Author
+
+Ronaldo Rodrigues — ORCID: [0009-0006-7449-1190](https://orcid.org/0009-0006-7449-1190)

autoq_qec-0.2.1/autoq_qec/__init__.py

@@ -0,0 +1,24 @@
+"""
+AutoQ QEC Estimator
+Multi-code fault-tolerant quantum error correction estimator.
+"""
+from .qec_estimator import (
+    CircuitProfile,
+    HardwareProfile,
+    CodeResult,
+    extract_circuit_profile,
+    estimate,
+    compare,
+)
+from .real_hardware import CalibratedHardware, HARDWARE_PROFILES
+from .recommender import rank, Recommendation
+from .algorithm_estimator import AlgorithmEstimator, AlgorithmEstimate
+
+__version__ = "0.2.1"
+__all__ = [
+    "CircuitProfile", "HardwareProfile", "CodeResult",
+    "CalibratedHardware", "HARDWARE_PROFILES",
+    "Recommendation",
+    "AlgorithmEstimator", "AlgorithmEstimate",
+    "extract_circuit_profile", "estimate", "compare", "rank",
+]

autoq_qec-0.2.1/autoq_qec/algorithm_estimator.py

@@ -0,0 +1,101 @@
+"""
+AutoQ QEC — Algorithm Estimator
+Estimativas analíticas de T-count para algoritmos quânticos conhecidos.
+ATENÇÃO: estimativas de ordem de grandeza. Usar circuito real quando possível.
+"""
+import math
+from dataclasses import dataclass
+
+
+@dataclass
+class AlgorithmEstimate:
+    algorithm: str
+    n_logical_qubits: int
+    t_count_estimate: int
+    t_count_uncertainty: str   # "±5×" ou "±2×"
+    source: str
+    notes: str
+
+
+class AlgorithmEstimator:
+
+    @staticmethod
+    def shor(N: int) -> AlgorithmEstimate:
+        """
+        Shor factoring de N.
+        T-count ≈ 20n³ onde n = ⌈log₂N⌉.
+        Fonte: Beauregard (2003) + síntese de portas fault-tolerant.
+        Incerteza: ±5× dependendo da implementação de aritmética modular
+        (verificado contra Shor N=15 real: fórmula subestima ~4,7×).
+        """
+        if N <= 2:
+            raise ValueError(
+                f"Shor requer N > 2 (N={N} não tem fatoração não-trivial a estimar)"
+            )
+        n = math.ceil(math.log2(N))
+        t_count = 20 * n**3
+        return AlgorithmEstimate(
+            algorithm=f"Shor N={N}",
+            n_logical_qubits=2*n + 3,
+            t_count_estimate=t_count,
+            t_count_uncertainty="±5×",
+            source="Beauregard, QIC 3:175 (2003); Fowler gate synthesis",
+            notes=f"n={n} bits. Implementações simples podem ter até 5× mais T-gates.",
+        )
+
+    @staticmethod
+    def grover(N: int) -> AlgorithmEstimate:
+        """
+        Grover search em N itens.
+        T-count ≈ 7n por iteração × ⌈π/4·√N⌉ iterações, com n=⌈log₂N⌉.
+        Nota: como n cresce com log₂N, o T-count total escala com √N·log₂N,
+        não apenas √N — o fator log₂N vem do custo do oracle genérico por
+        iteração, não só do número de iterações.
+        Fonte: estimativa com oracle genérico.
+        """
+        if N <= 1:
+            raise ValueError(f"Grover requer N > 1 itens de busca (N={N})")
+        n = math.ceil(math.log2(N))
+        iterations = math.ceil(math.pi/4 * math.sqrt(N))
+        t_per_iter = 7 * n
+        t_count = t_per_iter * iterations
+        return AlgorithmEstimate(
+            algorithm=f"Grover N={N}",
+            n_logical_qubits=n + 1,
+            t_count_estimate=t_count,
+            t_count_uncertainty="±10×",
+            source="Estimativa com oracle genérico de n T-gates",
+            notes="Depende fortemente do oracle. Incerteza alta sem oracle específico.",
+        )
+
+    @staticmethod
+    def qft(n: int) -> AlgorithmEstimate:
+        """
+        QFT em n qubits.
+        T-count ≈ n²/2 (rotações CP com síntese Solovay-Kitaev).
+        """
+        t_count = n*n // 2
+        return AlgorithmEstimate(
+            algorithm=f"QFT n={n}",
+            n_logical_qubits=n,
+            t_count_estimate=t_count,
+            t_count_uncertainty="±2×",
+            source="Rotações CP decompostas em Clifford+T",
+            notes="CP(π/2^k) para k>2 requer síntese com T-gates.",
+        )
+
+    @staticmethod
+    def vqe(n_qubits: int, depth: int) -> AlgorithmEstimate:
+        """
+        VQE com n_qubits e profundidade depth.
+        T-count ≈ 4 · n · depth (Trotterizado).
+        """
+        t_count = 4 * n_qubits * depth
+        return AlgorithmEstimate(
+            algorithm=f"VQE n={n_qubits} d={depth}",
+            n_logical_qubits=n_qubits,
+            t_count_estimate=t_count,
+            t_count_uncertainty="±3×",
+            source="Hamiltoniano Trotterizado com RZZ gates",
+            notes="Depende do Hamiltoniano. Incerteza moderada.",
+        )