Struct CircuitRebuildContext 

pub struct CircuitRebuildContext { /* private fields */ }

Context for rebuilding a circuit through value-level operations.

The context owns the new circuit identity and the accumulated classical variable / value tables that will be supplied to Circuit::from_operations in finish.

Lifecycle

let rebuild = CircuitRebuildContext::new(&source);
let root_remap = rebuild.root_classical();

// For definition expansion, allocate per-instance remaps:
let instance_remap = rebuild.allocate_classical_instance(&definition);

// Produce ValueOperations, then commit:
let circuit = rebuild.finish(qubits, operations, global_phase)?;

Design

CircuitRebuildContext delegates per-handle and per-expression remapping to ClassicalRemap so that callers can pass the remap into helpers without threading the full context. The context itself handles higher-level concerns: accumulating classical tables across allocate_classical_instance calls, resolving source parameters, and constructing the final Circuit.

Implementations

impl CircuitRebuildContext

pub fn new(source: &Circuit) -> Self

Creates a rebuild context for a new circuit with the same root-level classical tables as source.

The root ClassicalRemap maps every classical handle in source to a corresponding handle with the new circuit_id. Access it via root_classical.

pub fn root_classical(&self) -> &ClassicalRemap

Returns the remap for root-level classical handles from the source circuit.

Use this remap when preserving operations from the top-level operation stream. For definition bodies or other nested circuits, use allocate_classical_instance instead.

pub fn allocate_classical_instance( &mut self, circuit: &Circuit, ) -> ClassicalRemap

Allocates a fresh copy of circuit’s classical tables in the rebuilt circuit and returns the corresponding handle remap.

This is intended for definition expansion and other transforms that may instantiate the same source circuit more than once. Each call appends new entries to the accumulated classical tables and returns a ClassicalRemap with distinct rebuilt handles, so two expansions of the same definition never share classical state.

pub fn finish( self, qubits: Vec<Qubit>, operations: Vec<ValueOperation>, global_phase: Parameter, ) -> Result<Circuit, CompilerError>

Builds and validates the final Circuit from rebuilt value-level operations.

This is the only entry point for constructing the output circuit. It calls Circuit::from_operations which infers the classical circuit id, interns parameters, and runs full validation. Returns an error if any classical handle in operations is inconsistent with the accumulated classical tables.

pub fn resolve_source_param( source: &Circuit, param: &CircuitParam, ) -> Result<ParameterValue, CompilerError>

Resolves a storage-level parameter from source into a value-level parameter suitable for a rebuilt operation.

CircuitParam::Index is resolved against source’s parameter table. Resolved parameters are converted to fixed values when constant evaluation succeeds.

pub fn resolve_source_params( source: &Circuit, params: &[CircuitParam], ) -> Result<SmallVec<[ParameterValue; 1]>, CompilerError>

Resolves storage-level parameters from source into value-level parameters suitable for a rebuilt operation.

pub fn remap_preserved_operation( &self, source: &Circuit, operation: &Operation, classical_remap: &ClassicalRemap, ) -> Result<ValueOperation, CompilerError>

Converts an unchanged source operation into a rebuilt value-level operation, resolving parameters and remapping runtime classical handles.

This is the primary entry point for preserved (non-transformed) operations. It calls remap_instruction internally, so classical-control operations are recursively remapped. Passes that apply their own transform to control-flow bodies should use the lower-level remap methods instead.

pub fn remap_instruction( &self, source: &Circuit, instruction: &Instruction, classical_remap: &ClassicalRemap, ) -> Result<ValueInstruction, CompilerError>

Converts an instruction into its value-level rebuilt form.

Classical data operations are remapped via ClassicalRemap::remap_data_op. Classical control is recursively remapped via remap_control_flow. Other instruction kinds are cloned unchanged.

Passes that apply their own transform to control-flow bodies should use remap_non_control_instruction instead, which rejects classical control to prevent accidental double-processing.

pub fn remap_non_control_instruction( &self, instruction: &Instruction, classical_remap: &ClassicalRemap, ) -> Result<ValueInstruction, CompilerError>

Converts a non-control instruction into its value-level rebuilt form.

This helper rejects structured classical control so transforms that rewrite control-flow bodies themselves cannot accidentally preserve an unprocessed nested control operation. Use remap_instruction when the transform does not recurse into control flow.

pub fn remap_control_flow( &self, source: &Circuit, control: &ClassicalControlOp, classical_remap: &ClassicalRemap, ) -> Result<ValueClassicalControlOp, CompilerError>

Recursively remaps a classical control operation and its bodies.

Conditions, loop variables, and switch targets are remapped through classical_remap. Every operation inside each control-flow body is preserved and remapped via remap_preserved_sequence.

Passes that apply their own transform inside control-flow bodies (such as the knowledge rewriter or unitary decomposer with recurse_control_flow) should call remap_expr and remap_var on the condition or loop variable, then process the bodies through their own transform pipeline instead of calling this method.

pub fn remap_preserved_sequence( &self, source: &Circuit, operations: &[Operation], classical_remap: &ClassicalRemap, ) -> Result<Vec<ValueOperation>, CompilerError>

Remaps a sequence of preserved operations.

Each operation is individually remapped via remap_preserved_operation. This is a convenience for remapping control-flow bodies and other operation slices in bulk.

Trait Implementations

impl Clone for CircuitRebuildContext

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CircuitRebuildContext

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

Formats the value using the given formatter.