API Reference¶

This section provides comprehensive API documentation for QubitOS.

Python API¶

The core Python package qubitos provides four main modules:

Module	Description
`qubitos.client`	HAL client for communicating with quantum backends
`qubitos.pulsegen`	Pulse generation and GRAPE optimization
`qubitos.calibrator`	Calibration data loading and management
`qubitos.validation`	Validation utilities for quantum data

Quick Import Reference¶

# Client
from qubitos.client import HALClient, HALClientSync

# Pulse generation
from qubitos.pulsegen import GrapeOptimizer, GrapeConfig, generate_pulse
from qubitos.pulsegen.hamiltonians import (
    parse_pauli_string,
    get_target_unitary,
    build_hamiltonian,
)

# Calibration
from qubitos.calibrator import CalibrationLoader, load_calibration

# Validation
from qubitos.validation import (
    validate_hamiltonian,
    validate_pulse,
    validate_unitary,
)

Interface APIs¶

QubitOS exposes multiple interface layers for flexibility:

Interface	Use Case	Documentation
CLI	Shell scripts, interactive use	CLI Reference
REST API	Web integration, language-agnostic	REST API
gRPC API	High-performance, low-latency	gRPC API

Architecture Overview¶

┌─────────────────────────────────────────────────────────┐
│                      Python Client                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────┐ │
│  │ client  │  │pulsegen │  │calibrator│  │ validation │ │
│  └────┬────┘  └────┬────┘  └────┬────┘  └─────────────┘ │
└───────┼────────────┼────────────┼───────────────────────┘
        │            │            │
        │ gRPC       │ Pure Python│ Pure Python
        ▼            │            │
┌───────────────┐    │            │
│   HAL Server  │◄───┴────────────┘
│   (Rust)      │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│   Backends    │
│ (QuTiP, HW)   │
└───────────────┘

Versioning¶

QubitOS follows Semantic Versioning:

0.x.x: Development phase, API may change
1.x.x: Stable API, backwards compatible minor releases

Current version: 0.5.0

Type Annotations¶

All public APIs are fully type-annotated. Use mypy or your IDE for type checking:

# Check types
mypy src/qubitos

# Or with strict mode
mypy --strict src/qubitos

Error Handling¶

QubitOS defines specific exception types for each module:

from qubitos.client import HALClientError
from qubitos.calibrator import CalibrationError
from qubitos.validation import ValidationError
from qubitos.pulsegen import GrapeConfig  # Raises ValueError for invalid config

All exceptions inherit from Python's built-in Exception class.