跳转至

09 Driver API

Purpose

This chapter defines the unified backend driver interface.

Driver Role

The driver API is the backend-facing execution contract. It consumes canonical bundle and program information and translates that information into backend-specific planning, compilation, execution, and diagnostics.

In the source drafts, the driver layer is the final lowering boundary between canonical UQCI-side artifacts and backend-native execution chains. That positioning remains normative in this repository.

Required Responsibilities

A backend integration should expose stable entry points for:

  • validation
  • resource allocation
  • scheduling
  • compilation
  • execution
  • diagnostics

The repository's backend extension guidance also suggests additional lifecycle steps such as get_device_spec and fetch_results. Implementations may choose different method granularity, but the lifecycle responsibilities should remain visible.

Lifecycle Interpretation

The staged backend flow implied by the repository and reference drafts is:

  1. validate the canonical program against the capability envelope
  2. allocate resources and resolve conflicts
  3. schedule or order execution under timing and constraint rules
  4. compile to backend-facing forms
  5. run the compiled plan
  6. return results and diagnostics

This flow is intentionally implementation-oriented. It gives backend authors a practical contract while preserving canonical ownership upstream.

Minimal Contract

At the repository level, the minimum contract is:

  • validate(bundle) -> ValidationReport
  • plan(bundle) -> ExecutionPlan
  • run(bundle) -> RunResult

Implementations may internally decompose these calls into finer steps such as validate_ir, allocate_resources, schedule, and compile.

Inputs and Normative Dependencies

Drivers should consume the canonical program together with the normative sidecar artifacts required for execution. In practical repository terms, those inputs often include:

  • UQCIProgram
  • Manifest
  • DeviceSpec
  • CalSet when calibration context is required
  • optional supplemental artifacts such as pulseir

This makes the driver API schema-aware without making schema files themselves the semantic source of truth.

Architectural Rule

Drivers must consume UQCI IR and normative sidecars as the authoritative input surface. OpenQASM may be used as a compatibility export or debugging aid, but must not become the sole backend input truth.

That rule prevents the backend boundary from silently inverting the architecture.

Extension Rule

Backends may extend diagnostics and capability metadata, but they must still return standard result and validation abstractions so that the repository remains interoperable and testable.

Stability Rule

The driver API should remain stable enough that:

  • new backend families can be added without rewriting the canonical core
  • mock backends and future real backends can share the same top-level contract
  • tests can validate bundle-to-result behavior consistently across implementations