qubit-os-proto 0.1.0

Protocol Buffers for QubitOS quantum control kernel

QubitOS Protocol Buffers

Protocol Buffer definitions for QubitOS - the open-source quantum control kernel.

Overview

This repository contains the protocol buffer definitions that form the contract between QubitOS components:

• quantum.common.v1 - Shared types (TraceContext, Timestamp, Error)
• quantum.pulse.v1 - Pulse specifications (Hamiltonian, PulseShape, GRAPE)
• quantum.backend.v1 - Backend service interface (ExecutePulse, Health, HardwareInfo)

Installation

Python

pip install qubit-os-proto

from quantum.pulse.v1 import pulse_pb2, grape_pb2
from quantum.backend.v1 import service_pb2_grpc

Rust

# Cargo.toml
[dependencies]
qubit-os-proto = "0.1"

use qubit_os_proto::quantum::pulse::v1::PulseShape;
use qubit_os_proto::quantum::backend::v1::quantum_backend_client::QuantumBackendClient;

Structure

quantum/
├── common/v1/
│   └── common.proto      # Shared types
├── pulse/v1/
│   ├── hamiltonian.proto # System Hamiltonian specification
│   ├── pulse.proto       # Pulse waveform definition
│   └── grape.proto       # GRAPE optimization protocol
└── backend/v1/
    ├── service.proto     # QuantumBackend gRPC service
    ├── execution.proto   # Pulse execution messages
    └── hardware.proto    # Hardware info and health

Build-Time Generation

Code is generated automatically at build time - no manual generation step needed.

Rust: cargo build runs tonic-build via build.rs

Python: pip install . runs grpcio-tools via setup.py

For Contributors

If you need to lint or check protos directly:

# Install buf
brew install bufbuild/buf/buf  # macOS

# Lint protos
buf lint

# Format check
buf format -d

# Check for breaking changes (on PRs)
buf breaking --against 'https://github.com/qubit-os/qubit-os-proto.git#branch=main'

Versioning

• Proto packages use path-based versioning: quantum.pulse.v1, quantum.pulse.v2
• The proto_version field in messages is informational only
• Breaking changes require a new package version (v2, v3, etc.)
• Deprecated versions are supported for at least 2 minor releases

Documentation

• Design Document
• Pauli String Grammar
• Matrix Formats

License

Apache 2.0 - See LICENSE for details.