跳转至

13 Python Skeleton

Purpose

This chapter defines the reference Python skeleton of the open-source framework.

Core Requirement

The Python implementation must mirror the canonical architecture and remain modular, typed, testable, and backend-agnostic at the core.

Structural Principles

The reference Python implementation is a conformance-oriented skeleton rather than a complete production runtime. Its purpose is to make the specification executable, testable, and extensible without collapsing architectural layers.

The canonical package SHALL keep UQCI program semantics, sidecar artifacts, validation, and compatibility export logic in the core package. Backend-specific compilation and execution logic SHALL remain outside that package.

Canonical Package Layout

In the current repository, the canonical package is located under src/qos_uqci/. Its top-level modules reflect the intended division of responsibilities:

  • ir.py: canonical program containers and related orchestration-facing types
  • ops.py: operation-level objects such as GateOp, PulseOp, MeasureOp, and SweepOp
  • devicespec.py: typed DeviceSpec models
  • calset.py: typed CalSet models
  • result.py: ExecutionPlan, RunResult, ValidationReport, and related reporting types
  • bundle.py: bundle loading, writing, integrity checks, and validation helpers
  • driver.py: abstract backend-facing driver contracts such as UQCIDriver
  • lowering.py: repository-native lowering helpers and transformation utilities
  • openqasm_bridge.py: OpenQASM compatibility export helpers
  • errors.py: standard framework exceptions
  • cli.py: lightweight repository-facing command-line entrypoints
  • __init__.py: stable package exports for users and examples

The exact file split MAY vary in other implementations, but the separation of concerns SHALL be preserved.

Module Responsibility Boundaries

The Python skeleton should distinguish clearly among:

  • canonical semantic modules
  • sidecar-artifact modules
  • validation and bundle-handling modules
  • compatibility-export modules
  • backend-facing abstraction modules
  • user-facing repository tooling such as the CLI

This distinction is implementation-oriented, but it also supports standards work by making semantic ownership visible in code structure.

Type System and Validation

The reference Python implementation SHOULD use a typed data-modeling approach suitable for JSON interchange and schema generation. In this repository, Pydantic v2 is preferred because it supports:

  • explicit field validation
  • JSON Schema emission
  • versioned model evolution
  • predictable serialization for bundle artifacts

All externally visible models SHOULD carry full type hints. Public model names SHOULD remain close to the specification terminology to avoid drift between the repository and the published chapters.

Execution-Oriented Responsibilities

Taken together, the canonical package should support the following repository-native flow:

  1. model canonical UQCI programs and sidecars
  2. read and validate bundle artifacts
  3. generate or inspect compatibility exports
  4. provide standard abstractions for backend planning and results
  5. expose a lightweight CLI for validation, inspection, export, and demo execution

The package should remain backend-agnostic at the semantic core while still being practical for runnable examples and tests.

Execution Flow in Python

The minimal end-to-end flow of the Python skeleton is:

  1. Construct or load a canonical UQCIProgram.
  2. Load Manifest, DeviceSpec, and CalSet from an execution bundle.
  3. Validate the canonical program and sidecars.
  4. Lower the canonical IR either to a backend-native internal plan or to an OpenQASM compatibility profile.
  5. Submit the resulting execution plan to a backend driver.
  6. Return a standard RunResult and optional diagnostics.

At no step is OpenQASM required to become the only in-memory representation.

Relationship to Backends

The Python skeleton intentionally stops at the canonical boundary. Backend implementations live under backends/ and consume the canonical package rather than redefining it.

This allows:

  • multiple backend families to reuse the same semantic core
  • mock backends and future real backends to share driver contracts
  • repository tests to cover the main chain from bundle to bridge to backend to result

Testing and Quality Expectations

The Python skeleton SHOULD be directly testable with repository-native tools. A conforming reference implementation is expected to support:

  • unit tests for typed models and validation behavior
  • integration tests for bundle loading and export flows
  • backend tests using mock implementations
  • static checks such as linting and type checking

The Python skeleton SHOULD stay intentionally small in v0.1. Large runtime subsystems, distributed orchestration services, and production deployment concerns are explicitly out of scope for this chapter.