How qbraid/qbraid works
Project Type and Purpose
• qBraid-SDK is a Python-based, platform-agnostic quantum runtime framework (an open-source SDK/library).
• It streamlines end-to-end quantum job management: from program specification through transpilation, submission to quantum backends (cloud QPUs and simulators), to post-processing and visualization.
• It exposes plugin points for registering new program types, conversions, and providers.
High-Level Architecture Overview
┌──────────────────────┐
│ 1. User Code / CLI │
└──────────────────────┘
↓ calls API
┌──────────────────────┐
│ 2. Core SDK Modules │
│ • interface │
│ • transpiler │
│ • programs & passes│
│ • runtime │
│ • visualization │
└──────────────────────┘
↓ interacts
┌──────────────────────┐
│ 3. External Backends │
│ • qBraid Service │
│ • AWS Braket │
│ • IBM QiskitRuntime │
│ • IonQ / Azure / … │
│ • Native Simulator │
└──────────────────────┘
Main Components & Their Relationships
a. Interface Module (qbraid.interface)
• QPROGRAM_REGISTRY: maps identifiers (e.g., “qiskit”, “cirq”) → program types.
• Entry points for defining new program types and conversions.
• Exception and logging utilities.
b. Transpiler Module (qbraid.transpiler)
• ConversionGraph: directed graph of Conversion edges (source → target).
• Converter: finds shortest path and applies conversion functions.
• Graph, Edge, Scheme abstractions.
c. Programs & Passes (qbraid.programs, qbraid.passes)
• Core Program abstraction (Program, ExperimentType).
• Type registry, loaders, gate-model & annealing model implementations.
• Passes for QASM compatibility, decomposition, validation.
d. Runtime Module (qbraid.runtime)
• Provider & Device abstractions.
• Concrete providers: QbraidProvider, BraketProvider, QiskitRuntimeProvider, IonQProvider, AzureQuantumProvider, OQCProvider, NativeProvider.
• Job submission, result building, polling/tracking.
• Schemas for validation, options management, noise modeling.
e. Visualization Module (qbraid.visualization)
• Circuit drawing, histogram & distribution plotting, flair animations.
f. Bin Scripts & CLI (bin/)
• Version bumping, dev build scripts, submodule syncing.
g. Docs & Tests (docs/, tests/)
• Sphinx docs, API references, usage examples; comprehensive unit and integration tests.
Data Flow & Interactions
1) User code/CLI calls qbraid.SDK API →
2) Interface module identifies program type via QPROGRAM_REGISTRY →
3) Transpiler constructs ConversionGraph (rustworkx) →
4) Converter transpiles program to target IR →
5) Runtime module’s Provider discovers Devices →
6) Device.run(submitted programs, shots) →
7) Job objects created, submitted to external API →
8) Polling/tracking remote job status →
9) ResultBuilder converts raw response →
10) SDK returns Result objects →
11) Visualization module plots results.
Architectural Patterns & Principles
• Plugin/Registry pattern: dynamic registration of program types, conversions, providers.
• Graph-based routing: ConversionGraph for planning transpilation path.
• Provider/Strategy pattern: abstract Device interface with multiple backends.
• Modular pipeline: clear separation into interface, transpiler, runtime, visualization.
• Dependency inversion: core modules depend on abstractions, not concrete backends.