User Guide¶

Bloq takes a surface code layout of a logical computation and compiles it into a physical program: the quantum circuit and the classical decisions needed to run it. This guide follows that path from source to execution.

flowchart LR
  source["Block graph<br/>geometry + actions"] --> compile["Compilation<br/>logical correlations + physical blocks"]
  compile --> ir["Bloq IR<br/>operations + dependencies"]
  ir --> stim["Stim<br/>static circuit"]
  ir --> vm["VM<br/>verification simulator"]

The chapters build on each other, so read them in order the first time.

1. Describe the computation

Preliminaries reviews the basic concepts the rest of the guide relies on. Existing Works compares Bloq with related compilers and tools. Blocks and Pipes introduces the block graph: blocks placed in spacetime and joined by pipes. Actions adds named measurements and the decisions that depend on them. Modules packages a graph behind a reusable quantum and classical interface. BLOG Format shows how to write and exchange the complete source as text.

2. Understand compilation

Correlation Surfaces explains how Bloq tracks the signed Pauli relations behind every logical readout and output correction. Patch Alignment introduces the shared qubit lattice and stabilizer placement conventions. Circuit Constructions explains the fault-tolerant physical circuit design for each block and pipe. Compilation ties these ingredients together and produces Bloq IR.

3. Inspect and execute the result

Bloq IR is the main output of compilation and the input to downstream backend compilers. It keeps circuit templates and a dependency graph together. Bloq provides convenient APIs to visit and edit the IR, inspect and draw it, and save it as text or binary.

Backend Emission translates the IR for execution. Bloq provides a default Stim emitter for static Clifford computations and a simple verification VM for checking dynamic compilation outputs. Practical execution needs a custom backend:

Synchronization covers the explicit synchronization across logical patches and instructions needed for real hardware emulation. It explains how resource preparation, decoding, and classical dependencies determine when instructions can execute and where live patches must wait.

4. Walk through real examples

Building on the topics above, a series of tutorials provides real examples of compiling and simulating fault-tolerant surface code computations.

Tutorials¶