Module circuit 

Quantum Circuit Module

Core data structures for representing, constructing, and manipulating quantum circuits. The Circuit type is the primary IR container, supporting:

• Static circuits: fixed gate sequences with concrete numeric parameters.
• Parameterized circuits: symbolic gate angles for variational algorithms (VQE, QAOA, quantum machine learning).
• Dynamic circuits: runtime classical control flow driven by mid-circuit measurements — conditionals, loops, and switches over typed classical expressions.

Module Map

Submodule	Purpose	Key types
circuit_impl	Circuit container and builder API	Circuit
bit	Qubit identifier and conversions	Qubit, QubitError
gate	Gate definitions, matrix generation, arity	StandardGate, Instruction, UnitaryGate, MCGate, Directive, ClassicalDataOp
operation	Storage-IR operation (instruction + qubits + params)	Operation
value_instruction	Construction-IR operation tree, pre-insertion	ValueOperation, ValueInstruction, ValueClassicalControlOp
circuit_param	Parameter representation in both IR layers	ParameterValue (construction), CircuitParam (storage)
parameter	Symbolic/numeric parameter expressions	Parameter
classical	Runtime classical storage and type system	ClassicalVar, ClassicalValue, ClassicalType, Measurement
classical_expr	Side-effect-free typed classical expression AST	ClassicalExpr, ClassicalBinaryOp, ClassicalCompareOp
control_flow	Structured classical control-flow IR	IfOp, WhileOp, ForOp, SwitchOp, ClassicalControlOp
cfg	Structured control-flow graph view	CircuitCFG
circuit_verify	Classical-data and control-flow validation	Circuit::validate
circuit_to_matrix	Dense unitary matrix computation	circuit_to_matrix
ansatz	Variational circuit templates	Ansatz trait, TwoLocal, QAOAAnsatz
symbolic_matrix	Dense symbolic unitary for small subcircuits	Symbolic gate and matrix types
error	Unified error type catalog	CircuitError

Quick Start

Static circuit: Bell state → unitary matrix

use cqlib_core::circuit::{Circuit, Qubit};

let mut c = Circuit::new(2);
c.h(Qubit::new(0)).unwrap();
c.cx(Qubit::new(0), Qubit::new(1)).unwrap();
assert_eq!(c.num_qubits(), 2);
assert_eq!(c.operations().len(), 2);

Parameterized circuit: bind symbolic angles

use cqlib_core::circuit::{Circuit, Qubit, Parameter};
use std::collections::HashMap;

let theta = Parameter::symbol("θ");
let mut c = Circuit::new(1);
c.rx(Qubit::new(0), theta.clone()).unwrap();
c.rz(Qubit::new(0), theta).unwrap();

// Resolve symbols to concrete values
let mut bindings = HashMap::new();
bindings.insert("θ", std::f64::consts::PI);
let evaluated = c.assign_parameters(&Some(bindings)).unwrap();

Dynamic circuit: mid-circuit measurement with conditional gate

use cqlib_core::circuit::{Circuit, Qubit};

let mut c = Circuit::new(2);
let q0 = Qubit::new(0);
let q1 = Qubit::new(1);

c.h(q0).unwrap();
let m = c.measure(q0).unwrap();        // → Bit

// Apply X on q1 only when q0 measured as |1⟩
c.if_(m.expr().to_bool().unwrap(), |body| {
    body.x(q1)?;
    Ok(())
}).unwrap();

Architecture

The circuit IR has two layers designed to separate construction ergonomics from storage efficiency:

Layer	Operation type	Parameter type	Purpose
Construction IR	ValueOperation / ValueInstruction	ParameterValue	Self-contained, pre-insertion builder
Storage IR	Operation / Instruction	CircuitParam	Compact, interned, post-insertion storage

Circuit::from_operations and Circuit::append_value_operation are the public lowering entry points. They recursively intern symbolic Parameter values into the circuit’s indexmap::IndexSet parameter table and replace them with stable CircuitParam::Index references. Indexed parameters are never exposed to construction-IR callers, preventing dangling references.

Validation

Use Circuit::validate after construction or after loading external circuit IR. It checks:

• Classical handle ownership (no foreign circuit handles)
• Immutable ClassicalValue dominates all use sites (SSA)
• Scoped values do not escape their defining control-flow regions
• break and continue appear only in valid terminal positions

Gate arity and qubit membership are validated eagerly during Circuit::append, not deferred to post-hoc validation.

Error Handling

All construction methods that can fail return Result<_, CircuitError>. Common error variants:

Error variant	When
QubitNotFound	Qubit not registered in the circuit
QubitCountMismatch / ParameterCountMismatch	Wrong arity for fixed-arity instruction
InvalidParameterValue	Non-finite (NaN/Inf) fixed parameter
DuplicateQubits	Same qubit used twice in one operation
ForeignClassicalHandle	Handle from another circuit
UndefinedClassicalValue	Read of uninitialized classical value

See the error module for the full catalog with per-variant documentation.

Re-exports

pub use bit::Qubit;

pub use bit::QubitError;

pub use cfg::CircuitCFG;

pub use circuit_impl::Circuit;

pub use circuit_param::CircuitParam;

pub use circuit_param::ParameterValue;

pub use circuit_to_matrix::circuit_to_matrix;

pub use classical::CircuitId;

pub use classical::ClassicalType;

pub use classical::ClassicalValue;

pub use classical::ClassicalVar;

pub use classical::Measurement;

pub use classical_expr::ClassicalBinaryOp;

pub use classical_expr::ClassicalCast;

pub use classical_expr::ClassicalCompareOp;

pub use classical_expr::ClassicalExpr;

pub use classical_expr::ClassicalExprKind;

pub use classical_expr::ClassicalExprNode;

pub use classical_expr::ClassicalUnaryOp;

pub use control_flow::ClassicalControlKind;

pub use control_flow::ClassicalControlOp;

pub use control_flow::ControlBody;

pub use control_flow::ForOp;

pub use control_flow::IfOp;

pub use control_flow::SwitchCase;

pub use control_flow::SwitchOp;

pub use control_flow::WhileOp;

pub use dag::CircuitDag;

pub use dag::DagControlFlow;

pub use dag::DagNode;

pub use dag::DagSwitchCase;

pub use dag::DagWire;

pub use error::CircuitError;

pub use gate::circuit_gate::CircuitGate;

pub use gate::classical_data::ClassicalDataOp;

pub use gate::directive::Directive;

pub use gate::instruction::Instruction;

pub use gate::mc_gate::MCGate;

pub use gate::standard_gate::StandardGate;

pub use gate::unitary_gate::UnitaryGate;

pub use operation::Operation;

pub use operation::ValueOperation;

pub use parameter::Parameter;

pub use value_instruction::ValueClassicalControlOp;

pub use value_instruction::ValueControlBody;

pub use value_instruction::ValueInstruction;

pub use value_instruction::ValueSwitchCase;

pub use value_instruction::storage_operation_to_value;

Modules

ansatz

Quantum Ansatz library for variational quantum algorithms.

bit

Qubit Module

cfg

Structured control-flow graph representation for circuits.

circuit_impl

Quantum Circuit Module

circuit_param

Circuit Parameters Module

circuit_to_matrix

Circuit to Matrix Conversion

circuit_verify

Validation of circuit classical-data and structured control-flow invariants.

classical

Runtime classical storage for circuits.

classical_expr

Typed, side-effect-free runtime classical expressions.

control_flow

Expression-based classical control-flow IR.

dag

Operation-level dependency DAG for circuits.

depth

Circuit depth calculation via a per-wire ASAP longest-path DP.

error

Circuit Error Types

gate

Quantum Gate and Instruction Definitions

operation

Circuit Operation Module

parameter

Symbolic and numeric parameter type for quantum circuit gate angles.

symbolic_matrix

Symbolic matrix representations for quantum gates and circuits.

value_instruction

Value-level instruction types for circuit construction.

Structs

SwitchBuilder

Temporary builder for the ordered cases of a structured switch operation.