Crate bloq_graph 

Block graph representation for fault-tolerant surface code quantum computing.

This crate provides the core data structures for expressing quantum computations as graphs of surface code blocks connected by pipes (lattice surgery operations). It includes the .blog DSL parser, a block-graph gallery of standard circuits, ZX-calculus stabilizer analysis, and GLTF export for 3D visualization.

Public dependency: glam

glam is a public dependency: coordinates in the public API use [glam::IVec3], so its types appear in this crate’s signatures. The version is pinned to match the glam that bevy re-exports, keeping the editor and this crate on one vector type. A glam major-version bump is therefore a breaking change for this crate’s API even when nothing else here changes.

Re-exports

pub use bloq_utils::Basis;

pub use bloq_utils::Direction;

pub use bloq_utils::DirectionParseError;

pub use bloq_utils::Pauli;

pub use bloq_utils::PauliBasis;

pub use bloq_utils::PauliError;

pub use bloq_utils::PauliString;

pub use bloq_utils::PhasedPauliString;

pub use bloq_utils::PortRole;

pub use bloq_utils::RGBA;

pub use bloq_utils::UDirection;

pub use rustc_hash::FxHashMap;

Modules

ast

Abstract syntax tree for .blog source text.

prelude

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

verify

Graph-level logical verification by sampled ZX-diagram contraction.

Structs

ActionDag

An ordered dependency graph over a program’s Actions.

ActionNode

A source action and its cached measurement metadata.

ActionOwner

Authored module ownership of an action in a composed dependency graph.

BitBinding

One explicit binding to a child Boolean input.

BitOutput

One exported Boolean expression.

BitRef

A Boolean value in the parent or exported by a child.

Block

A single block placed at a 3D lattice position in a BlockGraph.

BlockGraph

A graph of surface code blocks connected by lattice-surgery pipes.

BlockLayerView

A read-only view of a single time (z) layer of a BlockGraph.

Branch

A branch ready to attach to a parent graph, including its resolve condition. Both arms use coordinates in the parent graph. External seams are supplied once to BlockGraph::try_add_branches.

BranchArm

Blocks and pipes authored as one arm of a named branch region.

BranchCut

One temporal pipe crossing from the unconditional prefix into an arm.

BranchProjection

One jointly reachable structural-branch assignment and its projected ordinary static graph.

BranchRegion

A named branch region with two explicitly authored static arms.

CancellationToken

Shared cancellation state for one request.

ComputationCancelled

A computation was cancelled before producing its result. Cancellation is neither a resource failure nor a semantic diagnosis.

CubeHeight

A cube’s height, written k*d + n over the code distance d.

DerivedSurface

A materialized stabilizer surface with readable-value provenance.

FeedbackOptions

Correspondence and resource bounds for feedback inference.

FeedbackTarget

A single Pauli correction site for an Action::Feedback.

GalleryEntry

A gallery example: its description, categories, and embedded .blog source.

GltfData

Intermediate geometry for glTF export: colored triangles, colored line segments, and text labels, accumulated before serialization to a glTF model.

InstancePort

A named port on one child instance.

LeafModuleCertificate

A certified signed boundary projection for one leaf module.

ModuleCertificationLimits

Limits applied before and during leaf-module certification.

ModuleInstance

One rotated, then translated, use of another module definition.

ModuleInterface

Public quantum and classical interface of a module.

ModuleJoinOptions

Docking preferences for module composition.

ModuleRotation

A child-module quarter turn applied before translation.

ModuleSummary

Canonical signed Pauli relation over one module’s declared Ports.

ModuleView

Definition ownership for a flat rendering projection of an authored graph.

ModuleViewModule

One visible definition in a module view.

OutputCorrectionRow

One equation in the terminal output-correction system.

PatchRotationKind

A patch-rotation block: rotates a surface code patch by 90 degrees over one time layer, translating it by an axis-aligned movement step.

Pipe

A directed pipe connecting one block to an adjacent block.

QuantumPort

One named quantum boundary of a module.

ReadoutPlan

One frozen named readout, indexed by its already available resolve choices.

ResolveValueDomain

Distinct jointly reachable values of an ordered set of Boolean action conditions.

RuntimeStabilizerBasis

The live stabilizer basis of a ZX graph, tracking the generators and the selective nodes whose runtime basis choice can still update it.

SelectiveFixing

The canonical fixing-row binding for one selective site.

SelectiveFixingTarget

A selective node and the Pauli basis it is forbidden from taking, used to constrain how selective supports are normalized.

Stabilizer

A stabilizer of a ZX graph, with its Pauli support broken out by the graph elements (ports, interior nodes, interior edges) it acts on for rendering.

StabilizerGenerator

A stabilizer generator paired with the StabilizerRowKind it plays.

StabilizerGenerators

Stabilizer state for a ZX graph: a stable public presentation plus private algebraic rank completion.

SymbolicFramePair

One output’s frame bits, each expressed as the constraint-index set whose runtime RHS bits XOR into it. An empty set is the constant false.

SymbolicOutputCorrection

The eliminated system: per-output frame-bit assignments plus the dependent rows whose RHS must XOR to zero for the system to be consistent at runtime.

SymbolicSite

One selective site and the fixing row that resolves it.

SymbolicStabilizerBasis

The surviving basis represented as an affine function of the fill assignment.

UnknownCertificationLimit

A configuration names no field in ModuleCertificationLimits.

WalkingKind

A walking block: a boundary orientation plus a diagonal in-plane movement that advances one time layer while shifting the patch by movement.

ZXEdge

An edge in a ZXGraph connecting two nodes, optionally Hadamard-typed.

ZXGraph

A ZX-calculus graph derived from a BlockGraph.

ZXLayerView

A precomputed snapshot of one time (z) layer of a ZXGraph: its nodes, in-layer edges, and the nodes with edges into the past or future layers.

ZXNode

A node in a ZXGraph: a spider or boundary at a lattice position.

Enums

Action

A classical-control action attached to a block graph program.

ActionDependency

Why one action must complete before another.

BinaryOp

A binary operator in an action expression.

BlockError

Errors produced when constructing or converting block kinds.

BlockGraphError

Errors from constructing, editing, parsing, validating, transforming, or exporting a BlockGraph.

BlockKind

The kind of a Block, determining its surface code semantics and lattice footprint.

CubeKind

A cube block’s boundary orientation, named by the Pauli basis (X or Z) assigned to each of the three axes in order.

Expr

A boolean expression tree over measurement outcome variables.

FeedbackInferenceError

A source/realization mismatch, unsupported contract, or inference limit.

FillPortsError

An error from filling a graph’s open ports with concrete boundary spiders.

GalleryCategory

A tag used to filter GalleryItem entries.

GalleryItem

A built-in example block graph, identified by a stable string id.

GltfFaceSelector

Selects filled block-graph faces to remove from a glTF export.

InvalidActionError

A semantic or graph-constraint violation found while validating a graph’s Actions.

InvalidBlockGraphError

A structural well-formedness violation found while validating a BlockGraph’s blocks, pipes, and lattice-surgery geometry.

MeasureTarget

The target of a measurement action — either a node or a specific edge.

MeasurementObservable

The Pauli basis a measurement action observes.

ModuleCertificationError

Error from certifying one independently authored module.

ModuleError

Error while loading or validating a module program.

NamedReadout

Executable named-readout recipe. Fixed rows borrow their existing storage.

NodeKind

The kind of a ZXNode: an X/Y/Z spider or a boundary node.

OutputCorrectionError

An error from solving or evaluating the output-correction system.

ParseError

An error from parsing or lowering .blog source text.

PortDirection

Direction of a quantum module port.

QuantumConnection

Explicit quantum composition authored by the parent module.

ReadoutCoordinates

Coordinates carried by a selected readout’s coefficient ordinals.

ResolveDomainError

A bounded value query exhausted Boolean work or found too many values.

RuntimeBasisError

An error from deriving or updating a RuntimeStabilizerBasis.

SelectiveKind

The two Pauli bases a selective block chooses between when resolved. The resolve condition being true selects the first named basis, false the second.

StabilizerError

An error from deriving stabilizer generators or measurement surfaces.

StabilizerRowKind

The role a stabilizer generator row plays in the basis.

SymbolicBasisError

A symbolic basis cannot represent a selective site’s fixing structure. This reports an unsupported symbolic model, not an invalid source graph. Callers can fall back to runtime-basis replay.

WalkingBoundaryKind

Boundary orientation of a walking block, restricted to the four temporal (non-spatial) cube orientations.

ZXError

An error from constructing, validating, or filling a ZXGraph.

Constants

EDITOR_AMBIENT_BRIGHTNESS

Ambient brightness shared by the editor and its baked glTF lighting.

EDITOR_DIRECTIONAL_ILLUMINANCE

Diagonal key-light illuminance shared by the editor and its baked glTF lighting.

MAX_CUBE_HEIGHT_CELLS

Largest supported cube footprint along the time axis, in cells.

Functions

block_as_gltf_data

Builds the geometry for a single block, with unit pipe length.

block_as_gltf_data_with_pipe_length

Builds the geometry for a single block, using pipe_length to size the gaps between blocks that pipes span.

block_graph_as_gltf_data

Builds the geometry for an entire block graph, laying blocks out on a grid with pipe_length-sized gaps between adjacent cells.

block_graph_as_gltf_data_with_popped_faces

Builds an entire block graph while removing the selected filled faces.

checked_add_position

Adds offset to position, rejecting an i32 coordinate overflow.

default_module_jobs

Default worker count for summarizing or compiling a module hierarchy: the machine’s parallelism capped at 4, and always 1 on wasm.

infer_feedback

Derives additional Pauli feedback for an existing realization.

infer_feedback_with

Derives missing feedback under an explicit component contract.

is_valid_tag

Returns whether tag is a legal block/pipe tag.

lower_blog_ast_deferred

Lowers parsed BLOG while deferring stabilizer-derived action dependencies.

lower_blog_ast_lenient

Lower editor drafts with checked geometry/syntax and lenient actions. Constraint failures remain in BlockGraph::action_graph_error.

lower_blog_graph_ast_deferred

Lowers parsed modular BLOG while deferring stabilizer-derived dependencies.

map_jobs

Maps f over items across at most jobs scoped worker threads, keeping the results in input order.

module_color

Stable ownership colors used by Bloq Editor and exported module viewers.

parse_actions

Parse an action snippet and lower it to Action values.

parse_blog_program_to_ast

Parse a BLOG module program without lowering it.

parse_blog_to_ast

Parse BLOG source text into its ast::SourceFile without lowering.

parse_blog_to_graph

Parse BLOG source text and lower it into a BlockGraph.

parse_blog_to_graph_with_limits

Parses BLOG into a hierarchy-preserving graph with explicit source budgets.

pipe_as_gltf_data

Builds the geometry for a pipe between two blocks.

pipe_between_positions_as_gltf_data

Builds the geometry for a pipe between two lattice positions.

qualified_name

Joins a module instance prefix and a local name with the __ separator used throughout module linking. An empty prefix returns name unchanged.

selective_fixings

Builds the canonical selective-site fixing map from generator row kinds.

selective_selector_name

The source-selector name used to pin a selective measurement at position.

solve_output_correction_symbolic

Solve the joint output-correction system once, symbolically.

solve_output_correction_symbolic_prefix

Solve the full joint system, materializing at most its first output_count outputs. All constraints and runtime consistency checks remain active.

stabilizer_as_gltf_data

Builds the geometry visualizing a stabilizer’s support overlaid on the graph.

Type Aliases

AnalyzedBranchProjections

Stabilizer tables for the jointly reachable static projections of a conditional block graph.

SelectiveFixings

Selective site to its fixing-row binding.