🌀 Quantum Virtual Machine (QVM) Knowledge Vault

Welcome to the central knowledge vault for the Quantum Virtual Machine (QVM), a hardware-agnostic quantum execution runtime designed under the "Write Once, Run Anywhere" (WORA) philosophy.

This Obsidian vault maps out the core compiler components, parser engines, topological mapping transpilers, simulation engines (Statevector and Matrix Product State), noise models, variational quantum algorithms, and API layers that power the system.

🗺️ Navigation Map of Content (MoC)

Select a node to dive into the technical specifications and mathematical definitions:

Rendering diagram...

🏢 1. System Design & Intermediate Representation

System Architecture: The high-level architectural pipeline, decoupling layers, and external library interfaces (Qiskit, Cirq).
Intermediate Representation: The central data container (QuantumCircuit), parameter bindings (Parameter, ParameterExpression), and JSON/OpenQASM serialization definitions.

📡 2. Input Ingestion & Compiler Frontend

OpenQASM3 Parsing and AST: Lark grammar parser specifications (qasm3.lark), AST processing, and translation of classical flow statements (while/for loops, conditional branches).

⚙️ 3. Transpilation & Topology Routing

Transpilation and Routing: Graph connectivity constraints (TargetArchitecture), pathfinding mapping, and comparative analysis of Greedy (BFS) routing versus SABRE lookahead heuristics.
Gate Decomposition: Decomposing non-native gates (e.g. Toffoli/CCX) into hardware-primitive basis sets (id, rz, sx, x, cx).

🧮 4. Execution Engines (Simulators)

Exact Statevector Simulation: Exact statevector linear algebra operations, Kronecker tensor-product construction, vectorized index permutation maps for multi-qubit gates, projective measurement, and classical register updates.
Matrix Product State Simulation: 1D Tensor Network simulator using Matrix Product State chains of 3-rank tensors, SVD-based bond-dimension truncation, local gate contraction, and measurement collapse.

🌡️ 5. Noise & Quantum Hardware Profiling

Noise and Hardware Profiles: Composable noise system using Monte Carlo Kraus trajectories, thermal relaxation models ( $T_1, T_2$ ), readout confusion matrices, and physical hardware profiles (IBM Manila/Lagos).

🧬 6. Variational & Application Layers

Variational Quantum Algorithms: Variational Quantum Eigensolver (VQE) and Quantum Approximate Optimization Algorithm (QAOA) implementations, analytical gradients (Parameter Shift Rule), and scipy minimizer configurations.
Tutorial 1: Quantum Circuit Basics: Qubits, superposition, gates ( $X, H, R_y$ ), projective measurement, and REST API calls.
Tutorial 2: Quantum Entanglement: Bell state $|\Phi^+\rangle$ , CNOT correlations, exact state evolution, and Qiskit/Cirq export.
Tutorial 3: Grover's Search Algorithm: 3-qubit unstructured search marking $|101\rangle$ , phase oracle, diffusion operator, and probability amplification.
Tutorial 4: Quantum Teleportation: Dynamic circuits in OpenQASM 3: 3-qubit protocol, mid-circuit measurement, and classical conditional corrections.
Tutorial 5: Variational Quantum Eigensolver: $\text{H}_2$ ground-state energy in STO-3G, parameterized ansatz, Pauli expectation values, and classical optimization.

🌐 7. Web API & Developer Services

Web API and Dashboard: FastAPI endpoint specification, request/response payload structures, CLI mapping, and the interactive dashboard user interface.
REST API Reference: /run: Complete reference for /run, Pydantic schemas, validation rules, status codes, curl, and Python requests examples.

🚀 Architectural Pipeline Flow

Every circuit executed in the QVM moves linearly through the following transformation pipeline:

Rendering diagram...