qm-labs/qm-qua-sdk-public

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.