qubitos 0.4.0

Python modules for QubitOS quantum control kernel

QubitOS Core

Open-source quantum control system: pulse optimization, multi-qubit scheduling, 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. 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.

QubitOS sits between your compiler output and the hardware. It takes circuit-level instructions, optimizes pulses against current calibration data, schedules them with constraint-aware parallelism, 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.

Features

Pulse Optimization (GRAPE)

Multi-qubit gradient ascent pulse engineering with per-qubit envelopes, dimension-scaled learning rates, and ZZ coupling drift Hamiltonians. Single-qubit gates at 99.9%+ fidelity, two-qubit gates at 95%+.

Pulse Scheduling

ASAP scheduling via topological sort with a constraint system (sequential, simultaneous, aligned, max-delay). Automatic qubit-conflict avoidance, crosstalk-aware serialization, and AWG clock grid alignment.

Parametric Gates

Google fSim(θ,φ) family (iSWAP, CZ, Sycamore) and IBM cross-resonance gates with full parameterization for hardware-native gate sets.

Error Budgets

Cumulative error tracking across sequences — gate infidelity, T1/T2 decoherence, leakage, crosstalk, readout errors. Fidelity prediction before execution with coherent noise correction (Wallman & Emerson 2016).

Benchmarking

Single and multi-qubit randomized benchmarking. Symplectic Clifford tableaux (Aaronson-Gottesman) for efficient n-qubit Clifford sampling, RB decay fitting, error-per-Clifford extraction.

Experiment Provenance

Merkle tree tracking with content-addressed storage, automatic diffing between optimization runs, and reproducibility verification.

Quick Start

pip install -e ".[dev]"

Generate a pulse

from qubitos.pulsegen import generate_pulse

# Single-qubit X gate
result = generate_pulse(gate="X", duration_ns=20, target_fidelity=0.999)
print(f"Fidelity: {result.fidelity:.4f}")

# Two-qubit CZ gate
result = generate_pulse(gate="CZ", num_qubits=2, duration_ns=80)
print(f"CZ fidelity: {result.fidelity:.4f}")

Schedule pulses

from qubitos.temporal import PulseScheduler, PulseOp, TemporalConstraint, ConstraintKind

scheduler = PulseScheduler()
ops = [
    PulseOp(pulse_id="h0", qubit_indices=(0,), duration_ns=20),
    PulseOp(pulse_id="h1", qubit_indices=(1,), duration_ns=20),
    PulseOp(pulse_id="cnot01", qubit_indices=(0, 1), duration_ns=40),
]
constraints = [
    TemporalConstraint(kind=ConstraintKind.SEQUENTIAL, pulse_a_id="h0", pulse_b_id="cnot01"),
]
result = scheduler.schedule_asap(ops, constraints=constraints)
print(result.ascii_timeline())

CLI

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

# Check backend health
qubit-os hal health

# Show calibration
qubit-os calibration show

Architecture

qubit-os-core/src/qubitos/
├── pulsegen/       # GRAPE optimizer, Hamiltonians, pulse shapes
├── temporal/       # Time model, pulse scheduling, decoherence budgets
├── calibrator/     # Calibration management, benchmarking, Cliffords
├── error_budget/   # Cumulative error tracking
├── provenance/     # Merkle tree experiment tracking
├── client/         # HAL gRPC client
├── validation/     # AgentBible integration
├── target_unitary.py  # Gate enum (X, Y, Z, H, CZ, CNOT, Toffoli, ...)
└── cli/            # Command-line interface

QubitOS is a three-repo system:

Repository	Purpose	Language
qubit-os-core	Python modules and CLI (this repo)	Python
qubit-os-hardware	HAL server (Rust + PyO3 + gRPC)	Rust
qubit-os-proto	Protocol Buffer definitions	Protobuf

Development

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

# Run tests (947 passing)
pytest tests/

# Type checking
mypy src/qubitos/ --ignore-missing-imports --exclude proto_convert

# Lint & format
ruff check src/ tests/
ruff format src/ tests/

Documentation

📖 Full Documentation — guides, tutorials, API reference, Jupyter notebooks.

• Installation Guide
• Quickstart
• API Reference
• Design Document
• Changelog

License

Apache 2.0 — See LICENSE for details.