Crate bloq_ir 

Program IR for bloq compiler output.

Bloq is the public, circuit-bearing graph IR produced by bloq_compile and consumed by backend emitters.

Traversal

Reads are id-native: every graph level (the Bloq top level or a region SubGraph body) exposes the same accessors — SubGraph::node, SubGraph::nodes, SubGraph::incoming/SubGraph::outgoing (yielding BloqEdgeRefs), the dataflow queries SubGraph::value_inputs / SubGraph::value_output / SubGraph::boundary_outputs — and Bloq::walk/Bloq::levels recurse through region bodies with a LevelPath for cross-level node identity. The underlying petgraph storage is not public API.

Derived reads

Three layers sit on top of raw traversal, for questions a consumer would otherwise answer by matching on node variants itself:

• Structural queries (Bloq::regions_of, Bloq::selection_seams, Bloq::node_by_block, SubGraph::quantum_tail, …) name a program’s recurring landmarks. Callers use them to construct MemoryRoundTargets for Bloq::insert_memory_rounds or Bloq::insert_memory_rounds_batch.
• Bloq::resolve_classical folds the classical dataflow graph under a fixed path into the measurement recipe behind a node’s value, and Bloq::classical_value answers the other half of the same question: the bit that path already fixes, including an activation predicate.
• NodeKey is a provenance-derived node identity that survives recompilation, for lining one program up against another compile of the same block graph.

Exhaustive data enums (deliberate)

The data enums (BloqNodeKind, ClassicalNode, RegionNode, NodeProvenance, ValueRole, …) are intentionally not #[non_exhaustive]: a backend must fail to compile — not silently wildcard — when the IR grows a construct, because an unhandled node kind would emit wrong output rather than error (e.g. bloq_stim rejects each region variant by name). Do not “fix” this by adding #[non_exhaustive] to them; error enums, by contrast, are non-exhaustive.

Modules

circuit

Circuit vocabulary embedded by Bloq IR templates and annotations.

lowering

Compiler and backend lowering surface.

prelude

The most commonly used items, for use bloq_ir::prelude::*.

visualization

Graph visualization shared with the editor. Standalone SVG views of the physical program DAG, using the editor’s layout.

Structs

AlignedLayer

Serial aligned slots projected onto one doubled-z display layer.

AlignedMomentRef

One node-local moment placed into an aligned slot.

AlignedSlot

Concurrent compatible moments. None is a real idle slot.

Bloq

The compiled bloq circuit IR: a graph of quantum, classical, and region nodes produced by bloq_compile, consumed by emitters and the verifier.

BloqEdgeRef

A borrowed graph edge with id-space endpoints — the id-native view of one BloqEdge, so traversal never exposes petgraph types.

BloqNode

A graph node, tagged by what kind of work it represents.

BloqNodeId

A node’s slot index in its own graph level (a crate::Bloq top level or one region crate::SubGraph body) — ids are level-local, not program-global.

BloqStats

Structural counts across every graph level, including guarded and RUS bodies.

BundleDetector

One row stored in a reusable detector bundle.

BundleMeasurement

A measurement in one bundle-local owner slot.

ClassicalResolution

What a classical node’s value is made of, under one fixed path.

CoordinateOverflowError

A coordinate plus layout offset does not fit the signed 32-bit lattice.

CycleDetected

The graph contains a cycle, so it has no topological emit order.

DetectorBundle

Shared detector rows with an ordered template signature.

DetectorBundleId

A detector bundle’s append-only index in a program.

DetectorBundlePool

Append-only, clone-cheap bundle storage.

DetectorBundleUse

One node-local binding of a reusable detector bundle.

FlattenLimits

Work allowed when materializing a circuit’s repeated operation stream.

FramePair

Logical Pauli-frame sign nodes for one terminal output.

LevelPath

Path from the top level to one graph level: the chain of enclosing region body hops. Empty = the top level.

LevelSegment

One hop of a LevelPath: the region descended through and its selected body.

LogicalInput

Input-port metadata for physical preparation hooks.

LogicalOutput

Terminal logical Pauli operators for one program output.

MomentLane

One node’s raw moments and whole-circuit qubit footprint.

MomentSegment

One viewer moment: a bucket of visible same-kind ops plus any invisible measurement-controlled feedforward assigned to that boundary, in op order.

MomentSegmenter

Incremental viewer-moment segmentation for structural circuit walkers.

NodeCx

Context for one node visited by Bloq::walk.

NodeDetector

An instance-space detector on a crate::QuantumNode.

NodeDetectorView

A borrowed detector row, mapped into instance space on demand.

NodeDetectors

Inline rows followed by bundle uses in node order, then row order.

NodeKey

A node identity that survives recompilation and renumbering.

NodeRef

A tape-unique node reference.

NodeSlices

Per-moment regions for one node.

PipePadding

Memory-padding provenance for one temporal pipe.

PipeSeam

One temporal pipe on a quantum seam, with the memory-padding templates the compiler recorded for it.

ProgramRegion

Identity and coordinates stored once for every program region.

ProgramRegionBreak

A gauge anticommutation located back to the node timeline it falls in.

ProgramSliceOptions

Detector and logical-observable region choices for a pinned program.

ProgramSlices

The whole program’s detector-slice data, keyed by node.

QuantumEdge

A quantum face seam: its temporal pipes, each carrying the memory-padding templates that may subdivide it.

QuantumGuard

Members and side tables enabled by one quantum node’s Value input.

QuantumNode

A template-backed quantum node: its ops come from instantiating the referenced templates from the pool, not from any per-node circuit.

QuantumTimeline

Cumulative round cuts projecting a multi-layer block onto source z layers.

RegionRef

A program-unique address of one region node: the path to its graph level plus its level-local id.

RegionView

One detector or logical-observable region at one moment.

SourceBlockRef

A reference to one source block by its lattice position.

SubGraph

A nested region body.

TemplateDetector

One detector inside a template: a measurement parity at optional decoder coords, tagged by the body scope it lives in.

TemplateId

A template’s index into the program’s shared crate::BloqTemplatePool.

TemporalPipeRef

A reference to one source temporal pipe.

TextParseError

A syntax or structure error in Bloq IR text, with its 1-based line number.

ValidatedPlans

Quantum emission stages keyed by scoped node address.

ValueInput

One Value input of a node.

ValueRef

A level-local Boolean source and its selected output.

Enums

Basis

Pauli X or Z basis (excludes Y and identity).

BinaryDecodeError

Why a byte buffer failed to decode as a binary .bloq artifact.

BloqEdge

Quantum seams, Boolean dependencies, recipe composition, and sequencing.

BloqNodeKind

What a BloqNode computes.

BloqStatsError

Failure to inventory stored IR; this does not certify well-formedness.

BloqValidationError

A well-formedness violation or resource exhaustion from Bloq::validate.

BodySelector

The body of a RegionNode.

BoundaryFace

Which temporal face of an instance a boundary operator binds.

ClassicalAssignment

The fixed path a Bloq::resolve_classical fold evaluates under.

ClassicalExpr

Combinational logic over a classical node’s incoming Value edges.

ClassicalNode

Classical logic and observable recipes. Composition edges include a child’s measurements and boundary bindings; value edges select a Boolean output.

DetectorBundleError

Local structure errors found before any detector rows are expanded.

EditError

Why a post-compile graph edit was rejected.

FlattenError

Why a template or program could not be flattened. The target is left unmodified on any of these.

InstanceProvenance

Why a template instance exists.

MembershipPinError

Why source membership choices could not be pinned to a static realization.

MemoryRoundTarget

Program-unique location for physical memory-round insertion.

MetadataValue

A portable scalar stored in Bloq producer metadata.

MomentAlignmentError

Why raw node moments could not be aligned against their graph level.

MomentKind

The kind of a viewer moment: a bucket ops fall into within one tick segment.

NodeDetectorAddress

Stable address of a node detector row.

NodeProvenance

What source-level construct an IR node realizes.

ObservableOutput

Boolean output selected from an observable.

PortRole

Direction assigned to an open port.

ProgramRegionId

Stable identity of a detector or logical-observable region.

ProgramSliceError

Why program_detector_slices could not build the tape.

RegionKind

Which RegionNode variant a structural query selects.

RegionNode

A structured control-flow region.

ResolveError

Why a classical fold could not be completed.

SpatialPortPart

Which half of a spatial-Port substitution an instance realizes.

StructureError

Why a structural query found no unique answer.

ValueRole

Edge provenance on a BloqEdge::Value edge: what source construct routed this bit here.

WalkControl

Flow control returned from a Bloq::walk callback (MLIR WalkResult): whether to descend, prune, or stop after the current node.

Constants

BLOQ_BINARY_EXTENSION

The conventional file extension for the binary format.

BLOQ_BINARY_MAGIC

File magic prefixing every binary .bloq artifact.

BLOQ_BINARY_VERSION

Pre-release binary format version; stays at 1 during rapid development.

BLOQ_TEXT_EXTENSION

The conventional file extension for the text format.

BLOQ_TEXT_VERSION

The pre-release text format version. IR changes update the codec without bumping this value until the format is released.

Functions

align_moment_lanes

Align raw node moments into deterministic concurrent layer batches.

aligned_moment_segments

Split a straight-line circuit into alignable kind buckets and idle gaps.

moment_segments

Split a straight-line op stream into viewer moments, first at Op::Tick.

program_detector_slices

Compute detector-slice regions for every quantum node of program.

program_detector_slices_with_options

Compute detector-slice regions using explicit region choices.

Type Aliases

NodeDetectorParity

A measurement-only detector parity in instance space (InstanceMeasurement). Validation rejects the generic parity type’s loop-state terms (WF-6).