Struct SubGraph 

pub struct SubGraph { /* private fields */ }

A nested region body.

This graph uses the same global crate::BloqTemplatePool as the enclosing Bloq — template ids resolve against that shared pool, so a SubGraph carries none of its own. Edges do not cross region boundaries. The body’s declared result and boundary bindings form its classical interface (WF-17/SEM-RVAL). Clones share immutable storage. Mutable access copies only this graph level when shared; nested bodies remain shared until they too are edited.

Implementations

impl SubGraph

pub fn new() -> Self

Create an empty graph level.

pub fn value_output(&self) -> Option<ValueRef>

The declared bit result, or None for constant false (SEM-RVAL). Local consumers do not affect this binding.

pub fn set_value_output(&mut self, output: Option<ValueRef>)

Select the body’s bit result. Validation checks that the node exists and produces a bit (WF-17).

pub fn boundary_outputs(&self) -> &[BloqNodeId]

Declared boundary-binding producers, independently of the bit result and any local consumers. Each id names an Observable or region (WF-17).

pub fn set_boundary_outputs(&mut self, outputs: Vec<BloqNodeId>)

Select the body’s boundary bindings. Validation checks producer kinds and rejects repeated ids; operator multiplicity within an Observable stays.

pub fn add_node(&mut self, node: BloqNode) -> BloqNodeId

Add a node and return its level-local id.

pub fn add_edge(&mut self, from: BloqNodeId, to: BloqNodeId, edge: BloqEdge)

Adds an edge from -> to. Panics when either endpoint id is stale (its node was removed and not reused).

Panics

Panics if either endpoint is stale.

pub fn node(&self, id: BloqNodeId) -> Option<&BloqNode>

The node at id, or None when the id is stale.

pub fn node_mut(&mut self, id: BloqNodeId) -> Option<&mut BloqNode>

Mutable access to the node at id, or None when the id is stale — the mutable pair of Self::node. Rewrites a node’s kind in place (e.g. rewriting a region predicate) without disturbing its edges.

pub fn remove_node(&mut self, id: BloqNodeId) -> Option<BloqNode>

Remove the node at id (and its incident edges), returning it, or None when the id is stale. Other node ids are unchanged (the id space is stable). Used to excise a classical sink — e.g. a dynamically-corrected observable the static fold cannot resolve — without renumbering. Declarations referencing this id are cleared along with incident edges. Rewrites preserving an output must retarget it before removal.

pub fn node_ids(&self) -> impl DoubleEndedIterator<Item = BloqNodeId> + '_

Every node id at this level, in ascending id order.

pub fn nodes( &self, ) -> impl DoubleEndedIterator<Item = (BloqNodeId, &BloqNode)> + '_

Every (id, node) at this level, in ascending id order.

pub fn quantum_nodes( &self, ) -> impl Iterator<Item = (BloqNodeId, &QuantumNode)> + '_

This level’s quantum (block-bearing) nodes, skipping the classical and region nodes that observable lowering and control flow introduce.

pub fn node_count(&self) -> usize

Number of live nodes.

pub fn edge_count(&self) -> usize

Number of live edges.

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

Every edge at this level.

pub fn for_each_edge_mut(&mut self, edit: impl FnMut(&mut BloqEdge))

Rewrite edge payloads without changing node identities or connectivity.

pub fn incoming( &self, id: BloqNodeId, ) -> impl Iterator<Item = BloqEdgeRef<'_>> + '_

The edges into id. Empty for a stale id.

pub fn outgoing( &self, id: BloqNodeId, ) -> impl Iterator<Item = BloqEdgeRef<'_>> + '_

The edges out of id. Empty for a stale id.

pub fn edges_between( &self, from: BloqNodeId, to: BloqNodeId, ) -> impl Iterator<Item = BloqEdgeRef<'_>> + '_

Every edge from -> to (parallel edges are legal).

pub fn has_path(&self, from: BloqNodeId, to: BloqNodeId) -> bool

Whether a directed path from -> to exists (any edge kind).

pub fn path_scratch(&self) -> PathScratch

Fresh scratch for Self::has_path_with_scratch, sized to this level.

pub fn has_path_with_scratch( &self, from: BloqNodeId, to: BloqNodeId, scratch: &mut PathScratch, ) -> bool

Self::has_path with caller-provided scratch: a batch of probes shares one visit-map allocation instead of re-allocating per call. Each probe still walks the graph (the map is reset, not memoized).

pub fn value_inputs( &self, id: BloqNodeId, ) -> impl Iterator<Item = ValueInput<'_>> + '_

The producers wired into id’s Value slots. Unordered; collect into a map or sort by slot as needed.

pub fn data_inputs( &self, id: BloqNodeId, ) -> impl Iterator<Item = ValueInput<'_>> + '_

Data operands, excluding a node’s separate activation slot.

pub fn value_consumers( &self, id: BloqNodeId, ) -> impl Iterator<Item = (BloqNodeId, u32)> + '_

The consumers of id’s single Value output: (consumer, slot).

pub fn data_consumers( &self, id: BloqNodeId, ) -> impl Iterator<Item = (BloqNodeId, u32)> + '_

Runtime and recipe consumers, sharing the operand-slot namespace.

pub fn compose_consumers( &self, id: BloqNodeId, ) -> impl Iterator<Item = (BloqNodeId, u32)> + '_

Consumers including this node’s recipe content.

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

This level’s open Value producers: value-producing classical or region nodes whose Value no in-level consumer reads. This diagnostic query is independent of the declared outputs (WF-17/SEM-RVAL).

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

Open producers with a corrected Boolean output. This diagnostic query does not select the declared bit result.

pub fn deterministic_emit_order(&self) -> Result<Vec<BloqNodeId>, CycleDetected>

The body’s deterministic Kahn topological order — the same schedule crate::Bloq::deterministic_emit_order gives the top level, for walkers that execute or emit a region body.

Errors

Returns crate::CycleDetected if the body has a cycle.

pub fn is_acyclic(&self) -> bool

Whether the body is acyclic — Self::deterministic_emit_order’s success condition, without materializing the order.

pub fn is_acyclic_with_edges(&self, extra: &[(BloqNodeId, BloqNodeId)]) -> bool

Whether the body stays acyclic when extra directed edges are added (duplicates and parallel edges are allowed). One O(V+E) answer for callers probing candidate insertions, instead of reachability walks or a graph copy per candidate.

impl SubGraph

pub fn stable_keys(&self) -> Result<Vec<(NodeKey, BloqNodeId)>, CycleDetected>

This level’s provenance-bearing nodes with their stable keys, in SubGraph::deterministic_emit_order.

Nodes sharing a provenance are numbered in that order, which is what makes the keys line up across two programs: the schedule follows graph shape, so corresponding nodes are reached in corresponding positions. Nodes with no provenance are skipped, not keyed.

Errors

Returns CycleDetected when the level has no emit order to number in.

impl SubGraph

pub fn predicates_can_coexist_values( &self, predicates: &[ValueRef], ) -> Result<bool, Error>

Whether selected level-local Boolean outputs can all be true. Shared Boolean ancestry retains equal and complementary controls. The graph must be acyclic, and every predicate must name an existing bit producer. Use PredicateAnalysis::assignment_reachable to reuse derived predicates across queries, or to ask for values other than all-true.

Errors

Returns crate::lowering::NodeTemplateInstanceMergeError for malformed predicate dataflow or exhausted Boolean resources.

pub fn predicates_can_coexist( &self, predicates: &[BloqNodeId], ) -> Result<bool, Error>

Whether default corrected outputs can all be true.

Errors

Returns an error for malformed predicates or exhausted Boolean resources.

impl SubGraph

pub fn quantum_input( &self, node: BloqNodeId, ) -> Result<BloqNodeId, StructureError>

The source of the single quantum edge into node.

This is the seam a padding edit subdivides: every consumer that idles before a node first has to establish that the node has exactly one quantum predecessor to idle behind.

Errors

Returns StructureError::QuantumInputNotUnique when node has zero or several incoming quantum edges (a stale id reads as zero).

pub fn quantum_tail(&self) -> Result<BloqNodeId, StructureError>

The unique quantum tail of this graph level: a quantum node with no outgoing quantum edge. Classical consumers do not disqualify it.

This query applies to top-level graphs and nested bodies alike.

Errors

Returns StructureError::QuantumTailNotUnique unless exactly one quantum node is terminal.

impl SubGraph

pub fn resolve_classical( &self, node: BloqNodeId, assignment: ClassicalAssignment<'_>, ) -> Result<ClassicalResolution, ResolveError>

Resolve a level-local node’s affine physical/decoder recipe under a fixed path.

Uses the same semantics and errors as Bloq::resolve_classical.

Errors

Returns ResolveError when the path cannot resolve the node to an affine physical/decoder parity.

pub fn resolve_value( &self, value: ValueRef, assignment: ClassicalAssignment<'_>, ) -> Result<ClassicalResolution, ResolveError>

Resolve a selected runtime output under a fixed path.

Errors

Returns the same errors as Self::resolve_classical.

Trait Implementations

impl Clone for SubGraph

fn clone(&self) -> SubGraph

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SubGraph

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

Formats the value using the given formatter.

impl Default for SubGraph

fn default() -> SubGraph

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SubGraph

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Index<BloqNodeId> for SubGraph

The panicking twin of SubGraph::node: panics on a stale id, for passes that hold ids they know are live.

type Output = BloqNode

The returned type after indexing.

fn index(&self, id: BloqNodeId) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Serialize for SubGraph

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.