# qbraid/qbraid architecture

> Architecture diagram of the GitHub repository qbraid/qbraid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qbraid/qbraid
- Repository: https://github.com/qbraid/qbraid

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External user
    User["User Code / CLI"]:::external

    %% Core SDK Modules
    subgraph "Core SDK Modules"
        direction TB
        Interface["Interface Module"]:::core
        Registry["QPROGRAM_REGISTRY"]:::plugin
        Interface --> Registry

        Transpiler["Transpiler Module"]:::core
        Graph["ConversionGraph"]:::plugin
        Converter["Converter"]:::plugin
        Edge["Edge & Scheme"]:::plugin
        ConvImpl["Conversions (rustworkx)"]:::plugin
        Transpiler --> Graph
        Transpiler --> Converter
        Transpiler --> Edge
        Transpiler --> ConvImpl

        Programs["Programs & Passes"]:::core
        ProgAbs["Program & ExperimentType"]:::plugin
        Loaders["Loaders & Registry"]:::plugin
        Impl["Gate-model & Annealing"]:::plugin
        Passes["QASM Passes"]:::plugin
        Programs --> ProgAbs
        Programs --> Loaders
        Programs --> Impl
        Programs --> Passes

        Runtime["Runtime Module"]:::core
        ProvAbs["Provider & Device"]:::plugin
        AWS["AWS Braket Provider"]:::plugin
        IBM["IBM QiskitRuntime Provider"]:::plugin
        IonQ["IonQ Provider"]:::plugin
        Azure["Azure Quantum Provider"]:::plugin
        OQC["OQC Provider"]:::plugin
        Native["Native Simulator"]:::plugin
        JobRes["Job & Result Builders"]:::plugin
        Runtime --> ProvAbs
        ProvAbs --> AWS
        ProvAbs --> IBM
        ProvAbs --> IonQ
        ProvAbs --> Azure
        ProvAbs --> OQC
        ProvAbs --> Native
        Runtime --> JobRes

        Visualization["Visualization Module"]:::core
        Draw["Circuit Drawing"]:::plugin
        Plot["Histogram & Plots"]:::plugin
        Flair["Flair Animations"]:::plugin
        Visualization --> Draw
        Visualization --> Plot
        Visualization --> Flair
    end

    %% External Backends
    subgraph "External Backends"
        direction TB
        QbraidService["qBraid Service"]:::external
        AWSBackend["AWS Braket"]:::external
        IBMBackend["IBM QiskitRuntime"]:::external
        IonQBackend["IonQ / Azure / …"]:::external
        Simulator["Native Simulator"]:::external
    end

    %% Data flow
    User -->|"calls API"| Interface
    Interface -->|"identify type"| Transpiler
    Transpiler -->|"transpile()"| Programs
    Programs -->|"run()"| Runtime
    Runtime -->|"submit jobs"| AWSBackend
    Runtime -->|"submit jobs"| IBMBackend
    Runtime -->|"submit jobs"| IonQBackend
    Runtime -->|"submit jobs"| Simulator
    AWSBackend -->|"result()"| Runtime
    IBMBackend -->|"result()"| Runtime
    IonQBackend -->|"result()"| Runtime
    Simulator -->|"result()"| Runtime
    Runtime -->|"build results"| Visualization
    Visualization -->|"display results"| User

    %% Click Events
    click Interface "https://github.com/qbraid/qbraid/tree/main/qbraid/interface/"
    click Registry "https://github.com/qbraid/qbraid/tree/main/qbraid/interface/"
    click Transpiler "https://github.com/qbraid/qbraid/tree/main/qbraid/transpiler/"
    click Graph "https://github.com/qbraid/qbraid/blob/main/qbraid/transpiler/graph.py"
    click Converter "https://github.com/qbraid/qbraid/blob/main/qbraid/transpiler/converter.py"
    click Edge "https://github.com/qbraid/qbraid/blob/main/qbraid/transpiler/edge.py"
    click ConvImpl "https://github.com/qbraid/qbraid/tree/main/qbraid/transpiler/conversions/"
    click Programs "https://github.com/qbraid/qbraid/blob/main/qbraid/programs/program.py"
    click ProgAbs "https://github.com/qbraid/qbraid/blob/main/qbraid/programs/program.py"
    click Loaders "https://github.com/qbraid/qbraid/blob/main/qbraid/programs/registry.py"
    click Impl "https://github.com/qbraid/qbraid/tree/main/qbraid/programs/gate_model/"
    click Passes "https://github.com/qbraid/qbraid/blob/main/qbraid/passes/qasm/compat.py"
    click Runtime "https://github.com/qbraid/qbraid/tree/main/qbraid/runtime/"
    click ProvAbs "https://github.com/qbraid/qbraid/blob/main/qbraid/runtime/provider.py"
    click AWS "https://github.com/qbraid/qbraid/blob/main/qbraid/runtime/aws/provider.py"
    click IBM "https://github.com/qbraid/qbraid/blob/main/qbraid/runtime/ibm/provider.py"
    click IonQ "https://github.com/qbraid/qbraid/blob/main/qbraid/runtime/ionq/provider.py"
    click Azure "https://github.com/qbraid/qbraid/blob/main/qbraid/runtime/azure/provider.py"
    click OQC "https://github.com/qbraid/qbraid/blob/main/qbraid/runtime/oqc/provider.py"
    click Native "https://github.com/qbraid/qbraid/blob/main/qbraid/runtime/native/provider.py"
    click JobRes "https://github.com/qbraid/qbraid/blob/main/qbraid/runtime/job.py"
    click Visualization "https://github.com/qbraid/qbraid/tree/main/qbraid/visualization/"
    click Draw "https://github.com/qbraid/qbraid/blob/main/qbraid/visualization/draw_circuit.py"
    click Plot "https://github.com/qbraid/qbraid/blob/main/qbraid/visualization/plot_counts.py"
    click Flair "https://github.com/qbraid/qbraid/blob/main/qbraid/visualization/flair_animations.py"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6,stroke-width:2px;
    classDef plugin fill:#E6F4EA,stroke:#28a745,stroke-width:2px,stroke-dasharray: 5 2;
    classDef external fill:#FFEFD5,stroke:#d97706,stroke-width:2px;
```
