Struct BlockGraph 

pub struct BlockGraph {
    pub name: String,
    pub interface: ModuleInterface,
    pub instances: Vec<ModuleInstance>,
    pub quantum_connections: Vec<QuantumConnection>,
    pub bit_bindings: Vec<BitBinding>,
    /* private fields */
}

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

This is the source-level, authoring representation: blocks sit at integer 3D lattice positions (the z axis is time), pipes connect adjacent endpoints, and classical control flow lives in a cached ActionDag. Structural edits refresh that DAG; metadata-only tag edits leave it intact. validate rebuilds and checks both structure and action semantics.

Fields

name: String

Definition name, main for the executable root.

interface: ModuleInterface

Public quantum and classical interface.

instances: Vec<ModuleInstance>

Rotated and translated references to other graph definitions.

quantum_connections: Vec<QuantumConnection>

Authored quantum seams between local blocks and child instances.

bit_bindings: Vec<BitBinding>

Authored bindings to child classical inputs.

Implementations

impl BlockGraph

pub fn try_add_branches( &mut self, branches: impl IntoIterator<Item = Branch>, shared_pipes: impl IntoIterator<Item = Pipe>, actions: impl IntoIterator<Item = Action>, ) -> Result<(), BlockGraphError>

Attaches branches, shared seams, and additional actions in one edit. Resolve actions are created from each branch’s condition. Existing actions are retained. All geometry, names, interfaces, and action dependencies are checked before changing the graph.

Errors

Returns an error for invalid geometry or actions, leaving self unchanged.

Examples

use bloq_graph::{BlockGraph, Branch, BranchArm, Expr, Pipe, Direction};
let mut graph = BlockGraph::from_text("BLOG 1.0\nmodule main {\n0: ZXZ [0,0,0]\n1: ZXZ [2,0,0]\nm = measure 1\n}")?;
let arm = BranchArm::try_from_blocks([([0, 0, 1], "Z")])?;
graph.try_add_branches(
    [Branch::new("cap", Expr::Var("m".into()), arm.clone(), arm)],
    [Pipe::new([0, 0, 0], Direction::ZPLUS)],
    [],
)?;
assert_eq!(graph.branch_regions()?.len(), 1);

pub fn try_add_branch_region( &mut self, name: impl Into<String>, on_false: BranchArm, on_true: BranchArm, ) -> Result<IVec3, BlockGraphError>

Adds a named explicit terminal region and shows its true arm.

Errors

Returns an error if the region name, geometry, seams, or actions are invalid.

pub fn try_add_branch_regions( &mut self, regions: Vec<(String, BranchArm, BranchArm)>, shared_pipes: Vec<Pipe>, ) -> Result<Vec<IVec3>, BlockGraphError>

Install disjoint region owners together, then resolve their common seams. Shared pipes remain in the common graph and are never copied into arms.

Errors

Returns an error if any region, shared pipe, or resulting action graph is invalid.

pub fn has_continuing_branches(&self) -> bool

Whether any region reconnects to spatial neighbors or later common code.

pub fn take_branch_arm( &mut self, positions: impl IntoIterator<Item = IVec3>, pipe_endpoints: impl IntoIterator<Item = (IVec3, IVec3)>, ) -> Result<BranchArm, BlockGraphError>

Captures selected blocks and their explicitly selected incident pipes, removing them from the currently visible graph.

Errors

Returns an error if a selected element is missing or the selection is not a closed arm.

pub fn restore_branch_arm( &mut self, arm: &BranchArm, ) -> Result<(), BlockGraphError>

Restores a previously captured loose arm to the visible graph.

Errors

Returns an error if the arm conflicts with existing geometry or actions.

pub fn branch_definitions(&self) -> &[BranchRegion]

Returns explicit branch definitions in declaration order.

pub fn branch_by_name(&self, name: &str) -> Option<&BranchRegion>

Finds an explicit branch definition by public name.

pub fn branch_by_target(&self, target: IVec3) -> Option<&BranchRegion>

Finds an explicit branch definition by stable internal anchor.

pub fn shown_branch_at(&self, position: IVec3) -> Option<&BranchRegion>

Returns the displayed region owning position, for scene picking.

pub fn set_shown_branch_arm( &mut self, name: &str, show_true: bool, ) -> Result<(), BlockGraphError>

Switches which arm is materialized for display.

Errors

Returns an error if the branch is unknown or the selected arm cannot be materialized.

pub fn branch_regions(&self) -> Result<Vec<BranchRegion>, BlockGraphError>

Returns explicit regions in resolve-action order.

Errors

Returns an error if branch actions and stored regions disagree.

pub fn branch_projections( &self, ) -> Result<Vec<BranchProjection>, BlockGraphError>

Projects every reachable explicit branch assignment.

Errors

Returns an error if branch validation, enumeration, or materialization fails.

pub fn project_branches( &self, assignments: impl IntoIterator<Item = (IVec3, bool)>, ) -> Result<Self, BlockGraphError>

Projects every explicit branch to an ordinary static graph.

Errors

Returns an error for missing assignments or an invalid projected graph.

impl BlockGraph

pub fn place_module( &mut self, name: &str, definition: &str, ) -> Result<IVec3, BlockGraphError>

Places a child beside the current geometry and exposes its public interface. Quantum ports, classical inputs, and classical outputs receive instance-qualified names. The graph is unchanged on failure.

Errors

Returns a declaration, geometry, coordinate, or certification error.

pub fn place_module_with( &mut self, name: &str, definition: &str, translation: Option<IVec3>, rotation: ModuleRotation, ) -> Result<IVec3, BlockGraphError>

Places a child with optional explicit translation and a local rotation. When translation is absent, the child is placed beside the current geometry.

Errors

Returns a declaration, geometry, coordinate, or certification error without changing the graph.

pub fn connect_modules( &mut self, output: &str, input: &str, ) -> Result<usize, BlockGraphError>

Aligns and docks two named child ports, joining all other touching compatible ports. Names use instance.port. Connected input-side instances move together. Direct seams preserve the endpoint Hadamards; obstructed compaction retains connection cubes.

Errors

Returns a declaration, geometry, coordinate, or certification error without changing the graph.

pub fn connect_modules_with( &mut self, output: &str, input: &str, options: ModuleJoinOptions, ) -> Result<usize, BlockGraphError>

Docks named child ports with explicit alignment, compaction, and Hadamard preferences.

Errors

Returns a declaration, geometry, coordinate, or certification error without changing the graph.

pub fn bind_modules( &mut self, source: &str, target: &str, ) -> Result<(), BlockGraphError>

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

Errors

Returns a declaration, dependency, or certification error without changing the graph.

pub fn translate_module( &mut self, name: &str, offset: IVec3, compact: bool, ) -> Result<IVec3, BlockGraphError>

Translates an instance’s connected group and joins touching compatible free ports. Returns the applied offset, including any successful seam compaction.

Errors

Returns a declaration, geometry, coordinate, or certification error without changing the graph.

impl BlockGraph

pub fn replace_local_body(&mut self, body: Self)

Replaces local geometry and actions while retaining interfaces and definitions.

impl BlockGraph

pub fn new() -> Self

Creates an empty block graph.

pub fn infer_pipe_basis(&self, pipe: &Pipe) -> [Option<Basis>; 3]

Infers the X/Y/Z basis assignment for each face of a pipe from pipe.src.

pub fn infer_pipe_basis_from_endpoint( &self, pipe: &Pipe, endpoint: IVec3, ) -> [Option<Basis>; 3]

Infers the X/Y/Z basis assignment for each face of a pipe from one endpoint.

pub fn infer_spatial_port_cube_kind(&self, position: IVec3) -> Option<CubeKind>

Infers the unique non-spatial cube that continues a spatial Port into a plain temporal pipe.

The authored spatial pipe fixes the two bases perpendicular to its axis. The missing basis equals the temporal basis, leaving the other spatial axis as the cube normal.

pub fn layer(&self, z: i32) -> BlockLayerView<'_>

Returns a read-only view of the time layer at z.

pub fn cube_layer_components(&self) -> BTreeMap<i32, Vec<Vec<IVec3>>>

The +X/+Y connected components of each time layer’s cubes, keyed by the layer the cube is anchored in, each component sorted and the components ordered by their lowest member.

Spatial connectivity is the unit of shared time: merged patches drive the same data qubits, so anything schedule-like belongs to a whole component — the height propagated here, the CX-slot depth bloq_compile derives. +Z pipes are temporal and do not join components.

pub fn action_graph(&self) -> &ActionDag

Returns the current action DAG.

Structural and action-affecting edits refresh this DAG; tag-only edits leave it intact.

pub fn action_graph_error(&self) -> Option<&BlockGraphError>

Returns the error from the last failed DAG rebuild; Some means the cached DAG is an unvalidated best effort. Cleared by the next successful rebuild.

pub fn analyze_action_graph(&self) -> Result<ActionDag, BlockGraphError>

Derives an independent action DAG, including correlation dependencies.

This inspection query does not change the source or compile physical IR. Authored hierarchies use the compiler’s module linker and correlation composition, retaining definition and instance ownership in each node. Continuing branches use the guarded causal readout planner. Composed and continuing-branch DAGs retain dependencies without assigning a single measurement stabilizer to each node.

Errors

Returns an error for invalid sources, causal cycles, unavailable readouts, or exhausted analysis budgets.

pub fn analyze_action_graph_with_limits( &self, limits: ModuleCertificationLimits, ) -> Result<ActionDag, BlockGraphError>

Derives an action DAG with explicit source-analysis resource limits.

Errors

Returns the same typed failures as Self::analyze_action_graph, including exhaustion of the supplied budgets.

pub fn actions(&self) -> Vec<Action>

Returns the actions in source order.

pub fn has_actions(&self) -> bool

Returns true if the graph has any actions.

pub fn get_block_id(&self, pos: impl Into<IVec3>) -> Option<u32>

Returns the internal node ID for the block at the given position.

pub fn to_zx_graph(&self) -> Result<ZXGraph, BlockGraphError>

Converts this static block graph to a ZX-calculus graph.

A graph with structural Branch actions must first be expanded with BlockGraph::branch_projections; optional topology has no single ZX graph representation.

Errors

Returns an error if graph validation or ZX conversion fails.

pub fn stabilizers(&self) -> Result<StabilizerGenerators, BlockGraphError>

Derives the stabilizer generators for this graph via the unified compute backend.

Structural sources must first be expanded with BlockGraph::branch_projections; one generator table cannot describe several optional topologies.

Errors

Returns an error if validation or stabilizer derivation fails.

pub fn stabilizers_with_limits( &self, limits: ModuleCertificationLimits, ) -> Result<StabilizerGenerators, BlockGraphError>

Derive a static table with explicit construction and search limits.

Errors

Returns an error if validation, resource limits, or stabilizer derivation fails.

pub fn with_analyzed_action_graph( self, stabilizers: &StabilizerGenerators, ) -> Result<Self, BlockGraphError>

Rebuilds the action DAG with stabilizer-derived dependencies and surfaces.

stabilizers must come from this graph. The returned graph stores only derived metadata; BLOG serialization remains unchanged.

Errors

Returns an error if action validation or readout dependency attachment fails.

pub fn analyze_actions( self, ) -> Result<(Self, StabilizerGenerators), BlockGraphError>

Computes stabilizers once and installs their derived action analysis.

For a graph with structural branches, the returned table is only the canonical all-true, common-prefix analysis table used by the compiler; it is not the stabilizer family of the conditional graph. Use BlockGraph::branch_projections and derive each projection’s stabilizers for semantic inspection.

Errors

Returns an error if stabilizer derivation or action analysis fails.

pub fn analyze_actions_with_limits( self, limits: ModuleCertificationLimits, ) -> Result<(Self, StabilizerGenerators), BlockGraphError>

Analyze source actions without replacing explicit resource limits with defaults.

Errors

Returns an error if resource-limited stabilizer derivation or action analysis fails.

pub fn fill_ports_auto( &self, ) -> Result<Vec<(BlockGraph, Vec<StabilizerGenerator>)>, BlockGraphError>

Fills port blocks using compatible external stabilizer support and returns each closed graph with the generators that selected its fill. Static variants retain selected measurement records and their aliases, removing feedback and resolves for filled caps. Returns an error if postselection or a structural branch needs an unselected record.

Errors

Returns an error if automatic filling or postselection validation fails.

pub fn fill_ports_auto_with_limits( &self, limits: ModuleCertificationLimits, ) -> Result<Vec<(BlockGraph, Vec<StabilizerGenerator>)>, BlockGraphError>

Fills ports with explicit limits for source and filled-graph analysis.

Errors

Returns the same errors as fill_ports_auto, including exhaustion of a caller’s certification budget.

pub fn filled_graphs(&self) -> Result<Vec<BlockGraph>, BlockGraphError>

The closed graphs fill_ports_auto produces, without the generators that selected each fill.

Errors

Returns the same automatic-filling errors as Self::fill_ports_auto.

pub fn filled_graphs_with_limits( &self, limits: ModuleCertificationLimits, ) -> Result<Vec<BlockGraph>, BlockGraphError>

The graphs from fill_ports_auto_with_limits, without their selecting stabilizer generators.

Errors

Returns the same errors as Self::fill_ports_auto_with_limits.

pub fn spans( &self, ) -> Option<(RangeInclusive<i32>, RangeInclusive<i32>, RangeInclusive<i32>)>

Returns the inclusive coordinate span of the graph on each axis, including both stored arms of every branch, or None when empty.

pub fn randomly_resolve_selectives( &self, seed: u64, ) -> Result<(BlockGraph, HashMap<Block, Block>), BlockGraphError>

Resolve all selective blocks from one random assignment of their action measurement variables. Resolve expressions that share a variable are therefore sampled jointly; sites without actions retain independent random choices. Returns the resolved graph and a map from original to resolved blocks. Resolution is deterministic in seed. Authored module sources must be explicitly flattened first.

If at least one selective is resolved, the result is structure-only and all actions are removed, including structural branches. Project branches first when a concrete conditional topology is required.

Panics

Panics if internally cached resolve metadata names a non-selective block.

Errors

Returns a typed hierarchy error unless child instances are explicitly flattened.

pub fn add_action(&mut self, action: Action) -> Result<(), BlockGraphError>

Appends an action, revalidating and re-analyzing the whole action set against the graph. See set_actions.

Errors

Returns a BlockGraphError if the resulting action set fails validation or physical analysis.

pub fn set_actions( &mut self, actions: Vec<Action>, ) -> Result<(), BlockGraphError>

Replaces all actions, validating the new set against the graph and, once the topology is structurally complete, deriving each measurement’s stabilizer surface and its implicit dependency edges.

Errors

Returns a BlockGraphError if the new action set fails semantic or graph-constraint validation, a measurement surface is unavailable, or the derived edges close a dependency cycle; the previous actions are left in place.

pub fn set_actions_with_inputs( &mut self, actions: Vec<Action>, inputs: impl IntoIterator<Item = String>, ) -> Result<(), BlockGraphError>

Replaces actions while declaring external Boolean inputs.

Module bodies use these names for values bound by their parent. A standalone graph compiler has no producer for them.

Errors

Returns the same errors as set_actions, plus InvalidActionError::InvalidActionName for an invalid input name.

pub fn set_actions_deferred( &mut self, actions: Vec<Action>, ) -> Result<(), BlockGraphError>

Replaces actions after source validation, deferring stabilizer surfaces and implicit dependencies to analyze_actions.

Errors

Returns a BlockGraphError for invalid source semantics without changing the previous actions.

pub fn set_actions_lenient( &mut self, actions: Vec<Action>, ) -> Result<(), BlockGraphError>

Replaces all actions without failing on a graph-constraint violation, recording it in action_graph_error instead.

This supports incremental editing, where an action list can be temporarily incomplete. Names and nonempty feedback targets remain strict so actions can survive a BLOG round-trip.

Callers that must not install a broken action set use set_actions.

Errors

Returns BlockGraphError if a Measure/Let name is invalid or feedback has no targets; the previous actions are left in place.

pub fn clear_actions(&mut self)

Removes all actions.

pub fn shift_positions(&self, offset: IVec3) -> Result<Self, BlockGraphError>

Returns a new BlockGraph shifted by the given offset.

Errors

Returns BlockGraphError::CoordinateOverflow if any shifted block footprint, pipe endpoint, or action position exceeds the coordinate range.

pub fn rotate_about_origin( &self, axis: UDirection, quarter_turns: i32, ) -> Result<Self, BlockGraphError>

Returns a new BlockGraph rotated around the origin along the given axis.

Rotation preserves blocks, pipes, branches, and actions. Rotations that cannot represent a block’s time-oriented geometry return a typed error.

Errors

Returns an unsupported-orientation, coordinate, or validation error.

pub fn rotate_about_origin_lenient( &self, axis: UDirection, quarter_turns: i32, ) -> Result<Self, BlockGraphError>

Rotates the graph without validating the result.

Errors

Returns an unsupported-orientation or coordinate-overflow error.

pub fn flip_xz_basis_lenient(&self) -> Result<Self, BlockGraphError>

Returns a new BlockGraph with X/Z bases flipped.

Swaps block and feedback bases and negates selective resolve conditions to preserve their ordered choices in the canonical XY/XZ/YZ representation. Fixed T/Y resources retain their kind; each incident pipe toggles its Hadamard. A selective’s Y arm also needs its outcome sign flipped because H conjugation sends Y to -Y; Pauli feedback along the other arm’s axis supplies that sign without changing its X/Z outcome. Positions, tags, and structural branch conditions are retained.

Errors

Returns a flatten-required error for an authored module source.

pub fn flip_xz_basis(&self) -> Result<Self, BlockGraphError>

Returns a validated copy with X/Z bases flipped, including the Hadamard frame on every fixed T/Y resource’s incident pipe and selective Y signs.

Errors

Returns an error if the flipped graph or its actions are invalid.

pub fn with_zero_min_z(&self) -> Result<Self, BlockGraphError>

Returns a new BlockGraph with all blocks shifted in the z-axis so that the minimum z-coordinate is zero.

Errors

Returns BlockGraphError::CoordinateNormalizationOverflow if the normalized z span cannot be represented by i32 coordinates.

pub fn is_empty(&self) -> bool

Returns true if this graph and every reachable definition contain no blocks. Both authored branch arms count. An unresolved definition returns false.

pub fn block_count(&self) -> usize

Returns the number of blocks in this definition’s local geometry.

pub fn pipe_count(&self) -> usize

Returns the number of pipes in this definition’s local geometry.

pub fn walking_count(&self) -> usize

Returns the number of walking blocks in this definition’s local geometry.

pub fn patch_rotation_count(&self) -> usize

Returns the number of patch rotation blocks in this definition’s local geometry.

pub fn port_count(&self) -> usize

Returns the number of Port blocks in this definition’s local geometry.

pub fn y_count(&self) -> usize

Returns the number of Y-basis blocks in this definition’s local geometry.

pub fn t_count(&self) -> usize

Returns the number of T blocks in this definition’s local geometry.

pub fn selective_count(&self) -> usize

Returns the number of selective blocks in this definition’s local geometry.

pub fn blocks(&self) -> impl Iterator<Item = &Block>

Returns this definition’s local blocks, without expanding child instances.

pub fn pipes(&self) -> impl Iterator<Item = &Pipe>

Returns this definition’s local pipes, without expanding child instances.

pub fn pipes_at(&self, position: IVec3) -> impl Iterator<Item = &Pipe>

Pipes incident to the block anchored at position, including pipes at an extended block’s other endpoints. A missing anchor yields no pipes. Visits only the block’s adjacency, without scanning the graph.

pub fn positions(&self) -> impl Iterator<Item = IVec3>

Returns local block positions, without expanding child instances.

pub fn is_clifford(&self) -> bool

Returns true if every reachable definition and branch arm has no T blocks. An unresolved definition returns false.

pub fn is_rigid(&self) -> bool

Returns true if every reachable definition and branch arm has a statically known block kind. An unresolved definition returns false.

pub fn is_open(&self) -> bool

Returns true if the root has a public quantum boundary. Child Ports consumed by module seams do not make the root open.

pub fn get_block(&self, position: impl Into<IVec3>) -> Option<&Block>

Returns a reference to the block at the given position, if it exists.

pub fn get_endpoint_block(&self, position: impl Into<IVec3>) -> Option<&Block>

Returns the owning block for a connectable endpoint position.

For ordinary blocks this is the block at position; for extended blocks this also resolves the virtual end position back to the block stored at its start position.

pub fn has_block_at(&self, position: impl Into<IVec3>) -> bool

Returns true if a block exists at the given position.

pub fn has_endpoint_at(&self, position: impl Into<IVec3>) -> bool

Returns true if a connectable block endpoint exists at the given position.

pub fn occupied_positions(&self) -> impl Iterator<Item = IVec3> + '_

Iterates over every lattice cell reserved by some block.

pub fn can_place_block(&self, block: &Block) -> Result<(), BlockGraphError>

Checks whether block can be placed without an illegal footprint overlap.

Errors

Returns BlockGraphError::BlockPositionOccupied if a reserved cell collides with an existing block that does not permit the overlap.

pub fn set_cube_height( &mut self, position: IVec3, height: CubeHeight, ) -> Result<(), BlockGraphError>

Sets the cube height at position, re-checking the resulting footprint.

Height propagation can grow a cube from one cell to several, so the new footprint has to clear the same occupancy check a fresh placement would.

Errors

BlockGraphError::BlockNotFound if nothing is placed at position, BlockGraphError::Block if the block is not a cube or the footprint leaves the coordinate range, or BlockGraphError::BlockPositionOccupied if the grown footprint collides.

Panics

Panics if graph indexes change after the initial existence check.

pub fn has_pipe_between(&self, u: impl Into<IVec3>, v: impl Into<IVec3>) -> bool

Returns true if a pipe exists between the two positions.

pub fn set_block_kind( &mut self, position: impl Into<IVec3>, kind: BlockKind, ) -> Result<(), BlockGraphError>

Update a block kind while preserving graph indexes and refreshing action metadata.

Errors

Returns an error if the block is missing or the new kind violates geometry or branch rules.

Panics

Panics if graph indexes or an existing cube height are internally invalid.

pub fn set_block_tag( &mut self, position: impl Into<IVec3>, tag: impl Into<String>, ) -> Result<(), BlockGraphError>

Update a block tag while preserving graph indexes and action metadata. An empty tag clears the tag.

Errors

Returns BlockGraphError::BlockNotFound if no block occupies position, or BlockGraphError::InvalidTag if tag is malformed.

pub fn set_port_color( &mut self, position: impl Into<IVec3>, rgb: [u8; 3], ) -> Result<(), BlockGraphError>

Updates a Port’s RGB display color. Alpha remains fixed; default gray is omitted from serialization.

Errors

Returns BlockGraphError::BlockNotFound if no block occupies position, or BlockError::PortColorOnNonPort if that block is not a Port.

pub fn set_port_role( &mut self, position: impl Into<IVec3>, role: PortRole, ) -> Result<(), BlockGraphError>

Assigns the role of a Port block.

Errors

Returns an error if the block is missing or is not a Port.

pub fn add_block(&mut self, block: Block) -> IVec3

Add a block to the graph, returning its position.

This mutates topology and refreshes cached action metadata for any existing actions.

Panics

Panics if the block’s position is already occupied. Use try_add_block for a fallible alternative.

pub fn try_add_block(&mut self, block: Block) -> Result<IVec3, BlockGraphError>

Adds a block to the graph, returning its position or an error if the position is occupied.

This mutates topology and refreshes cached action metadata for any existing actions.

Errors

Returns an error for an occupied or unrepresentable block footprint.

pub fn remove_block(&mut self, pos: impl Into<IVec3>) -> Option<Block>

Removes and returns the block at the given position, if it exists.

This mutates topology and refreshes cached action metadata for any existing actions.

pub fn add_pipe(&mut self, pipe: Pipe)

Add a pipe connecting two blocks.

This mutates topology and refreshes cached action metadata for any existing actions.

Panics

Panics if either endpoint does not exist or if the pipe already exists. Use try_add_pipe for a fallible alternative.

pub fn try_add_pipe(&mut self, pipe: Pipe) -> Result<(), BlockGraphError>

Adds a pipe connecting two blocks, returning an error if either endpoint is missing or the pipe already exists.

This mutates topology and refreshes cached action metadata for any existing actions.

Errors

Returns an error for invalid endpoints, missing blocks, or a duplicate pipe.

pub fn remove_pipe( &mut self, u: impl Into<IVec3>, v: impl Into<IVec3>, ) -> Option<Pipe>

Removes and returns the pipe between the two positions, if it exists.

pub fn get_pipe( &self, u: impl Into<IVec3>, v: impl Into<IVec3>, ) -> Option<&Pipe>

Returns a reference to the pipe between the two positions, if it exists.

pub fn get_pipe_between_blocks( &self, u: impl Into<IVec3>, v: impl Into<IVec3>, ) -> Option<&Pipe>

Returns the pipe connecting the blocks anchored at u and v.

Unlike get_pipe, this accepts block positions rather than physical pipe endpoints. This matters for multi-cell blocks whose connected endpoint is offset from the stored block position.

pub fn set_pipe_tag( &mut self, u: impl Into<IVec3>, v: impl Into<IVec3>, tag: impl Into<String>, ) -> Result<(), BlockGraphError>

Update a pipe tag while preserving graph topology and action metadata. An empty tag clears the tag.

Errors

Returns BlockGraphError::PipeNotFound if no pipe connects u and v, or BlockGraphError::InvalidTag if tag is malformed.

pub fn set_pipe_hadamard( &mut self, u: impl Into<IVec3>, v: impl Into<IVec3>, hadamard: bool, ) -> Result<(), BlockGraphError>

Update a pipe Hadamard flag and refresh action metadata.

Errors

Returns BlockGraphError::PipeNotFound if no pipe connects u and v.

pub fn neighbors(&self, position: impl Into<IVec3>) -> Vec<&Block>

Returns all blocks directly connected to the block owning the given endpoint.

pub fn neighbor_positions(&self, position: impl Into<IVec3>) -> Vec<IVec3>

Returns the physical neighbor endpoint positions for pipes attached to the given connectable endpoint.

pub fn degree(&self, position: impl Into<IVec3>) -> usize

Returns the number of pipes attached to the given connectable endpoint.

pub fn block_pairs_with_pipe( &self, ) -> impl Iterator<Item = (&Block, &Block, &Pipe)>

Returns an iterator over (block_u, block_v, pipe) triples for every pipe in the graph.

pub fn pipe_endpoints_with_blocks( &self, ) -> impl Iterator<Item = (IVec3, IVec3, &Block, &Block, &Pipe)>

Returns physical endpoint positions and owner blocks for every pipe.

pub fn validate(&self) -> Result<(), BlockGraphError>

Audits structure and source actions, including signed dependencies. Hierarchical graphs use composed certificates and their C0 contract; leaves retain the local stabilizer/action audit.

Errors

Returns the first structural, action, or stabilizer-derived validation error.

pub fn validate_structure(&self) -> Result<(), BlockGraphError>

Validates graph structural constraints without validating action semantics.

Errors

Returns the first structural graph error.

pub fn validate_source(&self) -> Result<(), BlockGraphError>

Validates graph structure and action-source semantics without deriving stabilizer surfaces or implicit physical dependencies.

Errors

Returns the first structural or source-action error.

pub fn structural_errors(&self) -> Vec<BlockGraphError>

Lists every structural violation rather than stopping at the first, for callers that need to tell a defect an edit introduced from one the graph already carried. An empty result means the same as BlockGraph::validate_structure returning Ok.

Violations are complete per validation phase, not across phases: an overlapping footprint or an unresolvable pipe endpoint suppresses the later geometry checks, which assume those hold.

impl BlockGraph

pub fn write_module_gltf_file( &self, pipe_length: f32, path: impl AsRef<Path>, popped_faces: &[GltfFaceSelector], ) -> Result<(), BlockGraphError>

Exports an independent rendering projection colored by module definition.

Uses the editor’s opaque ownership colors and retains ordinary colors on cross-definition pipes. The authored hierarchy is unchanged.

Errors

Returns a materialization, serialization, or file-I/O error.

pub fn write_module_html_viewer( &self, pipe_length: f32, path: impl AsRef<Path>, popped_faces: &[GltfFaceSelector], ) -> Result<(), BlockGraphError>

Exports a module ownership view with independently toggled definition highlights.

Retains the authored graph and creates an independent flat rendering projection. The HTML embeds its model and loads model-viewer from a CDN.

Errors

Returns a materialization, serialization, or file-I/O error.

pub fn write_to_gltf_file( &self, pipe_length: f32, path: impl AsRef<Path>, stabilizer: Option<&StabilizerGenerator>, popped_faces: &[GltfFaceSelector], ) -> Result<(), BlockGraphError>

Exports the graph as a .gltf file, optionally overlaying a stabilizer generator.

Uses the editor’s orientation and baked diffuse lighting in unlit materials.

Errors

Returns a graph, serialization, or file-I/O error.

pub fn write_to_gltf_html_viewer( &self, pipe_length: f32, path: impl AsRef<Path>, stabilizer: Option<&StabilizerGenerator>, popped_faces: &[GltfFaceSelector], ) -> Result<(), BlockGraphError>

Exports the graph as an HTML viewer with an embedded glTF scene.

The model data is embedded as a base64 data URI, but the model-viewer renderer is loaded from a CDN, so the page requires network access.

Errors

Returns a graph, serialization, or file-I/O error.

impl BlockGraph

pub fn to_program_blog_text(&self) -> Result<String, ModuleError>

Serializes the complete executable hierarchy as BLOG.

Procedural graphs infer their interfaces; authored interfaces and helper definitions are retained exactly. Use to_blog_body_text explicitly for a local geometry/actions projection.

Errors

Returns a typed error when a procedural graph’s interface cannot be inferred.

pub fn to_blog_body_text(&self) -> String

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

Panics

Panics if internal block, pipe, branch, or action indexes are inconsistent.

pub fn to_file(&self, path: impl AsRef<Path>) -> Result<(), BlockGraphError>

Writes the graph to a file in .blog text format.

Errors

Returns BlockGraphError::Io if the file cannot be written.

pub fn from_blog_text(blog_text: &str) -> Result<Self, BlockGraphError>

Parses a block graph from .blog text format.

BLOG is an authoring format, so the result may be structurally incomplete. Call Self::validate when a complete graph is required.

Errors

Returns a parse or graph-construction error for invalid BLOG input.

pub fn from_text(text: &str) -> Result<Self, BlockGraphError>

Parses executable BLOG or graph-body text, retaining module hierarchy.

This is the same input model as Python’s BlockGraph.from_text and the native compiler. Geometry, authored interfaces, child instances, seams, bindings, and helper definitions are owned by the returned graph. Imports require Self::load.

Errors

Returns typed syntax, module, graph-construction, or resource-limit errors.

Examples

use bloq_graph::BlockGraph;
let graph = BlockGraph::from_text("BLOG 1.0\nmodule main {\n0: ZXZ [0,0,0]\n}\n")?;
assert_eq!(graph.block_count(), 1);

pub fn from_text_with_limits( text: &str, limits: ModuleCertificationLimits, ) -> Result<Self, BlockGraphError>

Parses executable BLOG or graph-body text with explicit source budgets.

The same limits govern action analysis and hierarchy expansion.

Errors

Returns typed syntax, module, graph-construction, or resource-limit errors.

pub fn load(path: impl AsRef<Path>) -> Result<Self, BlockGraphError>

Loads BLOG as a block graph, resolving imports relative to each file.

This matches Python’s BlockGraph.load. Module instances and interfaces remain authored; call Self::flatten explicitly when a consumer needs one expanded geometry projection.

Errors

Returns typed I/O, parse, import-resolution, graph, or resource-limit errors.

pub fn load_with_limits( path: impl AsRef<Path>, limits: ModuleCertificationLimits, ) -> Result<Self, BlockGraphError>

Loads BLOG as a graph with explicit source-analysis and expansion budgets.

The same limits apply to every imported hierarchy.

Errors

Returns typed I/O, parse, import-resolution, graph, or resource-limit errors.

pub fn fix_shadowed_faces(&self) -> Self

Returns a new graph with cube kinds adjusted so that shadowed pipe faces have consistent basis assignments.

impl BlockGraph

pub const ENTRY_MODULE: &'static str = "main"

Required name of the executable root module.

pub fn definition( name: impl Into<String>, body: Self, interface: ModuleInterface, instances: Vec<ModuleInstance>, quantum_connections: Vec<QuantumConnection>, bit_bindings: Vec<BitBinding>, ) -> Self

Installs one definition’s interface and child composition on its local graph.

pub fn with_inferred_interface(self) -> Result<Self, ModuleError>

Adds inferred quantum and classical ports to a procedurally authored graph.

Errors

Returns a typed interface error when Port directions cannot be inferred.

Panics

Panics only if the generated Port-name sequence is internally exhausted.

pub fn from_definitions(definitions: Vec<Self>) -> Result<Self, ModuleError>

Constructs a hierarchy rooted at main, preserving each definition once.

Errors

Returns a typed declaration, geometry, dependency, or resource-limit error.

pub fn from_definitions_with_limits( definitions: Vec<Self>, limits: ModuleCertificationLimits, ) -> Result<Self, ModuleError>

Constructs a hierarchy with explicit source and expansion limits.

Errors

Returns a typed declaration, geometry, dependency, or resource-limit error.

pub fn modules( &self, ) -> impl ExactSizeIterator<Item = &Self> + DoubleEndedIterator + Clone

Borrows every named definition, including this root, without copying topology.

pub fn module_mut(&mut self, name: &str) -> Option<&mut Self>

Mutably borrows one named definition for edits checked by validation.

pub fn root(&self) -> &Self

Returns the executable root; its local topology is stored directly here.

pub fn module(&self, name: &str) -> Option<&Self>

Borrows one named definition, including the root.

pub fn local_body(&self) -> &Self

Borrows this definition’s local topology and actions.

pub fn clone_local_definition(&self) -> Self

Copies one definition without copying the root’s helper library.

pub fn has_module_structure(&self) -> bool

Whether explicitly authored interfaces or child composition are present.

pub fn flatten(&self) -> Result<Self, ModuleCertificationError>

Explicitly materializes the authored hierarchy as one flat projection.

Errors

Returns an expansion or graph-construction error.

pub fn flatten_with_limits( &self, limits: ModuleCertificationLimits, ) -> Result<Self, ModuleCertificationError>

Materializes one flat projection without resetting explicit source budgets.

Errors

Returns a typed invalid-hierarchy, graph, or resource-limit error.

pub fn validate_with_limits( &self, limits: ModuleCertificationLimits, ) -> Result<(), ModuleError>

Validates all authored definitions, interfaces, seams, and dependency cycles.

Errors

Returns typed source, module, geometry, or resource-limit errors.

pub fn extract_definition(&self, name: &str) -> Result<Self, ModuleError>

Extracts an independently compilable graph rooted at one named definition.

Includes its transitive helper definitions and renames the selected root to main, resolving any collision with a reachable original root.

Errors

Returns a typed missing-definition, invalid-hierarchy, or resource error.

pub fn extract_definition_with_limits( &self, name: &str, limits: ModuleCertificationLimits, ) -> Result<Self, ModuleError>

Extracts one definition and its dependencies with explicit source budgets.

Errors

Returns a typed missing-definition, invalid-hierarchy, or resource error.

Panics

Panics if validated dependency bookkeeping is internally inconsistent.

pub fn certify_leaf( &self, name: &str, limits: ModuleCertificationLimits, ) -> Result<LeafModuleCertificate, ModuleCertificationError>

Certifies one definition without flattening its ZX rows.

Errors

Returns an error if the definition is missing or cannot be certified within limits.

impl BlockGraph

pub fn to_blog_text(&self) -> String

Canonical BLOG 1.0 text. Resolved imports are written inline.

impl BlockGraph

pub fn summarize_root( &self, limits: ModuleCertificationLimits, ) -> Result<Arc<ModuleSummary>, ModuleCertificationError>

Builds the root’s signed quantum summary without flattening child bodies. Native concurrency defaults to the available cores capped at four.

Errors

Returns an error if validation, certification, or a resource limit fails.

pub fn summarize_root_with_jobs( &self, limits: ModuleCertificationLimits, jobs: NonZeroUsize, ) -> Result<Arc<ModuleSummary>, ModuleCertificationError>

Builds the root summary using at most jobs concurrent module workers.

Definitions at the same dependency depth run in parallel on native targets. WebAssembly remains serial.

Errors

Returns an error if validation, certification, or a resource limit fails.

pub fn direct_pipe_endpoints(&self, module: &str) -> Option<Vec<(IVec3, IVec3)>>

Physical endpoints of direct child-to-child pipes in declaration order.

Panics

Panics if validated module geometry is internally inconsistent.

pub fn direct_pipe_endpoints_by_module( &self, ) -> HashMap<String, Vec<(IVec3, IVec3)>>

Physical direct-pipe endpoints for every module, sharing geometry work.

Panics

Panics if validated module geometry is internally inconsistent.

impl BlockGraph

pub fn validate_resource_limits( &self, limits: ModuleCertificationLimits, ) -> Result<(), BlockGraphError>

Checks the whole source hierarchy’s conservative expansion budgets.

Errors

Returns typed declaration, cycle, graph, or resource-limit errors.

pub fn validate_local_resource_limits( &self, limits: ModuleCertificationLimits, ) -> Result<(), BlockGraphError>

Checks authored geometry size before cloning or enumerating occupied cells. Both branch arms count; cube footprints use their cached height in cells. This checks max_expanded_blocks and max_occupied_cells only.

Errors

Returns a crate::StabilizerError::ResourceLimited wrapped in crate::BlockGraphError::Stabilizer when a count exceeds its limit or cannot fit in usize.

Trait Implementations

impl Clone for BlockGraph

fn clone(&self) -> BlockGraph

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BlockGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BlockGraph

fn default() -> Self

Returns the “default value” for a type.

impl Display for BlockGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for BlockGraph

type Err = BlockGraphError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl TryFrom<&BlockGraph> for ZXGraph

type Error = ZXError

The type returned in the event of a conversion error.

fn try_from(graph: &BlockGraph) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&ZXGraph> for BlockGraph

type Error = ZXError

The type returned in the event of a conversion error.

fn try_from(value: &ZXGraph) -> Result<Self, Self::Error>

Performs the conversion.