Architecture¶

MicroQuantum is deliberately layered so each level depends only on the levels below it:

Experiments / Analysis
         │
Runtime / Backends / Providers
         │
Algorithms
         │
Problems
         │
Core engine (circuits · operators · states · IR · transpiler)
         │
      NumPy

Source layout¶

src/microquantum/
├── __init__.py          public package surface (numpy-only)
├── core/                circuits, operators, pauli, states, measurement,
│                        parameters, gradients, registers, qasm, IR input,
│                        transpiler passes, dynamic circuits, device/target
├── ir/                  intermediate representation & compiler
├── backends/            backend contract, capabilities, registry,
│                        provider, adapters + local simulators
├── runtime/             ExecutionPlan, ExecutionRuntime, strategies
├── problems/            Sampling / Optimization / Hamiltonian /
│                        Eigenvalue / Search
├── algorithms/          VQE, QAOA, Grover, QPE, QFT, HHL, walks, ...
├── optimizers/          classical optimizers (NumPy-only)
├── experiments/         records, sweeps, experiments (MQ-07)
├── analysis/            sampling / expectation / state / aggregation
├── optimization/        QUBO builder, Ising converter
├── providers/           optional vendor boundary (never imported by SDK)
├── adapters/            domain adapters (QuantumProblem/QuantumResult)
├── qml/ qec/ chemistry/ benchmarks/ mitigation/   feature libraries
├── analytics/           CSV loaders & base analytics
└── stdlib/              system standard library: bits · numbers · states
                         (canonical home for shared utilities)

See Package Ecosystem for the canonical import map of the nine conceptual boundaries (core / circuit / gates / states / measurement / compiler / runtime / backends / stdlib).

Layering rules¶

Independent implementation — all quantum operations are implemented from scratch with NumPy; no Qiskit/Cirq/OpenQASM dependency.
Layer separation — analytics never touch raw matrices; problems never execute; backends never re-implement simulation logic.
Big-endian qubit ordering — qubit 0 is most-significant; tensor axis 0 = qubit 0 (the mathematical convention).
Standardized results — every successful run funnels into a typed, JSON-serializable result.
Public surface only — __init__.py is the friendly gateway; internal helpers stay private.
NumPy-only runtime — GPU acceleration is opt-in at the array layer (set_array_backend()).

Execution flow¶

Problem -> Algorithm -> ExecutionPlan -> (compile?) -> Backend
                                                     -> Job -> BackendResult
     ExecutionRecord (one per run) -> ExperimentResult -> Analysis

The runtime and backend layers never re-implement simulation; a user-provided Backend drops in through a plan’s backend field.