# qm-labs/qm-qua-sdk-public architecture

> Architecture diagram of the GitHub repository qm-labs/qm-qua-sdk-public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qm-labs/qm-qua-sdk-public
- Repository: https://github.com/qm-labs/qm-qua-sdk-public

## Overview

1. **What this repo is**
   - `qm-qua` is a Python SDK for Quantum Machines’ OPX/QOP stack.
   - It serves two main roles: a Pythonic DSL for writing QUA programs, and a client layer for submitting, running, simulating, and monitoring those programs on external Quantum Machines services/hardware.

2. **Public package boundary**
   - The top-level `qm` package exposes the main user-facing objects such as the quantum machine manager and quantum machine abstractions.
   - Everything else is organized as supporting layers: language construction, program conversion, API clients, job/result handling, simulation, and Octave integration.

3. **QUA language layer**
   - `qm/qua` is the DSL implementation.
   - It contains scope management, expression handling, type hints, variable handling, pulses/waits/play/measure primitives, stream processing, and iterator extensions.
   - This layer is where users build a QUA program in Python before it is serialized or submitted.

4. **Program construction and serialization**
   - `qm/program` and `qm/serialization` are the bridge from Python DSL objects to backend-facing program/config representations.
   - The program layer validates and normalizes configuration data, fills defaults, and converts dict-based configs into protobuf-friendly structures.
   - The serialization layer walks QUA AST-like structures and emits the script/protocol payloads expected by the backend.

5. **Configuration and element modeling**
   - `qm/elements`, `qm/elements_db.py`, and `qm/containers` model hardware elements, inputs/outputs, and capability metadata.
   - `qm/type_hinting` and `qm/utils/config_utils.py` support structured config objects and validation.
   - This is the boundary where user configuration is turned into a machine-usable description of channels, pulses, mixers, oscillators, and integrations.

6. **Backend API layer**
   - `qm/api` contains the client APIs for talking to QOP-related services.
   - It includes frontend, info, job manager, job result, simulation, server detection, and model classes.
   - `qm/api/v2` is a newer API surface with job APIs, job-result APIs, and QMM/QM clients; `qm/api/stubs` and `qm/api/models` support compatibility and structured transport data.
   - The repo clearly separates transport/API concerns from the DSL and business logic.

7. **Job lifecycle and execution tracking**
   - `qm/jobs` models job states and transitions: pending, running, simulated, queueing, and deprecated/legacy queue paths.
   - This layer sits between “submitted program” and “live execution,” and it abstracts over old and new API behaviors.
   - Job objects likely own metadata, identifiers, execution state, and access to results.

8. **Live result streaming**
   - `qm/_stream_results` manages streaming result retrieval, including single-stream and multi-stream fetchers plus a streams manager.
   - This is the data plane for incremental measurement results rather than only final outputs.
   - The design suggests asynchronous or chunked consumption from backend result channels, with utility code for coordinating multiple streams.

9. **Simulation path**
   - `qm/simulate` provides simulation interfaces, loopback support, raw simulation, and credentials.
   - `qm/results/simulator_samples.py` and the simulated job APIs connect simulated execution to the same job/result abstractions used by real hardware runs.
   - This keeps simulation close to production semantics while still being a separate execution path.

10. **Octave subsystem**
   - `qm/octave` and `qm/octave_sdk` are dedicated to Octave hardware integration and calibration workflows.
   - They include Octave client communication, connectivity, health monitoring, conflict management, calibration DB/configuration, and mixer calibration utilities.
   - Architecturally, this is a distinct hardware-control boundary used to configure and maintain RF/control hardware alongside the OPX workflow.

11. **Operational and support utilities**
   - `qm/logger.py`, `qm/logging_utils.py`, `qm/datadog_api.py`, and `qm/persistence.py` support observability and state persistence.
   - `qm/exceptions.py`, `qm/utils`, and `qm/type_hinting` provide shared error handling, helpers, and typing support.
   - `qm/waveform_report` and `qm/results` provide reporting/inspection utilities for generated waveforms and simulation samples.

12. **Overall data flow**
   - Typical flow: user writes QUA in `qm/qua` → program/config are validated and serialized → API clients submit to QOP/OPX services → job objects track execution → result streams are consumed through `_stream_results` → optional waveform/reporting tools render outputs.
   - Simulation and Octave calibration are parallel subsystems that feed into the same program/job execution boundary, but they interact with different external services/hardware.

Main entry points: [`qm/api/v2`](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/api/v2) (API v2), [`qm/qua`](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/qua) (QUA DSL), [`qm/program`](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/program) (Program build), [`qm/utils`](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/utils) (Utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_dsl["QUA DSL"]
  node_qua_dsl["QUA DSL<br/>language layer"]
  node_qua_scope["Scopes<br/>scope mgmt"]
  node_qua_expr["Expressions<br/>expr model<br/>[_expressions.py]"]
  node_qua_ops["Primitives<br/>QUA ops"]
  node_qua_streams["Streams<br/>stream DSL"]
end

subgraph group_group_build["Program build"]
  node_program_build["Program build<br/>config bridge"]
  node_config_validate["Validate config<br/>schema validation"]
  node_config_convert["Config convert<br/>dict->pb"]
  node_serialization["Serialize<br/>script emit"]
end

subgraph group_group_runtime["Runtime APIs"]
  node_api_v2["API v2<br/>client surface"]
  node_api_legacy["API v1<br/>compat client"]
  node_jobs["Jobs<br/>lifecycle model"]
  node_stream_results["Result streams<br/>streaming I/O"]
  node_simulation["Simulation<br/>sim path"]
end

subgraph group_group_hw["Hardware integration"]
  node_octave["Octave<br/>hardware control"]
  node_octave_sdk["Octave SDK<br/>device client"]
end

subgraph group_group_support["Support"]
  node_results["Results<br/>reporting"]
  node_utils["Utils<br/>shared helpers"]
end

node_qm_public["qm<br/>public package<br/>[__init__.py]"]
node_quantum_machine["Quantum machine<br/>runtime object<br/>[QuantumMachine.py]"]
node_qmm["Manager<br/>entrypoint"]

node_qm_public -->|"exposes"| node_qmm
node_qm_public -->|"exposes"| node_quantum_machine
node_qmm -->|"uses"| node_api_v2
node_quantum_machine -->|"uses"| node_api_v2
node_qua_dsl -->|"depends on"| node_qua_scope
node_qua_dsl -->|"depends on"| node_qua_expr
node_qua_dsl -->|"contains"| node_qua_ops
node_qua_dsl -->|"contains"| node_qua_streams
node_qua_dsl -->|"builds into"| node_program_build
node_program_build -->|"validates"| node_config_validate
node_program_build -->|"normalizes"| node_config_convert
node_program_build -->|"feeds"| node_serialization
node_serialization -->|"payload for"| node_api_v2
node_api_legacy -->|"creates"| node_jobs
node_api_v2 -->|"creates"| node_jobs
node_jobs -->|"reads"| node_stream_results
node_api_v2 -->|"streams"| node_stream_results
node_api_v2 -->|"supports"| node_simulation
node_simulation -->|"produces"| node_results
node_octave -->|"built on"| node_octave_sdk
node_octave -->|"configures"| node_qmm
node_results -->|"consumed by"| node_stream_results
node_utils -->|"supports"| node_program_build
node_utils -->|"supports"| node_api_v2
node_utils -->|"supports"| node_qua_dsl

click node_qm_public "https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/__init__.py"
click node_qua_dsl "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/qua"
click node_qua_scope "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/qua/_scope_management"
click node_qua_expr "https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/qua/_expressions.py"
click node_qua_ops "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/qua/_dsl"
click node_qua_streams "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/qua/_dsl/stream_processing"
click node_program_build "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/program"
click node_config_validate "https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/program/_validate_config_schema.py"
click node_config_convert "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/program/_dict_to_pb_converter"
click node_serialization "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/serialization"
click node_api_v2 "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/api/v2"
click node_api_legacy "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/api"
click node_jobs "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/jobs"
click node_stream_results "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/_stream_results"
click node_simulation "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/simulate"
click node_quantum_machine "https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/QuantumMachine.py"
click node_qmm "https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/quantum_machines_manager.py"
click node_octave "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/octave"
click node_octave_sdk "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/octave_sdk"
click node_results "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/results"
click node_utils "https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/utils"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_qua_dsl,node_qua_scope,node_qua_expr,node_qua_ops,node_qua_streams toneBlue
class node_program_build,node_config_validate,node_config_convert,node_serialization toneAmber
class node_api_v2,node_api_legacy,node_jobs,node_stream_results,node_simulation toneMint
class node_octave,node_octave_sdk toneRose
class node_results,node_utils toneIndigo
class node_qm_public,node_quantum_machine,node_qmm toneNeutral
```

## Components

### QUA DSL

Python-side language building and scope management

- [QUA DSL](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/qua): language layer · Python DSL for building QUA programs · `qm/qua`
- [Scopes](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/qua/_scope_management): scope mgmt · Scope stack and lifecycle control for nested QUA construction · `qm/qua/_scope_management`
- [Expressions](https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/qua/_expressions.py): expr model · Expression objects, type hints, and shared DSL utilities · `qm/qua/_expressions.py`
- [Primitives](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/qua/_dsl): QUA ops · Play, measure, wait, phase, stream, and variable primitives · `qm/qua/_dsl`
- [Streams](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/qua/_dsl/stream_processing): stream DSL · Input/output streams and stream processing constructs · `qm/qua/_dsl/stream_processing`

### Program build

Configuration validation and script serialization

- [Program build](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/program): config bridge · Validates config and prepares backend-facing program structures · `qm/program`
- [Validate config](https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/program/_validate_config_schema.py): schema validation · Schema checks and default filling for configuration data · `qm/program/_validate_config_schema.py`
- [Config convert](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/program/_dict_to_pb_converter): dict->pb · Converts dict-based config into protobuf-friendly backend structures · `qm/program/_dict_to_pb_converter`
- [Serialize](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/serialization): script emit · Walks QUA AST-like structures and emits script/protocol payloads · `qm/serialization`

### Runtime APIs

Submission, job control, and result access

- [API v2](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/api/v2): client surface · Newer client surface for QMM, QM, job, and result APIs · `qm/api/v2`
- [API v1](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/api): compat client · Legacy frontend, info, job manager, and simulation APIs · `qm/api`
- [Jobs](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/jobs): lifecycle model · Pending, running, simulated, and queueing job state abstractions · `qm/jobs`
- [Result streams](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/_stream_results): streaming I/O · Incremental result retrieval and multi-stream coordination · `qm/_stream_results`
- [Simulation](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/simulate): sim path · Simulation interfaces, loopback, raw simulation, and credentials · `qm/simulate`

### Hardware integration

Octave and machine-facing control layers

- [Octave](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/octave): hardware control · Octave integration, calibration, health, and connectivity management · `qm/octave`
- [Octave SDK](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/octave_sdk): device client · Lower-level Octave client, connectivity, and conflict handling · `qm/octave_sdk`

### Support

Shared utilities, types, and reporting

- [Results](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/results): reporting · Simulation samples and waveform reporting utilities · `qm/results`
- [Utils](https://github.com/qm-labs/qm-qua-sdk-public/tree/main/qm/utils): shared helpers · General utilities, protobuf helpers, config helpers, and typing support · `qm/utils`

### Other components

- [qm](https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/__init__.py): public package · Top-level user-facing package boundary exposing manager and machine objects · `qm/__init__.py`
- [Quantum machine](https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/QuantumMachine.py): runtime object · Machine/session abstraction bridging user code to backend execution · `qm/QuantumMachine.py`
- [Manager](https://github.com/qm-labs/qm-qua-sdk-public/blob/main/qm/quantum_machines_manager.py): entrypoint · Quantum machines manager and high-level orchestration entrypoint · `qm/quantum_machines_manager.py`

## Connections

- qm → Manager: exposes · Public package exports the manager entrypoint
- qm → Quantum machine: exposes · Public package exports machine/session objects
- Manager → API v2: uses · Manager orchestrates modern API clients
- Quantum machine → API v2: uses · Machine object submits jobs and reads results through client APIs
- QUA DSL → Scopes: depends on · DSL constructs rely on scope tracking
- QUA DSL → Expressions: depends on · DSL primitives build and combine expressions
- QUA DSL → Primitives: contains · Core measurement, pulse, wait, and variable operations
- QUA DSL → Streams: contains · Stream processing and stream declarations live here
- QUA DSL → Program build: builds into · DSL output is normalized into backend-ready program structures
- Program build → Validate config: validates · Program layer checks and fills configuration defaults
- Program build → Config convert: normalizes · Turns config dictionaries into protobuf-friendly objects
- Program build → Serialize: feeds · Prepared program data is serialized for backend submission
- Serialize → API v2: payload for · Serialized scripts and protocol payloads are sent through APIs
- API v1 → Jobs: creates · Legacy APIs still surface job abstractions
- API v2 → Jobs: creates · Job APIs instantiate and manage execution objects
- Jobs → Result streams: reads · Job objects expose incremental result consumption
- API v2 → Result streams: streams · Result APIs provide live and final result transport
- API v2 → Simulation: supports · Client APIs cover simulation execution paths
- Simulation → Results: produces · Simulation path reuses sample/result representations
- Octave → Octave SDK: built on · High-level Octave workflows sit on the lower-level SDK
- Octave → Manager: configures · Octave calibration and setup support machine orchestration
- Results → Result streams: consumed by · Result helpers complement streamed measurement consumption
- Utils → Program build: supports · Config and protobuf utilities back program construction
- Utils → API v2: supports · Shared helpers and type utilities support clients and transport
- Utils → QUA DSL: supports · General helpers and type support are shared by the DSL