QSBIT compiler

qsbit-compiler compiles QIR programs into RV32I executables for qsbit-sim. It validates input, maps quantum operations to the target, schedules them, and generates code using LLVM 21.

Supported QIR · Adaptive QIR · QEC examples

Build

Install the prerequisites, then run from the repository root:

cmake --preset clang-ninja
cmake --build --preset clang-ninja --parallel
cmake --install build-clang --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"

Install the Python runner with uv:

uv tool install .
uv tool update-shell

Reopen your shell if its configuration changed. Install qsbit-sim on PATH before running compiled programs.

Compile

Compile the Bell-pair example from the repository root:

qsbitc examples/bell.ll --target targets/sim-default.json -o out/bell.elf

The compiler writes the ELF, lowered LLVM IR, schedule, manifest, and run configuration under out/. Keep these files together.

Run

qsbit-run out/bell.elf --backend mock --shots 1

The mock backend supplies predetermined measurement bits. The runner saves results to out/runs/results.json, with a trace and summary for each shot. Use --sim PATH to select a different simulator executable.

For quantum-state evolution, configure the simulator's Aer backend, then run:

qsbit-run out/bell.elf --backend aer --shots 16

Each shot starts a fresh simulator process. Ideal Bell measurements produce 00 or 11; a finite sample need not split equally.

qsbit-validate program.elf checks an artifact bundle without running the simulator. It uses the same manifest, digest, profile, and ABI validation as qsbit-run.

Supported input

The compiler accepts LLVM text and bitcode implementing the supported Base or Adaptive QIR subset. Base programs use static resources and terminal measurements; Adaptive programs can use intermediate measurements, branches, loops, reset, and decoder feedback. Unsupported instructions produce errors. Qubit placement, routing, and dynamic resource allocation are not supported.

Learn more

• Build setup: dependencies and compiler selection.
• Compiler contracts: modules, QIR constraints, targets, and artifacts.
• Adaptive QIR: control flow and decoder calls.
• CUDA-Q export: generate QIR input.
• Testing: stage checks and simulator integration.

License

Apache License 2.0.