Core Types Reference

The types in this reference are the data structures you create, inspect, and pass between b01t APIs. You rarely construct most of them directly — decorators and build methods produce them for you — but understanding their fields lets you inspect compiled programs, check safety properties, and serialize or lower them correctly.

from b01t import (
    QReg, Wire, IRProgram, ExactProgram,
    Certification, Effect, DSLValidationError,
    is_safe_program, dump_ir,
)

QReg

A quantum register: a named, contiguous block of qubits.

QReg(name: str, size: int, kind: str = "sys")

name

str

required

size

int

required

Number of qubits in this register.

kind

str

default:"\"sys\""

Methods and indexing

__getitem__(idx: int)

Wire

Returns the Wire at position idx. Raises IndexError if out of bounds.

wires()

list[Wire]

Returns a list of all wires in the register, in order.

__len__()

int

Returns the number of qubits (size).

__iter__()

Iterator[Wire]

Iterates over all wires in the register.

from b01t import QReg

sys = QReg("sys", 3)

wire0 = sys[0]          # Wire(reg="sys", index=0)
all_wires = sys.wires() # [Wire("sys", 0), Wire("sys", 1), Wire("sys", 2)]
n = len(sys)            # 3

for w in sys:
    print(w)            # sys[0], sys[1], sys[2]

Wire

A reference to a single qubit within a register. Wires are frozen dataclass instances and are used everywhere gates accept qubit arguments.

Wire(reg: str, index: int, kind: str = "sys")

reg

str

The name of the register this wire belongs to.

index

int

Zero-based index within the register.

kind

str

Kind of the parent register: "sys" or "anc".

from b01t import QReg, Wire

q = QReg("q", 2)
w = q[1]       # Wire(reg="q", index=1)
print(w)       # q[1]

You typically obtain Wire objects by indexing a QReg rather than constructing them directly.

ExactProgram

The result of calling .build_exact() on a @coherent or @primitive function. Represents a certified exact program.

# Constructed by build_exact(), not directly
ExactProgram(
    name: str,
    regs: tuple[QReg, ...],
    ops: tuple[ExactOp, ...],
    certification: Certification,
)

name

str

The function name from the decorator.

regs

tuple[QReg, ...]

All registers in the program, including any ancilla registers allocated during the build. System registers appear first.

ops

tuple[ExactOp, ...]

The compiled op sequence. Contains ExactGateOp, ExactAncillaBlock, or ExactParOp instances.

certification

Certification

Certification.SAFE for @coherent programs; Certification.PRIMITIVE for @primitive programs.

IRProgram

The result of calling .build() on a @parametric or @adaptive function, or of calling lower_exact_program() on an ExactProgram.

# Constructed by build() or lower_exact_program(), not directly
IRProgram(
    name: str,
    effect: Effect,
    regs: list[QReg],
    ops: list[Op],
    is_safe: bool,
)

name

str

The function name from the decorator.

effect

Effect

Effect.COHERENT for @parametric; Effect.ADAPTIVE for @adaptive.

regs

list[QReg]

Declared registers in the order they were passed to .build().

ops

list[Op]

The compiled op sequence. Contains GateOp, MeasureOp, MeasureAllOp, IfOp, AncillaBlockOp, or ParOp instances.

is_safe

bool

True if the program passed the safety checker (coherent effect + well-formed ancilla blocks with exact-safe gates only). Always False for adaptive programs.

Certification

Enum marking the safety level of an ExactProgram.

Value	Meaning
`Certification.SAFE`	Produced by `@coherent`. Ancilla cleanliness is certified by the compiler.
`Certification.PRIMITIVE`	Produced by `@primitive`. Coherent and unitary, but ancilla management is the caller’s responsibility.

from b01t import Certification

if prog.certification == Certification.SAFE:
    print("ancilla-certified")

Effect

Enum describing the computational effect of an IRProgram.

Value	Meaning
`Effect.COHERENT`	Unitary program; no measurement or classical branching.
`Effect.ADAPTIVE`	Allows mid-circuit measurement and classical feed-forward via `if_then`.

from b01t import Effect

if prog.effect == Effect.COHERENT:
    print("unitary")

DSLValidationError

Raised whenever a b01t rule is violated. Inherits from RuntimeError. Common causes:

Using a forbidden gate in a context (e.g., rx in @coherent)
Calling a gate outside a build context
Ancilla discipline violations (missing uncompute, nested blocks)
Duplicate register names
Measurement in a @coherent function
if_then in a non-adaptive function
Calling .build_exact() or .build() with wrong argument types

from b01t import coherent, QReg, rx, DSLValidationError

@coherent
def bad(q: QReg) -> None:
    rx(1.0, q[0])  # parametric gate not allowed in @coherent

try:
    prog = bad.build_exact(("q", 1))
except DSLValidationError as e:
    print(e)
# gate 'rx' is not allowed in @coherent (parameterized rotations are not in the exact gate set)

is_safe_program

from b01t import is_safe_program

is_safe_program(effect: Effect, ops: Sequence[Op]) -> bool

Checks whether a list of broad IR ops satisfies the safety predicate: coherent effect, only exact-safe gates at the top level, and well-formed ancilla blocks with correct compute / phase / uncompute structure.

effect

Effect

required

The effect of the program. Returns False immediately if effect is Effect.ADAPTIVE.

ops

Sequence[Op]

required

The list of ops to check.

Returns: bool — True if all ops satisfy the safety conditions.

from b01t import parametric, QReg, h, cx, is_safe_program

@parametric
def bell(a: QReg, b: QReg) -> None:
    h(a[0])
    cx(a[0], b[0])

prog = bell.build(("a", 1), ("b", 1))
print(prog.is_safe)  # True — h and cx are exact-safe

dump_ir

from b01t import dump_ir

dump_ir(ir: IRProgram) -> str

Pretty-prints an IRProgram as a human-readable text string. Useful for debugging and inspecting compiled programs.

IRProgram

required

The IR program to print.

Returns: a multi-line string with the program name, effect, safety flag, register declarations, and indented op listing.

from b01t import parametric, QReg, h, cx, dump_ir

@parametric
def bell(a: QReg, b: QReg) -> None:
    h(a[0])
    cx(a[0], b[0])

prog = bell.build(("a", 1), ("b", 1))
print(dump_ir(prog))
# program bell
# effect: coherent
# safe: True
# registers:
#   - a[1] (sys)
#   - b[1] (sys)
# ops:
#   h a[0]
#   cx a[0], b[0]

Decorators

Gates

Kit

Types

Core Types Reference

QReg

Methods and indexing

Wire

ExactProgram

IRProgram

Certification

Effect

DSLValidationError

is_safe_program

dump_ir

​QReg

​Methods and indexing

​Wire

​ExactProgram

​IRProgram

​Certification

​Effect

​DSLValidationError

​is_safe_program

​dump_ir

QReg

Methods and indexing

Wire

ExactProgram

IRProgram

Certification

Effect

DSLValidationError

is_safe_program

dump_ir