# QubitOS

**Open-Source Quantum Control Kernel**

QubitOS sits between the compiler and quantum hardware. It optimizes
control pulses against live calibration data, schedules them with
constraint-aware parallelism, and dispatches through a hardware
abstraction layer.

Current release: **v0.7.1** (parallel ``noise_sweep_comparison`` with
deterministic seeds and optional per-cell checkpointing). Previous:
**v0.7.0** (Lyapunov feedback controller, open-loop vs closed-loop
comparison framework, Rust feedback hot path).
Next milestone: **v0.8.0** (3-level transmon with leakage-aware
Lyapunov control). See
[ROADMAP.txt](https://github.com/qubit-os/qubit-os/blob/main/ROADMAP.txt).

## Start here

- [Quickstart](guides/quickstart.txt) — first pulse in 20–30 minutes.
  Install QubitOS, start the HAL server, and execute a quantum gate.
- [Architecture](concepts/architecture.txt) — the kernel and its five
  planes (control, calibration, backend ABI, simulation, feedback).
- [Feedback concepts](concepts/feedback.txt) — parallel noise sweeps and
  reproducibility (v0.7.1).
- [API Reference](api/index.txt) — Python, REST, and gRPC surfaces.
- [Notebooks](notebooks/01-quickstart.ipynb) — runnable Jupyter
  examples for pulse generation, optimization, and SME trajectories.

## What QubitOS does

### Pulse optimization (GRAPE)

Generate optimal control pulses for quantum gates using gradient ascent:

```python
from qubitos.pulsegen import GrapeOptimizer, GrapeConfig
from qubitos.pulsegen.hamiltonians import get_target_unitary

config = GrapeConfig(
    num_time_steps=100,
    duration_ns=50,
    target_fidelity=0.999,
)
optimizer = GrapeOptimizer(config)
target = get_target_unitary("X", num_qubits=1)
result = optimizer.optimize(target, num_qubits=1)
print(f"Achieved fidelity: {result.fidelity:.4f}")
```

### Stochastic master equation (v0.6.0)

Simulate continuously measured open quantum systems with the Itô SDE
form of the SME. Trajectory and Monte Carlo ensemble; Python reference
implementation plus Rust + Rayon for parallel ensembles.

```python
from qubitos.sme import SMESolver, SMEConfig
from qubitos.lindblad import CollapseOperator

config = SMEConfig(
    num_time_steps=1000,
    duration_ns=20.0,
    measurement_efficiency=0.5,
    random_seed=42,
    collapse_ops=CollapseOperator.from_t1_t2(t1_us=45.0, t2_us=35.0),
)
solver = SMESolver(config=config)
result = solver.solve_trajectory(initial_rho=rho0, hamiltonians=h_list,
                                 target_rho=rho_target)
print(f"Final fidelity: {result.final_fidelity:.4f}")
```

### Lyapunov feedback controller (v0.7.0)

Close the loop on the SME runtime. A Lyapunov function V(rho_c) =
1 - Tr[rho_target rho_c] drives a per-axis feedback law that adds a
real-time correction to the baseline drive Hamiltonian. The
`noise_sweep_comparison` API produces the open-loop vs closed-loop
fidelity curves; `crossover_point` returns the noise strength where
the closed loop starts to win.

```python
from qubitos.feedback import (
    AXIS_X, AXIS_Y, AXIS_Z,
    FeedbackConfig, LyapunovController,
    solve_with_feedback,
)

fb_config = FeedbackConfig(
    gains=(5.0e6,),
    control_axes=(AXIS_X, AXIS_Y, AXIS_Z),
    max_correction_amplitude=50.0e6 * 2.0 * 3.14159,
    delay_ns=0.0,
)
controller = LyapunovController(fb_config, rho_target)
result = solve_with_feedback(solver, controller, rho0, hamiltonians,
                             target_rho=rho_target)
print(f"Final fidelity: {result.sme_result.final_fidelity:.4f}")
print(f"V(T):           {result.lyapunov_trajectory[-1]:.4f}")
```

### Hardware abstraction

Execute pulses through a unified gRPC/REST interface:

```python
from qubitos.client import HALClientSync

with HALClientSync("localhost:50051") as client:
    result = client.execute_pulse(
        i_envelope=pulse.i_envelope,
        q_envelope=pulse.q_envelope,
        duration_ns=50,
        target_qubits=[0],
        num_shots=1024,
    )
    print(f"Measurement: {result.bitstring_counts}")
```

### Calibration management

Calibration is treated as live runtime state, not a static snapshot:

```python
from qubitos.calibrator import CalibrationLoader

loader = CalibrationLoader()
calibration = loader.load("path/to/calibration.yaml")
if calibration.is_valid:
    print(f"T1: {calibration.t1_us} µs")
    print(f"T2: {calibration.t2_us} µs")
```

## Backend integration honesty

IQM is the primary live integration and the only backend exercised
against real hardware. IBM Quantum, AWS Braket, and the QuTiP simulator
are mock-tested and demonstrate the backend abstraction; they are not
maintained as production cloud integrations.

## Repository

QubitOS is a monorepo at
[qubit-os/qubit-os](https://github.com/qubit-os/qubit-os):

| Module    | Purpose                                                 | Language |
|-----------|---------------------------------------------------------|----------|
| `core/`   | Python: GRAPE, SME, calibration, scheduling, CLI        | Python   |
| `hal/`    | Rust: gRPC server, backend dispatch, Lindblad and SME   | Rust     |
| `proto/`  | Protocol Buffer API contracts                           | Protobuf |

The previous split repositories (`qubit-os-core`, `qubit-os-hardware`,
`qubit-os-proto`) are archived and redirect to the monorepo.

## Quick links

- [Installation Guide](guides/installation.txt) — setup
- [Troubleshooting](guides/troubleshooting.txt) — common issues
- [Design Specifications](specs/README.txt) — per-subsystem technical specs
- [CLI Reference](api/cli.txt) — command-line interface
- [Source](https://github.com/qubit-os/qubit-os) — issues, releases, code
- [Contributing](https://github.com/qubit-os/qubit-os/blob/main/CONTRIBUTING.txt)

## License

Apache License 2.0. See
[LICENSE](https://github.com/qubit-os/qubit-os/blob/main/LICENSE).
