Struct Circuit 

pub struct Circuit<const N: usize> { /* private fields */ }

A quantum circuit with a fixed number of qubits

Implementations

impl<const N: usize> Circuit<N>

pub fn new() -> Circuit<N>

Create a new empty circuit with N qubits

pub fn with_capacity(capacity: usize) -> Circuit<N>

Create a new circuit with estimated capacity

pub fn add_gate<G>(&mut self, gate: G) -> Result<&mut Circuit<N>, QuantRS2Error>

where G: GateOp + Clone + Send + Sync + 'static,

Add a gate to the circuit

pub fn add_gate_arc( &mut self, gate: Arc<dyn GateOp + Sync + Send>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Add a gate from an Arc (for copying gates between circuits)

pub fn gates(&self) -> &[Arc<dyn GateOp + Sync + Send>]

Get all gates in the circuit

pub fn gates_as_boxes(&self) -> Vec<Box<dyn GateOp>>

Get gates as Vec for compatibility with existing optimization code

pub fn count_gates_by_type(&self) -> HashMap<String, usize>

Circuit introspection methods for optimization Count gates by type

pub fn calculate_depth(&self) -> usize

Calculate circuit depth (longest sequential path)

pub fn count_two_qubit_gates(&self) -> usize

Count two-qubit gates

pub fn count_multi_qubit_gates(&self) -> usize

Count multi-qubit gates (3 or more qubits)

pub fn calculate_critical_path(&self) -> usize

Calculate the critical path length (same as depth for now, but could be enhanced)

pub fn calculate_gate_density(&self) -> f64

Calculate gate density (gates per qubit)

pub fn get_used_qubits(&self) -> HashSet<QubitId>

Get all unique qubits used in the circuit

pub fn uses_all_qubits(&self) -> bool

Check if the circuit uses all available qubits

pub fn gates_on_qubit( &self, target_qubit: QubitId, ) -> Vec<&Arc<dyn GateOp + Sync + Send>>

Get gates that operate on a specific qubit

pub fn gates_in_range( &self, start: usize, end: usize, ) -> &[Arc<dyn GateOp + Sync + Send>]

Get gates between two indices (inclusive)

pub fn is_empty(&self) -> bool

Check if circuit is empty

pub fn get_stats(&self) -> CircuitStats

Get circuit statistics summary

pub const fn num_qubits(&self) -> usize

Get the number of qubits in the circuit

pub fn num_gates(&self) -> usize

Get the number of gates in the circuit

pub fn get_gate_names(&self) -> Vec<String>

Get the names of all gates in the circuit

pub fn h( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Hadamard gate to a qubit

pub fn x( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Pauli-X gate to a qubit

pub fn y( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Pauli-Y gate to a qubit

pub fn z( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Pauli-Z gate to a qubit

pub fn rx( &mut self, target: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a rotation around X-axis

pub fn ry( &mut self, target: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a rotation around Y-axis

pub fn rz( &mut self, target: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a rotation around Z-axis

pub fn s( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Phase gate (S gate)

pub fn sdg( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Phase-dagger gate (S† gate)

pub fn t( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a T gate

pub fn tdg( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a T-dagger gate (T† gate)

pub fn sx( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Square Root of X gate (√X)

pub fn sxdg( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Square Root of X Dagger gate (√X†)

pub fn cnot( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a CNOT gate

pub fn cx( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a CNOT gate (alias for cnot)

pub fn cy( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a CY gate (Controlled-Y)

pub fn cz( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a CZ gate (Controlled-Z)

pub fn ch( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a CH gate (Controlled-Hadamard)

pub fn cs( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a CS gate (Controlled-Phase/S)

pub fn crx( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a controlled rotation around X-axis (CRX)

pub fn cry( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a controlled rotation around Y-axis (CRY)

pub fn crz( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a controlled rotation around Z-axis (CRZ)

pub fn cp( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, lambda: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a controlled phase gate

pub fn swap( &mut self, qubit1: impl Into<QubitId>, qubit2: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a SWAP gate

pub fn toffoli( &mut self, control1: impl Into<QubitId>, control2: impl Into<QubitId>, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Toffoli (CCNOT) gate

pub fn cswap( &mut self, control: impl Into<QubitId>, target1: impl Into<QubitId>, target2: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Fredkin (CSWAP) gate

pub fn u( &mut self, target: impl Into<QubitId>, theta: f64, phi: f64, lambda: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a U gate (general single-qubit rotation)

U(θ, φ, λ) = [[cos(θ/2), -e^(iλ)·sin(θ/2)], [e^(iφ)·sin(θ/2), e^(i(φ+λ))·cos(θ/2)]]

pub fn p( &mut self, target: impl Into<QubitId>, lambda: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a P gate (phase gate with parameter)

P(λ) = [[1, 0], [0, e^(iλ)]]

pub fn id( &mut self, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply an Identity gate

pub fn iswap( &mut self, qubit1: impl Into<QubitId>, qubit2: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply an iSWAP gate

iSWAP swaps two qubits and phases |01⟩ and |10⟩ by i

pub fn ecr( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply an ECR gate (IBM native echoed cross-resonance gate)

pub fn rxx( &mut self, qubit1: impl Into<QubitId>, qubit2: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply an RXX gate (two-qubit XX rotation)

RXX(θ) = exp(-i * θ/2 * X⊗X)

pub fn ryy( &mut self, qubit1: impl Into<QubitId>, qubit2: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply an RYY gate (two-qubit YY rotation)

RYY(θ) = exp(-i * θ/2 * Y⊗Y)

pub fn rzz( &mut self, qubit1: impl Into<QubitId>, qubit2: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply an RZZ gate (two-qubit ZZ rotation)

RZZ(θ) = exp(-i * θ/2 * Z⊗Z)

pub fn rzx( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply an RZX gate (two-qubit ZX rotation / cross-resonance)

RZX(θ) = exp(-i * θ/2 * Z⊗X)

pub fn dcx( &mut self, qubit1: impl Into<QubitId>, qubit2: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a DCX gate (double CNOT gate)

DCX = CNOT(0,1) @ CNOT(1,0)

pub fn ccx( &mut self, control1: impl Into<QubitId>, control2: impl Into<QubitId>, target: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a CCX gate (alias for Toffoli)

pub fn fredkin( &mut self, control: impl Into<QubitId>, target1: impl Into<QubitId>, target2: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a Fredkin gate (alias for cswap)

pub fn measure( &mut self, qubit: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Measure a qubit (currently adds a placeholder measure gate)

Note: This is currently a placeholder implementation for QASM export compatibility. For actual quantum measurements, use the measurement module functionality.

pub fn reset( &mut self, _qubit: impl Into<QubitId>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Reset a qubit to |0⟩ state

Note: This operation is not yet fully implemented. Reset operations are complex and require special handling in quantum circuits.

pub fn barrier( &mut self, qubits: &[QubitId], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Add a barrier to prevent optimization across this point

Barriers are used to prevent gate optimization algorithms from reordering gates across specific points in the circuit. This is useful for maintaining timing constraints or preserving specific circuit structure.

pub fn run<S>(&self, simulator: S) -> Result<Register<N>, QuantRS2Error>

where S: Simulator<N>,

Run the circuit on a simulator

pub fn decompose(&self) -> Result<Circuit<N>, QuantRS2Error>

Decompose the circuit into a sequence of standard gates

This method will return a new circuit with complex gates decomposed into sequences of simpler gates.

pub const fn build(self) -> Circuit<N>

Build the circuit (for compatibility - returns self)

pub fn optimize(&self) -> Result<Circuit<N>, QuantRS2Error>

Optimize the circuit by combining or removing gates

This method will return a new circuit with simplified gates by removing unnecessary gates or combining adjacent gates.

pub fn create_composite( &self, start_idx: usize, end_idx: usize, name: &str, ) -> Result<CompositeGate, QuantRS2Error>

Create a composite gate from a subsequence of this circuit

This method allows creating a custom gate that combines several other gates, which can be applied as a single unit to a circuit.

pub fn add_composite( &mut self, composite: &CompositeGate, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Add all gates from a composite gate to this circuit

pub fn measure_all(&mut self) -> Result<&mut Circuit<N>, QuantRS2Error>

Measure all qubits in the circuit

pub fn with_classical_control(self) -> ClassicalCircuit<N>

Convert this circuit to a ClassicalCircuit with classical control support

pub fn h_all( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply Hadamard gates to multiple qubits at once

Example

let mut circuit = Circuit::<5>::new();
circuit.h_all(&[0, 1, 2])?; // Apply H to qubits 0, 1, and 2

pub fn x_all( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply Pauli-X gates to multiple qubits at once

Example

let mut circuit = Circuit::<5>::new();
circuit.x_all(&[0, 2, 4])?; // Apply X to qubits 0, 2, and 4

pub fn y_all( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply Pauli-Y gates to multiple qubits at once

pub fn z_all( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply Pauli-Z gates to multiple qubits at once

pub fn h_range( &mut self, range: Range<u32>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply Hadamard gates to a range of qubits

Example

let mut circuit = Circuit::<5>::new();
circuit.h_range(0..3)?; // Apply H to qubits 0, 1, and 2

pub fn x_range( &mut self, range: Range<u32>, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply Pauli-X gates to a range of qubits

pub fn bell_state( &mut self, qubit1: u32, qubit2: u32, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Prepare a Bell state |Φ+⟩ = (|00⟩ + |11⟩)/√2 on two qubits

Example

let mut circuit = Circuit::<2>::new();
circuit.bell_state(0, 1)?; // Prepare Bell state on qubits 0 and 1

pub fn ghz_state( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Prepare a GHZ state (|000…⟩ + |111…⟩)/√2 on specified qubits

Example

let mut circuit = Circuit::<3>::new();
circuit.ghz_state(&[0, 1, 2])?; // Prepare GHZ state on qubits 0, 1, and 2

pub fn w_state( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Prepare a W state on specified qubits

W state: (|100…⟩ + |010…⟩ + |001…⟩ + …)/√n

This is an approximation using rotation gates.

pub fn plus_state_all(&mut self) -> Result<&mut Circuit<N>, QuantRS2Error>

Prepare a product state |++++…⟩ by applying Hadamard to all qubits

Example

let mut circuit = Circuit::<4>::new();
circuit.plus_state_all()?; // Prepare |+⟩ on all 4 qubits

pub fn rx_all( &mut self, qubits: &[u32], theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply a rotation gate to multiple qubits with the same angle

pub fn ry_all( &mut self, qubits: &[u32], theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply RY rotation to multiple qubits

pub fn rz_all( &mut self, qubits: &[u32], theta: f64, ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply RZ rotation to multiple qubits

pub fn cnot_ladder( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Create a ladder of CNOT gates connecting adjacent qubits

Example

let mut circuit = Circuit::<4>::new();
circuit.cnot_ladder(&[0, 1, 2, 3])?; // Creates: CNOT(0,1), CNOT(1,2), CNOT(2,3)

pub fn cnot_ring( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Create a ring of CNOT gates connecting qubits in a cycle

Like CNOT ladder but also connects last to first qubit.

pub fn swap_ladder( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Create a ladder of SWAP gates connecting adjacent qubits

Example

let mut circuit = Circuit::<4>::new();
circuit.swap_ladder(&[0, 1, 2, 3])?; // Creates: SWAP(0,1), SWAP(1,2), SWAP(2,3)

pub fn cz_ladder( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Create a ladder of CZ gates connecting adjacent qubits

Example

let mut circuit = Circuit::<4>::new();
circuit.cz_ladder(&[0, 1, 2, 3])?; // Creates: CZ(0,1), CZ(1,2), CZ(2,3)

pub fn swap_all( &mut self, pairs: &[(u32, u32)], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply SWAP gates to multiple qubit pairs

Arguments

• pairs - Slice of (control, target) qubit pairs

Example

let mut circuit = Circuit::<6>::new();
circuit.swap_all(&[(0, 1), (2, 3), (4, 5)])?; // Swap three pairs simultaneously

pub fn cz_all( &mut self, pairs: &[(u32, u32)], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply CZ gates to multiple qubit pairs

Arguments

• pairs - Slice of (control, target) qubit pairs

Example

let mut circuit = Circuit::<6>::new();
circuit.cz_all(&[(0, 1), (2, 3), (4, 5)])?; // Apply CZ to three pairs

pub fn cnot_all( &mut self, pairs: &[(u32, u32)], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Apply CNOT gates to multiple qubit pairs

Arguments

• pairs - Slice of (control, target) qubit pairs

Example

let mut circuit = Circuit::<6>::new();
circuit.cnot_all(&[(0, 1), (2, 3), (4, 5)])?; // Apply CNOT to three pairs

pub fn barrier_all( &mut self, qubits: &[u32], ) -> Result<&mut Circuit<N>, QuantRS2Error>

Add barriers to multiple qubits

Barriers prevent optimization across them and can be used to visualize circuit structure.

Example

let mut circuit = Circuit::<5>::new();
circuit.h_all(&[0, 1, 2])?;
circuit.barrier_all(&[0, 1, 2])?; // Prevent optimization across this point
circuit.cnot_ladder(&[0, 1, 2])?;

impl<const N: usize> Circuit<N>

Extension trait for circuit slicing

pub fn slice(&self, strategy: SlicingStrategy) -> SlicingResult

Slice this circuit using the given strategy

impl<const N: usize> Circuit<N>

Extension methods for circuits

pub fn topological_analysis(&self) -> TopologicalAnalysis

Perform topological analysis

pub fn topological_sort(&self, strategy: TopologicalStrategy) -> Vec<usize>

Get topological order with specific strategy

Trait Implementations

impl<const N: usize> Clone for Circuit<N>

fn clone(&self) -> Circuit<N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const N: usize> Debug for Circuit<N>

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

Formats the value using the given formatter.

impl<const N: usize> Default for Circuit<N>

fn default() -> Circuit<N>

Returns the “default value” for a type.