Quanta SDK — Architecture (v1.2.0-production)¶

Overview¶

Quanta SDK is a standalone quantum software architecture engineered for 2026 quantum computing frontiers, structured across 5 Core Scientific Paradigms. The framework pairs a zero-dependency Python/NumPy core with Apple Silicon Metal GPU acceleration, analytical Daleckii-Krein Hilbert gradients, and dual-track fault-tolerant quantum error correction (FTQC).

Layered Architecture Diagram¶

+---------------------------------------------------------------------------------+
|                       LAYER 4: AGENTIC & MCP ORCHESTRATION                      |
|  23 Model Context Protocol (MCP) Tools | Claude, Gemini, GPT Autonomous Agents  |
|  "Governing end-to-end quantum workflows via natural language and agentic loops"|
+---------------------------------------------------------------------------------+
|               LAYER 3: DEEP LEARNING & DECLARATIVE COGNITIVE API                |
|  quanta.torch: QuantumLayer | Daleckii-Krein Autograd | Lie Algebra Barren Tool |
|  BiomorphicResonantBrain | SWR Replay | ContinuousResonator (Schrödinger Flow)  |
|  search() | optimize() | vqe() | factor() | portfolio_optimize() | resolve()    |
|  "What to solve?" -- high-level algorithmic execution without manual gate design|
+---------------------------------------------------------------------------------+
|                       LAYER 2: ALGORITHMIC CIRCUIT DSL                          |
|  @circuit | 31 Native Gates (IBM Heron, Google Sycamore, IonQ native parity)    |
|  Parametric Rotations (RX, RY, RZ, P, U) | measure() | sweep() | equivalence    |
|  "How to construct the quantum circuit?"                                        |
+---------------------------------------------------------------------------------+
|             LAYER 1: 2026 DUAL-TRACK FAULT-TOLERANCE (FTQC ENGINE)              |
|  Track A: Edmonds Blossom MWPM | Willow-Compliant 3D Spacetime Syndrome Cycles  |
|  Track B: Gross [[144, 12, 12]] qLDPC | Native Normalized Min-Sum BP-OSD-0      |
|  Non-Clifford: 15-to-1 Bravyi-Kitaev Magic State Distillation | Lattice Surgery  |
+---------------------------------------------------------------------------------+
|                 LAYER 0: PHYSICAL COMPUTATION & HARDWARE BACKENDS               |
|  DAG Circuit (Kahn) | Compiler Pipeline (CancelInverses, MergeRotations, Route) |
|  Metal/MLX Zero-Copy GPU (52.09x) | SIMD Clifford (>3.13M g/s) | MPS (250q)     |
|  7-Channel Kraus Lindblad Noise | Multi-Cloud (IBM REST, Google Cirq, IonQ)     |
|  "How to execute on physical hardware and high-performance simulators?"         |
+---------------------------------------------------------------------------------+

Dependency Graph¶

mcp_server.py ──┐
                ▼
      quanta.torch / layer3/ ───────► simulator/ ───────► core/
                 │                        │                 ▲
                 ▼                        ▼                 │
             qec/ (FTQC) ────────────► dag/ ────────────────┘
                 │                        ▲
                 ▼                        │
            compiler/ ────────────────────┘
                 │
                 ▼
         backends/ & export/

Rule: Dependencies always flow downward and inward toward the standalone core (core/). No lower layer depends on an upper layer.

Module Details¶

core/ -- Building Blocks¶

File	Responsibility
`types.py`	QubitRef, Instruction, QubitRegister
`gates.py`	31 gates + broadcast (IBM Heron parity)
`circuit.py`	@circuit decorator, CircuitBuilder
`measure.py`	Flexible measurement (full, partial)
`equivalence.py`	Unitary comparison, fidelity
`custom_gate.py`	User-defined unitary gates

dag/ -- Directed Acyclic Graph¶

File	Responsibility
`node.py`	InputNode, OpNode, OutputNode (immutable)
`dag_circuit.py`	Topological sort (Kahn's), depth, parallel layers

compiler/ -- Optimization Pipeline¶

File	Responsibility
`pipeline.py`	CompilerPass Protocol, chaining, statistics
`passes/optimize.py`	CancelInverses (H.H=I), MergeRotations
`passes/translate.py`	IBM/Google/Quantinuum gate set transpilation
`passes/routing.py`	Topology-aware SWAP insertion (linear/ring/grid)

simulator/ -- Simulation Engines¶

File	Responsibility
`base.py`	`SimulatorBackend` ABC — abstract interface for all simulators
`statevector.py`	Dense tensor contraction, up to 27 qubits (exact), `apply_phase()` + `apply_noise()`
`sparse.py`	Dict-based sparse statevector, up to 50 qubits, O(k) memory
`mps.py`	Matrix Product State (SVD), 200+ qubits, O(n·χ²) memory
`factory.py`	`create_simulator()` — auto-selects best backend
`router.py`	Circuit-aware routing (Clifford detection, qubit count)
`density_matrix.py`	Mixed states + Kraus noise channels, up to 13 qubits
`pauli_frame.py`	Aaronson-Gottesman stabilizer tableau, 50-qubit GHZ in <5s
`noise.py`	7 noise channels: Depolarizing, BitFlip, PhaseFlip, AmplitudeDamping, T2Relaxation, Crosstalk, ReadoutError
`accelerated.py`	JAX-GPU / CuPy auto-detection, NumPy fallback

layer3/ -- Declarative API¶

File	Responsibility
`search.py`	Auto Grover search
`optimize.py`	QAOA optimization
`agent.py`	Multi-agent decision modeling
`vqe.py`	Variational Quantum Eigensolver
`shor.py`	Integer factoring (period finding + QFT)
`qsvm.py`	Quantum kernel SVM classification
`finance.py`	Portfolio optimization (Markowitz + QAOA)
`hamiltonian.py`	Trotterized time evolution, molecular Hamiltonians
`entity_resolution.py`	QAOA-based customer deduplication
`monte_carlo.py`	Quantum Monte Carlo, amplitude estimation, option pricing
`clustering.py`	Quantum swap-test distances + k-means clustering
`qml.py`	Quantum ML: variational classifier, quantum kernel, feature maps

export/ -- QASM I/O¶

File	Responsibility
`qasm.py`	OpenQASM 3.0 export
`qasm_import.py`	QASM 2.0/3.0 import to DAG

qec/ -- 2026 Dual-Track Fault-Tolerance (FTQC)¶

File	Responsibility
`codes.py`	BitFlip [[3,1,3]], PhaseFlip [[3,1,3]], Steane [[7,1,3]]
`surface_code.py`	Rotated Surface Code [[d^2,1,d]], 3D spacetime syndrome extraction
`color_code.py`	2D Triangular Color Code, transversal Clifford, restriction decoder
`decoder.py`	Edmonds Blossom MWPM (full-weight perfect matching) and Union-Find
`qldpc.py`	Gross [[144, 12, 12]] Bivariate Bicycle code, Normalized Min-Sum BP-OSD-0
`distillation.py`	15-to-1 Bravyi-Kitaev magic state distillation factory, lattice surgery

quanta.torch / cognitive/ -- Deep Learning & Biomorphic Quantum Engine¶

Module / File	Responsibility
`quanta.torch.QuantumLayer`	PyTorch nn.Module layer with analytical parameter-shift autograd VJP
`quanta.torch.ContinuousResonator`	Continuous-time Schrödinger evolution, Daleckii-Krein Fréchet derivatives
`quanta.torch.BiomorphicResonantBrain`	Dual-hemisphere quantum brain with 4 neuromodulators (DA, ACh, 5-HT, NE)
`quanta.torch.lie_algebra`	Dynamical Lie algebra dim(g) dimension and analytical barren plateau tool
`quanta.cognitive`	SWR memory consolidation, REM sleep continual replay, CSF phase shield

benchmark/ -- Quality Benchmarking & Empirical Verification¶

File	Responsibility
`qasmbench.py`	10 standard + 3 large QASMBench circuits
`benchpress_adapter.py`	Cross-SDK benchmarking API (Nation et al.)
`run_paper_benchmarks.py`	Peer-reviewed empirical microsecond benchmarks

Support Modules¶

File	Responsibility
`runner.py`	6-stage orchestrator: build > DAG > compile > sim > noise > sample > result
`result.py`	Measurement results, probabilities, Dirac notation, statevector
`visualize.py`	ASCII and SVG circuit diagrams
`visualize_state.py`	Probability histogram, Bloch sphere, phase diagram
`mcp_server.py`	MCP server — 23 quantum tools for autonomous AI assistants (SSE + stdio)

Data Flow¶

User Code / Autonomous AI Agent (MCP)
          │
          ▼
   @circuit / layer3 / quanta.torch
          │
          ▼
   DAGCircuit (Kahn topological sort)
          │
          ▼
   CompilerPipeline (CancelInverses, MergeRotations, Routing)
          │
          ▼
   QEC Fault-Tolerance Shield (Edmonds Blossom MWPM / Gross qLDPC BP-OSD)
          │
          ▼
   Execution Backend (Metal/MLX, StateVector, Clifford SIMD, MPS, or IBM/Google/IonQ Hardware)
          │
          ▼
   Result (Measurement counts, statevector, analytical gradients, syndrome logs)

Architectural Design Principles¶

Standalone First-Principles Core: Full quantum execution capability in pure Python/NumPy without requiring heavy C++/LLVM toolchains or CUDA runtimes.
Apple Silicon Zero-Copy GPU Acceleration: Metal Performance Shaders / MLX zero-copy Unified Memory tensor pipeline yielding up to 52.09× peak speedup.
Continuous Hilbert Gradients: Analytical closed-form Daleckii-Krein Fréchet derivatives maintaining exact machine precision (\(9.99\times 10^{-16}\)) with Lie algebra barren plateau guarantees.
2026 Dual-Track FTQC: Full Edmonds Blossom MWPM on 2D surface codes and high-rate canonical Gross \([[144, 12, 12]]\) qLDPC with native BP-OSD-0, slashing physical qubit overhead by \(12\times\).
AI-Native MCP Orchestration: 23 native Model Context Protocol tools enabling Claude, GPT, and Gemini agents to autonomously design, simulate, transpile, and verify quantum workloads.
Falsifiable Empiricism & Certified Rigor: 2,076 fully automated tests with zero mock or synthetic oracles, certifying mathematical unitarity and CPTP trace preservation.

Authorship & Identity Metadata¶

Lead Author & Principal Architect: Abdullah Enes SARI (ORCID: 0000-0002-8827-0587)
Affiliation: ONMARTECH Quantum Computing Initiative (info@onmartech.com)
Permanent Software DOI: GitHub Release v1.2.0