> ## Documentation Index
> Fetch the complete documentation index at: https://b01t.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Types Reference

> Reference for the core b01t types you interact with: QReg, Wire, IRProgram, ExactProgram, Certification, Effect, DSLValidationError, and utility functions.

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.

```python theme={null}
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.

```python theme={null}
QReg(name: str, size: int, kind: str = "sys")
```

<ParamField path="name" type="str" required>
  Register name. Must be unique within a program.
</ParamField>

<ParamField path="size" type="int" required>
  Number of qubits in this register.
</ParamField>

<ParamField path="kind" type="str" default="&#x22;sys&#x22;">
  Register kind. `"sys"` for user-declared registers, `"anc"` for ancilla registers allocated by `ancilla(...)`.
</ParamField>

### Methods and indexing

<ResponseField name="__getitem__(idx: int)" type="Wire">
  Returns the `Wire` at position `idx`. Raises `IndexError` if out of bounds.
</ResponseField>

<ResponseField name="wires()" type="list[Wire]">
  Returns a list of all wires in the register, in order.
</ResponseField>

<ResponseField name="__len__()" type="int">
  Returns the number of qubits (`size`).
</ResponseField>

<ResponseField name="__iter__()" type="Iterator[Wire]">
  Iterates over all wires in the register.
</ResponseField>

```python theme={null}
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.

```python theme={null}
Wire(reg: str, index: int, kind: str = "sys")
```

<ResponseField name="reg" type="str">
  The name of the register this wire belongs to.
</ResponseField>

<ResponseField name="index" type="int">
  Zero-based index within the register.
</ResponseField>

<ResponseField name="kind" type="str">
  Kind of the parent register: `"sys"` or `"anc"`.
</ResponseField>

```python theme={null}
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.

```python theme={null}
# Constructed by build_exact(), not directly
ExactProgram(
    name: str,
    regs: tuple[QReg, ...],
    ops: tuple[ExactOp, ...],
    certification: Certification,
)
```

<ResponseField name="name" type="str">
  The function name from the decorator.
</ResponseField>

<ResponseField name="regs" type="tuple[QReg, ...]">
  All registers in the program, including any ancilla registers allocated during the build. System registers appear first.
</ResponseField>

<ResponseField name="ops" type="tuple[ExactOp, ...]">
  The compiled op sequence. Contains `ExactGateOp`, `ExactAncillaBlock`, or `ExactParOp` instances.
</ResponseField>

<ResponseField name="certification" type="Certification">
  `Certification.SAFE` for `@coherent` programs; `Certification.PRIMITIVE` for `@primitive` programs.
</ResponseField>

***

## IRProgram

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

```python theme={null}
# Constructed by build() or lower_exact_program(), not directly
IRProgram(
    name: str,
    effect: Effect,
    regs: list[QReg],
    ops: list[Op],
    is_safe: bool,
)
```

<ResponseField name="name" type="str">
  The function name from the decorator.
</ResponseField>

<ResponseField name="effect" type="Effect">
  `Effect.COHERENT` for `@parametric`; `Effect.ADAPTIVE` for `@adaptive`.
</ResponseField>

<ResponseField name="regs" type="list[QReg]">
  Declared registers in the order they were passed to `.build()`.
</ResponseField>

<ResponseField name="ops" type="list[Op]">
  The compiled op sequence. Contains `GateOp`, `MeasureOp`, `MeasureAllOp`, `IfOp`, `AncillaBlockOp`, or `ParOp` instances.
</ResponseField>

<ResponseField name="is_safe" type="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.
</ResponseField>

***

## 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. |

```python theme={null}
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`. |

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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.

<ParamField path="effect" type="Effect" required>
  The effect of the program. Returns `False` immediately if `effect` is `Effect.ADAPTIVE`.
</ParamField>

<ParamField path="ops" type="Sequence[Op]" required>
  The list of ops to check.
</ParamField>

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

```python theme={null}
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

```python theme={null}
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.

<ParamField path="ir" type="IRProgram" required>
  The IR program to print.
</ParamField>

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

```python theme={null}
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]
```