bloq¶

A compiler for fault-tolerant surface code computation.

What is bloq?¶

Turning a logical algorithm into an executable surface code program requires several compilation stages:

Compilation pipeline from quantum algorithm to circuit, ZX diagram, BlockGraph, physical program, and backend target. Bloq compiles the BlockGraph into the physical program.

Bloq compiles surface code spacetime layouts into physical programs with the circuit, decoding, and classical-control information needed for simulation and hardware execution. It connects the logical layout to a physical instruction stream that combines quantum operations with classical control.

The input is a BlockGraph: a 3D spacetime layout composed of primitive logical blocks and actions such as measurement-controlled branches and logical Pauli feedback. The same graph can own reusable definitions, placed instances, and their quantum and classical interfaces. Loading and saving retain that hierarchy; one compile API handles both local and composed graphs. The output is Bloq IR, which records physical gates, detectors, logical observables, classical control, and source provenance.

Bloq provides Rust and Python APIs, a CLI, and an interactive editor.

Key features¶

Surface Code Building Blocks Compose cubes for memory and lattice surgery, patch rotations, walking patches (sliding or gliding), Y-basis initialization and measurement, logical Hadamards, and T-state cultivation.
Dynamic Quantum-Classical Computation Express logical measurements, classical bindings, Pauli feedback, measurement-controlled branch selection, repeat-until-success regions, and shot discard.
Reusable Modules Define logical components such as AND, MAJ, and UMA independently, then compose and link them into larger computations such as adders, retaining their quantum and classical interfaces.
Correlation Surfaces A shared logical model tracks measurement signs, byproduct operators, and authored feedback across modules and reachable branches, deriving corrected readouts and output Pauli frames together.
Physical Circuits And Decoding Information Block and pipe constructions have physical circuit realizations with detector and logical-observable information for downstream decoding and correction.
An Editable Physical IR Rust and Python APIs expose physical operations, control dependencies, and provenance. Use the IR for backend emission, causal timing and synchronization, and memory-round padding.

Quick example¶

Here we use bloq to compile a surface code logical T gate to Bloq IR.

Define its blocks, connections, and adaptive measurement in BLOG, and save this source as t-gate.blog:

BLOG 1.0

module main {
  in q_in: data = 0
  out q_out: data = 2

  0: Port [0, 0, 0]
  1: XZX [0, 0, 1]
  2: Port [0, 0, 2]
  3: T [1, 0, 0]
  4: XZX [1, 0, 1]
  5: YX [1, 0, 2]
  [0, 0, 0] -> +Z
  [0, 0, 1] -> +Z
  [0, 0, 1] -> +X
  [1, 0, 0] -> +Z
  [1, 0, 2] -> -Z

  mzz = measure 1 -> +X
  resolve 5 if mzz
}

Compile that graph at code distance 11 and inspect the resulting IR:

Python Rust CLI

import bloq

graph = bloq.BlockGraph.load("t-gate.blog")
program = bloq.compile(graph, distance=11)
program.save("t-gate.bloqir")
print(program.stats())

use bloq::prelude::*;

fn main() -> Result {
    let graph = BlockGraph::load("t-gate.blog")?;
    let program = compile(&graph, 11)?;
    std::fs::write("t-gate.bloqir", program.to_text())?;
    println!("{}", program.stats()?);
    Ok(())
}

bloq compile --quiet t-gate.blog -d 11 --backend ir-text -o t-gate.bloqir
bloq stats t-gate.bloqir

We get the following output:

Bloq IR
├── Compiled Templates: 10
├── Nodes: 20
│   ├── Compute: 6
│   ├── Discard: 0
│   ├── Observable: 7
│   ├── Quantum: 6
│   └── RepeatUntilSuccess: 1
├── Edges: 32
│   ├── Compose: 2
│   ├── Order: 14
│   ├── Quantum: 5
│   └── Value: 11
└── Static: No