qubitos 0.3.0

Python modules for QubitOS quantum control kernel

QubitOS Core

Open-source real-time quantum control system: pulse optimization, calibration management, and hardware abstraction.

Why This Exists

Quantum processors drift. Gate fidelities measured during Tuesday's calibration are wrong by Thursday. Coherence times shift with temperature, TLS defects come and go, and crosstalk changes as you bring neighboring qubits online. So every serious quantum experiment starts the same way: recalibrate, re-optimize pulses, hope the hardware holds still long enough to run your circuit.

Most quantum software treats this as somebody else's problem. Qiskit and Cirq give you circuit-level abstractions and assume calibration data is accurate and static. But if you have actually tried to run a multi-qubit algorithm on real hardware, you know it is not. The gap between "my simulation says 99.9% fidelity" and "the QPU returned garbage" is almost always a calibration or pulse-level problem, and there is no open-source tool that closes that loop.

QubitOS is built to sit between your compiler output and the hardware. It takes circuit-level instructions, optimizes pulses against current calibration data (not last week's), and executes them through a hardware abstraction layer that talks to real backends. The control loop is designed to be fast enough for feedback-based protocols where you need microsecond-scale decisions.

This started because I kept running into the same problem across QubitPulseOpt, qco-integration, and the circuit optimizer: optimizing gates in isolation does not help if the hardware has drifted since calibration. QubitOS is the system that ties all of those pieces together.

Overview

QubitOS Core provides:

• pulsegen - GRAPE/DRAG pulse optimization with Lindblad noise modeling (99.9% single-qubit fidelity)
• calibrator - Live calibration tracking, drift detection, and automatic re-optimization triggers
• client - gRPC client for the Rust Hardware Abstraction Layer
• cli - Command-line interface for pulse generation, execution, and calibration management

Installation

# From PyPI (when available)
pip install qubitos

# From source
git clone https://github.com/qubit-os/qubit-os-core.git
cd qubit-os-core
pip install -e ".[dev]"

Quick Start

Generate an X-gate pulse

from qubitos.pulsegen import generate_pulse
from qubitos.client import HALClient

# Generate optimized pulse
pulse = generate_pulse(gate="X", duration_ns=20, target_fidelity=0.999)

# Execute on simulator
async with HALClient("localhost:50051") as client:
    result = await client.execute_pulse(
        i_envelope=pulse.i_envelope.tolist(),
        q_envelope=pulse.q_envelope.tolist(),
        duration_ns=20,
        target_qubits=[0],
        num_shots=1000,
    )
    print(f"Counts: {result.bitstring_counts}")
    if result.fidelity_estimate is not None:
        print(f"Fidelity: {result.fidelity_estimate:.4f}")

CLI Usage

# Generate a pulse
qubit-os pulse generate --gate X --duration 20 --output x_gate.json

# Execute a pulse
qubit-os pulse execute x_gate.json --shots 1000

# Check backend health
qubit-os hal health

# Show calibration
qubit-os calibration show

Architecture

qubitos/
├── client/         # HAL gRPC client
├── pulsegen/       # Pulse optimization (GRAPE, DRAG)
├── calibrator/     # Calibration management
├── validation/     # AgentBible integration
└── cli/            # Command-line interface

Configuration

QubitOS uses a configuration hierarchy (later overrides earlier):

1. Built-in defaults
2. Environment variables (QUBITOS_*)
3. config.yaml
4. CLI arguments

# Environment variables
export QUBITOS_HAL_HOST=localhost
export QUBITOS_HAL_PORT=50051
export QUBITOS_LOG_LEVEL=info

Development

Setup

# Clone and install
git clone https://github.com/qubit-os/qubit-os-core.git
cd qubit-os-core
pip install -e ".[dev]"

# Run tests
pytest tests/

# Type checking
mypy src/qubitos/

# Linting
ruff check src/
ruff format src/

Running Tests

# All tests
pytest

# With coverage
pytest --cov=qubitos --cov-report=html

# Specific module
pytest tests/unit/test_grape.py

# Integration tests (requires HAL running)
pytest tests/integration/

Documentation

• Design Document
• CLI Reference
• API Reference
• User Guide

License

Apache 2.0 - See LICENSE for details.