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() -> Self

Create a new empty circuit with N qubits

pub fn with_capacity(capacity: usize) -> Self

Create a new circuit with estimated capacity

pub fn add_gate<G: GateOp + Clone + Send + Sync + 'static>( &mut self, gate: G, ) -> QuantRS2Result<&mut Self>

Add a gate to the circuit

pub fn add_gate_arc( &mut self, gate: Arc<dyn GateOp + Send + Sync>, ) -> QuantRS2Result<&mut Self>

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

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

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 + Send + Sync>>

Get gates that operate on a specific qubit

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

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 get_single_qubit_for_gate( &self, gate_type: &str, index: usize, ) -> PyResult<u32>

Get a qubit for a specific single-qubit gate by gate type and index

pub fn get_rotation_params_for_gate( &self, gate_type: &str, index: usize, ) -> PyResult<(u32, f64)>

Get rotation parameters (qubit, angle) for a specific gate by gate type and index

pub fn get_two_qubit_params_for_gate( &self, gate_type: &str, index: usize, ) -> PyResult<(u32, u32)>

Get two-qubit parameters (control, target) for a specific gate by gate type and index

pub fn get_controlled_rotation_params_for_gate( &self, gate_type: &str, index: usize, ) -> PyResult<(u32, u32, f64)>

Get controlled rotation parameters (control, target, angle) for a specific gate

pub fn get_three_qubit_params_for_gate( &self, gate_type: &str, index: usize, ) -> PyResult<(u32, u32, u32)>

Get three-qubit parameters for gates like Toffoli or Fredkin

pub fn h(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply a Hadamard gate to a qubit

pub fn x(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply a Pauli-X gate to a qubit

pub fn y(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply a Pauli-Y gate to a qubit

pub fn z(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply a Pauli-Z gate to a qubit

pub fn rx( &mut self, target: impl Into<QubitId>, theta: f64, ) -> QuantRS2Result<&mut Self>

Apply a rotation around X-axis

pub fn ry( &mut self, target: impl Into<QubitId>, theta: f64, ) -> QuantRS2Result<&mut Self>

Apply a rotation around Y-axis

pub fn rz( &mut self, target: impl Into<QubitId>, theta: f64, ) -> QuantRS2Result<&mut Self>

Apply a rotation around Z-axis

pub fn s(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply a Phase gate (S gate)

pub fn sdg(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply a Phase-dagger gate (S† gate)

pub fn t(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply a T gate

pub fn tdg(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply a T-dagger gate (T† gate)

pub fn sx(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply a Square Root of X gate (√X)

pub fn sxdg(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

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

pub fn cnot( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a CNOT gate

pub fn cx( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a CNOT gate (alias for cnot)

pub fn cy( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a CY gate (Controlled-Y)

pub fn cz( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a CZ gate (Controlled-Z)

pub fn ch( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a CH gate (Controlled-Hadamard)

pub fn cs( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a CS gate (Controlled-Phase/S)

pub fn crx( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, theta: f64, ) -> QuantRS2Result<&mut Self>

Apply a controlled rotation around X-axis (CRX)

pub fn cry( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, theta: f64, ) -> QuantRS2Result<&mut Self>

Apply a controlled rotation around Y-axis (CRY)

pub fn crz( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, theta: f64, ) -> QuantRS2Result<&mut Self>

Apply a controlled rotation around Z-axis (CRZ)

pub fn cp( &mut self, control: impl Into<QubitId>, target: impl Into<QubitId>, lambda: f64, ) -> QuantRS2Result<&mut Self>

Apply a controlled phase gate

pub fn swap( &mut self, qubit1: impl Into<QubitId>, qubit2: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a SWAP gate

pub fn toffoli( &mut self, control1: impl Into<QubitId>, control2: impl Into<QubitId>, target: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a Toffoli (CCNOT) gate

pub fn cswap( &mut self, control: impl Into<QubitId>, target1: impl Into<QubitId>, target2: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a Fredkin (CSWAP) gate

pub fn u( &mut self, target: impl Into<QubitId>, theta: f64, phi: f64, lambda: f64, ) -> QuantRS2Result<&mut Self>

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, ) -> QuantRS2Result<&mut Self>

Apply a P gate (phase gate with parameter)

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

pub fn id(&mut self, target: impl Into<QubitId>) -> QuantRS2Result<&mut Self>

Apply an Identity gate

pub fn iswap( &mut self, qubit1: impl Into<QubitId>, qubit2: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

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>, ) -> QuantRS2Result<&mut Self>

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, ) -> QuantRS2Result<&mut Self>

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, ) -> QuantRS2Result<&mut Self>

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, ) -> QuantRS2Result<&mut Self>

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, ) -> QuantRS2Result<&mut Self>

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>, ) -> QuantRS2Result<&mut Self>

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>, ) -> QuantRS2Result<&mut Self>

Apply a CCX gate (alias for Toffoli)

pub fn fredkin( &mut self, control: impl Into<QubitId>, target1: impl Into<QubitId>, target2: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

Apply a Fredkin gate (alias for cswap)

pub fn measure( &mut self, qubit: impl Into<QubitId>, ) -> QuantRS2Result<&mut Self>

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>) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

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: Simulator<N>>(&self, simulator: S) -> QuantRS2Result<Register<N>>

Run the circuit on a simulator

pub fn decompose(&self) -> QuantRS2Result<Self>

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) -> Self

Build the circuit (for compatibility - returns self)

pub fn optimize(&self) -> QuantRS2Result<Self>

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, ) -> QuantRS2Result<CompositeGate>

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, ) -> QuantRS2Result<&mut Self>

Add all gates from a composite gate to this circuit

pub fn measure_all(&mut self) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

Apply Pauli-Y gates to multiple qubits at once

pub fn z_all(&mut self, qubits: &[u32]) -> QuantRS2Result<&mut Self>

Apply Pauli-Z gates to multiple qubits at once

pub fn h_range(&mut self, range: Range<u32>) -> QuantRS2Result<&mut Self>

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>) -> QuantRS2Result<&mut Self>

Apply Pauli-X gates to a range of qubits

pub fn bell_state( &mut self, qubit1: u32, qubit2: u32, ) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

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) -> QuantRS2Result<&mut Self>

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, ) -> QuantRS2Result<&mut Self>

Apply a rotation gate to multiple qubits with the same angle

pub fn ry_all( &mut self, qubits: &[u32], theta: f64, ) -> QuantRS2Result<&mut Self>

Apply RY rotation to multiple qubits

pub fn rz_all( &mut self, qubits: &[u32], theta: f64, ) -> QuantRS2Result<&mut Self>

Apply RZ rotation to multiple qubits

pub fn cnot_ladder(&mut self, qubits: &[u32]) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

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)]) -> QuantRS2Result<&mut Self>

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)]) -> QuantRS2Result<&mut Self>

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)]) -> QuantRS2Result<&mut Self>

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]) -> QuantRS2Result<&mut Self>

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) -> Self

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.