Python API Reference¶

The bloq namespace provides the main workflow: author or load a BlockGraph, compile it to Bloq, then emit a circuit or lower the program for VM verification. Import bloq.ir for the concrete types returned by IR accessors. These are the same native objects, with no conversion layer.

This page groups signatures and generated docstrings by task. For a complete first program, use the quickstart.

Compiled-program inspection types and exchange-format constants.

Use these types when inspecting a bloq.Bloq, matching node or circuit variants, or writing a custom backend. They are the same native objects returned by program accessors; importing this namespace adds no wrappers or conversions.

Examples

>>> import bloq
>>> from bloq.ir import CircuitOp, RegionKind
>>> program = bloq.compile(bloq.GalleryItem.X_MEMORY.load(), distance=3)
>>> isinstance(program.template(0).circuit.ops()[0], CircuitOp)
True
>>> program.regions_of(RegionKind.RepeatUntilSuccess)
[]

Compilation¶

compile returns a Bloq program at an odd code distance in 3..=255. It accepts both local and hierarchical sources through BlockGraph. Pass validate=True to request a full IR audit after compilation; required local checks run in either case.

The free compile function shares a process-wide template cache with no automatic eviction. Use clear_compile_cache between large distance sweeps, or a CompileContext when a Python object should own a fixed configuration and private cache. A context can serve concurrent callers. Budget overrides use limits={"FIELD": count}; None disables that field’s limit.

func bloq.compile

compile(graph: BlockGraph, distance: int = 3, *, prepare_t_with_mpps: bool = False, validate: bool = False, limits: Mapping[str, int | None] | None = None) → Bloq¶

Compiles graph into a Bloq IR program with a one-shot context. Circuit templates are still cached process-wide, so repeated calls at one distance stay warm.

Use CompileContext when one object should own the configuration and cache lifetime instead of sharing the process-global cache.

Parameters:

graph: BlockGraph¶

The block graph to compile.

distance: int = 3¶

The odd code distance to compile at, in 3..=255.

prepare_t_with_mpps: bool = False¶

Use compact T-source preparation with one stabilizer MPP instead of MSC-LS cultivation.

validate: bool = False¶

Explicitly audit the compiled IR using the configured Boolean limits. Defaults to False.

limits: Mapping[str, int | None] | None = None¶

Compiler budget overrides keyed by field name. Non-negative counts impose a budget, None disables it, and omitted fields keep their defaults. See the field list at https://bloqec.com/docs/dev/api/rust/bloq_graph/struct.ModuleCertificationLimits.html.

Raises:

• CompileError – If compilation fails.

• InvalidArgumentError – If the distance or a limit field is invalid.

• OverflowError – If a limit count is negative or exceeds usize.

Emits:

CompileWarning: Once per advisory the compile recorded — currently a

spatial Hadamard pipe under the fixed-bulk convention, whose effective distance can be lower than the requested code distance.

Examples

>>> import bloq
>>> graph = bloq.GalleryItem.X_MEMORY.load()
>>> bloq.compile(graph, distance=3)
<Bloq nodes=2 edges=1 qubits=17>

class bloq.CompileContext

class CompileContext(distance: int = 3, *, prepare_t_with_mpps: bool = False, limits: Mapping[str, int | None] | None = None)¶

A reusable compilation context with a fixed configuration and a private template cache. The free compile function instead shares a process-global cache; use a context when its cache lifetime should follow one Python object.

compile releases the GIL and takes a shared receiver, so one context can serve several threads at once — the template cache is internally synchronized.

Examples

>>> import bloq
>>> context = bloq.CompileContext(distance=3)
>>> program = context.compile(bloq.GalleryItem.X_MEMORY.load())
>>> program.metadata[bloq.ir.CODE_DISTANCE_METADATA_KEY]
3

meth bloq.CompileContext.compile

compile(graph: BlockGraph, *, validate: bool = False) → Bloq¶

Compiles graph into a Bloq IR program.

Parameters:

graph: BlockGraph¶

The block graph to compile.

validate: bool = False¶

Explicitly audit the resulting IR, using this context’s Boolean limits. Defaults to False; compilation always performs its required local checks.

Raises:

CompileError – If compilation fails.

Emits:

CompileWarning: Once per advisory the compile recorded — currently

a spatial Hadamard pipe under the fixed-bulk convention, whose effective distance can be lower than the requested code distance.

Examples

>>> import bloq
>>> context = bloq.CompileContext(distance=3)
>>> context.compile(bloq.GalleryItem.X_MEMORY.load())
<Bloq nodes=2 edges=1 qubits=17>
>>> context.compile(bloq.GalleryItem.CNOT.load())  # reuses cached templates
<Bloq nodes=... edges=... qubits=65>

attr bloq.CompileContext.distance

distance¶

The fixed code distance used by this context.

attr bloq.CompileContext.prepare_t_with_mpps

prepare_t_with_mpps¶

Whether this context uses compact T-source MPP preparation.

func bloq.clear_compile_cache

clear_compile_cache() → None¶

Drops every circuit template cached by compile, releasing their memory.

compile caches templates process-wide and never evicts them, so a process that compiles at many code distances — a distance sweep, say — keeps every distance’s templates resident. Call this between phases of such a run to give the memory back; the next compile simply refills the cache.

Compilations already in flight on other threads are unaffected.

Examples

>>> import bloq
>>> bloq.compile(bloq.GalleryItem.X_MEMORY.load(), distance=3)
<Bloq nodes=2 edges=1 qubits=17>
>>> bloq.clear_compile_cache()
>>> bloq.compile(bloq.GalleryItem.X_MEMORY.load(), distance=3)  # recompiles
<Bloq nodes=2 edges=1 qubits=17>

func bloq.is_valid_distance

is_valid_distance(distance: int) → bool¶

Whether distance is a code distance this compiler accepts: odd and in 3..=255.

Use it to filter a sweep before compiling. Negative and arbitrarily large integers return False; non-integers raise TypeError.

Parameters:

distance: int¶

The candidate code distance.

Examples

>>> import bloq
>>> [d for d in (1, 2, 3, 4, 1000) if bloq.is_valid_distance(d)]
[3]

Clifford proxies¶

Clifford proxies replace T resources with perfect input ports and pin selective sites to measurement arms. Supply the pins explicitly, or use the random helper with a seed for reproducibility. These programs support circuit-distance analysis; they do not verify the original non-Clifford computation or replace structural branch selection.

func bloq.compile_clifford_proxy

compile_clifford_proxy(graph: BlockGraph, pins: collections.abc.Sequence[bool], distance: int = 3, *, prepare_t_with_mpps: bool = False, limits: Mapping[str, int | None] | None = None) → Bloq¶

Compiles graph with every dynamic element replaced by a Clifford stand-in — a distance oracle, not a semantics oracle. Each selective block is statically pinned to one measurement arm by the corresponding pins bit (deterministic block order, one bit per selective site); T blocks become perfect input ports. The result suits Stim distance searches such as shortest_graphlike_error.

pins carries one bit per selective site in deterministic block order; pass an empty list for a graph with no selective blocks.

Both this function and compile_random_clifford_proxy accept simple and hierarchical block graphs. The detector-slice proxy remains an editor view and retains T regions, so it is not a Stim distance-search circuit.

Parameters:

graph: BlockGraph¶

The block graph to compile.

pins: collections.abc.Sequence[bool]¶

One bit per selective site in deterministic block order, pinning each to a measurement arm; empty when the graph has no selective blocks.

distance: int = 3¶

The odd code distance to compile at, in 3..=255.

prepare_t_with_mpps: bool = False¶

Use compact T-source preparation with one stabilizer MPP instead of MSC-LS cultivation.

limits: Mapping[str, int | None] | None = None¶

Compiler budget overrides; non-negative counts impose a budget, None disables it, and omitted fields keep their defaults.

Raises:

• CompileError – If compilation fails.

• InvalidArgumentError – If the distance or a limit field is invalid.

• OverflowError – If a limit count is negative or exceeds usize.

Emits:

CompileWarning: Once per advisory the compile recorded — currently a

spatial Hadamard pipe under the fixed-bulk convention, whose effective distance can be lower than the requested code distance.

Examples

>>> import bloq
>>> graph = bloq.GalleryItem.X_MEMORY.load()
>>> bloq.compile_clifford_proxy(graph, [], distance=3).quantum_node_count
1

func bloq.compile_random_clifford_proxy

compile_random_clifford_proxy(graph: BlockGraph, distance: int = 3, *, prepare_t_with_mpps: bool = False, seed: int | None = None, limits: Mapping[str, int | None] | None = None) → Bloq¶

Compiles one random static Clifford proxy path. Shared selective controls are sampled jointly; the seed is stored under CLIFFORD_PROXY_SEED_METADATA_KEY.

Parameters:

graph: BlockGraph¶

The block graph to compile.

distance: int = 3¶

The odd code distance to compile at, in 3..=255.

prepare_t_with_mpps: bool = False¶

T preparation option; proxy T blocks remain ports.

seed: int | None = None¶

Reproducible path seed; None generates one.

limits: Mapping[str, int | None] | None = None¶

Compiler budget overrides; non-negative counts impose a budget, None disables it, and omitted fields keep their defaults.

Source authoring¶

BlockGraph owns source geometry, actions, and module definitions. Its BLOG load/save operations retain authored hierarchy; compilation consumes that same graph representation. Call flatten() only when an independent flat projection is needed, such as for an explicit port-filling experiment.

Use ActionDag and expressions for named measurements, feedback, and control. GalleryItem.load() supplies reusable examples. The BLOG format describes the corresponding source syntax.

class bloq.BlockGraph

class BlockGraph¶

A graph of surface code blocks connected by pipes.

Blocks sit at integer lattice positions; pipes are lattice-surgery connections between adjacent blocks. Build one incrementally with add_block / add_pipe, load a ready-made graph from GalleryItem, or parse .blog text with parse_blog.

Examples

>>> from bloq import BlockGraph, Block, Pipe
>>> graph = BlockGraph()
>>> graph.add_block(Block((0, 0, 0), "ZXZ"))
(0, 0, 0)
>>> graph.add_block(Block((0, 0, 1), "ZXZ"))
(0, 0, 1)
>>> graph.add_pipe(Pipe((0, 0, 0), "+Z"))
>>> graph.block_count, graph.pipe_count
(2, 1)
>>> graph.validate()

meth bloq.BlockGraph.definition

static definition(name: str, body: BlockGraph, *, inputs: dict[str, tuple[int, int, int]] | None = None, outputs: dict[str, tuple[int, int, int]] | None = None, bit_inputs: collections.abc.Sequence[str] | None = None, bit_outputs: dict[str, Expr | str] | None = None, actions: collections.abc.Sequence[Action] | None = None, resources: Mapping[str, str] | None = None) → BlockGraph¶

Copies a graph into a reusable module definition. Omitted interface arguments retain the body’s existing declarations. Quantum port dictionaries retain insertion order; positions name local Port blocks. Supplying inputs or outputs replaces the quantum interface. Child instances and connections are retained. Validate the completed hierarchy with from_definitions.

Parameters:

name: str¶

Definition name; use main for the executable root.

body: BlockGraph¶

Graph containing local geometry, actions, and child instances.

inputs: dict[str, tuple[int, int, int]] | None = None¶

Names and positions of quantum input Ports.

outputs: dict[str, tuple[int, int, int]] | None = None¶

Names and positions of quantum output Ports.

bit_inputs: collections.abc.Sequence[str] | None = None¶

Classical names supplied by the parent.

bit_outputs: dict[str, Expr | str] | None = None¶

Exported expressions or local/child value names.

actions: collections.abc.Sequence[Action] | None = None¶

Optional replacement actions, using the declared bit inputs.

resources: Mapping[str, str] | None = None¶

Quantum port resource types; unspecified ports use data.

Raises:

• InvalidArgumentError – If a resource names an undeclared port.

• BlockGraphError – If classical input declarations are invalid.

meth bloq.BlockGraph.from_definitions

static from_definitions(definitions: collections.abc.Sequence[BlockGraph], *, limits: Mapping[str, int | None] | None = None) → BlockGraph¶

Assembles module definitions into a validated hierarchy rooted at main. Each definition is stored once; input graphs remain independent. Definitions must be local graphs without their own helper libraries.

Parameters:

definitions: collections.abc.Sequence[BlockGraph]¶

Reusable definitions and one executable main.

limits: Mapping[str, int | None] | None = None¶

Source-analysis and expansion budget overrides.

Raises:

BlockGraphError – If names, interfaces, seams, geometry, or dependencies are invalid.

meth bloq.BlockGraph.from_text

static from_text(text: str, *, limits: Mapping[str, int | None] | None = None) → BlockGraph¶

Parses .blog text into a block graph, retaining module definitions, instances, interfaces, and connections. This is the same native constructor as Rust’s BlockGraph::from_text. Use load() to resolve imports relative to a file.

Parameters:

text: str¶

The .blog source text.

limits: Mapping[str, int | None] | None = None¶

Source-analysis and module-expansion budget overrides. Use non-negative counts or None for unlimited; compilation overrides are passed separately to compile.

Raises:

• ParseError – If text is not valid .blog.

• InvalidArgumentError – If a limit field is unknown.

• OverflowError – If a limit count is negative or exceeds usize.

meth bloq.BlockGraph.load

static load(path: str | os.PathLike | pathlib.Path, *, limits: Mapping[str, int | None] | None = None) → BlockGraph¶

Loads a .blog file through Rust’s native BlockGraph::load constructor, resolving module imports relative to each file.

Like from_text, retains the module hierarchy. Both simple and hierarchical graphs are accepted by compile.

Parameters:

path: str | os.PathLike | pathlib.Path¶

A filesystem path, including pathlib.Path objects.

limits: Mapping[str, int | None] | None = None¶

Source-analysis and module-expansion budget overrides. Use non-negative counts or None for unlimited; the same limits apply to each imported hierarchy.

Raises:

• OSError – If the root file or an imported file cannot be read.

• ParseError – If BLOG parsing or module resolution fails.

• BlockGraphError – If graph structure is invalid.

• InvalidArgumentError – If a limit field is unknown.

• OverflowError – If a limit count is negative or exceeds usize.

meth bloq.BlockGraph.action_graph

action_graph() → ActionDag¶

Returns an independent snapshot of the current source action DAG.

Local structural edits refresh the cached DAG. is_analyzed says whether correlation support dependencies are present. For child instances, call flatten() explicitly to inspect the combined action program.

meth bloq.BlockGraph.actions

actions() → list[Action]¶

The graph’s actions as structured Action values; str(action) renders the BLOG statement (positions, not block ids).

meth bloq.BlockGraph.add_action

add_action(action: Action) → None¶

Appends one structured action, rederiving measurement surfaces and the action DAG.

Parameters:

action: Action¶

The structured action to append.

Raises:

BlockGraphError – If action semantics, measurement-surface derivation, or the resulting dependency DAG is invalid.

meth bloq.BlockGraph.add_actions_from_text

add_actions_from_text(text: str) → None¶

Appends actions parsed from BLOG action-statement text, e.g. "m = measure 0 -> +Z". Block IDs refer to get_block_id values.

Parameters:

text: str¶

BLOG action-statement text; numeric block IDs refer to get_block_id values.

Raises:

• ParseError – If text is not valid action-statement syntax.

• BlockGraphError – If action semantics, measurement-surface derivation, or the resulting dependency DAG is invalid.

Examples

>>> from bloq import BlockGraph, Block
>>> graph = BlockGraph()
>>> graph.add_block(Block((0, 0, 0), "ZXZ"))
(0, 0, 0)
>>> graph.add_actions_from_text("m = measure 0")
>>> [str(a) for a in graph.actions()]
['m = measure [0, 0, 0]']

meth bloq.BlockGraph.add_block

add_block(block: Block) → tuple[int, int, int]¶

Adds a block, returning its position. Raises BlockGraphError if the position is occupied.

Parameters:

block: Block¶

The block to add.

meth bloq.BlockGraph.add_branches

add_branches(branches: collections.abc.Sequence[Branch], *, pipes: collections.abc.Sequence[Pipe] | None = None, actions: collections.abc.Sequence[Action] | None = None) → None¶

Attaches branches, shared seams, and additional actions in one edit. Each branch supplies its own resolve condition. Existing actions remain. The graph is unchanged if geometry or action validation fails.

Parameters:

branches: collections.abc.Sequence[Branch]¶

Named branches with explicit false and true arms.

pipes: collections.abc.Sequence[Pipe] | None = None¶

Shared pipes joining arm boundaries to the common graph or other branches. They are stored once, outside the arms.

actions: collections.abc.Sequence[Action] | None = None¶

Additional actions, including measurements used by selectors.

Raises:

BlockGraphError – If geometry, interfaces, names, or actions are invalid.

meth bloq.BlockGraph.add_instance

add_instance(name: str, definition: str, translation: tuple[int, int, int] = (0, 0, 0), *, rotation: tuple[UDirection | str, int] | None = None) → None¶

Places a named child definition, rotating before translating. The completed hierarchy checks names, geometry, and supported orientations.

Parameters:

name: str¶

Instance name in this parent.

definition: str¶

Reusable definition name.

translation: tuple[int, int, int] = (0, 0, 0)¶

Placement in the parent’s lattice coordinates.

rotation: tuple[UDirection | str, int] | None = None¶

Optional axis and angle in degrees, such as ("Z", 180).

Raises:

InvalidArgumentError – If the axis or rotation angle is invalid.

meth bloq.BlockGraph.add_pipe

add_pipe(pipe: Pipe) → None¶

Adds a pipe. Raises BlockGraphError if an endpoint is missing or the pipe already exists.

Parameters:

pipe: Pipe¶

The pipe to add.

meth bloq.BlockGraph.analyze_action_graph

analyze_action_graph(*, limits: Mapping[str, int | None] | None = None) → ActionDag¶

Derives an independent DAG including correlation support dependencies.

Accepts local graphs and authored module hierarchies without changing the source. Hierarchies use the compiler’s module linker and correlation composition. owners() identifies each action’s definition and instance. Continuing branches use guarded causal readout planning.

Parameters:

limits: Mapping[str, int | None] | None = None¶

Source-analysis budget overrides, as accepted by from_text.

Raises:

• BlockGraphError – If module validation, readout analysis or resource limits fail.

• InvalidArgumentError – If a limit field is unknown.

• OverflowError – If a limit count is negative or exceeds usize.

Examples

>>> import bloq
>>> source = bloq.GalleryItem.T_GATE.load()
>>> dag = source.analyze_action_graph()
>>> dag.is_analyzed
True

meth bloq.BlockGraph.bind

bind(source: str, target: str) → None¶

Supplies a parent value or child bit output to a child classical input. For example, bind("read.result", "correct.flip") creates a dependency between those instances. The completed hierarchy validates the binding.

Raises:

InvalidArgumentError – If a qualified endpoint is malformed.

meth bloq.BlockGraph.bind_modules

bind_modules(source: str, target: str) → None¶

Binds a parent value or child bit output to a child’s classical input. Replaces the current binding and removes an unused exposed parent input.

Raises:

BlockGraphError – If values or dependencies are invalid; the graph is unchanged.

meth bloq.BlockGraph.blocks

blocks() → list[Block]¶

Blocks authored in this definition’s local body, excluding child instances.

meth bloq.BlockGraph.can_place_block

can_place_block(block: Block) → bool¶

Returns True when block can be placed without overlap.

Parameters:

block: Block¶

The candidate block to test.

meth bloq.BlockGraph.clear_actions

clear_actions() → None¶

Removes all actions from the graph.

meth bloq.BlockGraph.connect

connect(source: tuple[int, int, int] | str, target: tuple[int, int, int] | str, *, hadamard: bool = False) → None¶

Connects a child quantum output to an input or a parent-local block. Endpoints are local position tuples or strings such as gate.q_out. At least one endpoint must belong to an instance. Connections do not route geometry; the completed hierarchy checks placement and boundary bases.

Raises:

InvalidArgumentError – If endpoint syntax is invalid or both endpoints are local.

meth bloq.BlockGraph.connect_modules

connect_modules(output: str, input: str, *, align: bool = True, compact: bool = True, hadamard: bool = False) → int¶

Aligns and docks named child ports, joining all other touching compatible ports. The input instance’s connected group moves together. Endpoint Hadamards are preserved; obstructed compaction retains connection cubes.

Parameters:

output: str¶

Child output name, such as child0.control_out.

input: str¶

Child input name, such as child1.control_in.

align: bool = True¶

Align the input group’s selected port to the output.

compact: bool = True¶

Prefer direct seams over parent connection cubes.

hadamard: bool = False¶

Extra basis change at the selected seam.

Returns:

Number of port pairs joined.

Raises:

BlockGraphError – If ports, types, faces, or placement are invalid; the graph is unchanged.

meth bloq.BlockGraph.degree

degree(pos: tuple[int, int, int]) → int¶

The number of pipes attached to the block at pos.

Parameters:

pos: tuple[int, int, int]¶

The (x, y, z) lattice position.

meth bloq.BlockGraph.export_gltf

export_gltf(path: str | os.PathLike | pathlib.Path, pipe_length: float = 2.0, stabilizer: StabilizerGenerator | collections.abc.Sequence[int] | None = None, pop_faces_at_directions: collections.abc.Sequence[Direction | str] | None = None, pop_faces_at_blocks: collections.abc.Sequence[tuple[tuple[int, int, int], Direction | str]] | None = None, pop_faces_at_pipes: collections.abc.Sequence[tuple[tuple[int, int, int], tuple[int, int, int], Direction | str]] | None = None, module_view: bool = False) → None¶

Exports the graph as a .gltf scene, optionally overlaying a stabilizer row. Set module_view=True to color an authored hierarchy by definition.

Parameters:

path: str | os.PathLike | pathlib.Path¶

Filesystem path to write the .gltf file to.

pipe_length: float = 2.0¶

Rendered pipe length in scene units. Defaults to 2.0.

module_view: bool = False¶

Color by module definition without changing the hierarchy. Cannot be combined with a stabilizer overlay.

stabilizer: StabilizerGenerator | collections.abc.Sequence[int] | None = None¶

Optional generator, or indices of logical generators whose phase-free product supplies the displayed correlation support.

pop_faces_at_directions: collections.abc.Sequence[Direction | str] | None = None¶

Signed lattice directions whose outward faces are removed, for example ["-Y"].

pop_faces_at_blocks: collections.abc.Sequence[tuple[tuple[int, int, int], Direction | str]] | None = None¶

(position, face_direction) pairs selecting individual block faces.

pop_faces_at_pipes: collections.abc.Sequence[tuple[tuple[int, int, int], tuple[int, int, int], Direction | str]] | None = None¶

(u, v, face_direction) triples selecting individual pipe faces.

Raises:

OSError – If the file cannot be written.

meth bloq.BlockGraph.export_html_viewer

export_html_viewer(path: str | os.PathLike | pathlib.Path, pipe_length: float = 2.0, stabilizer: StabilizerGenerator | collections.abc.Sequence[int] | None = None, pop_faces_at_directions: collections.abc.Sequence[Direction | str] | None = None, pop_faces_at_blocks: collections.abc.Sequence[tuple[tuple[int, int, int], Direction | str]] | None = None, pop_faces_at_pipes: collections.abc.Sequence[tuple[tuple[int, int, int], tuple[int, int, int], Direction | str]] | None = None, module_view: bool = False) → None¶

Exports the graph as a self-contained HTML viewer page (the model-viewer renderer is loaded from a CDN, so viewing needs network). Set module_view=True for the editor’s definition colors and module legend.

Parameters:

path: str | os.PathLike | pathlib.Path¶

Filesystem path to write the HTML file to.

pipe_length: float = 2.0¶

Rendered pipe length in scene units. Defaults to 2.0.

module_view: bool = False¶

Color by module definition without changing the hierarchy. Cannot be combined with a stabilizer overlay.

stabilizer: StabilizerGenerator | collections.abc.Sequence[int] | None = None¶

Optional generator, or indices of logical generators whose phase-free product supplies the displayed correlation support.

pop_faces_at_directions: collections.abc.Sequence[Direction | str] | None = None¶

Signed lattice directions whose outward faces are removed, for example ["-Y"].

pop_faces_at_blocks: collections.abc.Sequence[tuple[tuple[int, int, int], Direction | str]] | None = None¶

(position, face_direction) pairs selecting individual block faces.

pop_faces_at_pipes: collections.abc.Sequence[tuple[tuple[int, int, int], tuple[int, int, int], Direction | str]] | None = None¶

(u, v, face_direction) triples selecting individual pipe faces.

Raises:

OSError – If the file cannot be written.

meth bloq.BlockGraph.fill_ports_auto

fill_ports_auto() → list[tuple[BlockGraph, list[StabilizerGenerator]]]¶

Builds compatible static boundary fills, returning (closed_graph, stabilizer_generators) pairs.

Port, T, and Selective sites use full compatible boundary support. Variants retain selected measurement records and aliases, and remove feedback and resolves for filled caps.

filled_graphs() is the same thing without the generators, for the common case of only wanting the closed graphs. Call flatten() first for authored module interfaces or child instances.

Raises:

BlockGraphError – If a boundary cannot be filled, or postselection or a structural branch needs an omitted measurement record.

meth bloq.BlockGraph.filled_graphs

filled_graphs() → list[BlockGraph]¶

The graphs from fill_ports_auto(), without their selecting generators. Call flatten() first for authored module interfaces or child instances.

Raises:

BlockGraphError – If the ports cannot be filled.

Examples

>>> import bloq
>>> filled = bloq.GalleryItem.BELL_STATE.load().flatten().filled_graphs()
>>> all(not graph.is_open for graph in filled)
True

meth bloq.BlockGraph.flatten

flatten(*, limits: Mapping[str, int | None] | None = None) → BlockGraph¶

Expands module instances into one independent graph for geometry, boundary filling, or flat source analysis. Compilation preserves the hierarchy and does not require this conversion.

Parameters:

limits: Mapping[str, int | None] | None = None¶

Source-expansion budget overrides. Use non-negative counts or None for unlimited; omitted fields retain their defaults.

Raises:

BlockGraphError – If expansion cannot produce a valid flat graph.

meth bloq.BlockGraph.flip_xz_basis

flip_xz_basis() → BlockGraph¶

Returns a new graph with X/Z bases flipped (topology-preserving). Call flatten() first for authored module interfaces or child instances.

Raises:

BlockGraphError – If the basis flip cannot be applied.

meth bloq.BlockGraph.get_block

get_block(pos: tuple[int, int, int]) → Block | None¶

Returns the block at pos, or None if absent.

Parameters:

pos: tuple[int, int, int]¶

The (x, y, z) lattice position.

meth bloq.BlockGraph.get_block_id

get_block_id(pos: tuple[int, int, int]) → int | None¶

Returns the internal node ID for the block at pos, or None.

Parameters:

pos: tuple[int, int, int]¶

The (x, y, z) lattice position.

meth bloq.BlockGraph.get_pipe

get_pipe(u: tuple[int, int, int], v: tuple[int, int, int]) → Pipe | None¶

Returns the pipe between u and v, or None if absent.

Parameters:

u: tuple[int, int, int]¶

One endpoint position (x, y, z).

v: tuple[int, int, int]¶

The other endpoint position (x, y, z).

meth bloq.BlockGraph.has_actions

has_actions() → bool¶

True if the graph carries any actions.

meth bloq.BlockGraph.has_block_at

has_block_at(pos: tuple[int, int, int]) → bool¶

True if a block occupies pos.

Parameters:

pos: tuple[int, int, int]¶

The (x, y, z) lattice position.

meth bloq.BlockGraph.has_pipe_between

has_pipe_between(u: tuple[int, int, int], v: tuple[int, int, int]) → bool¶

True if a pipe connects u and v.

Parameters:

u: tuple[int, int, int]¶

One endpoint position (x, y, z).

v: tuple[int, int, int]¶

The other endpoint position (x, y, z).

meth bloq.BlockGraph.module

module(name: str, *, limits: Mapping[str, int | None] | None = None) → BlockGraph¶

Extracts a named definition as an independent graph, retaining its reachable helper definitions and naming its executable root main. The copy can be edited, saved, pickled, and compiled independently.

Parameters:

name: str¶

The definition name.

limits: Mapping[str, int | None] | None = None¶

Source-analysis and expansion budget overrides.

Raises:

• KeyError – If the definition is absent.

• BlockGraphError – If its independent hierarchy cannot be constructed.

meth bloq.BlockGraph.neighbors

neighbors(pos: tuple[int, int, int]) → list[Block]¶

All blocks directly connected to the block at pos.

Parameters:

pos: tuple[int, int, int]¶

The (x, y, z) lattice position.

meth bloq.BlockGraph.occupied_positions

occupied_positions() → list[tuple[int, int, int]]¶

Local lattice cells reserved by blocks (multi-cell blocks contribute their full footprint).

meth bloq.BlockGraph.pipes

pipes() → list[Pipe]¶

Pipes authored in this definition’s local body, excluding child instances.

meth bloq.BlockGraph.place_module

place_module(name: str, definition: str, translation: tuple[int, int, int] | None = None, *, rotation: tuple[UDirection | str, int] | None = None) → tuple[int, int, int]¶

Places a module instance and exposes its quantum and classical interface. With no translation, places it beside the current geometry. The graph must contain the named definition; input graphs remain independent.

Parameters:

name: str¶

New instance name.

definition: str¶

Definition already stored in this graph.

translation: tuple[int, int, int] | None = None¶

Optional explicit lattice placement.

rotation: tuple[UDirection | str, int] | None = None¶

Optional axis and angle, such as ("Z", 180).

Returns:

The instance’s translation.

Raises:

BlockGraphError – If placement, names, or interfaces are invalid; the graph is unchanged.

meth bloq.BlockGraph.placement_error

placement_error(block: Block) → str | None¶

Why block cannot be placed, or None when it can.

The message add_block would have raised, without raising it — for callers reporting the reason rather than just refusing.

Parameters:

block: Block¶

The candidate block to test.

Examples

>>> import bloq
>>> graph = bloq.BlockGraph()
>>> graph.add_block(bloq.Block((0, 0, 0), "ZXZ"))
(0, 0, 0)
>>> graph.placement_error(bloq.Block((0, 0, 1), "ZXZ")) is None
True
>>> "occupied" in graph.placement_error(bloq.Block((0, 0, 0), "ZXZ"))
True

meth bloq.BlockGraph.positions

positions() → list[tuple[int, int, int]]¶

Positions of this definition’s local blocks, excluding child instances.

meth bloq.BlockGraph.project_branches

project_branches(assignments: collections.abc.Sequence[tuple[tuple[int, int, int], bool]]) → BlockGraph¶

Projects every structural branch to a static true or false arm.

The returned graph has no branch actions and can be passed to stabilizers(). Every branch target must appear exactly once. Call flatten() first for authored module interfaces or child instances.

Parameters:

assignments: collections.abc.Sequence[tuple[tuple[int, int, int], bool]]¶

(target_position, value) pairs for every branch.

Raises:

BlockGraphError – If a target is unknown, duplicated, or omitted, or the branch regions are invalid.

meth bloq.BlockGraph.randomly_resolve_selectives

randomly_resolve_selectives(seed: int | None = None) → tuple[BlockGraph, dict[Block, Block]]¶

Resolves all selective blocks by randomly choosing a measurement basis. Returns (resolved_graph, replacements) where replacements maps each original selective block to its resolved block. Deterministic when seed is given.

If any selective is resolved, the returned graph is structure-only and has no actions, including structural branches. Project branches first when a concrete conditional topology is required. Call flatten() first for authored module interfaces or child instances.

Parameters:

seed: int | None = None¶

Optional RNG seed; when given, resolution is deterministic. Defaults to None (nondeterministic).

meth bloq.BlockGraph.remove_block

remove_block(pos: tuple[int, int, int]) → Block | None¶

Removes and returns the block at pos, or None if absent.

Parameters:

pos: tuple[int, int, int]¶

The (x, y, z) lattice position.

meth bloq.BlockGraph.remove_pipe

remove_pipe(u: tuple[int, int, int], v: tuple[int, int, int]) → Pipe | None¶

Removes and returns the pipe between u and v, or None if absent.

Parameters:

u: tuple[int, int, int]¶

One endpoint position (x, y, z).

v: tuple[int, int, int]¶

The other endpoint position (x, y, z).

meth bloq.BlockGraph.rotate_about_origin

rotate_about_origin(axis: UDirection | str, quarter_turns: int) → BlockGraph¶

Returns a new graph rotated about the origin around axis by quarter_turns 90-degree steps. Discards actions. Call flatten() first for authored module interfaces or child instances.

Parameters:

axis: UDirection | str¶

A UDirection or its axis letter ("X" / "Y" / "Z").

quarter_turns: int¶

Number of 90-degree steps; may be negative.

Raises:

• InvalidArgumentError – If axis is invalid or a rotated position exceeds the 32-bit coordinate range.

• BlockGraphError – If the rotation cannot be applied.

meth bloq.BlockGraph.save

save(path: str | os.PathLike | pathlib.Path) → None¶

Writes the graph to a .blog file.

Parameters:

path: str | os.PathLike | pathlib.Path¶

Filesystem path to write the .blog file to.

Raises:

OSError – If the file cannot be written.

meth bloq.BlockGraph.set_actions

set_actions(actions: collections.abc.Sequence[Action]) → None¶

Replaces all actions, rederiving measurement surfaces and the action DAG.

Parameters:

actions: collections.abc.Sequence[Action]¶

The structured actions to install, replacing any existing.

Raises:

BlockGraphError – If action semantics, measurement-surface derivation, or the resulting dependency DAG is invalid.

meth bloq.BlockGraph.set_block_kind

set_block_kind(pos: tuple[int, int, int], kind: BlockKind | str) → None¶

Replaces the kind of the block at pos.

Parameters:

pos: tuple[int, int, int]¶

The (x, y, z) lattice position.

kind: BlockKind | str¶

A BlockKind or its BLOG spelling.

Raises:

• InvalidArgumentError – If kind is an invalid spelling.

• BlockGraphError – If no block occupies pos, or the new kind is incompatible.

meth bloq.BlockGraph.set_block_tag

set_block_tag(pos: tuple[int, int, int], tag: str) → None¶

Replaces the tag of the block at pos.

Parameters:

pos: tuple[int, int, int]¶

The (x, y, z) lattice position.

tag: str¶

The new tag string.

Raises:

BlockGraphError – If no block occupies pos.

meth bloq.BlockGraph.set_pipe_hadamard

set_pipe_hadamard(u: tuple[int, int, int], v: tuple[int, int, int], hadamard: bool) → None¶

Sets whether the pipe between u and v carries a Hadamard.

Parameters:

u: tuple[int, int, int]¶

One endpoint position (x, y, z).

v: tuple[int, int, int]¶

The other endpoint position (x, y, z).

hadamard: bool¶

Whether the pipe carries a Hadamard across the seam.

Raises:

BlockGraphError – If no pipe connects u and v.

meth bloq.BlockGraph.set_pipe_tag

set_pipe_tag(u: tuple[int, int, int], v: tuple[int, int, int], tag: str) → None¶

Replaces the tag of the pipe between u and v.

Parameters:

u: tuple[int, int, int]¶

One endpoint position (x, y, z).

v: tuple[int, int, int]¶

The other endpoint position (x, y, z).

tag: str¶

The new tag string.

Raises:

BlockGraphError – If no pipe connects u and v.

meth bloq.BlockGraph.set_port_role

set_port_role(pos: tuple[int, int, int], role: str) → None¶

Assigns a Port’s "auto", "input", "output", or "multiplex" role.

meth bloq.BlockGraph.shift_positions

shift_positions(offset: tuple[int, int, int]) → BlockGraph¶

Returns a new graph shifted by offset. Call flatten() first for authored module interfaces or child instances.

Parameters:

offset: tuple[int, int, int]¶

The (x, y, z) amount to shift every position by.

Raises:

• InvalidArgumentError – If a shifted position exceeds the 32-bit coordinate range.

• BlockGraphError – If the graph retains module structure.

meth bloq.BlockGraph.stabilizers

stabilizers() → list[StabilizerGenerator]¶

Derives the stabilizer generators of the graph’s ZX diagram. Call flatten() first if the graph contains child instances.

Raises:

BlockGraphError – If the stabilizers cannot be derived.

Examples

>>> import bloq
>>> graph = bloq.GalleryItem.X_MEMORY.load()
>>> graph.stabilizers()[0].kind
'logical'

meth bloq.BlockGraph.to_text

to_text() → str¶

Serializes the graph to .blog text (BLOG 1.0).

meth bloq.BlockGraph.translate_module

translate_module(name: str, offset: tuple[int, int, int], *, compact: bool = True) → tuple[int, int, int]¶

Translates a connected group and joins touching compatible free ports. Returns the applied offset, including any successful compaction.

Raises:

BlockGraphError – If geometry or interfaces are invalid; the graph is unchanged.

meth bloq.BlockGraph.validate

validate() → None¶

Validates structural constraints and action semantics.

Raises:

BlockGraphError – If a structural or action-semantic constraint is violated.

meth bloq.BlockGraph.validate_structure

validate_structure() → None¶

Validates structural constraints only (skips action semantics).

Raises:

BlockGraphError – If a structural constraint is violated.

meth bloq.BlockGraph.with_zero_min_z

with_zero_min_z() → BlockGraph¶

Returns a new graph shifted so the minimum z-coordinate is zero. Call flatten() first for authored module interfaces or child instances.

Raises:

• InvalidArgumentError – If normalization exceeds the 32-bit coordinate range.

• BlockGraphError – If the graph retains module structure.

attr bloq.BlockGraph.block_count

block_count¶

Number of blocks in this definition’s local body, excluding child instances.

attr bloq.BlockGraph.has_module_structure

has_module_structure¶

Whether the graph declares module interfaces, instances, or definitions. A leaf with an explicit quantum or classical interface also returns true.

attr bloq.BlockGraph.is_clifford

is_clifford¶

True when the graph and its reachable instances contain no T blocks.

attr bloq.BlockGraph.is_empty

is_empty¶

True if the graph and its reachable instances have no blocks.

attr bloq.BlockGraph.is_open

is_open¶

True when the graph contains at least one port.

attr bloq.BlockGraph.is_rigid

is_rigid¶

True when every block, including reachable instances, has a statically known kind (no selectives).

attr bloq.BlockGraph.module_names

module_names¶

Names of all graph definitions, including the root.

attr bloq.BlockGraph.patch_rotation_count

patch_rotation_count¶

Number of patch-rotation blocks in this definition’s local body.

attr bloq.BlockGraph.pipe_count

pipe_count¶

Number of pipes in this definition’s local body, excluding child instances.

attr bloq.BlockGraph.port_count

port_count¶

Number of port blocks in this definition’s local body.

attr bloq.BlockGraph.selective_count

selective_count¶

Number of selective blocks in this definition’s local body.

attr bloq.BlockGraph.t_count

t_count¶

Number of T blocks in this definition’s local body.

attr bloq.BlockGraph.walking_count

walking_count¶

Number of walking blocks in this definition’s local body.

attr bloq.BlockGraph.y_count

y_count¶

Number of Y blocks in this definition’s local body.

class bloq.Block

class Block(pos: tuple[int, int, int], kind: BlockKind | str, height: str = 'd', tag: str | None = None, role: str = 'auto')¶

A block placed at a 3D lattice position.

The kind argument accepts a BlockKind or its BLOG spelling ("ZXZ", "T", …).

Examples

>>> from bloq import Block
>>> b = Block((0, 1, 2), "ZXZ")
>>> b.pos
(0, 1, 2)
>>> str(b.kind)
'ZXZ'

attr bloq.Block.height

height¶

The block’s height as a k*d + n expression of the code distance, in the canonical BLOG spelling ("d", "2d", "d/2", "3d+2").

attr bloq.Block.kind

kind¶

The block’s kind.

attr bloq.Block.pos

pos¶

The block’s (x, y, z) lattice position.

attr bloq.Block.role

role¶

The Port’s "auto", "input", "output", or "multiplex" role; None for non-Ports.

attr bloq.Block.tag

tag¶

The block’s tag string, or None.

class bloq.BlockKind

class BlockKind¶

The kind of a block: a cube, a moving block, Y, a fixed measurement, Port, T, or a selective block. Data-carrying kinds are built via the static constructors.

Examples

>>> from bloq import BlockKind
>>> k = BlockKind.cube("ZXZ")
>>> k.is_cube
True
>>> tuple(str(b) for b in k.bases)
('Z', 'X', 'Z')
>>> BlockKind.t().is_clifford
False

meth bloq.BlockKind.cube

static cube(spec: str) → BlockKind¶

A cube block from its face-basis spelling, e.g. "XZZ".

Parameters:

spec: str¶

The three face bases as an X/Z string, e.g. "XZZ" (case-insensitive).

Raises:

InvalidArgumentError – If spec is not a valid cube spelling.

meth bloq.BlockKind.measurement

static measurement(basis: Basis | str) → BlockKind¶

A fixed terminal transversal measurement in the X or Z basis.

Parameters:

basis: Basis | str¶

A Basis or its "X" / "Z" letter (case-insensitive).

Raises:

InvalidArgumentError – If basis is not X or Z.

meth bloq.BlockKind.parse

static parse(text: str) → BlockKind¶

Parses a BLOG kind spelling ("XZZ", "X", "Y", "Z", "PORT", "T", "XY", …).

Walking and patch-rotation kinds carry movement data and cannot be spelled as a single token; build them via walking / patch_rotation.

Parameters:

text: str¶

A BLOG kind token, e.g. "XZZ", "X", "Y", "Z", "PORT", "T", or "XY".

Raises:

InvalidArgumentError – If text is not a valid single-token kind spelling.

meth bloq.BlockKind.patch_rotation

static patch_rotation(basis: Basis | str, movement: tuple[int, int]) → BlockKind¶

A patch-rotation block from a basis and an (x, y) movement of (+/-1, 0) or (0, +/-1).

Parameters:

basis: Basis | str¶

A Basis or its "X" / "Z" letter (case-insensitive).

movement: tuple[int, int]¶

The (x, y) step: (+/-1, 0) or (0, +/-1).

Raises:

InvalidArgumentError – If basis or movement is invalid.

meth bloq.BlockKind.port

static port() → BlockKind¶

An open port block.

meth bloq.BlockKind.selective

static selective(spec: str) → BlockKind¶

A selective block from its spelling ("XY", "XZ", or "YZ").

Parameters:

spec: str¶

The selective spelling: "XY", "XZ", or "YZ".

Raises:

InvalidArgumentError – If spec is not a valid selective spelling.

meth bloq.BlockKind.t

static t() → BlockKind¶

The non-Clifford T block.

meth bloq.BlockKind.walking

static walking(boundary: str, movement: tuple[int, int]) → BlockKind¶

A walking block from its boundary spelling (e.g. "ZXZ") and an (x, y) movement of (+/-1, 0), (0, +/-1), or (+/-1, +/-1).

Parameters:

boundary: str¶

The boundary basis spelling, e.g. "ZXZ" (case-insensitive).

movement: tuple[int, int]¶

The (x, y) step: (+/-1, 0), (0, +/-1), or (+/-1, +/-1).

Raises:

InvalidArgumentError – If boundary or movement is invalid.

meth bloq.BlockKind.y

static y() → BlockKind¶

The Y-basis block.

meth bloq.BlockKind.flip_xz_basis

flip_xz_basis() → BlockKind¶

Returns a new kind with X/Z bases flipped.

attr bloq.BlockKind.bases

bases¶

The (x, y, z) face bases, when this kind has a fixed basis assignment.

attr bloq.BlockKind.is_clifford

is_clifford¶

True if this kind is Clifford (everything except T).

attr bloq.BlockKind.is_cube

is_cube¶

True if this is a cube block.

attr bloq.BlockKind.is_dynamic

is_dynamic¶

True for kinds whose behavior is resolved at runtime (T, selective).

attr bloq.BlockKind.is_measurement

is_measurement¶

True if this is a fixed terminal measurement block.

attr bloq.BlockKind.is_patch_rotation

is_patch_rotation¶

True if this is a patch-rotation block.

attr bloq.BlockKind.is_port

is_port¶

True if this is an open port block.

attr bloq.BlockKind.is_selective

is_selective¶

True if this is a selective block.

attr bloq.BlockKind.is_t

is_t¶

True if this is a T block.

attr bloq.BlockKind.is_walking

is_walking¶

True if this is a walking (moving) block.

attr bloq.BlockKind.is_y

is_y¶

True if this is the Y-basis block.

attr bloq.BlockKind.measurement_basis

measurement_basis¶

The X or Z basis of a fixed measurement block; None for other kinds.

attr bloq.BlockKind.movement

movement¶

The (x, y) in-plane step of a walking or patch-rotation kind, as passed to walking / patch_rotation; None for kinds that do not move.

Examples

>>> from bloq import BlockKind
>>> BlockKind.walking("ZXZ", (1, 0)).movement
(1, 0)
>>> BlockKind.cube("ZXZ").movement is None
True