跳转至

14 Backend Directory Structure

Purpose

This chapter defines how backend implementations should be organized in the repository.

Core Requirement

Backend-specific logic must remain structurally separated from the canonical core.

Separation Rule

The repository SHALL distinguish between canonical modules and backend modules.

  • Canonical modules define protocol semantics, sidecar artifacts, compatibility export, validation, and common execution result types.
  • Backend modules define target-specific legality checks, resource models, scheduling strategies, compilation passes, execution stubs, and diagnostics.

Backend modules MUST NOT redefine canonical semantic objects in incompatible ways.

Current Repository Layout

In the current repository, backend-specific code is placed under backends/ and canonical code is placed under src/qos_uqci/. The active backend layout is:

src/qos_uqci/
  ir.py
  ops.py
  devicespec.py
  calset.py
  result.py
  bundle.py
  driver.py
  openqasm_bridge.py
  errors.py

backends/
  base.py
  mock_superconducting/
    backend.py
    __init__.py
  mock_neutral_atom/
    backend.py
    __init__.py
  mock_ion_trap/
    README.md

This layout aligns with the reference Word drafts while adapting them to the repository's lighter v0.1 structure.

Current Backend Organization

The repository currently includes:

  • backends/base.py for shared backend abstractions or common helpers
  • backends/mock_superconducting/ for the runnable superconducting mock backend
  • backends/mock_neutral_atom/ for the runnable neutral-atom mock backend
  • backends/mock_ion_trap/README.md as a reserved extension point for a future ion-trap mock backend

This organization keeps current implementations runnable while leaving visible space for future backend families.

Relationship to Examples and Tests

The backend layout is reinforced by repository-native companion directories:

  • examples/mock_backends/ contains backend-oriented DeviceSpec examples
  • tests/ contains backend integration tests for the runnable mock backends

This helps keep the backend directory narrowly focused on implementation code while moving demo artifacts and verification logic to dedicated locations.

Backend Module Responsibilities

Each backend package SHOULD provide the following responsibilities in a discoverable location:

  • backend identity and capability summary
  • a device-specific DeviceSpec example or factory
  • canonical IR validation against backend constraints
  • resource allocation and scheduling logic
  • compilation from canonical operations to backend-native execution steps
  • mock or real execution entrypoints
  • diagnostics and debug summaries

These responsibilities MAY be grouped in one file for a lightweight reference backend or split across several files for a larger implementation.

In the current repository, the runnable mock backends keep most of these responsibilities in a small number of files in order to stay lightweight and easy to inspect.

Future Backend Families

The directory structure SHOULD leave room for additional platform families such as:

  • ion trap
  • photonic
  • spin qubit
  • simulator or emulator
  • cloud broker backends

The repository SHALL avoid encoding vendor-specific assumptions into the top-level layout. Backend names SHOULD describe device families or stable backend roles rather than temporary marketing names.

Packaging Considerations

Backends MAY be shipped inside the repository or as optional external packages. The normative requirement is not physical co-location, but preservation of the canonical boundary and compatibility with the standard driver contract.

The current repository keeps them local because v0.1 is a reference implementation. Future versions may split some backends into optional packages without changing the architectural rule described in this chapter.