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

Examples found in repository

examples/optimization_demo.rs (line 35)

fn create_sample_circuit() -> Circuit<4> {
    // Create a circuit that has optimization opportunities
    let mut circuit = Circuit::<4>::new();

    // Add some gates with optimization opportunities
    // Pattern 1: Redundant gates (H-H = I, X-X = I)
    let _ = circuit.h(0);
    let _ = circuit.h(0);

    // Pattern 2: Commutable gates
    let _ = circuit.x(1);
    let _ = circuit.z(0);
    let _ = circuit.cnot(0, 1);

    // Pattern 3: Mergeable rotations
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);

    // Pattern 4: Known patterns (H-X-H = Z)
    let _ = circuit.h(3);
    let _ = circuit.x(3);
    let _ = circuit.h(3);

    // Pattern 5: Decomposable gates
    let _ = circuit.toffoli(0, 1, 2);

    circuit
}

examples/equivalence_demo.rs (line 40)

fn demo_structural_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("1. Structural Equivalence Check");
    println!("   Checking if two circuits have identical gate sequences");

    // Create two identical Bell state circuits
    let mut circuit1 = Circuit::<2>::new();
    circuit1.h(0)?;
    circuit1.cnot(0, 1)?;

    let mut circuit2 = Circuit::<2>::new();
    circuit2.h(0)?;
    circuit2.cnot(0, 1)?;

    // Check structural equivalence
    let checker = EquivalenceChecker::default();
    let result = checker.check_structural_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: H(0), CNOT(0,1)");
    println!("   Circuit 2: H(0), CNOT(0,1)");
    println!("   Structurally equivalent: {}", result.equivalent);
    println!("   Details: {}", result.details);

    Ok(())
}

/// Demonstrate algebraic equivalence (different gates, same result)
fn demo_algebraic_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("2. Algebraic Equivalence Check");
    println!("   Different gate sequences that produce the same result");

    // Circuit 1: X followed by X (should equal identity)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.x(0)?;
    circuit1.x(0)?;

    // Circuit 2: Empty circuit (identity)
    let circuit2 = Circuit::<1>::new();

    // Check equivalence
    let mut checker = EquivalenceChecker::default();
    let result = checker.check_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: X(0), X(0)");
    println!("   Circuit 2: (empty)");
    println!("   Equivalent: {}", result.equivalent);
    println!("   Check type: {:?}", result.check_type);

    // Another example: HZH = X
    let mut circuit3 = Circuit::<1>::new();
    circuit3.h(0)?;
    circuit3.z(0)?;
    circuit3.h(0)?;

    let mut circuit4 = Circuit::<1>::new();
    circuit4.x(0)?;

    let result2 = checker.check_structural_equivalence(&circuit3, &circuit4)?;

    println!("\n   Circuit 3: H(0), Z(0), H(0)");
    println!("   Circuit 4: X(0)");
    println!("   Structurally equivalent: {}", result2.equivalent);
    println!("   (Note: They are algebraically equivalent but not structurally)");

    Ok(())
}

/// Demonstrate phase equivalence
fn demo_phase_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("3. Global Phase Equivalence");
    println!("   Circuits that differ only by a global phase");

    // Circuit 1: S gate (phase π/2)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.s(0)?;

    // Circuit 2: Z followed by T (phase π + π/4 = 5π/4)
    // This gives the same result up to global phase
    let mut circuit2 = Circuit::<1>::new();
    circuit2.z(0)?;
    circuit2.t(0)?;

    // Check with phase ignored
    let mut checker_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: true,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Check without phase ignored
    let mut checker_no_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: S(0)");
    println!("   Circuit 2: Z(0), T(0)");

    // Note: This example is simplified - actual phase relationship may differ
    println!("   With global phase ignored: (would check if implemented)");
    println!("   Without global phase: (would check if implemented)");

    Ok(())
}

/// Demonstrate detection of non-equivalent circuits
fn demo_non_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("4. Non-Equivalence Detection");
    println!("   Detecting when circuits are NOT equivalent");

    // Circuit 1: Bell state |00> + |11>
    let mut circuit1 = Circuit::<2>::new();
    circuit1.h(0)?;
    circuit1.cnot(0, 1)?;

    // Circuit 2: Different entangled state |01> + |10>
    let mut circuit2 = Circuit::<2>::new();
    circuit2.h(0)?;
    circuit2.x(1)?;
    circuit2.cnot(0, 1)?;

    let checker = EquivalenceChecker::default();
    let result = checker.check_structural_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: H(0), CNOT(0,1)");
    println!("   Circuit 2: H(0), X(1), CNOT(0,1)");
    println!("   Equivalent: {}", result.equivalent);
    println!("   Details: {}", result.details);

    Ok(())
}

/// Demonstrate custom tolerance settings
fn demo_custom_tolerance() -> Result<(), Box<dyn std::error::Error>> {
    println!("5. Custom Tolerance Settings");
    println!("   Using different tolerance levels for approximate equivalence");

    // Create circuits that might have small numerical differences
    let mut circuit1 = Circuit::<1>::new();
    circuit1.rx(0, PI / 4.0)?;

    let mut circuit2 = Circuit::<1>::new();
    circuit2.rx(0, PI / 4.0 + 1e-12)?; // Tiny difference

    // Strict tolerance
    let mut strict_checker = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-15,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Relaxed tolerance
    let mut relaxed_checker = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: RX(0, π/4)");
    println!("   Circuit 2: RX(0, π/4 + 1e-12)");
    println!("   With strict tolerance (1e-15): (would check if implemented)");
    println!("   With relaxed tolerance (1e-10): (would check if implemented)");

    Ok(())
}

/// Additional example: Verify circuit optimization preserves behavior
fn verify_optimization_example() -> Result<(), Box<dyn std::error::Error>> {
    println!("\nBonus: Verifying Circuit Optimization");

    // Original circuit with redundant gates
    let mut original = Circuit::<2>::new();
    original.h(0)?;
    original.cnot(0, 1)?;
    original.cnot(0, 1)?; // This cancels the previous CNOT
    original.h(0)?;

    // Optimized circuit (manually optimized for this example)
    let optimized = Circuit::<2>::new();
    // Empty circuit since H-CNOT-CNOT-H = H-H = I

    let checker = EquivalenceChecker::default();
    println!("   Original: H(0), CNOT(0,1), CNOT(0,1), H(0)");
    println!("   Optimized: (empty)");

    // In practice, you would use the circuit optimizer and then verify:
    // let optimized = original.optimize()?;
    // let result = checker.check_equivalence(&original, &optimized)?;

    Ok(())
}

examples/noise_optimization_demo.rs (line 15)

fn main() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("=== Noise-Aware Circuit Optimization Demo ===\n");

    // Create a test circuit
    let mut circuit = Circuit::<4>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(Hadamard { target: QubitId(2) })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    println!("Original circuit:");
    println!("H(0), CNOT(0,1), H(2), CNOT(2,3), CNOT(1,2)");
    println!("Total gates: {}\n", circuit.num_gates());

    // Test different noise models
    demo_uniform_noise(&circuit)?;
    demo_ibm_noise(&circuit)?;
    demo_noise_aware_cost_model(&circuit)?;
    demo_noise_optimization_passes(&circuit)?;

    Ok(())
}

fn demo_uniform_noise(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Uniform Noise Model ---");

    let noise_model = NoiseModel::uniform(4);
    let optimizer = NoiseAwareOptimizer::new(noise_model.clone());

    println!("Noise characteristics:");
    println!(
        "  Single-qubit error rate: {:.2e}",
        noise_model.single_qubit_error(0)
    );
    println!(
        "  Two-qubit error rate: {:.2e}",
        noise_model.two_qubit_error(0, 1)
    );
    println!("  T1 time: {:.1} μs", noise_model.t1_time(0));
    println!("  T2 time: {:.1} μs", noise_model.t2_time(0));
    println!("  CNOT gate time: {:.1} ns", noise_model.gate_time("CNOT"));

    let original_fidelity = optimizer.estimate_fidelity(circuit);
    println!("\nOriginal circuit fidelity: {:.4}", original_fidelity);

    let optimized = optimizer.optimize(circuit)?;
    let optimized_fidelity = optimizer.estimate_fidelity(&optimized);
    println!("Optimized circuit fidelity: {:.4}", optimized_fidelity);

    if optimized_fidelity > original_fidelity {
        println!(
            "✓ Fidelity improved by {:.4}",
            optimized_fidelity - original_fidelity
        );
    } else {
        println!("→ No fidelity improvement (circuit already optimal)");
    }

    println!();
    Ok(())
}

fn demo_ibm_noise(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- IBM-like Noise Model ---");

    let noise_model = NoiseModel::ibm_like(4);
    let coupling_map = CouplingMap::linear(4);
    let optimizer = NoiseAwareOptimizer::new(noise_model.clone()).with_coupling_map(coupling_map);

    println!("IBM-like noise characteristics:");
    println!(
        "  Single-qubit error rate: {:.2e}",
        noise_model.single_qubit_error(0)
    );
    println!(
        "  Two-qubit error rate (adjacent): {:.2e}",
        noise_model.two_qubit_error(0, 1)
    );
    println!("  Hadamard gate time: {:.1} ns", noise_model.gate_time("H"));
    println!("  CNOT gate time: {:.1} ns", noise_model.gate_time("CNOT"));

    let original_fidelity = optimizer.estimate_fidelity(circuit);
    println!("\nOriginal circuit fidelity: {:.4}", original_fidelity);

    let optimized = optimizer.optimize(circuit)?;
    let optimized_fidelity = optimizer.estimate_fidelity(&optimized);
    println!("Optimized circuit fidelity: {:.4}", optimized_fidelity);

    println!("Available optimization passes:");
    for pass in optimizer.get_passes() {
        println!("  - {}", pass.name());
    }

    println!();
    Ok(())
}

fn demo_noise_aware_cost_model(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Noise-Aware Cost Analysis ---");

    let uniform_noise = NoiseModel::uniform(4);
    let ibm_noise = NoiseModel::ibm_like(4);

    let uniform_cost_model = NoiseAwareCostModel::new(uniform_noise);
    let ibm_cost_model = NoiseAwareCostModel::new(ibm_noise);

    let uniform_cost = uniform_cost_model.circuit_cost(circuit);
    let ibm_cost = ibm_cost_model.circuit_cost(circuit);

    println!("Circuit costs with different noise models:");
    println!("  Uniform noise model: {:.2}", uniform_cost);
    println!("  IBM-like noise model: {:.2}", ibm_cost);

    // Analyze individual gate costs
    println!("\nGate-by-gate cost analysis (IBM model):");
    for (i, gate) in circuit.gates().iter().enumerate() {
        let gate_cost = ibm_cost_model.gate_cost(gate.as_ref());
        println!("  Gate {}: {} - Cost: {:.2}", i, gate.name(), gate_cost);
    }

    println!();
    Ok(())
}

fn demo_noise_optimization_passes(
    circuit: &Circuit<4>,
) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Individual Optimization Passes ---");

    let noise_model = NoiseModel::ibm_like(4);
    let coupling_map = CouplingMap::linear(4);

    // Test coherence optimization
    let coherence_opt = CoherenceOptimization::new(noise_model.clone());
    let cost_model = NoiseAwareCostModel::new(noise_model.clone());

    if coherence_opt.should_apply() {
        let coherence_result = coherence_opt.apply(circuit, &cost_model)?;
        println!("✓ Coherence optimization applied");
        println!("  Original gates: {}", circuit.num_gates());
        println!("  After coherence opt: {}", coherence_result.num_gates());
    }

    // Test noise-aware mapping
    let mapping_opt = NoiseAwareMapping::new(noise_model.clone(), coupling_map.clone());
    if mapping_opt.should_apply() {
        let mapping_result = mapping_opt.apply(circuit, &cost_model)?;
        println!("✓ Noise-aware mapping applied");
        println!("  Original gates: {}", circuit.num_gates());
        println!("  After mapping opt: {}", mapping_result.num_gates());
    }

    // Test dynamical decoupling
    let dd_opt = DynamicalDecoupling::new(noise_model.clone());
    if dd_opt.should_apply() {
        let dd_result = dd_opt.apply(circuit, &cost_model)?;
        println!("✓ Dynamical decoupling applied");
        println!("  Original gates: {}", circuit.num_gates());
        println!("  After DD insertion: {}", dd_result.num_gates());
    }

    println!();
    Ok(())
}

fn demo_fidelity_comparison() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Fidelity Comparison Across Noise Models ---");

    // Create circuits of different complexity
    let circuits = vec![
        create_simple_circuit()?,
        create_medium_circuit()?,
        create_complex_circuit()?,
    ];

    let noise_models = vec![
        ("Ideal", NoiseModel::new()),
        ("Uniform", NoiseModel::uniform(4)),
        ("IBM-like", NoiseModel::ibm_like(4)),
    ];

    println!(
        "{:<12} {:<8} {:<8} {:<8}",
        "Circuit", "Ideal", "Uniform", "IBM-like"
    );
    println!("{:-<40}", "");

    for (i, circuit) in circuits.iter().enumerate() {
        let circuit_name = match i {
            0 => "Simple",
            1 => "Medium",
            2 => "Complex",
            _ => "Unknown",
        };

        print!("{:<12}", circuit_name);

        for (_, noise_model) in &noise_models {
            let optimizer = NoiseAwareOptimizer::new(noise_model.clone());
            let fidelity = optimizer.estimate_fidelity(circuit);
            print!(" {:<8.4}", fidelity);
        }
        println!();
    }

    println!();
    Ok(())
}

fn create_simple_circuit() -> quantrs2_core::error::QuantRS2Result<Circuit<4>> {
    let mut circuit = Circuit::<4>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    Ok(circuit)
}

fn create_medium_circuit() -> quantrs2_core::error::QuantRS2Result<Circuit<4>> {
    let mut circuit = Circuit::<4>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(Hadamard { target: QubitId(1) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;
    Ok(circuit)
}

fn create_complex_circuit() -> quantrs2_core::error::QuantRS2Result<Circuit<4>> {
    let mut circuit = Circuit::<4>::new();
    for i in 0..4 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }
    for i in 0..3 {
        circuit.add_gate(CNOT {
            control: QubitId(i),
            target: QubitId(i + 1),
        })?;
    }
    for i in 0..4 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }
    for i in 0..3 {
        circuit.add_gate(CNOT {
            control: QubitId(i + 1),
            target: QubitId(i),
        })?;
    }
    Ok(circuit)
}

examples/routing_demo.rs (line 14)

fn main() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("=== Quantum Circuit Routing Demo ===\n");

    // Create a test circuit with gates that require routing
    let mut circuit = Circuit::<4>::new();

    // Add gates that create connectivity issues on linear devices
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(Hadamard { target: QubitId(1) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(3),
    })?; // Non-adjacent!
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(0),
    })?; // Another non-adjacent!

    println!("Original circuit:");
    println!("H(0), H(1), CNOT(0,3), CNOT(1,2), CNOT(2,0)");
    println!("Total gates: {}\n", circuit.num_gates());

    // Test different coupling maps
    demo_linear_coupling(&circuit)?;
    demo_grid_coupling(&circuit)?;
    demo_custom_device(&circuit)?;

    Ok(())
}

examples/tensor_network_demo.rs (line 67)

fn demo_circuit_compression() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Circuit Compression ---");

    // Create a circuit with repetitive structure
    let mut circuit = Circuit::<4>::new();

    // Add many gates
    for i in 0..3 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }

    for i in 0..3 {
        circuit.add_gate(CNOT {
            control: QubitId(i),
            target: QubitId(i + 1),
        })?;
    }

    for i in 0..4 {
        circuit.add_gate(T { target: QubitId(i) })?;
    }

    for i in (1..4).rev() {
        circuit.add_gate(CNOT {
            control: QubitId(i - 1),
            target: QubitId(i),
        })?;
    }

    println!("Original circuit: {} gates", circuit.num_gates());

    // Compress using tensor networks
    let compressor = TensorNetworkCompressor::new(16); // max bond dimension
    let compressed = compressor.compress(&circuit)?;

    println!(
        "Compression ratio: {:.2}%",
        compressed.compression_ratio() * 100.0
    );

    // Check fidelity
    let fidelity = compressed.fidelity(&circuit)?;
    println!("Fidelity with original: {:.6}", fidelity);

    println!();
    Ok(())
}

fn demo_mps_representation() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Matrix Product State Representation ---");

    // Create a circuit that generates an interesting entangled state
    let mut circuit = Circuit::<6>::new();

    // Create W state: (|100000⟩ + |010000⟩ + |001000⟩ + |000100⟩ + |000010⟩ + |000001⟩)/√6
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(RotationZ {
        target: QubitId(0),
        theta: std::f64::consts::PI / 3.0,
    })?;

    for i in 0..5 {
        circuit.add_gate(CNOT {
            control: QubitId(i),
            target: QubitId(i + 1),
        })?;
    }

    println!("Created circuit for W state preparation");

    // Convert to MPS
    let mps = MatrixProductState::from_circuit(&circuit)?;
    println!("Converted to MPS representation");

    // Compress with different bond dimensions
    let bond_dims = vec![2, 4, 8, 16];

    for &max_bond in &bond_dims {
        let mut mps_copy = MatrixProductState::from_circuit(&circuit)?;
        mps_copy.compress(max_bond, 1e-10)?;

        // In a real implementation, would calculate actual compression metrics
        println!("Max bond dimension {}: compression successful", max_bond);
    }

    println!();
    Ok(())
}

fn demo_compression_methods() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Different Compression Methods ---");

    let mut circuit = Circuit::<5>::new();

    // Build a deep circuit
    for _ in 0..5 {
        for i in 0..5 {
            circuit.add_gate(Hadamard { target: QubitId(i) })?;
        }
        for i in 0..4 {
            circuit.add_gate(CNOT {
                control: QubitId(i),
                target: QubitId(i + 1),
            })?;
        }
    }

    println!("Built deep circuit with {} gates", circuit.num_gates());

    // Test different compression methods
    let methods = vec![
        CompressionMethod::SVD,
        CompressionMethod::DMRG,
        CompressionMethod::TEBD,
    ];

    for method in methods {
        let compressor = TensorNetworkCompressor::new(32).with_method(method.clone());

        let compressed = compressor.compress(&circuit)?;

        println!("\n{:?} compression:", method);
        println!(
            "  Compression ratio: {:.2}%",
            compressed.compression_ratio() * 100.0
        );

        // Try to decompress
        let decompressed = compressed.decompress()?;
        println!("  Decompressed to {} gates", decompressed.num_gates());
    }

    println!();
    Ok(())
}

fn demo_tensor_contraction() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Tensor Contraction Optimization ---");

    // Create a circuit with specific structure
    let mut circuit = Circuit::<4>::new();

    // Layer 1: Single-qubit gates
    for i in 0..4 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }

    // Layer 2: Entangling gates
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;

    // Layer 3: Cross entangling
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    // Convert to tensor network
    let converter = CircuitToTensorNetwork::<4>::new()
        .with_max_bond_dim(8)
        .with_tolerance(1e-12);

    let tn = converter.convert(&circuit)?;

    println!("Converted circuit to tensor network");
    println!("Network has {} tensors", circuit.num_gates());

    // Contract the network
    let result = tn.contract_all()?;
    println!("Contracted to single tensor of rank {}", result.rank());

    println!();
    Ok(())
}

fn demo_circuit_analysis() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Circuit Analysis via Tensor Networks ---");

    // Create circuits to compare
    let mut circuit1 = Circuit::<3>::new();
    circuit1.add_gate(Hadamard { target: QubitId(0) })?;
    circuit1.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit1.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    let mut circuit2 = Circuit::<3>::new();
    circuit2.add_gate(Hadamard { target: QubitId(0) })?;
    circuit2.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(2),
    })?;
    circuit2.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;

    // Convert to MPS for efficient comparison
    let mps1 = MatrixProductState::from_circuit(&circuit1)?;
    let mps2 = MatrixProductState::from_circuit(&circuit2)?;

    // Calculate overlap (would indicate circuit similarity)
    let overlap = mps1.overlap(&mps2)?;
    println!("Circuit overlap: |⟨ψ₁|ψ₂⟩| = {:.6}", overlap.norm());

    // Compress both circuits
    let compressor = TensorNetworkCompressor::new(16);
    let comp1 = compressor.compress(&circuit1)?;
    let comp2 = compressor.compress(&circuit2)?;

    println!(
        "Circuit 1 compression: {:.2}%",
        comp1.compression_ratio() * 100.0
    );
    println!(
        "Circuit 2 compression: {:.2}%",
        comp2.compression_ratio() * 100.0
    );

    Ok(())
}

examples/qasm_example.rs (line 28)

fn export_example() {
    println!("1. Exporting a circuit to OpenQASM 3.0");
    println!("--------------------------------------");

    // Create a quantum teleportation circuit
    let mut builder = CircuitBuilder::<3>::new();

    // Create Bell pair between Alice and Bob
    let _ = builder.h(Qubit::new(1));
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));

    // Alice's operations
    let _ = builder.cx(Qubit::new(0), Qubit::new(1));
    let _ = builder.h(Qubit::new(0));

    // Measurements (in real teleportation, these would be mid-circuit)
    let _ = builder.measure(Qubit::new(0));
    let _ = builder.measure(Qubit::new(1));

    // Bob's corrections (would be conditional in real circuit)
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));
    let _ = builder.cz(Qubit::new(0), Qubit::new(2));

    let circuit = builder.build();

    // Export with default options
    match export_qasm3(&circuit) {
        Ok(qasm) => {
            println!("Teleportation circuit in OpenQASM 3.0:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }

    // Export with custom options
    let options = ExportOptions {
        include_stdgates: true,
        decompose_custom: true,
        include_gate_comments: true,
        optimize: true,
        pretty_print: true,
    };

    let mut exporter = QasmExporter::new(options);
    match exporter.export(&circuit) {
        Ok(qasm) => {
            println!("\nWith custom options:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }
}

fn parse_example() {
    println!("\n2. Parsing OpenQASM 3.0 code");
    println!("----------------------------");

    let qasm_code = r#"
OPENQASM 3.0;
include "stdgates.inc";

// Quantum registers
qubit[5] q;
bit[5] c;

// Create W state
reset q;
ry(1.91063) q[0];  // arccos(1/sqrt(5))
cx q[0], q[1];

// Controlled rotations to distribute amplitude
cry(1.10715) q[1], q[2];  // arccos(1/2)
cx q[1], q[2];

cry(0.95532) q[2], q[3];  // arccos(1/sqrt(3))
cx q[2], q[3];

cry(pi/4) q[3], q[4];
cx q[3], q[4];

// Measure all qubits
measure q -> c;
"#;

    match parse_qasm3(qasm_code) {
        Ok(program) => {
            println!("Successfully parsed QASM program!");
            println!("Version: {}", program.version);
            println!("Includes: {:?}", program.includes);
            println!("Declarations: {} items", program.declarations.len());
            println!("Statements: {} operations", program.statements.len());

            // Pretty print the parsed program
            println!("\nReconstructed QASM:");
            println!("{}", program);
        }
        Err(e) => println!("Parse error: {}", e),
    }
}

fn validation_example() {
    println!("\n3. Validating QASM programs");
    println!("---------------------------");

    // Valid program
    let valid_qasm = r#"
OPENQASM 3.0;

gate mybell a, b {
    h a;
    cx a, b;
}

qubit[4] q;
bit[2] c;

mybell q[0], q[1];
mybell q[2], q[3];

measure q[0] -> c[0];
measure q[2] -> c[1];
"#;

    println!("Validating correct program...");
    match parse_qasm3(valid_qasm) {
        Ok(program) => match validate_qasm3(&program) {
            Ok(()) => println!("✓ Program is valid!"),
            Err(e) => println!("✗ Validation error: {}", e),
        },
        Err(e) => println!("Parse error: {}", e),
    }

    // Program with errors
    let invalid_qasm = r#"
OPENQASM 3.0;

qubit[2] q;
bit[2] c;

// Error: using undefined register
h r[0];

// Error: index out of bounds
cx q[0], q[5];

// Error: wrong number of parameters
rx q[0];  // Missing angle parameter
"#;

    println!("\nValidating program with errors...");
    match parse_qasm3(invalid_qasm) {
        Ok(program) => match validate_qasm3(&program) {
            Ok(()) => println!("Program is valid (unexpected!)"),
            Err(e) => println!("✓ Caught validation error: {}", e),
        },
        Err(e) => println!("Parse error: {}", e),
    }
}

fn round_trip_example() {
    println!("\n4. Round-trip conversion");
    println!("------------------------");

    // Create a variational circuit
    let mut builder = CircuitBuilder::<4>::new();

    // Layer 1: Single-qubit rotations
    for i in 0..4 {
        let _ = builder.ry(Qubit::new(i), 0.5);
        let _ = builder.rz(Qubit::new(i), 0.3);
    }

    // Layer 2: Entangling gates
    for i in 0..3 {
        let _ = builder.cx(Qubit::new(i), Qubit::new(i + 1));
    }
    let _ = builder.cx(Qubit::new(3), Qubit::new(0)); // Circular connectivity

    // Layer 3: More rotations
    for i in 0..4 {
        let _ = builder.rx(Qubit::new(i), -0.2);
    }

    // Measurements
    for i in 0..4 {
        let _ = builder.measure(Qubit::new(i));
    }

    let original = builder.build();

    println!(
        "Original circuit created with {} gates",
        original.gates().len()
    );

    // Export to QASM
    match export_qasm3(&original) {
        Ok(qasm) => {
            println!("\nExported QASM:");
            println!("{}", qasm);

            // Parse it back
            match parse_qasm3(&qasm) {
                Ok(program) => {
                    println!("\n✓ Successfully parsed the exported QASM!");

                    // Validate it
                    match validate_qasm3(&program) {
                        Ok(()) => println!("✓ Validation passed!"),
                        Err(e) => println!("✗ Validation error: {}", e),
                    }

                    // Count operations
                    let gate_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Gate(_))
                        })
                        .count();
                    let measure_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Measure(_))
                        })
                        .count();

                    println!("\nParsed circuit has:");
                    println!("  - {} gate operations", gate_count);
                    println!("  - {} measurements", measure_count);
                }
                Err(e) => println!("Parse error: {}", e),
            }
        }
        Err(e) => println!("Export error: {}", e),
    }
}

Additional examples can be found in:

• examples/pulse_demo.rs
• examples/classical_control_demo.rs
• examples/distributed_demo.rs
• examples/crosstalk_demo.rs
• examples/advanced_features_demo.rs
• examples/qc_co_optimization_demo.rs

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

Examples found in repository

examples/noise_optimization_demo.rs (line 16)

fn main() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("=== Noise-Aware Circuit Optimization Demo ===\n");

    // Create a test circuit
    let mut circuit = Circuit::<4>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(Hadamard { target: QubitId(2) })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    println!("Original circuit:");
    println!("H(0), CNOT(0,1), H(2), CNOT(2,3), CNOT(1,2)");
    println!("Total gates: {}\n", circuit.num_gates());

    // Test different noise models
    demo_uniform_noise(&circuit)?;
    demo_ibm_noise(&circuit)?;
    demo_noise_aware_cost_model(&circuit)?;
    demo_noise_optimization_passes(&circuit)?;

    Ok(())
}

fn demo_uniform_noise(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Uniform Noise Model ---");

    let noise_model = NoiseModel::uniform(4);
    let optimizer = NoiseAwareOptimizer::new(noise_model.clone());

    println!("Noise characteristics:");
    println!(
        "  Single-qubit error rate: {:.2e}",
        noise_model.single_qubit_error(0)
    );
    println!(
        "  Two-qubit error rate: {:.2e}",
        noise_model.two_qubit_error(0, 1)
    );
    println!("  T1 time: {:.1} μs", noise_model.t1_time(0));
    println!("  T2 time: {:.1} μs", noise_model.t2_time(0));
    println!("  CNOT gate time: {:.1} ns", noise_model.gate_time("CNOT"));

    let original_fidelity = optimizer.estimate_fidelity(circuit);
    println!("\nOriginal circuit fidelity: {:.4}", original_fidelity);

    let optimized = optimizer.optimize(circuit)?;
    let optimized_fidelity = optimizer.estimate_fidelity(&optimized);
    println!("Optimized circuit fidelity: {:.4}", optimized_fidelity);

    if optimized_fidelity > original_fidelity {
        println!(
            "✓ Fidelity improved by {:.4}",
            optimized_fidelity - original_fidelity
        );
    } else {
        println!("→ No fidelity improvement (circuit already optimal)");
    }

    println!();
    Ok(())
}

fn demo_ibm_noise(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- IBM-like Noise Model ---");

    let noise_model = NoiseModel::ibm_like(4);
    let coupling_map = CouplingMap::linear(4);
    let optimizer = NoiseAwareOptimizer::new(noise_model.clone()).with_coupling_map(coupling_map);

    println!("IBM-like noise characteristics:");
    println!(
        "  Single-qubit error rate: {:.2e}",
        noise_model.single_qubit_error(0)
    );
    println!(
        "  Two-qubit error rate (adjacent): {:.2e}",
        noise_model.two_qubit_error(0, 1)
    );
    println!("  Hadamard gate time: {:.1} ns", noise_model.gate_time("H"));
    println!("  CNOT gate time: {:.1} ns", noise_model.gate_time("CNOT"));

    let original_fidelity = optimizer.estimate_fidelity(circuit);
    println!("\nOriginal circuit fidelity: {:.4}", original_fidelity);

    let optimized = optimizer.optimize(circuit)?;
    let optimized_fidelity = optimizer.estimate_fidelity(&optimized);
    println!("Optimized circuit fidelity: {:.4}", optimized_fidelity);

    println!("Available optimization passes:");
    for pass in optimizer.get_passes() {
        println!("  - {}", pass.name());
    }

    println!();
    Ok(())
}

fn demo_noise_aware_cost_model(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Noise-Aware Cost Analysis ---");

    let uniform_noise = NoiseModel::uniform(4);
    let ibm_noise = NoiseModel::ibm_like(4);

    let uniform_cost_model = NoiseAwareCostModel::new(uniform_noise);
    let ibm_cost_model = NoiseAwareCostModel::new(ibm_noise);

    let uniform_cost = uniform_cost_model.circuit_cost(circuit);
    let ibm_cost = ibm_cost_model.circuit_cost(circuit);

    println!("Circuit costs with different noise models:");
    println!("  Uniform noise model: {:.2}", uniform_cost);
    println!("  IBM-like noise model: {:.2}", ibm_cost);

    // Analyze individual gate costs
    println!("\nGate-by-gate cost analysis (IBM model):");
    for (i, gate) in circuit.gates().iter().enumerate() {
        let gate_cost = ibm_cost_model.gate_cost(gate.as_ref());
        println!("  Gate {}: {} - Cost: {:.2}", i, gate.name(), gate_cost);
    }

    println!();
    Ok(())
}

fn demo_noise_optimization_passes(
    circuit: &Circuit<4>,
) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Individual Optimization Passes ---");

    let noise_model = NoiseModel::ibm_like(4);
    let coupling_map = CouplingMap::linear(4);

    // Test coherence optimization
    let coherence_opt = CoherenceOptimization::new(noise_model.clone());
    let cost_model = NoiseAwareCostModel::new(noise_model.clone());

    if coherence_opt.should_apply() {
        let coherence_result = coherence_opt.apply(circuit, &cost_model)?;
        println!("✓ Coherence optimization applied");
        println!("  Original gates: {}", circuit.num_gates());
        println!("  After coherence opt: {}", coherence_result.num_gates());
    }

    // Test noise-aware mapping
    let mapping_opt = NoiseAwareMapping::new(noise_model.clone(), coupling_map.clone());
    if mapping_opt.should_apply() {
        let mapping_result = mapping_opt.apply(circuit, &cost_model)?;
        println!("✓ Noise-aware mapping applied");
        println!("  Original gates: {}", circuit.num_gates());
        println!("  After mapping opt: {}", mapping_result.num_gates());
    }

    // Test dynamical decoupling
    let dd_opt = DynamicalDecoupling::new(noise_model.clone());
    if dd_opt.should_apply() {
        let dd_result = dd_opt.apply(circuit, &cost_model)?;
        println!("✓ Dynamical decoupling applied");
        println!("  Original gates: {}", circuit.num_gates());
        println!("  After DD insertion: {}", dd_result.num_gates());
    }

    println!();
    Ok(())
}

fn demo_fidelity_comparison() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Fidelity Comparison Across Noise Models ---");

    // Create circuits of different complexity
    let circuits = vec![
        create_simple_circuit()?,
        create_medium_circuit()?,
        create_complex_circuit()?,
    ];

    let noise_models = vec![
        ("Ideal", NoiseModel::new()),
        ("Uniform", NoiseModel::uniform(4)),
        ("IBM-like", NoiseModel::ibm_like(4)),
    ];

    println!(
        "{:<12} {:<8} {:<8} {:<8}",
        "Circuit", "Ideal", "Uniform", "IBM-like"
    );
    println!("{:-<40}", "");

    for (i, circuit) in circuits.iter().enumerate() {
        let circuit_name = match i {
            0 => "Simple",
            1 => "Medium",
            2 => "Complex",
            _ => "Unknown",
        };

        print!("{:<12}", circuit_name);

        for (_, noise_model) in &noise_models {
            let optimizer = NoiseAwareOptimizer::new(noise_model.clone());
            let fidelity = optimizer.estimate_fidelity(circuit);
            print!(" {:<8.4}", fidelity);
        }
        println!();
    }

    println!();
    Ok(())
}

fn create_simple_circuit() -> quantrs2_core::error::QuantRS2Result<Circuit<4>> {
    let mut circuit = Circuit::<4>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    Ok(circuit)
}

fn create_medium_circuit() -> quantrs2_core::error::QuantRS2Result<Circuit<4>> {
    let mut circuit = Circuit::<4>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(Hadamard { target: QubitId(1) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;
    Ok(circuit)
}

fn create_complex_circuit() -> quantrs2_core::error::QuantRS2Result<Circuit<4>> {
    let mut circuit = Circuit::<4>::new();
    for i in 0..4 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }
    for i in 0..3 {
        circuit.add_gate(CNOT {
            control: QubitId(i),
            target: QubitId(i + 1),
        })?;
    }
    for i in 0..4 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }
    for i in 0..3 {
        circuit.add_gate(CNOT {
            control: QubitId(i + 1),
            target: QubitId(i),
        })?;
    }
    Ok(circuit)
}

examples/routing_demo.rs (line 17)

fn main() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("=== Quantum Circuit Routing Demo ===\n");

    // Create a test circuit with gates that require routing
    let mut circuit = Circuit::<4>::new();

    // Add gates that create connectivity issues on linear devices
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(Hadamard { target: QubitId(1) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(3),
    })?; // Non-adjacent!
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(0),
    })?; // Another non-adjacent!

    println!("Original circuit:");
    println!("H(0), H(1), CNOT(0,3), CNOT(1,2), CNOT(2,0)");
    println!("Total gates: {}\n", circuit.num_gates());

    // Test different coupling maps
    demo_linear_coupling(&circuit)?;
    demo_grid_coupling(&circuit)?;
    demo_custom_device(&circuit)?;

    Ok(())
}

examples/tensor_network_demo.rs (line 71)

fn demo_circuit_compression() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Circuit Compression ---");

    // Create a circuit with repetitive structure
    let mut circuit = Circuit::<4>::new();

    // Add many gates
    for i in 0..3 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }

    for i in 0..3 {
        circuit.add_gate(CNOT {
            control: QubitId(i),
            target: QubitId(i + 1),
        })?;
    }

    for i in 0..4 {
        circuit.add_gate(T { target: QubitId(i) })?;
    }

    for i in (1..4).rev() {
        circuit.add_gate(CNOT {
            control: QubitId(i - 1),
            target: QubitId(i),
        })?;
    }

    println!("Original circuit: {} gates", circuit.num_gates());

    // Compress using tensor networks
    let compressor = TensorNetworkCompressor::new(16); // max bond dimension
    let compressed = compressor.compress(&circuit)?;

    println!(
        "Compression ratio: {:.2}%",
        compressed.compression_ratio() * 100.0
    );

    // Check fidelity
    let fidelity = compressed.fidelity(&circuit)?;
    println!("Fidelity with original: {:.6}", fidelity);

    println!();
    Ok(())
}

fn demo_mps_representation() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Matrix Product State Representation ---");

    // Create a circuit that generates an interesting entangled state
    let mut circuit = Circuit::<6>::new();

    // Create W state: (|100000⟩ + |010000⟩ + |001000⟩ + |000100⟩ + |000010⟩ + |000001⟩)/√6
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(RotationZ {
        target: QubitId(0),
        theta: std::f64::consts::PI / 3.0,
    })?;

    for i in 0..5 {
        circuit.add_gate(CNOT {
            control: QubitId(i),
            target: QubitId(i + 1),
        })?;
    }

    println!("Created circuit for W state preparation");

    // Convert to MPS
    let mps = MatrixProductState::from_circuit(&circuit)?;
    println!("Converted to MPS representation");

    // Compress with different bond dimensions
    let bond_dims = vec![2, 4, 8, 16];

    for &max_bond in &bond_dims {
        let mut mps_copy = MatrixProductState::from_circuit(&circuit)?;
        mps_copy.compress(max_bond, 1e-10)?;

        // In a real implementation, would calculate actual compression metrics
        println!("Max bond dimension {}: compression successful", max_bond);
    }

    println!();
    Ok(())
}

fn demo_compression_methods() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Different Compression Methods ---");

    let mut circuit = Circuit::<5>::new();

    // Build a deep circuit
    for _ in 0..5 {
        for i in 0..5 {
            circuit.add_gate(Hadamard { target: QubitId(i) })?;
        }
        for i in 0..4 {
            circuit.add_gate(CNOT {
                control: QubitId(i),
                target: QubitId(i + 1),
            })?;
        }
    }

    println!("Built deep circuit with {} gates", circuit.num_gates());

    // Test different compression methods
    let methods = vec![
        CompressionMethod::SVD,
        CompressionMethod::DMRG,
        CompressionMethod::TEBD,
    ];

    for method in methods {
        let compressor = TensorNetworkCompressor::new(32).with_method(method.clone());

        let compressed = compressor.compress(&circuit)?;

        println!("\n{:?} compression:", method);
        println!(
            "  Compression ratio: {:.2}%",
            compressed.compression_ratio() * 100.0
        );

        // Try to decompress
        let decompressed = compressed.decompress()?;
        println!("  Decompressed to {} gates", decompressed.num_gates());
    }

    println!();
    Ok(())
}

fn demo_tensor_contraction() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Tensor Contraction Optimization ---");

    // Create a circuit with specific structure
    let mut circuit = Circuit::<4>::new();

    // Layer 1: Single-qubit gates
    for i in 0..4 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }

    // Layer 2: Entangling gates
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;

    // Layer 3: Cross entangling
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    // Convert to tensor network
    let converter = CircuitToTensorNetwork::<4>::new()
        .with_max_bond_dim(8)
        .with_tolerance(1e-12);

    let tn = converter.convert(&circuit)?;

    println!("Converted circuit to tensor network");
    println!("Network has {} tensors", circuit.num_gates());

    // Contract the network
    let result = tn.contract_all()?;
    println!("Contracted to single tensor of rank {}", result.rank());

    println!();
    Ok(())
}

fn demo_circuit_analysis() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Circuit Analysis via Tensor Networks ---");

    // Create circuits to compare
    let mut circuit1 = Circuit::<3>::new();
    circuit1.add_gate(Hadamard { target: QubitId(0) })?;
    circuit1.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit1.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    let mut circuit2 = Circuit::<3>::new();
    circuit2.add_gate(Hadamard { target: QubitId(0) })?;
    circuit2.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(2),
    })?;
    circuit2.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;

    // Convert to MPS for efficient comparison
    let mps1 = MatrixProductState::from_circuit(&circuit1)?;
    let mps2 = MatrixProductState::from_circuit(&circuit2)?;

    // Calculate overlap (would indicate circuit similarity)
    let overlap = mps1.overlap(&mps2)?;
    println!("Circuit overlap: |⟨ψ₁|ψ₂⟩| = {:.6}", overlap.norm());

    // Compress both circuits
    let compressor = TensorNetworkCompressor::new(16);
    let comp1 = compressor.compress(&circuit1)?;
    let comp2 = compressor.compress(&circuit2)?;

    println!(
        "Circuit 1 compression: {:.2}%",
        comp1.compression_ratio() * 100.0
    );
    println!(
        "Circuit 2 compression: {:.2}%",
        comp2.compression_ratio() * 100.0
    );

    Ok(())
}

examples/pulse_demo.rs (line 173)

fn demo_pulse_compilation() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Circuit to Pulse Compilation ---");

    // Create device configuration
    let device_config = DeviceConfig::default_config(4);
    println!("Device configuration:");
    println!("  Qubits: 4");
    println!("  Qubit frequencies: ~5 GHz");
    println!("  Sample rate: {} GS/s", device_config.sample_rate);

    // Create compiler
    let compiler = PulseCompiler::new(device_config);

    // Create a simple circuit
    let mut circuit = Circuit::<4>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(RotationZ {
        target: QubitId(1),
        theta: PI / 4.0,
    })?;

    println!("\nCompiling circuit:");
    for (i, gate) in circuit.gates().iter().enumerate() {
        println!("  {}: {}", i, gate.name());
    }

    // Compile to pulses
    let pulse_schedule = compiler.compile(&circuit)?;

    println!("\nCompiled pulse schedule:");
    println!("  Duration: {} ns", pulse_schedule.duration);
    println!("  Instructions: {}", pulse_schedule.instructions.len());

    // Show channel usage
    let mut channel_usage = std::collections::HashMap::new();
    for (_, instruction) in &pulse_schedule.instructions {
        match instruction {
            PulseInstruction::Play { channel, .. } => {
                *channel_usage.entry(format!("{:?}", channel)).or_insert(0) += 1;
            }
            _ => {}
        }
    }

    println!("\nChannel usage:");
    for (channel, count) in channel_usage {
        println!("  {}: {} pulses", channel, count);
    }

    println!();
    Ok(())
}

examples/crosstalk_demo.rs (line 79)

fn demo_scheduling_strategies() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Scheduling Strategies ---");

    // Create a test circuit
    let mut circuit = Circuit::<5>::new();

    // Layer 1: Single-qubit gates
    for i in 0..5 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }

    // Layer 2: Two-qubit gates
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;
    circuit.add_gate(CZ {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    // Layer 3: More single-qubit gates
    for i in 0..5 {
        circuit.add_gate(RotationZ {
            target: QubitId(i),
            theta: std::f64::consts::PI / 4.0,
        })?;
    }

    println!("Test circuit: {} gates on 5 qubits", circuit.num_gates());

    let model = CrosstalkModel::uniform(5, 0.05);

    // Strategy 1: Minimize crosstalk
    let scheduler1 =
        CrosstalkScheduler::new(model.clone()).with_strategy(SchedulingStrategy::MinimizeCrosstalk);

    let schedule1 = scheduler1.schedule(&circuit)?;

    println!("\nMinimize Crosstalk Strategy:");
    println!("  Time slices: {}", schedule1.time_slices.len());
    println!("  Total crosstalk: {:.4}", schedule1.total_crosstalk);
    println!("  Execution time: {:.1} ns", schedule1.execution_time);

    // Strategy 2: Minimize time with constraint
    let scheduler2 =
        CrosstalkScheduler::new(model.clone()).with_strategy(SchedulingStrategy::MinimizeTime {
            max_crosstalk: 0.02,
        });

    let schedule2 = scheduler2.schedule(&circuit)?;

    println!("\nMinimize Time Strategy (max crosstalk = 0.02):");
    println!("  Time slices: {}", schedule2.time_slices.len());
    println!("  Total crosstalk: {:.4}", schedule2.total_crosstalk);
    println!("  Execution time: {:.1} ns", schedule2.execution_time);

    // Strategy 3: Balanced
    let scheduler3 = CrosstalkScheduler::new(model).with_strategy(SchedulingStrategy::Balanced {
        time_weight: 0.5,
        crosstalk_weight: 0.5,
    });

    let schedule3 = scheduler3.schedule(&circuit)?;

    println!("\nBalanced Strategy:");
    println!("  Time slices: {}", schedule3.time_slices.len());
    println!("  Total crosstalk: {:.4}", schedule3.total_crosstalk);
    println!("  Execution time: {:.1} ns", schedule3.execution_time);

    // Show time slice details for first schedule
    println!("\nTime slice details (MinimizeCrosstalk):");
    for (i, slice) in schedule1.time_slices.iter().enumerate() {
        println!(
            "  Slice {}: {} gates, max crosstalk = {:.4}, duration = {:.1} ns",
            i,
            slice.gates.len(),
            slice.max_crosstalk,
            slice.duration
        );
    }

    println!();
    Ok(())
}

fn demo_crosstalk_analysis() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Cross-talk Analysis ---");

    // Create a circuit with potential crosstalk issues
    let mut circuit = Circuit::<6>::new();

    // Parallel two-qubit gates on neighboring qubits
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(4),
        target: QubitId(5),
    })?;

    // More gates that might have crosstalk
    circuit.add_gate(CZ {
        control: QubitId(1),
        target: QubitId(2),
    })?;
    circuit.add_gate(CZ {
        control: QubitId(3),
        target: QubitId(4),
    })?;

    let model = CrosstalkModel::uniform(6, 0.05);
    let analyzer = CrosstalkAnalyzer::new(model);

    let analysis = analyzer.analyze(&circuit);

    println!("Circuit analysis:");
    println!("  Total gates: {}", analysis.total_gates);
    println!("  Maximum crosstalk: {:.4}", analysis.max_crosstalk);
    println!("  Problematic pairs: {}", analysis.problematic_pairs.len());

    println!("\nTop problematic gate pairs:");
    for (i, (g1, g2, crosstalk)) in analysis.problematic_pairs.iter().take(3).enumerate() {
        println!(
            "  {}. Gates {} and {}: crosstalk = {:.4}",
            i + 1,
            g1,
            g2,
            crosstalk
        );
    }

    // Get reordering suggestions
    let suggestions = analyzer.suggest_reordering(&circuit)?;

    println!("\nSuggested reorderings:");
    for suggestion in suggestions.iter().take(3) {
        println!(
            "  Move gates {} and {} apart: {}",
            suggestion.gate1, suggestion.gate2, suggestion.reason
        );
        println!(
            "    Expected improvement: {:.4}",
            suggestion.expected_improvement
        );
    }

    println!();
    Ok(())
}

fn demo_device_specific_scheduling() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Device-Specific Scheduling ---");

    // Create a realistic device characterization
    let mut characterization = CrosstalkCharacterization {
        measured_crosstalk: std::collections::HashMap::new(),
        single_qubit_measurements: std::collections::HashMap::new(),
        significance_threshold: 0.01,
        device_coupling: vec![
            (0, 1),
            (1, 2),
            (2, 3),
            (3, 4), // Linear connectivity
            (0, 5),
            (1, 5),
            (2, 5),
            (3, 5),
            (4, 5), // Star center at qubit 5
        ],
    };

    // Add some measured crosstalk values
    characterization
        .single_qubit_measurements
        .insert((0, 1), 0.02);
    characterization
        .single_qubit_measurements
        .insert((1, 2), 0.02);
    characterization
        .single_qubit_measurements
        .insert((0, 5), 0.03);
    characterization
        .single_qubit_measurements
        .insert((1, 5), 0.03);

    characterization
        .measured_crosstalk
        .insert(((0, 1), (2, 3)), 0.05);
    characterization
        .measured_crosstalk
        .insert(((0, 1), (3, 4)), 0.02);
    characterization
        .measured_crosstalk
        .insert(((0, 5), (1, 5)), 0.08);

    let model = CrosstalkModel::from_characterization(&characterization);
    let scheduler = CrosstalkScheduler::new(model);

    // Create circuit that uses the device topology
    let mut circuit = Circuit::<6>::new();

    // Operations on linear chain
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    // Operations using star center
    circuit.add_gate(Hadamard { target: QubitId(5) })?;
    circuit.add_gate(CZ {
        control: QubitId(5),
        target: QubitId(0),
    })?;
    circuit.add_gate(CZ {
        control: QubitId(5),
        target: QubitId(3),
    })?;

    let schedule = scheduler.schedule(&circuit)?;

    println!("Device-specific schedule:");
    println!("  Device topology: Linear chain + star center");
    println!("  Time slices: {}", schedule.time_slices.len());
    println!("  Total crosstalk: {:.4}", schedule.total_crosstalk);

    println!("\nSchedule details:");
    for (i, slice) in schedule.time_slices.iter().enumerate() {
        let gates = &circuit.gates();
        print!("  Slice {}: ", i);
        for &gate_idx in &slice.gates {
            print!("{} ", gates[gate_idx].name());
        }
        println!("(crosstalk: {:.4})", slice.max_crosstalk);
    }

    println!();
    Ok(())
}

fn demo_adaptive_scheduling() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Adaptive Scheduling ---");

    // Create a circuit with varying gate densities
    let mut circuit = Circuit::<8>::new();

    // Dense region: many gates on qubits 0-3
    for _ in 0..3 {
        for i in 0..3 {
            circuit.add_gate(Hadamard { target: QubitId(i) })?;
            circuit.add_gate(RotationZ {
                target: QubitId(i),
                theta: 0.1,
            })?;
        }
        circuit.add_gate(CNOT {
            control: QubitId(0),
            target: QubitId(1),
        })?;
        circuit.add_gate(CNOT {
            control: QubitId(2),
            target: QubitId(3),
        })?;
    }

    // Sparse region: few gates on qubits 4-7
    circuit.add_gate(Hadamard { target: QubitId(4) })?;
    circuit.add_gate(CNOT {
        control: QubitId(4),
        target: QubitId(5),
    })?;
    circuit.add_gate(PauliX { target: QubitId(7) })?;

    println!("Circuit with dense (qubits 0-3) and sparse (qubits 4-7) regions");
    println!("Total gates: {}", circuit.num_gates());

    let model = CrosstalkModel::uniform(8, 0.05);
    let analyzer = CrosstalkAnalyzer::new(model.clone());

    // Analyze before scheduling
    let analysis = analyzer.analyze(&circuit);
    println!("\nCrosstalk analysis:");
    println!(
        "  Problematic pairs in dense region: {}",
        analysis
            .problematic_pairs
            .iter()
            .filter(|(g1, g2, _)| {
                let gates = circuit.gates();
                let q1 = gates[*g1].qubits()[0].id();
                let q2 = gates[*g2].qubits()[0].id();
                q1 < 4 && q2 < 4
            })
            .count()
    );

    // Schedule with adaptive strategy
    let scheduler = CrosstalkScheduler::new(model);
    let schedule = scheduler.schedule(&circuit)?;

    println!("\nAdaptive scheduling results:");
    println!("  Time slices: {}", schedule.time_slices.len());
    println!(
        "  Average gates per slice: {:.1}",
        circuit.num_gates() as f64 / schedule.time_slices.len() as f64
    );

    Ok(())
}

examples/advanced_features_demo.rs (line 24)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== QuantRS2 Circuit Advanced Features Demo ===\n");

    // 1. Basic circuit creation
    println!("1. Creating a basic quantum circuit:");
    let mut circuit = Circuit::<3>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;
    println!("   Circuit with {} gates created", circuit.gates().len());

    // 2. ZX-calculus optimization
    println!("\n2. ZX-calculus optimization:");
    let zx_optimizer = ZXOptimizer::new();
    let zx_diagram = zx_optimizer.circuit_to_zx(&circuit)?;
    println!(
        "   ZX diagram with {} nodes created",
        zx_diagram.nodes.len()
    );

    // 3. SciRS2 graph analysis
    println!("\n3. SciRS2 graph analysis:");
    let mut analyzer = SciRS2CircuitAnalyzer::new();
    let analysis = analyzer.analyze_circuit(&circuit)?;
    println!(
        "   Graph metrics: {} nodes, {} edges",
        analysis.metrics.num_nodes, analysis.metrics.num_edges
    );
    println!("   Communities detected: {}", analysis.communities.len());

    // 4. ML-based optimization
    println!("\n4. ML-based circuit optimization:");
    let ml_strategy = MLStrategy::NeuralNetwork {
        architecture: vec![32, 16, 8],
        learning_rate: 0.001,
        epochs: 10,
        batch_size: 16,
    };
    let mut ml_optimizer = MLCircuitOptimizer::new(ml_strategy);
    let ml_result = ml_optimizer.optimize(&circuit)?;
    println!(
        "   ML optimization completed in {:?}",
        ml_result.optimization_time
    );

    // 5. Fault-tolerant compilation
    println!("\n5. Fault-tolerant compilation:");
    let code = QECCode::SteaneCode;
    let ft_compiler = FaultTolerantCompiler::new(code);
    let ft_circuit = ft_compiler.compile(&circuit)?;
    println!(
        "   Fault-tolerant circuit: {} physical qubits, {} magic states",
        ft_circuit.physical_qubit_count, ft_circuit.magic_state_requirements
    );

    // 6. Photonic circuit conversion
    println!("\n6. Photonic quantum computation:");
    let photonic_circuit = PhotonicConverter::quantum_to_photonic(&circuit)?;
    println!(
        "   Photonic circuit: {} modes, {} gates",
        photonic_circuit.num_modes,
        photonic_circuit.gates.len()
    );

    // 7. Topological quantum computation
    println!("\n7. Topological quantum computation:");
    let anyon_model = AnyonModel::fibonacci();
    let topo_compiler = TopologicalCompiler::new(anyon_model);
    let topo_circuit = topo_compiler.compile_quantum_circuit(&circuit)?;
    println!(
        "   Topological circuit: {} anyons, {} braiding operations",
        topo_circuit.anyon_count(),
        topo_circuit.total_braiding_operations()
    );

    // 8. Circuit-to-simulator interface
    println!("\n8. Circuit compilation for simulators:");
    let mut compiler = CircuitCompiler::new();
    compiler.add_target(CompilationTarget {
        backend: SimulatorBackend::StateVector {
            max_qubits: 20,
            use_gpu: false,
            memory_optimization: MemoryOptimization::Basic,
        },
        optimization_level: SimulatorOptimizationLevel::Basic,
        instruction_set: InstructionSet::Universal,
        parallel_execution: true,
        batch_size: Some(10),
    });

    let compiled = compiler.compile(&circuit)?;
    println!(
        "   Compiled circuit: {} instructions, estimated memory: {} bytes",
        compiled.instructions.len(),
        compiled.resources.memory_bytes
    );

    // 9. Mid-circuit measurements and feed-forward
    println!("\n9. Mid-circuit measurements and feed-forward:");
    let mut measurement_circuit = MeasurementCircuit::<2>::new();
    measurement_circuit.add_gate(Box::new(Hadamard { target: QubitId(0) }))?;
    let bit = measurement_circuit.measure(QubitId(0))?;

    let condition = ClassicalCondition::equals(
        ClassicalValue::Integer(bit as u64),
        ClassicalValue::Integer(1),
    );
    measurement_circuit.add_conditional(condition, Box::new(PauliX { target: QubitId(1) }))?;
    println!(
        "   Measurement circuit with {} operations created",
        measurement_circuit.num_operations()
    );

    // 10. Cross-talk aware scheduling
    println!("\n10. Cross-talk aware scheduling:");
    let crosstalk_model = CrosstalkModel::uniform(3, 0.05);
    let scheduler = CrosstalkScheduler::new(crosstalk_model);
    let schedule = scheduler.schedule(&circuit)?;
    println!(
        "   Scheduled into {} time slices, total crosstalk: {:.3}",
        schedule.time_slices.len(),
        schedule.total_crosstalk
    );

    println!("\n=== Demo completed successfully! ===");
    Ok(())
}

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

Examples found in repository

examples/noise_optimization_demo.rs (line 136)

fn demo_noise_aware_cost_model(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Noise-Aware Cost Analysis ---");

    let uniform_noise = NoiseModel::uniform(4);
    let ibm_noise = NoiseModel::ibm_like(4);

    let uniform_cost_model = NoiseAwareCostModel::new(uniform_noise);
    let ibm_cost_model = NoiseAwareCostModel::new(ibm_noise);

    let uniform_cost = uniform_cost_model.circuit_cost(circuit);
    let ibm_cost = ibm_cost_model.circuit_cost(circuit);

    println!("Circuit costs with different noise models:");
    println!("  Uniform noise model: {:.2}", uniform_cost);
    println!("  IBM-like noise model: {:.2}", ibm_cost);

    // Analyze individual gate costs
    println!("\nGate-by-gate cost analysis (IBM model):");
    for (i, gate) in circuit.gates().iter().enumerate() {
        let gate_cost = ibm_cost_model.gate_cost(gate.as_ref());
        println!("  Gate {}: {} - Cost: {:.2}", i, gate.name(), gate_cost);
    }

    println!();
    Ok(())
}

examples/synthesis_demo.rs (line 50)

fn demo_single_qubit_synthesis() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Single-Qubit Unitary Synthesis ---");

    let config = SynthesisConfig::default();
    let synthesizer = SingleQubitSynthesizer::new(config);

    // Test common single-qubit unitaries
    let unitaries = vec![
        ("Hadamard", hadamard()),
        ("Pauli-X", pauli_x()),
        ("Pauli-Y", pauli_y()),
        ("Pauli-Z", pauli_z()),
        ("RX(π/4)", rotation_x(PI / 4.0)),
        ("RY(π/3)", rotation_y(PI / 3.0)),
        ("RZ(π/2)", rotation_z(PI / 2.0)),
    ];

    for (name, unitary) in unitaries {
        let circuit: Circuit<1> = synthesizer.synthesize(&unitary, QubitId(0))?;
        println!("{:>12}: {} gates", name, circuit.num_gates());

        // Show gate sequence for Hadamard as example
        if name == "Hadamard" {
            println!("             Gate sequence: ");
            for (i, gate) in circuit.gates().iter().enumerate() {
                println!("             {}: {}", i, gate.name());
            }
        }
    }

    println!();
    Ok(())
}

fn demo_two_qubit_synthesis() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Two-Qubit Unitary Synthesis ---");

    let config = SynthesisConfig::default();
    let synthesizer = TwoQubitSynthesizer::new(config);

    // Test CNOT synthesis
    let cnot_matrix = cnot();
    let circuit: Circuit<2> = synthesizer.synthesize(&cnot_matrix, QubitId(0), QubitId(1))?;

    println!("CNOT synthesis:");
    println!("  Gates: {}", circuit.num_gates());
    println!("  Gate sequence:");
    for (i, gate) in circuit.gates().iter().enumerate() {
        println!("    {}: {}", i, gate.name());
    }

    // Test controlled rotation
    let theta = PI / 4.0;
    println!("\nControlled RY(π/4) synthesis:");
    let controlled_ry_circuit: Circuit<2> = synthesizer.cartan_decomposition(
        &cnot_matrix, // Placeholder - would be actual controlled-RY matrix
        QubitId(0),
        QubitId(1),
    )?;
    println!("  Gates: {}", controlled_ry_circuit.num_gates());

    println!();
    Ok(())
}

fn demo_common_operations() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Common Quantum Operations ---");

    let synthesizer = UnitarySynthesizer::default_config();

    // Quantum Fourier Transform
    println!("Quantum Fourier Transform:");
    for n_qubits in 2..=4 {
        let qft_circuit: Circuit<4> = synthesizer.synthesize_qft(n_qubits)?;
        println!("  QFT-{}: {} gates", n_qubits, qft_circuit.num_gates());
    }

    // Toffoli gate
    let toffoli_circuit: Circuit<3> =
        synthesizer.synthesize_toffoli(QubitId(0), QubitId(1), QubitId(2))?;
    println!("\nToffoli gate: {} gates", toffoli_circuit.num_gates());

    // Show first few gates of Toffoli decomposition
    println!("  First 5 gates:");
    for (i, gate) in toffoli_circuit.gates().iter().take(5).enumerate() {
        println!("    {}: {}", i, gate.name());
    }

    println!();
    Ok(())
}

examples/pulse_demo.rs (line 184)

fn demo_pulse_compilation() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Circuit to Pulse Compilation ---");

    // Create device configuration
    let device_config = DeviceConfig::default_config(4);
    println!("Device configuration:");
    println!("  Qubits: 4");
    println!("  Qubit frequencies: ~5 GHz");
    println!("  Sample rate: {} GS/s", device_config.sample_rate);

    // Create compiler
    let compiler = PulseCompiler::new(device_config);

    // Create a simple circuit
    let mut circuit = Circuit::<4>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(RotationZ {
        target: QubitId(1),
        theta: PI / 4.0,
    })?;

    println!("\nCompiling circuit:");
    for (i, gate) in circuit.gates().iter().enumerate() {
        println!("  {}: {}", i, gate.name());
    }

    // Compile to pulses
    let pulse_schedule = compiler.compile(&circuit)?;

    println!("\nCompiled pulse schedule:");
    println!("  Duration: {} ns", pulse_schedule.duration);
    println!("  Instructions: {}", pulse_schedule.instructions.len());

    // Show channel usage
    let mut channel_usage = std::collections::HashMap::new();
    for (_, instruction) in &pulse_schedule.instructions {
        match instruction {
            PulseInstruction::Play { channel, .. } => {
                *channel_usage.entry(format!("{:?}", channel)).or_insert(0) += 1;
            }
            _ => {}
        }
    }

    println!("\nChannel usage:");
    for (channel, count) in channel_usage {
        println!("  {}: {} pulses", channel, count);
    }

    println!();
    Ok(())
}

examples/qasm_example.rs (line 215)

fn round_trip_example() {
    println!("\n4. Round-trip conversion");
    println!("------------------------");

    // Create a variational circuit
    let mut builder = CircuitBuilder::<4>::new();

    // Layer 1: Single-qubit rotations
    for i in 0..4 {
        let _ = builder.ry(Qubit::new(i), 0.5);
        let _ = builder.rz(Qubit::new(i), 0.3);
    }

    // Layer 2: Entangling gates
    for i in 0..3 {
        let _ = builder.cx(Qubit::new(i), Qubit::new(i + 1));
    }
    let _ = builder.cx(Qubit::new(3), Qubit::new(0)); // Circular connectivity

    // Layer 3: More rotations
    for i in 0..4 {
        let _ = builder.rx(Qubit::new(i), -0.2);
    }

    // Measurements
    for i in 0..4 {
        let _ = builder.measure(Qubit::new(i));
    }

    let original = builder.build();

    println!(
        "Original circuit created with {} gates",
        original.gates().len()
    );

    // Export to QASM
    match export_qasm3(&original) {
        Ok(qasm) => {
            println!("\nExported QASM:");
            println!("{}", qasm);

            // Parse it back
            match parse_qasm3(&qasm) {
                Ok(program) => {
                    println!("\n✓ Successfully parsed the exported QASM!");

                    // Validate it
                    match validate_qasm3(&program) {
                        Ok(()) => println!("✓ Validation passed!"),
                        Err(e) => println!("✗ Validation error: {}", e),
                    }

                    // Count operations
                    let gate_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Gate(_))
                        })
                        .count();
                    let measure_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Measure(_))
                        })
                        .count();

                    println!("\nParsed circuit has:");
                    println!("  - {} gate operations", gate_count);
                    println!("  - {} measurements", measure_count);
                }
                Err(e) => println!("Parse error: {}", e),
            }
        }
        Err(e) => println!("Export error: {}", e),
    }
}

examples/crosstalk_demo.rs (line 313)

fn demo_device_specific_scheduling() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Device-Specific Scheduling ---");

    // Create a realistic device characterization
    let mut characterization = CrosstalkCharacterization {
        measured_crosstalk: std::collections::HashMap::new(),
        single_qubit_measurements: std::collections::HashMap::new(),
        significance_threshold: 0.01,
        device_coupling: vec![
            (0, 1),
            (1, 2),
            (2, 3),
            (3, 4), // Linear connectivity
            (0, 5),
            (1, 5),
            (2, 5),
            (3, 5),
            (4, 5), // Star center at qubit 5
        ],
    };

    // Add some measured crosstalk values
    characterization
        .single_qubit_measurements
        .insert((0, 1), 0.02);
    characterization
        .single_qubit_measurements
        .insert((1, 2), 0.02);
    characterization
        .single_qubit_measurements
        .insert((0, 5), 0.03);
    characterization
        .single_qubit_measurements
        .insert((1, 5), 0.03);

    characterization
        .measured_crosstalk
        .insert(((0, 1), (2, 3)), 0.05);
    characterization
        .measured_crosstalk
        .insert(((0, 1), (3, 4)), 0.02);
    characterization
        .measured_crosstalk
        .insert(((0, 5), (1, 5)), 0.08);

    let model = CrosstalkModel::from_characterization(&characterization);
    let scheduler = CrosstalkScheduler::new(model);

    // Create circuit that uses the device topology
    let mut circuit = Circuit::<6>::new();

    // Operations on linear chain
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    // Operations using star center
    circuit.add_gate(Hadamard { target: QubitId(5) })?;
    circuit.add_gate(CZ {
        control: QubitId(5),
        target: QubitId(0),
    })?;
    circuit.add_gate(CZ {
        control: QubitId(5),
        target: QubitId(3),
    })?;

    let schedule = scheduler.schedule(&circuit)?;

    println!("Device-specific schedule:");
    println!("  Device topology: Linear chain + star center");
    println!("  Time slices: {}", schedule.time_slices.len());
    println!("  Total crosstalk: {:.4}", schedule.total_crosstalk);

    println!("\nSchedule details:");
    for (i, slice) in schedule.time_slices.iter().enumerate() {
        let gates = &circuit.gates();
        print!("  Slice {}: ", i);
        for &gate_idx in &slice.gates {
            print!("{} ", gates[gate_idx].name());
        }
        println!("(crosstalk: {:.4})", slice.max_crosstalk);
    }

    println!();
    Ok(())
}

fn demo_adaptive_scheduling() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Adaptive Scheduling ---");

    // Create a circuit with varying gate densities
    let mut circuit = Circuit::<8>::new();

    // Dense region: many gates on qubits 0-3
    for _ in 0..3 {
        for i in 0..3 {
            circuit.add_gate(Hadamard { target: QubitId(i) })?;
            circuit.add_gate(RotationZ {
                target: QubitId(i),
                theta: 0.1,
            })?;
        }
        circuit.add_gate(CNOT {
            control: QubitId(0),
            target: QubitId(1),
        })?;
        circuit.add_gate(CNOT {
            control: QubitId(2),
            target: QubitId(3),
        })?;
    }

    // Sparse region: few gates on qubits 4-7
    circuit.add_gate(Hadamard { target: QubitId(4) })?;
    circuit.add_gate(CNOT {
        control: QubitId(4),
        target: QubitId(5),
    })?;
    circuit.add_gate(PauliX { target: QubitId(7) })?;

    println!("Circuit with dense (qubits 0-3) and sparse (qubits 4-7) regions");
    println!("Total gates: {}", circuit.num_gates());

    let model = CrosstalkModel::uniform(8, 0.05);
    let analyzer = CrosstalkAnalyzer::new(model.clone());

    // Analyze before scheduling
    let analysis = analyzer.analyze(&circuit);
    println!("\nCrosstalk analysis:");
    println!(
        "  Problematic pairs in dense region: {}",
        analysis
            .problematic_pairs
            .iter()
            .filter(|(g1, g2, _)| {
                let gates = circuit.gates();
                let q1 = gates[*g1].qubits()[0].id();
                let q2 = gates[*g2].qubits()[0].id();
                q1 < 4 && q2 < 4
            })
            .count()
    );

    // Schedule with adaptive strategy
    let scheduler = CrosstalkScheduler::new(model);
    let schedule = scheduler.schedule(&circuit)?;

    println!("\nAdaptive scheduling results:");
    println!("  Time slices: {}", schedule.time_slices.len());
    println!(
        "  Average gates per slice: {:.1}",
        circuit.num_gates() as f64 / schedule.time_slices.len() as f64
    );

    Ok(())
}

examples/advanced_features_demo.rs (line 33)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== QuantRS2 Circuit Advanced Features Demo ===\n");

    // 1. Basic circuit creation
    println!("1. Creating a basic quantum circuit:");
    let mut circuit = Circuit::<3>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;
    println!("   Circuit with {} gates created", circuit.gates().len());

    // 2. ZX-calculus optimization
    println!("\n2. ZX-calculus optimization:");
    let zx_optimizer = ZXOptimizer::new();
    let zx_diagram = zx_optimizer.circuit_to_zx(&circuit)?;
    println!(
        "   ZX diagram with {} nodes created",
        zx_diagram.nodes.len()
    );

    // 3. SciRS2 graph analysis
    println!("\n3. SciRS2 graph analysis:");
    let mut analyzer = SciRS2CircuitAnalyzer::new();
    let analysis = analyzer.analyze_circuit(&circuit)?;
    println!(
        "   Graph metrics: {} nodes, {} edges",
        analysis.metrics.num_nodes, analysis.metrics.num_edges
    );
    println!("   Communities detected: {}", analysis.communities.len());

    // 4. ML-based optimization
    println!("\n4. ML-based circuit optimization:");
    let ml_strategy = MLStrategy::NeuralNetwork {
        architecture: vec![32, 16, 8],
        learning_rate: 0.001,
        epochs: 10,
        batch_size: 16,
    };
    let mut ml_optimizer = MLCircuitOptimizer::new(ml_strategy);
    let ml_result = ml_optimizer.optimize(&circuit)?;
    println!(
        "   ML optimization completed in {:?}",
        ml_result.optimization_time
    );

    // 5. Fault-tolerant compilation
    println!("\n5. Fault-tolerant compilation:");
    let code = QECCode::SteaneCode;
    let ft_compiler = FaultTolerantCompiler::new(code);
    let ft_circuit = ft_compiler.compile(&circuit)?;
    println!(
        "   Fault-tolerant circuit: {} physical qubits, {} magic states",
        ft_circuit.physical_qubit_count, ft_circuit.magic_state_requirements
    );

    // 6. Photonic circuit conversion
    println!("\n6. Photonic quantum computation:");
    let photonic_circuit = PhotonicConverter::quantum_to_photonic(&circuit)?;
    println!(
        "   Photonic circuit: {} modes, {} gates",
        photonic_circuit.num_modes,
        photonic_circuit.gates.len()
    );

    // 7. Topological quantum computation
    println!("\n7. Topological quantum computation:");
    let anyon_model = AnyonModel::fibonacci();
    let topo_compiler = TopologicalCompiler::new(anyon_model);
    let topo_circuit = topo_compiler.compile_quantum_circuit(&circuit)?;
    println!(
        "   Topological circuit: {} anyons, {} braiding operations",
        topo_circuit.anyon_count(),
        topo_circuit.total_braiding_operations()
    );

    // 8. Circuit-to-simulator interface
    println!("\n8. Circuit compilation for simulators:");
    let mut compiler = CircuitCompiler::new();
    compiler.add_target(CompilationTarget {
        backend: SimulatorBackend::StateVector {
            max_qubits: 20,
            use_gpu: false,
            memory_optimization: MemoryOptimization::Basic,
        },
        optimization_level: SimulatorOptimizationLevel::Basic,
        instruction_set: InstructionSet::Universal,
        parallel_execution: true,
        batch_size: Some(10),
    });

    let compiled = compiler.compile(&circuit)?;
    println!(
        "   Compiled circuit: {} instructions, estimated memory: {} bytes",
        compiled.instructions.len(),
        compiled.resources.memory_bytes
    );

    // 9. Mid-circuit measurements and feed-forward
    println!("\n9. Mid-circuit measurements and feed-forward:");
    let mut measurement_circuit = MeasurementCircuit::<2>::new();
    measurement_circuit.add_gate(Box::new(Hadamard { target: QubitId(0) }))?;
    let bit = measurement_circuit.measure(QubitId(0))?;

    let condition = ClassicalCondition::equals(
        ClassicalValue::Integer(bit as u64),
        ClassicalValue::Integer(1),
    );
    measurement_circuit.add_conditional(condition, Box::new(PauliX { target: QubitId(1) }))?;
    println!(
        "   Measurement circuit with {} operations created",
        measurement_circuit.num_operations()
    );

    // 10. Cross-talk aware scheduling
    println!("\n10. Cross-talk aware scheduling:");
    let crosstalk_model = CrosstalkModel::uniform(3, 0.05);
    let scheduler = CrosstalkScheduler::new(crosstalk_model);
    let schedule = scheduler.schedule(&circuit)?;
    println!(
        "   Scheduled into {} time slices, total crosstalk: {:.3}",
        schedule.time_slices.len(),
        schedule.total_crosstalk
    );

    println!("\n=== Demo completed successfully! ===");
    Ok(())
}

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 fn num_qubits(&self) -> usize

Get the number of qubits in the circuit

Examples found in repository

examples/distributed_demo.rs (line 86)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🌐 Distributed Circuit Execution Demo");
    println!("====================================\n");

    // Example 1: Setting up a distributed executor
    println!("1. Creating Distributed Executor");
    println!("--------------------------------");

    let mut executor = DistributedExecutor::new();
    println!("Created distributed executor with default configuration");
    println!("  Load balancing: {:?}", executor.load_balancer.strategy);
    println!("  Scheduling policy: {:?}", executor.scheduler.policy);
    println!(
        "  Fault tolerance enabled: {}",
        executor.fault_tolerance.enable_failover
    );
    println!(
        "  Redundancy level: {}",
        executor.fault_tolerance.redundancy_level
    );

    // Example 2: Adding different types of backends
    println!("\n2. Adding Execution Backends");
    println!("----------------------------");

    // Add a quantum hardware backend
    let hardware_backend = create_hardware_backend();
    println!("Adding hardware backend: {}", hardware_backend.id);
    executor.add_backend(hardware_backend)?;

    // Add a simulator backend
    let simulator_backend = create_simulator_backend();
    println!("Adding simulator backend: {}", simulator_backend.id);
    executor.add_backend(simulator_backend)?;

    // Add a cloud service backend
    let cloud_backend = create_cloud_backend();
    println!("Adding cloud backend: {}", cloud_backend.id);
    executor.add_backend(cloud_backend)?;

    // Add a hybrid backend
    let hybrid_backend = create_hybrid_backend();
    println!("Adding hybrid backend: {}", hybrid_backend.id);
    executor.add_backend(hybrid_backend)?;

    println!("Total backends added: {}", executor.backends.len());

    // Example 3: System health status
    println!("\n3. System Health Status");
    println!("-----------------------");

    let health = executor.get_health_status();
    println!("System health:");
    println!("  Total backends: {}", health.total_backends);
    println!("  Available backends: {}", health.available_backends);
    println!("  Total qubits: {}", health.total_qubits);
    println!(
        "  Average queue time: {:.2} seconds",
        health.average_queue_time
    );
    println!("  System load: {:.1}%", health.system_load * 100.0);

    // Example 4: Creating and submitting jobs
    println!("\n4. Creating and Submitting Jobs");
    println!("-------------------------------");

    // Create different types of circuits for testing
    let jobs = create_test_jobs();

    for (i, job) in jobs.iter().enumerate() {
        println!(
            "Job {}: {} ({} qubits, {} gates, priority: {:?})",
            i + 1,
            job.id,
            job.circuit.num_qubits(),
            job.circuit.num_gates(),
            job.priority
        );

        match executor.submit_job(job.clone()) {
            Ok(job_id) => println!("  ✅ Submitted successfully: {}", job_id),
            Err(e) => println!("  ❌ Submission failed: {}", e),
        }
    }

    // Example 5: Different load balancing strategies
    println!("\n5. Load Balancing Strategies");
    println!("----------------------------");

    let strategies = vec![
        ("Round Robin", LoadBalancingStrategy::RoundRobin),
        ("Least Connections", LoadBalancingStrategy::LeastConnections),
        ("Least Queue Time", LoadBalancingStrategy::LeastQueueTime),
        ("Best Performance", LoadBalancingStrategy::BestPerformance),
    ];

    for (name, strategy) in strategies {
        executor.load_balancer.strategy = strategy.clone();
        println!("  {}: {:?}", name, strategy);
    }

    // Example 6: Backend types and capabilities
    println!("\n6. Backend Types and Capabilities");
    println!("---------------------------------");

    for backend in &executor.backends {
        println!("Backend: {} ({:?})", backend.id, backend.status);
        match &backend.backend_type {
            BackendType::Hardware {
                vendor,
                model,
                location,
            } => {
                println!("  Type: Hardware ({} {} in {})", vendor, model, location);
            }
            BackendType::Simulator {
                simulator_type,
                host,
            } => {
                println!("  Type: Simulator ({:?} on {})", simulator_type, host);
            }
            BackendType::CloudService {
                provider,
                service_name,
                region,
            } => {
                println!(
                    "  Type: Cloud ({} {} in {})",
                    provider, service_name, region
                );
            }
            BackendType::Hybrid {
                quantum_backend: _,
                classical_resources,
            } => {
                println!(
                    "  Type: Hybrid ({} CPU cores, {:.1} GB memory)",
                    classical_resources.cpu_cores, classical_resources.memory_gb
                );
            }
        }

        println!("  Capabilities:");
        println!("    Max qubits: {}", backend.performance.max_qubits);
        println!("    Max depth: {}", backend.performance.max_depth);
        println!(
            "    Supported gates: {:?}",
            backend.capabilities.supported_gates
        );
        println!(
            "    Mid-circuit measurements: {}",
            backend.capabilities.mid_circuit_measurements
        );
        println!(
            "    Queue length: {}/{}",
            backend.queue_info.queue_length, backend.queue_info.max_queue_size
        );
        println!(
            "    Estimated wait time: {:.1} seconds",
            backend.queue_info.estimated_wait_time
        );
        println!();
    }

    // Example 7: Execution parameters and error mitigation
    println!("7. Execution Parameters and Error Mitigation");
    println!("--------------------------------------------");

    let error_mitigation_techniques = vec![
        (
            "Readout Error Mitigation",
            ErrorMitigation::ReadoutErrorMitigation,
        ),
        (
            "Zero Noise Extrapolation",
            ErrorMitigation::ZeroNoiseExtrapolation,
        ),
        (
            "Clifford Data Regression",
            ErrorMitigation::CliffordDataRegression,
        ),
        (
            "Symmetry Verification",
            ErrorMitigation::SymmetryVerification,
        ),
    ];

    for (name, technique) in error_mitigation_techniques {
        println!("  {}: {:?}", name, technique);
    }

    let result_formats = vec![
        ("Counts", ResultFormat::Counts),
        ("Probabilities", ResultFormat::Probabilities),
        ("Statevector", ResultFormat::Statevector),
        ("Expectation Values", ResultFormat::ExpectationValues),
    ];

    println!("\nResult formats:");
    for (name, format) in result_formats {
        println!("  {}: {:?}", name, format);
    }

    // Example 8: Fault tolerance and redundancy
    println!("\n8. Fault Tolerance and Redundancy");
    println!("---------------------------------");

    println!("Current fault tolerance configuration:");
    println!(
        "  Failover enabled: {}",
        executor.fault_tolerance.enable_failover
    );
    println!(
        "  Redundancy level: {}",
        executor.fault_tolerance.redundancy_level
    );
    println!(
        "  Error correction: {:?}",
        executor.fault_tolerance.error_correction
    );

    // Demonstrate different error correction strategies
    let error_correction_strategies = vec![
        ("None", ErrorCorrectionStrategy::None),
        ("Majority Voting", ErrorCorrectionStrategy::MajorityVoting),
        (
            "Quantum Error Correction",
            ErrorCorrectionStrategy::QuantumErrorCorrection,
        ),
        (
            "Classical Post-processing",
            ErrorCorrectionStrategy::ClassicalPostProcessing,
        ),
    ];

    println!("\nAvailable error correction strategies:");
    for (name, strategy) in error_correction_strategies {
        println!("  {}: {:?}", name, strategy);
    }

    // Example 9: Resource management and allocation
    println!("\n9. Resource Management and Allocation");
    println!("------------------------------------");

    println!("Resource pool:");
    println!(
        "  Total qubits: {}",
        executor.resource_manager.resource_pool.total_qubits
    );
    println!(
        "  Available slots: {}",
        executor.resource_manager.resource_pool.available_slots
    );
    println!(
        "  Memory pool: {:.1} GB",
        executor.resource_manager.resource_pool.memory_pool
    );
    println!(
        "  Compute pool: {:.1} CPU hours",
        executor.resource_manager.resource_pool.compute_pool
    );

    println!("\nAllocation policies:");
    if let Some(max_qubits) = executor
        .resource_manager
        .allocation_policies
        .max_qubits_per_user
    {
        println!("  Max qubits per user: {}", max_qubits);
    }
    if let Some(max_time) = executor
        .resource_manager
        .allocation_policies
        .max_execution_time
    {
        println!("  Max execution time: {:.1} seconds", max_time);
    }
    println!(
        "  Fair share: {}",
        executor.resource_manager.allocation_policies.fair_share
    );
    println!(
        "  Reserved resources: {:.1}%",
        executor
            .resource_manager
            .allocation_policies
            .reserved_resources
            * 100.0
    );

    // Example 10: Network configuration and authentication
    println!("\n10. Network Configuration and Authentication");
    println!("-------------------------------------------");

    for backend in &executor.backends {
        println!(
            "Backend {}: {}",
            backend.id, backend.network_config.endpoint
        );
        println!(
            "  Auth type: {:?}",
            backend.network_config.credentials.auth_type
        );
        println!(
            "  Connection timeout: {:.1}s",
            backend.network_config.timeouts.connection_timeout
        );
        println!(
            "  Request timeout: {:.1}s",
            backend.network_config.timeouts.request_timeout
        );
        println!(
            "  Max retries: {}",
            backend.network_config.retry_policy.max_retries
        );
        println!(
            "  Backoff strategy: {:?}",
            backend.network_config.retry_policy.backoff_strategy
        );
    }

    // Example 11: Job status and results (mock)
    println!("\n11. Job Status and Results");
    println!("--------------------------");

    for job in jobs.iter().take(3) {
        let status = executor.get_job_status(&job.id)?;
        println!("Job {}: {:?}", job.id, status);

        // Mock getting results for completed jobs
        if status == ExecutionStatus::Queued {
            let result = executor.get_results(&job.id)?;
            println!("  Status: {:?}", result.status);
            println!("  Backends used: {:?}", result.metadata.backends_used);
            println!("  Total time: {:?}", result.metadata.total_time);
            println!("  Queue time: {:?}", result.metadata.queue_time);
            println!("  Resource usage:");
            println!(
                "    CPU hours: {:.3}",
                result.metadata.resource_usage.cpu_hours
            );
            println!(
                "    Memory hours: {:.3}",
                result.metadata.resource_usage.memory_hours
            );
            println!(
                "    Qubit hours: {:.3}",
                result.metadata.resource_usage.qubit_hours
            );
            println!(
                "    Network usage: {:.3} GB",
                result.metadata.resource_usage.network_usage
            );
        }
    }

    // Example 12: Connectivity topologies
    println!("\n12. Connectivity Topologies");
    println!("---------------------------");

    let topologies = vec![
        ("Linear", distributed::TopologyType::Linear),
        (
            "2D Grid (3x3)",
            distributed::TopologyType::Grid2D { rows: 3, cols: 3 },
        ),
        ("All-to-all", distributed::TopologyType::AllToAll),
        (
            "Random (70% density)",
            distributed::TopologyType::Random { density: 0.7 },
        ),
    ];

    for (name, topology) in topologies {
        println!("  {}: {:?}", name, topology);
    }

    println!("\n✅ Distributed Circuit Execution Demo completed!");
    println!("\nNote: This demo shows the distributed execution framework structure.");
    println!("Real distributed execution requires actual quantum backends and networking.");

    Ok(())
}

pub fn num_gates(&self) -> usize

Get the number of gates in the circuit

Examples found in repository

examples/noise_optimization_demo.rs (line 33)

fn main() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("=== Noise-Aware Circuit Optimization Demo ===\n");

    // Create a test circuit
    let mut circuit = Circuit::<4>::new();
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(Hadamard { target: QubitId(2) })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    println!("Original circuit:");
    println!("H(0), CNOT(0,1), H(2), CNOT(2,3), CNOT(1,2)");
    println!("Total gates: {}\n", circuit.num_gates());

    // Test different noise models
    demo_uniform_noise(&circuit)?;
    demo_ibm_noise(&circuit)?;
    demo_noise_aware_cost_model(&circuit)?;
    demo_noise_optimization_passes(&circuit)?;

    Ok(())
}

fn demo_uniform_noise(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Uniform Noise Model ---");

    let noise_model = NoiseModel::uniform(4);
    let optimizer = NoiseAwareOptimizer::new(noise_model.clone());

    println!("Noise characteristics:");
    println!(
        "  Single-qubit error rate: {:.2e}",
        noise_model.single_qubit_error(0)
    );
    println!(
        "  Two-qubit error rate: {:.2e}",
        noise_model.two_qubit_error(0, 1)
    );
    println!("  T1 time: {:.1} μs", noise_model.t1_time(0));
    println!("  T2 time: {:.1} μs", noise_model.t2_time(0));
    println!("  CNOT gate time: {:.1} ns", noise_model.gate_time("CNOT"));

    let original_fidelity = optimizer.estimate_fidelity(circuit);
    println!("\nOriginal circuit fidelity: {:.4}", original_fidelity);

    let optimized = optimizer.optimize(circuit)?;
    let optimized_fidelity = optimizer.estimate_fidelity(&optimized);
    println!("Optimized circuit fidelity: {:.4}", optimized_fidelity);

    if optimized_fidelity > original_fidelity {
        println!(
            "✓ Fidelity improved by {:.4}",
            optimized_fidelity - original_fidelity
        );
    } else {
        println!("→ No fidelity improvement (circuit already optimal)");
    }

    println!();
    Ok(())
}

fn demo_ibm_noise(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- IBM-like Noise Model ---");

    let noise_model = NoiseModel::ibm_like(4);
    let coupling_map = CouplingMap::linear(4);
    let optimizer = NoiseAwareOptimizer::new(noise_model.clone()).with_coupling_map(coupling_map);

    println!("IBM-like noise characteristics:");
    println!(
        "  Single-qubit error rate: {:.2e}",
        noise_model.single_qubit_error(0)
    );
    println!(
        "  Two-qubit error rate (adjacent): {:.2e}",
        noise_model.two_qubit_error(0, 1)
    );
    println!("  Hadamard gate time: {:.1} ns", noise_model.gate_time("H"));
    println!("  CNOT gate time: {:.1} ns", noise_model.gate_time("CNOT"));

    let original_fidelity = optimizer.estimate_fidelity(circuit);
    println!("\nOriginal circuit fidelity: {:.4}", original_fidelity);

    let optimized = optimizer.optimize(circuit)?;
    let optimized_fidelity = optimizer.estimate_fidelity(&optimized);
    println!("Optimized circuit fidelity: {:.4}", optimized_fidelity);

    println!("Available optimization passes:");
    for pass in optimizer.get_passes() {
        println!("  - {}", pass.name());
    }

    println!();
    Ok(())
}

fn demo_noise_aware_cost_model(circuit: &Circuit<4>) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Noise-Aware Cost Analysis ---");

    let uniform_noise = NoiseModel::uniform(4);
    let ibm_noise = NoiseModel::ibm_like(4);

    let uniform_cost_model = NoiseAwareCostModel::new(uniform_noise);
    let ibm_cost_model = NoiseAwareCostModel::new(ibm_noise);

    let uniform_cost = uniform_cost_model.circuit_cost(circuit);
    let ibm_cost = ibm_cost_model.circuit_cost(circuit);

    println!("Circuit costs with different noise models:");
    println!("  Uniform noise model: {:.2}", uniform_cost);
    println!("  IBM-like noise model: {:.2}", ibm_cost);

    // Analyze individual gate costs
    println!("\nGate-by-gate cost analysis (IBM model):");
    for (i, gate) in circuit.gates().iter().enumerate() {
        let gate_cost = ibm_cost_model.gate_cost(gate.as_ref());
        println!("  Gate {}: {} - Cost: {:.2}", i, gate.name(), gate_cost);
    }

    println!();
    Ok(())
}

fn demo_noise_optimization_passes(
    circuit: &Circuit<4>,
) -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Individual Optimization Passes ---");

    let noise_model = NoiseModel::ibm_like(4);
    let coupling_map = CouplingMap::linear(4);

    // Test coherence optimization
    let coherence_opt = CoherenceOptimization::new(noise_model.clone());
    let cost_model = NoiseAwareCostModel::new(noise_model.clone());

    if coherence_opt.should_apply() {
        let coherence_result = coherence_opt.apply(circuit, &cost_model)?;
        println!("✓ Coherence optimization applied");
        println!("  Original gates: {}", circuit.num_gates());
        println!("  After coherence opt: {}", coherence_result.num_gates());
    }

    // Test noise-aware mapping
    let mapping_opt = NoiseAwareMapping::new(noise_model.clone(), coupling_map.clone());
    if mapping_opt.should_apply() {
        let mapping_result = mapping_opt.apply(circuit, &cost_model)?;
        println!("✓ Noise-aware mapping applied");
        println!("  Original gates: {}", circuit.num_gates());
        println!("  After mapping opt: {}", mapping_result.num_gates());
    }

    // Test dynamical decoupling
    let dd_opt = DynamicalDecoupling::new(noise_model.clone());
    if dd_opt.should_apply() {
        let dd_result = dd_opt.apply(circuit, &cost_model)?;
        println!("✓ Dynamical decoupling applied");
        println!("  Original gates: {}", circuit.num_gates());
        println!("  After DD insertion: {}", dd_result.num_gates());
    }

    println!();
    Ok(())
}

examples/routing_demo.rs (line 34)

fn main() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("=== Quantum Circuit Routing Demo ===\n");

    // Create a test circuit with gates that require routing
    let mut circuit = Circuit::<4>::new();

    // Add gates that create connectivity issues on linear devices
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(Hadamard { target: QubitId(1) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(3),
    })?; // Non-adjacent!
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(0),
    })?; // Another non-adjacent!

    println!("Original circuit:");
    println!("H(0), H(1), CNOT(0,3), CNOT(1,2), CNOT(2,0)");
    println!("Total gates: {}\n", circuit.num_gates());

    // Test different coupling maps
    demo_linear_coupling(&circuit)?;
    demo_grid_coupling(&circuit)?;
    demo_custom_device(&circuit)?;

    Ok(())
}

examples/synthesis_demo.rs (line 45)

fn demo_single_qubit_synthesis() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Single-Qubit Unitary Synthesis ---");

    let config = SynthesisConfig::default();
    let synthesizer = SingleQubitSynthesizer::new(config);

    // Test common single-qubit unitaries
    let unitaries = vec![
        ("Hadamard", hadamard()),
        ("Pauli-X", pauli_x()),
        ("Pauli-Y", pauli_y()),
        ("Pauli-Z", pauli_z()),
        ("RX(π/4)", rotation_x(PI / 4.0)),
        ("RY(π/3)", rotation_y(PI / 3.0)),
        ("RZ(π/2)", rotation_z(PI / 2.0)),
    ];

    for (name, unitary) in unitaries {
        let circuit: Circuit<1> = synthesizer.synthesize(&unitary, QubitId(0))?;
        println!("{:>12}: {} gates", name, circuit.num_gates());

        // Show gate sequence for Hadamard as example
        if name == "Hadamard" {
            println!("             Gate sequence: ");
            for (i, gate) in circuit.gates().iter().enumerate() {
                println!("             {}: {}", i, gate.name());
            }
        }
    }

    println!();
    Ok(())
}

fn demo_two_qubit_synthesis() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Two-Qubit Unitary Synthesis ---");

    let config = SynthesisConfig::default();
    let synthesizer = TwoQubitSynthesizer::new(config);

    // Test CNOT synthesis
    let cnot_matrix = cnot();
    let circuit: Circuit<2> = synthesizer.synthesize(&cnot_matrix, QubitId(0), QubitId(1))?;

    println!("CNOT synthesis:");
    println!("  Gates: {}", circuit.num_gates());
    println!("  Gate sequence:");
    for (i, gate) in circuit.gates().iter().enumerate() {
        println!("    {}: {}", i, gate.name());
    }

    // Test controlled rotation
    let theta = PI / 4.0;
    println!("\nControlled RY(π/4) synthesis:");
    let controlled_ry_circuit: Circuit<2> = synthesizer.cartan_decomposition(
        &cnot_matrix, // Placeholder - would be actual controlled-RY matrix
        QubitId(0),
        QubitId(1),
    )?;
    println!("  Gates: {}", controlled_ry_circuit.num_gates());

    println!();
    Ok(())
}

fn demo_common_operations() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Common Quantum Operations ---");

    let synthesizer = UnitarySynthesizer::default_config();

    // Quantum Fourier Transform
    println!("Quantum Fourier Transform:");
    for n_qubits in 2..=4 {
        let qft_circuit: Circuit<4> = synthesizer.synthesize_qft(n_qubits)?;
        println!("  QFT-{}: {} gates", n_qubits, qft_circuit.num_gates());
    }

    // Toffoli gate
    let toffoli_circuit: Circuit<3> =
        synthesizer.synthesize_toffoli(QubitId(0), QubitId(1), QubitId(2))?;
    println!("\nToffoli gate: {} gates", toffoli_circuit.num_gates());

    // Show first few gates of Toffoli decomposition
    println!("  First 5 gates:");
    for (i, gate) in toffoli_circuit.gates().iter().take(5).enumerate() {
        println!("    {}: {}", i, gate.name());
    }

    println!();
    Ok(())
}

fn demo_gate_sets() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Different Gate Sets ---");

    let gate_sets = vec![
        ("Universal", GateSet::Universal),
        ("IBM", GateSet::IBM),
        ("Google", GateSet::Google),
        ("Rigetti", GateSet::Rigetti),
    ];

    let hadamard_matrix = hadamard();

    for (name, gate_set) in gate_sets {
        let synthesizer = UnitarySynthesizer::for_gate_set(gate_set);

        // For this demo, just show the configuration
        println!("{} gate set configured", name);

        // In a full implementation, would show different gate decompositions
        // For now, all use the same underlying synthesis
        let config = SynthesisConfig {
            gate_set: synthesizer.config.gate_set.clone(),
            ..Default::default()
        };

        println!("  Tolerance: {}", config.tolerance);
        println!("  Max gates: {}", config.max_gates);
    }

    println!();
    Ok(())
}

fn demo_validation() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Unitary Matrix Validation ---");

    let synthesizer = UnitarySynthesizer::default_config();

    // Test valid unitaries
    println!("Valid unitaries:");

    let identity_2x2 = DMatrix::from_vec(
        2,
        2,
        vec![
            C64::new(1.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(1.0, 0.0),
        ],
    );

    match synthesizer.validate_unitary(&identity_2x2) {
        Ok(_) => println!("  ✓ 2x2 Identity matrix"),
        Err(e) => println!("  ✗ 2x2 Identity matrix: {}", e),
    }

    let hadamard_matrix = DMatrix::from_vec(
        2,
        2,
        vec![
            C64::new(1.0 / 2.0_f64.sqrt(), 0.0),
            C64::new(1.0 / 2.0_f64.sqrt(), 0.0),
            C64::new(1.0 / 2.0_f64.sqrt(), 0.0),
            C64::new(-1.0 / 2.0_f64.sqrt(), 0.0),
        ],
    );

    match synthesizer.validate_unitary(&hadamard_matrix) {
        Ok(_) => println!("  ✓ Hadamard matrix"),
        Err(e) => println!("  ✗ Hadamard matrix: {}", e),
    }

    // Test invalid unitaries
    println!("\nInvalid unitaries:");

    let non_square = DMatrix::from_vec(
        2,
        3,
        vec![
            C64::new(1.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(1.0, 0.0),
            C64::new(0.0, 0.0),
        ],
    );

    match synthesizer.validate_unitary(&non_square) {
        Ok(_) => println!("  ✓ Non-square matrix (unexpected)"),
        Err(_) => println!("  ✗ Non-square matrix (expected)"),
    }

    let non_unitary = DMatrix::from_vec(
        2,
        2,
        vec![
            C64::new(2.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(1.0, 0.0),
        ],
    );

    match synthesizer.validate_unitary(&non_unitary) {
        Ok(_) => println!("  ✓ Non-unitary matrix (unexpected)"),
        Err(_) => println!("  ✗ Non-unitary matrix (expected)"),
    }

    let wrong_dimension = DMatrix::from_vec(
        3,
        3,
        vec![
            C64::new(1.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(1.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(0.0, 0.0),
            C64::new(1.0, 0.0),
        ],
    );

    match synthesizer.validate_unitary(&wrong_dimension) {
        Ok(_) => println!("  ✓ Non-power-of-2 dimension (unexpected)"),
        Err(_) => println!("  ✗ Non-power-of-2 dimension (expected)"),
    }

    println!();
    Ok(())
}

fn demo_synthesis_comparison() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Synthesis Algorithm Comparison ---");

    let test_unitaries = vec![
        ("Identity", DMatrix::identity(2, 2)),
        (
            "Hadamard",
            DMatrix::from_vec(
                2,
                2,
                vec![
                    C64::new(1.0 / 2.0_f64.sqrt(), 0.0),
                    C64::new(1.0 / 2.0_f64.sqrt(), 0.0),
                    C64::new(1.0 / 2.0_f64.sqrt(), 0.0),
                    C64::new(-1.0 / 2.0_f64.sqrt(), 0.0),
                ],
            ),
        ),
        (
            "T gate",
            DMatrix::from_vec(
                2,
                2,
                vec![
                    C64::new(1.0, 0.0),
                    C64::new(0.0, 0.0),
                    C64::new(0.0, 0.0),
                    C64::from_polar(1.0, PI / 4.0),
                ],
            ),
        ),
    ];

    let optimization_levels = vec![0, 1, 2, 3];

    println!(
        "{:<12} {:<8} {:<8} {:<8} {:<8}",
        "Unitary", "Opt-0", "Opt-1", "Opt-2", "Opt-3"
    );
    println!("{:-<48}", "");

    for (name, unitary) in test_unitaries {
        print!("{:<12}", name);

        for &opt_level in &optimization_levels {
            let config = SynthesisConfig {
                optimization_level: opt_level,
                ..Default::default()
            };

            let synthesizer = UnitarySynthesizer::new(config);
            match synthesizer.synthesize::<1>(&unitary) {
                Ok(circuit) => print!(" {:<8}", circuit.num_gates()),
                Err(_) => print!(" {:<8}", "Error"),
            }
        }
        println!();
    }

    println!();
    Ok(())
}

examples/tensor_network_demo.rs (line 92)

fn demo_circuit_compression() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Circuit Compression ---");

    // Create a circuit with repetitive structure
    let mut circuit = Circuit::<4>::new();

    // Add many gates
    for i in 0..3 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }

    for i in 0..3 {
        circuit.add_gate(CNOT {
            control: QubitId(i),
            target: QubitId(i + 1),
        })?;
    }

    for i in 0..4 {
        circuit.add_gate(T { target: QubitId(i) })?;
    }

    for i in (1..4).rev() {
        circuit.add_gate(CNOT {
            control: QubitId(i - 1),
            target: QubitId(i),
        })?;
    }

    println!("Original circuit: {} gates", circuit.num_gates());

    // Compress using tensor networks
    let compressor = TensorNetworkCompressor::new(16); // max bond dimension
    let compressed = compressor.compress(&circuit)?;

    println!(
        "Compression ratio: {:.2}%",
        compressed.compression_ratio() * 100.0
    );

    // Check fidelity
    let fidelity = compressed.fidelity(&circuit)?;
    println!("Fidelity with original: {:.6}", fidelity);

    println!();
    Ok(())
}

fn demo_mps_representation() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Matrix Product State Representation ---");

    // Create a circuit that generates an interesting entangled state
    let mut circuit = Circuit::<6>::new();

    // Create W state: (|100000⟩ + |010000⟩ + |001000⟩ + |000100⟩ + |000010⟩ + |000001⟩)/√6
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(RotationZ {
        target: QubitId(0),
        theta: std::f64::consts::PI / 3.0,
    })?;

    for i in 0..5 {
        circuit.add_gate(CNOT {
            control: QubitId(i),
            target: QubitId(i + 1),
        })?;
    }

    println!("Created circuit for W state preparation");

    // Convert to MPS
    let mps = MatrixProductState::from_circuit(&circuit)?;
    println!("Converted to MPS representation");

    // Compress with different bond dimensions
    let bond_dims = vec![2, 4, 8, 16];

    for &max_bond in &bond_dims {
        let mut mps_copy = MatrixProductState::from_circuit(&circuit)?;
        mps_copy.compress(max_bond, 1e-10)?;

        // In a real implementation, would calculate actual compression metrics
        println!("Max bond dimension {}: compression successful", max_bond);
    }

    println!();
    Ok(())
}

fn demo_compression_methods() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Different Compression Methods ---");

    let mut circuit = Circuit::<5>::new();

    // Build a deep circuit
    for _ in 0..5 {
        for i in 0..5 {
            circuit.add_gate(Hadamard { target: QubitId(i) })?;
        }
        for i in 0..4 {
            circuit.add_gate(CNOT {
                control: QubitId(i),
                target: QubitId(i + 1),
            })?;
        }
    }

    println!("Built deep circuit with {} gates", circuit.num_gates());

    // Test different compression methods
    let methods = vec![
        CompressionMethod::SVD,
        CompressionMethod::DMRG,
        CompressionMethod::TEBD,
    ];

    for method in methods {
        let compressor = TensorNetworkCompressor::new(32).with_method(method.clone());

        let compressed = compressor.compress(&circuit)?;

        println!("\n{:?} compression:", method);
        println!(
            "  Compression ratio: {:.2}%",
            compressed.compression_ratio() * 100.0
        );

        // Try to decompress
        let decompressed = compressed.decompress()?;
        println!("  Decompressed to {} gates", decompressed.num_gates());
    }

    println!();
    Ok(())
}

fn demo_tensor_contraction() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Tensor Contraction Optimization ---");

    // Create a circuit with specific structure
    let mut circuit = Circuit::<4>::new();

    // Layer 1: Single-qubit gates
    for i in 0..4 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }

    // Layer 2: Entangling gates
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;

    // Layer 3: Cross entangling
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    // Convert to tensor network
    let converter = CircuitToTensorNetwork::<4>::new()
        .with_max_bond_dim(8)
        .with_tolerance(1e-12);

    let tn = converter.convert(&circuit)?;

    println!("Converted circuit to tensor network");
    println!("Network has {} tensors", circuit.num_gates());

    // Contract the network
    let result = tn.contract_all()?;
    println!("Contracted to single tensor of rank {}", result.rank());

    println!();
    Ok(())
}

examples/crosstalk_demo.rs (line 104)

fn demo_scheduling_strategies() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Scheduling Strategies ---");

    // Create a test circuit
    let mut circuit = Circuit::<5>::new();

    // Layer 1: Single-qubit gates
    for i in 0..5 {
        circuit.add_gate(Hadamard { target: QubitId(i) })?;
    }

    // Layer 2: Two-qubit gates
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;
    circuit.add_gate(CZ {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    // Layer 3: More single-qubit gates
    for i in 0..5 {
        circuit.add_gate(RotationZ {
            target: QubitId(i),
            theta: std::f64::consts::PI / 4.0,
        })?;
    }

    println!("Test circuit: {} gates on 5 qubits", circuit.num_gates());

    let model = CrosstalkModel::uniform(5, 0.05);

    // Strategy 1: Minimize crosstalk
    let scheduler1 =
        CrosstalkScheduler::new(model.clone()).with_strategy(SchedulingStrategy::MinimizeCrosstalk);

    let schedule1 = scheduler1.schedule(&circuit)?;

    println!("\nMinimize Crosstalk Strategy:");
    println!("  Time slices: {}", schedule1.time_slices.len());
    println!("  Total crosstalk: {:.4}", schedule1.total_crosstalk);
    println!("  Execution time: {:.1} ns", schedule1.execution_time);

    // Strategy 2: Minimize time with constraint
    let scheduler2 =
        CrosstalkScheduler::new(model.clone()).with_strategy(SchedulingStrategy::MinimizeTime {
            max_crosstalk: 0.02,
        });

    let schedule2 = scheduler2.schedule(&circuit)?;

    println!("\nMinimize Time Strategy (max crosstalk = 0.02):");
    println!("  Time slices: {}", schedule2.time_slices.len());
    println!("  Total crosstalk: {:.4}", schedule2.total_crosstalk);
    println!("  Execution time: {:.1} ns", schedule2.execution_time);

    // Strategy 3: Balanced
    let scheduler3 = CrosstalkScheduler::new(model).with_strategy(SchedulingStrategy::Balanced {
        time_weight: 0.5,
        crosstalk_weight: 0.5,
    });

    let schedule3 = scheduler3.schedule(&circuit)?;

    println!("\nBalanced Strategy:");
    println!("  Time slices: {}", schedule3.time_slices.len());
    println!("  Total crosstalk: {:.4}", schedule3.total_crosstalk);
    println!("  Execution time: {:.1} ns", schedule3.execution_time);

    // Show time slice details for first schedule
    println!("\nTime slice details (MinimizeCrosstalk):");
    for (i, slice) in schedule1.time_slices.iter().enumerate() {
        println!(
            "  Slice {}: {} gates, max crosstalk = {:.4}, duration = {:.1} ns",
            i,
            slice.gates.len(),
            slice.max_crosstalk,
            slice.duration
        );
    }

    println!();
    Ok(())
}

fn demo_crosstalk_analysis() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Cross-talk Analysis ---");

    // Create a circuit with potential crosstalk issues
    let mut circuit = Circuit::<6>::new();

    // Parallel two-qubit gates on neighboring qubits
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(2),
        target: QubitId(3),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(4),
        target: QubitId(5),
    })?;

    // More gates that might have crosstalk
    circuit.add_gate(CZ {
        control: QubitId(1),
        target: QubitId(2),
    })?;
    circuit.add_gate(CZ {
        control: QubitId(3),
        target: QubitId(4),
    })?;

    let model = CrosstalkModel::uniform(6, 0.05);
    let analyzer = CrosstalkAnalyzer::new(model);

    let analysis = analyzer.analyze(&circuit);

    println!("Circuit analysis:");
    println!("  Total gates: {}", analysis.total_gates);
    println!("  Maximum crosstalk: {:.4}", analysis.max_crosstalk);
    println!("  Problematic pairs: {}", analysis.problematic_pairs.len());

    println!("\nTop problematic gate pairs:");
    for (i, (g1, g2, crosstalk)) in analysis.problematic_pairs.iter().take(3).enumerate() {
        println!(
            "  {}. Gates {} and {}: crosstalk = {:.4}",
            i + 1,
            g1,
            g2,
            crosstalk
        );
    }

    // Get reordering suggestions
    let suggestions = analyzer.suggest_reordering(&circuit)?;

    println!("\nSuggested reorderings:");
    for suggestion in suggestions.iter().take(3) {
        println!(
            "  Move gates {} and {} apart: {}",
            suggestion.gate1, suggestion.gate2, suggestion.reason
        );
        println!(
            "    Expected improvement: {:.4}",
            suggestion.expected_improvement
        );
    }

    println!();
    Ok(())
}

fn demo_device_specific_scheduling() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Device-Specific Scheduling ---");

    // Create a realistic device characterization
    let mut characterization = CrosstalkCharacterization {
        measured_crosstalk: std::collections::HashMap::new(),
        single_qubit_measurements: std::collections::HashMap::new(),
        significance_threshold: 0.01,
        device_coupling: vec![
            (0, 1),
            (1, 2),
            (2, 3),
            (3, 4), // Linear connectivity
            (0, 5),
            (1, 5),
            (2, 5),
            (3, 5),
            (4, 5), // Star center at qubit 5
        ],
    };

    // Add some measured crosstalk values
    characterization
        .single_qubit_measurements
        .insert((0, 1), 0.02);
    characterization
        .single_qubit_measurements
        .insert((1, 2), 0.02);
    characterization
        .single_qubit_measurements
        .insert((0, 5), 0.03);
    characterization
        .single_qubit_measurements
        .insert((1, 5), 0.03);

    characterization
        .measured_crosstalk
        .insert(((0, 1), (2, 3)), 0.05);
    characterization
        .measured_crosstalk
        .insert(((0, 1), (3, 4)), 0.02);
    characterization
        .measured_crosstalk
        .insert(((0, 5), (1, 5)), 0.08);

    let model = CrosstalkModel::from_characterization(&characterization);
    let scheduler = CrosstalkScheduler::new(model);

    // Create circuit that uses the device topology
    let mut circuit = Circuit::<6>::new();

    // Operations on linear chain
    circuit.add_gate(Hadamard { target: QubitId(0) })?;
    circuit.add_gate(CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    circuit.add_gate(CNOT {
        control: QubitId(1),
        target: QubitId(2),
    })?;

    // Operations using star center
    circuit.add_gate(Hadamard { target: QubitId(5) })?;
    circuit.add_gate(CZ {
        control: QubitId(5),
        target: QubitId(0),
    })?;
    circuit.add_gate(CZ {
        control: QubitId(5),
        target: QubitId(3),
    })?;

    let schedule = scheduler.schedule(&circuit)?;

    println!("Device-specific schedule:");
    println!("  Device topology: Linear chain + star center");
    println!("  Time slices: {}", schedule.time_slices.len());
    println!("  Total crosstalk: {:.4}", schedule.total_crosstalk);

    println!("\nSchedule details:");
    for (i, slice) in schedule.time_slices.iter().enumerate() {
        let gates = &circuit.gates();
        print!("  Slice {}: ", i);
        for &gate_idx in &slice.gates {
            print!("{} ", gates[gate_idx].name());
        }
        println!("(crosstalk: {:.4})", slice.max_crosstalk);
    }

    println!();
    Ok(())
}

fn demo_adaptive_scheduling() -> quantrs2_core::error::QuantRS2Result<()> {
    println!("--- Adaptive Scheduling ---");

    // Create a circuit with varying gate densities
    let mut circuit = Circuit::<8>::new();

    // Dense region: many gates on qubits 0-3
    for _ in 0..3 {
        for i in 0..3 {
            circuit.add_gate(Hadamard { target: QubitId(i) })?;
            circuit.add_gate(RotationZ {
                target: QubitId(i),
                theta: 0.1,
            })?;
        }
        circuit.add_gate(CNOT {
            control: QubitId(0),
            target: QubitId(1),
        })?;
        circuit.add_gate(CNOT {
            control: QubitId(2),
            target: QubitId(3),
        })?;
    }

    // Sparse region: few gates on qubits 4-7
    circuit.add_gate(Hadamard { target: QubitId(4) })?;
    circuit.add_gate(CNOT {
        control: QubitId(4),
        target: QubitId(5),
    })?;
    circuit.add_gate(PauliX { target: QubitId(7) })?;

    println!("Circuit with dense (qubits 0-3) and sparse (qubits 4-7) regions");
    println!("Total gates: {}", circuit.num_gates());

    let model = CrosstalkModel::uniform(8, 0.05);
    let analyzer = CrosstalkAnalyzer::new(model.clone());

    // Analyze before scheduling
    let analysis = analyzer.analyze(&circuit);
    println!("\nCrosstalk analysis:");
    println!(
        "  Problematic pairs in dense region: {}",
        analysis
            .problematic_pairs
            .iter()
            .filter(|(g1, g2, _)| {
                let gates = circuit.gates();
                let q1 = gates[*g1].qubits()[0].id();
                let q2 = gates[*g2].qubits()[0].id();
                q1 < 4 && q2 < 4
            })
            .count()
    );

    // Schedule with adaptive strategy
    let scheduler = CrosstalkScheduler::new(model);
    let schedule = scheduler.schedule(&circuit)?;

    println!("\nAdaptive scheduling results:");
    println!("  Time slices: {}", schedule.time_slices.len());
    println!(
        "  Average gates per slice: {:.1}",
        circuit.num_gates() as f64 / schedule.time_slices.len() as f64
    );

    Ok(())
}

examples/vqe_demo.rs (line 43)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🧮 Variational Quantum Eigensolver (VQE) Demo");
    println!("============================================\n");

    // Example 1: Hardware-efficient ansatz for small molecules
    println!("1. Hardware-Efficient Ansatz for 4-qubit system");
    println!("-----------------------------------------------");

    let mut vqe_circuit = VQECircuit::<4>::new(VQEAnsatz::HardwareEfficient { layers: 2 })?;
    println!(
        "Created VQE circuit with {} parameters",
        vqe_circuit.num_parameters()
    );

    // Set some example parameters
    let param_names = vqe_circuit.parameter_names.clone();
    for (i, param_name) in param_names.iter().enumerate() {
        vqe_circuit.set_parameter(param_name, 0.1 * i as f64)?;
    }

    println!("Set parameters: {:?}", vqe_circuit.parameters);
    println!("Parameter names: {:?}\n", vqe_circuit.parameter_names);

    // Example 2: UCCSD ansatz for quantum chemistry
    println!("2. UCCSD Ansatz for quantum chemistry");
    println!("--------------------------------------");

    let uccsd_circuit = VQECircuit::<6>::new(VQEAnsatz::UCCSD {
        occupied_orbitals: 2,
        virtual_orbitals: 4,
    })?;
    println!(
        "Created UCCSD circuit with {} parameters",
        uccsd_circuit.num_parameters()
    );
    println!("Circuit has {} gates", uccsd_circuit.circuit.num_gates());

    // Example 3: Observables for different Hamiltonians
    println!("\n3. Creating Observables");
    println!("----------------------");

    // Heisenberg model
    let heisenberg = VQEObservable::heisenberg_model(4, 1.0);
    println!("Heisenberg model with {} terms", heisenberg.terms.len());

    // Transverse Field Ising Model
    let tfim = VQEObservable::tfim(4, 1.0, 0.5);
    println!("TFIM model with {} terms", tfim.terms.len());

    // Custom observable
    let mut custom_obs = VQEObservable::new();
    custom_obs.add_pauli_term(1.0, vec![(0, PauliOperator::Z), (1, PauliOperator::Z)]);
    custom_obs.add_pauli_term(0.5, vec![(0, PauliOperator::X)]);
    custom_obs.add_pauli_term(0.5, vec![(1, PauliOperator::X)]);
    println!("Custom observable with {} terms", custom_obs.terms.len());

    // Example 4: Custom ansatz construction
    println!("\n4. Custom Ansatz Construction");
    println!("-----------------------------");

    let mut custom_vqe = VQECircuit::<3>::new(VQEAnsatz::Custom)?;

    // Add custom parameterized gates
    custom_vqe.add_parameterized_ry(Qubit(0), "theta_0")?;
    custom_vqe.add_parameterized_rz(Qubit(1), "phi_1")?;
    custom_vqe.add_parameterized_ry(Qubit(2), "theta_2")?;

    // Add fixed gates to the underlying circuit
    custom_vqe.circuit.cnot(Qubit(0), Qubit(1))?;
    custom_vqe.circuit.cnot(Qubit(1), Qubit(2))?;

    println!(
        "Custom VQE circuit with {} parameters",
        custom_vqe.num_parameters()
    );

    // Set parameter values
    custom_vqe.set_parameter("theta_0", std::f64::consts::PI / 4.0)?;
    custom_vqe.set_parameter("phi_1", std::f64::consts::PI / 2.0)?;
    custom_vqe.set_parameter("theta_2", std::f64::consts::PI / 6.0)?;

    println!(
        "theta_0 = {:.4}",
        custom_vqe.get_parameter("theta_0").unwrap()
    );
    println!("phi_1 = {:.4}", custom_vqe.get_parameter("phi_1").unwrap());
    println!(
        "theta_2 = {:.4}",
        custom_vqe.get_parameter("theta_2").unwrap()
    );

    // Example 5: VQE Optimization (mock demonstration)
    println!("\n5. VQE Optimization");
    println!("-------------------");

    let optimizer = VQEOptimizer::new(VQEOptimizerType::GradientDescent);
    println!(
        "Created optimizer with max iterations: {}",
        optimizer.max_iterations
    );
    println!("Tolerance: {:.2e}", optimizer.tolerance);
    println!("Learning rate: {}", optimizer.learning_rate);

    // In a real implementation, this would actually optimize the parameters
    let result = optimizer.optimize(&mut custom_vqe, &custom_obs)?;
    println!("Optimization result:");
    println!("  Ground state energy: {:.6}", result.ground_state_energy);
    println!("  Converged: {}", result.converged);
    println!("  Iterations: {}", result.iterations);
    println!("  Gradient norm: {:.2e}", result.gradient_norm);

    // Example 6: Different optimizer types
    println!("\n6. Different Optimizer Types");
    println!("----------------------------");

    let optimizers = vec![
        ("Gradient Descent", VQEOptimizerType::GradientDescent),
        (
            "Adam",
            VQEOptimizerType::Adam {
                beta1: 0.9,
                beta2: 0.999,
            },
        ),
        ("BFGS", VQEOptimizerType::BFGS),
        ("Nelder-Mead", VQEOptimizerType::NelderMead),
        (
            "SPSA",
            VQEOptimizerType::SPSA {
                alpha: 0.602,
                gamma: 0.101,
            },
        ),
    ];

    for (name, opt_type) in optimizers {
        let opt = VQEOptimizer::new(opt_type);
        println!("  {}: {:?}", name, opt.optimizer_type);
    }

    // Example 7: Real-space ansatz
    println!("\n7. Real-Space Ansatz");
    println!("--------------------");

    let geometry = vec![
        (0.0, 0.0, 0.0), // Site 0
        (1.0, 0.0, 0.0), // Site 1
        (0.0, 1.0, 0.0), // Site 2
        (1.0, 1.0, 0.0), // Site 3
    ];

    let real_space_circuit = VQECircuit::<4>::new(VQEAnsatz::RealSpace { geometry })?;
    println!(
        "Real-space circuit with {} parameters",
        real_space_circuit.num_parameters()
    );
    println!("Based on 2x2 square lattice geometry");

    // Example 8: Molecular Hamiltonian
    println!("\n8. Molecular Hamiltonian");
    println!("------------------------");

    // Example one-body and two-body integrals (simplified)
    let one_body = vec![
        (0, 0, -1.0), // h_00
        (1, 1, -1.0), // h_11
        (0, 1, -0.5), // h_01
    ];

    let two_body = vec![
        (0, 1, 0, 1, 0.5), // (00|11)
        (0, 0, 1, 1, 0.3), // (01|01)
    ];

    let molecular_ham = VQEObservable::molecular_hamiltonian(&one_body, &two_body);
    println!(
        "Molecular Hamiltonian with {} terms",
        molecular_ham.terms.len()
    );

    println!("\n✅ VQE Demo completed successfully!");
    println!("\nNote: This demo shows the VQE framework structure.");
    println!("Real VQE optimization requires quantum simulation or hardware execution.");

    Ok(())
}

Additional examples can be found in:

• examples/qc_co_optimization_demo.rs
• examples/distributed_demo.rs

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

Examples found in repository

examples/optimization_demo.rs (line 39)

fn create_sample_circuit() -> Circuit<4> {
    // Create a circuit that has optimization opportunities
    let mut circuit = Circuit::<4>::new();

    // Add some gates with optimization opportunities
    // Pattern 1: Redundant gates (H-H = I, X-X = I)
    let _ = circuit.h(0);
    let _ = circuit.h(0);

    // Pattern 2: Commutable gates
    let _ = circuit.x(1);
    let _ = circuit.z(0);
    let _ = circuit.cnot(0, 1);

    // Pattern 3: Mergeable rotations
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);

    // Pattern 4: Known patterns (H-X-H = Z)
    let _ = circuit.h(3);
    let _ = circuit.x(3);
    let _ = circuit.h(3);

    // Pattern 5: Decomposable gates
    let _ = circuit.toffoli(0, 1, 2);

    circuit
}

examples/equivalence_demo.rs (line 41)

fn demo_structural_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("1. Structural Equivalence Check");
    println!("   Checking if two circuits have identical gate sequences");

    // Create two identical Bell state circuits
    let mut circuit1 = Circuit::<2>::new();
    circuit1.h(0)?;
    circuit1.cnot(0, 1)?;

    let mut circuit2 = Circuit::<2>::new();
    circuit2.h(0)?;
    circuit2.cnot(0, 1)?;

    // Check structural equivalence
    let checker = EquivalenceChecker::default();
    let result = checker.check_structural_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: H(0), CNOT(0,1)");
    println!("   Circuit 2: H(0), CNOT(0,1)");
    println!("   Structurally equivalent: {}", result.equivalent);
    println!("   Details: {}", result.details);

    Ok(())
}

/// Demonstrate algebraic equivalence (different gates, same result)
fn demo_algebraic_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("2. Algebraic Equivalence Check");
    println!("   Different gate sequences that produce the same result");

    // Circuit 1: X followed by X (should equal identity)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.x(0)?;
    circuit1.x(0)?;

    // Circuit 2: Empty circuit (identity)
    let circuit2 = Circuit::<1>::new();

    // Check equivalence
    let mut checker = EquivalenceChecker::default();
    let result = checker.check_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: X(0), X(0)");
    println!("   Circuit 2: (empty)");
    println!("   Equivalent: {}", result.equivalent);
    println!("   Check type: {:?}", result.check_type);

    // Another example: HZH = X
    let mut circuit3 = Circuit::<1>::new();
    circuit3.h(0)?;
    circuit3.z(0)?;
    circuit3.h(0)?;

    let mut circuit4 = Circuit::<1>::new();
    circuit4.x(0)?;

    let result2 = checker.check_structural_equivalence(&circuit3, &circuit4)?;

    println!("\n   Circuit 3: H(0), Z(0), H(0)");
    println!("   Circuit 4: X(0)");
    println!("   Structurally equivalent: {}", result2.equivalent);
    println!("   (Note: They are algebraically equivalent but not structurally)");

    Ok(())
}

/// Demonstrate phase equivalence
fn demo_phase_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("3. Global Phase Equivalence");
    println!("   Circuits that differ only by a global phase");

    // Circuit 1: S gate (phase π/2)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.s(0)?;

    // Circuit 2: Z followed by T (phase π + π/4 = 5π/4)
    // This gives the same result up to global phase
    let mut circuit2 = Circuit::<1>::new();
    circuit2.z(0)?;
    circuit2.t(0)?;

    // Check with phase ignored
    let mut checker_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: true,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Check without phase ignored
    let mut checker_no_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: S(0)");
    println!("   Circuit 2: Z(0), T(0)");

    // Note: This example is simplified - actual phase relationship may differ
    println!("   With global phase ignored: (would check if implemented)");
    println!("   Without global phase: (would check if implemented)");

    Ok(())
}

/// Demonstrate detection of non-equivalent circuits
fn demo_non_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("4. Non-Equivalence Detection");
    println!("   Detecting when circuits are NOT equivalent");

    // Circuit 1: Bell state |00> + |11>
    let mut circuit1 = Circuit::<2>::new();
    circuit1.h(0)?;
    circuit1.cnot(0, 1)?;

    // Circuit 2: Different entangled state |01> + |10>
    let mut circuit2 = Circuit::<2>::new();
    circuit2.h(0)?;
    circuit2.x(1)?;
    circuit2.cnot(0, 1)?;

    let checker = EquivalenceChecker::default();
    let result = checker.check_structural_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: H(0), CNOT(0,1)");
    println!("   Circuit 2: H(0), X(1), CNOT(0,1)");
    println!("   Equivalent: {}", result.equivalent);
    println!("   Details: {}", result.details);

    Ok(())
}

/// Demonstrate custom tolerance settings
fn demo_custom_tolerance() -> Result<(), Box<dyn std::error::Error>> {
    println!("5. Custom Tolerance Settings");
    println!("   Using different tolerance levels for approximate equivalence");

    // Create circuits that might have small numerical differences
    let mut circuit1 = Circuit::<1>::new();
    circuit1.rx(0, PI / 4.0)?;

    let mut circuit2 = Circuit::<1>::new();
    circuit2.rx(0, PI / 4.0 + 1e-12)?; // Tiny difference

    // Strict tolerance
    let mut strict_checker = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-15,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Relaxed tolerance
    let mut relaxed_checker = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: RX(0, π/4)");
    println!("   Circuit 2: RX(0, π/4 + 1e-12)");
    println!("   With strict tolerance (1e-15): (would check if implemented)");
    println!("   With relaxed tolerance (1e-10): (would check if implemented)");

    Ok(())
}

/// Additional example: Verify circuit optimization preserves behavior
fn verify_optimization_example() -> Result<(), Box<dyn std::error::Error>> {
    println!("\nBonus: Verifying Circuit Optimization");

    // Original circuit with redundant gates
    let mut original = Circuit::<2>::new();
    original.h(0)?;
    original.cnot(0, 1)?;
    original.cnot(0, 1)?; // This cancels the previous CNOT
    original.h(0)?;

    // Optimized circuit (manually optimized for this example)
    let optimized = Circuit::<2>::new();
    // Empty circuit since H-CNOT-CNOT-H = H-H = I

    let checker = EquivalenceChecker::default();
    println!("   Original: H(0), CNOT(0,1), CNOT(0,1), H(0)");
    println!("   Optimized: (empty)");

    // In practice, you would use the circuit optimizer and then verify:
    // let optimized = original.optimize()?;
    // let result = checker.check_equivalence(&original, &optimized)?;

    Ok(())
}

examples/qasm_example.rs (line 31)

fn export_example() {
    println!("1. Exporting a circuit to OpenQASM 3.0");
    println!("--------------------------------------");

    // Create a quantum teleportation circuit
    let mut builder = CircuitBuilder::<3>::new();

    // Create Bell pair between Alice and Bob
    let _ = builder.h(Qubit::new(1));
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));

    // Alice's operations
    let _ = builder.cx(Qubit::new(0), Qubit::new(1));
    let _ = builder.h(Qubit::new(0));

    // Measurements (in real teleportation, these would be mid-circuit)
    let _ = builder.measure(Qubit::new(0));
    let _ = builder.measure(Qubit::new(1));

    // Bob's corrections (would be conditional in real circuit)
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));
    let _ = builder.cz(Qubit::new(0), Qubit::new(2));

    let circuit = builder.build();

    // Export with default options
    match export_qasm3(&circuit) {
        Ok(qasm) => {
            println!("Teleportation circuit in OpenQASM 3.0:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }

    // Export with custom options
    let options = ExportOptions {
        include_stdgates: true,
        decompose_custom: true,
        include_gate_comments: true,
        optimize: true,
        pretty_print: true,
    };

    let mut exporter = QasmExporter::new(options);
    match exporter.export(&circuit) {
        Ok(qasm) => {
            println!("\nWith custom options:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }
}

examples/classical_control_demo.rs (line 55)

fn quantum_teleportation() -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 2: Quantum Teleportation");
    println!("--------------------------------");

    // Create Bell pair between qubits 1 and 2
    let mut circuit = Circuit::<3>::new();
    circuit.h(1)?;
    circuit.cnot(1, 2)?;

    // Convert to classical circuit for measurements
    let mut classical_circuit = circuit.with_classical_control();
    classical_circuit.add_classical_register("alice", 2)?;

    // Alice's operations
    classical_circuit.add_gate(quantrs2_core::gate::multi::CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    classical_circuit.add_gate(Hadamard { target: QubitId(0) })?;

    // Alice measures her qubits
    classical_circuit.measure(QubitId(0), "alice", 0)?;
    classical_circuit.measure(QubitId(1), "alice", 1)?;

    // Bob applies corrections based on Alice's measurements
    classical_circuit.add_conditional(
        ClassicalCondition {
            lhs: ClassicalValue::Register("alice".to_string()),
            op: ComparisonOp::Equal,
            rhs: ClassicalValue::Integer(0b01),
        },
        PauliX { target: QubitId(2) },
    )?;

    classical_circuit.add_conditional(
        ClassicalCondition {
            lhs: ClassicalValue::Register("alice".to_string()),
            op: ComparisonOp::Equal,
            rhs: ClassicalValue::Integer(0b10),
        },
        PauliZ { target: QubitId(2) },
    )?;

    classical_circuit.add_conditional(
        ClassicalCondition {
            lhs: ClassicalValue::Register("alice".to_string()),
            op: ComparisonOp::Equal,
            rhs: ClassicalValue::Integer(0b11),
        },
        PauliX { target: QubitId(2) }, // In reality, this would be X then Z
    )?;

    println!(
        "Created teleportation circuit with {} operations",
        classical_circuit.num_operations()
    );
    println!("Bob's qubit 2 receives the state that was on Alice's qubit 0\n");

    Ok(())
}

/// Adaptive phase estimation using conditional rotations
fn adaptive_phase_estimation() -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 3: Adaptive Phase Estimation");
    println!("-----------------------------------");

    let circuit = ClassicalCircuitBuilder::<4>::new()
        .classical_register("phase_bits", 3)?
        // First estimation round
        .gate(Hadamard { target: QubitId(0) })?
        .gate(quantrs2_core::gate::multi::CRZ {
            control: QubitId(0),
            target: QubitId(3),
            theta: std::f64::consts::PI,
        })?
        .gate(Hadamard { target: QubitId(0) })?
        .measure(QubitId(0), "phase_bits", 0)?
        // Second round (adaptive based on first measurement)
        .gate(Hadamard { target: QubitId(1) })?
        .conditional(
            ClassicalCondition::register_equals("phase_bits", 1),
            quantrs2_core::gate::single::Phase { target: QubitId(1) }
        )?
        .gate(quantrs2_core::gate::multi::CRZ {
            control: QubitId(1),
            target: QubitId(3),
            theta: std::f64::consts::PI / 2.0,
        })?
        .gate(Hadamard { target: QubitId(1) })?
        .measure(QubitId(1), "phase_bits", 1)?
        // Third round (adaptive based on previous measurements)
        .gate(Hadamard { target: QubitId(2) })?
        // Apply phase corrections based on previous measurements
        .conditional(
            ClassicalCondition {
                lhs: ClassicalValue::Register("phase_bits".to_string()),
                op: ComparisonOp::GreaterEqual,
                rhs: ClassicalValue::Integer(1),
            },
            quantrs2_core::gate::single::RotationZ {
                target: QubitId(2),
                theta: -std::f64::consts::PI / 4.0,
            }
        )?
        .gate(quantrs2_core::gate::multi::CRZ {
            control: QubitId(2),
            target: QubitId(3),
            theta: std::f64::consts::PI / 4.0,
        })?
        .gate(Hadamard { target: QubitId(2) })?
        .measure(QubitId(2), "phase_bits", 2)?
        .build();

    println!(
        "Created adaptive phase estimation circuit with {} operations",
        circuit.num_operations()
    );
    println!("The circuit adaptively estimates the phase using 3 rounds of measurement\n");

    // Demonstrate builder pattern
    println!("Alternative: Using standard circuit with conversion");
    let mut standard_circuit = Circuit::<4>::new();
    standard_circuit.h(0)?;
    standard_circuit.h(1)?;
    standard_circuit.h(2)?;

    let classical = standard_circuit.with_classical_control();
    println!("Converted standard circuit to classical control\n");

    Ok(())
}

examples/distributed_demo.rs (line 763)

fn create_test_jobs() -> Vec<DistributedJob<4>> {
    let mut jobs = Vec::new();

    // Job 1: Simple Bell state circuit
    let mut bell_circuit = Circuit::<4>::new();
    bell_circuit.h(Qubit(0)).unwrap();
    bell_circuit.cnot(Qubit(0), Qubit(1)).unwrap();

    jobs.push(DistributedJob {
        id: "bell_state_job".to_string(),
        circuit: bell_circuit,
        parameters: ExecutionParameters {
            shots: 1000,
            optimization_level: 1,
            error_mitigation: vec![ErrorMitigation::ReadoutErrorMitigation],
            result_format: ResultFormat::Counts,
            memory_requirement: None,
        },
        priority: Priority::Normal,
        target_backends: None,
        submitted_at: Instant::now(),
        deadline: None,
    });

    // Job 2: GHZ state circuit
    let mut ghz_circuit = Circuit::<4>::new();
    ghz_circuit.h(Qubit(0)).unwrap();
    ghz_circuit.cnot(Qubit(0), Qubit(1)).unwrap();
    ghz_circuit.cnot(Qubit(1), Qubit(2)).unwrap();
    ghz_circuit.cnot(Qubit(2), Qubit(3)).unwrap();

    jobs.push(DistributedJob {
        id: "ghz_state_job".to_string(),
        circuit: ghz_circuit,
        parameters: ExecutionParameters {
            shots: 5000,
            optimization_level: 2,
            error_mitigation: vec![
                ErrorMitigation::ReadoutErrorMitigation,
                ErrorMitigation::ZeroNoiseExtrapolation,
            ],
            result_format: ResultFormat::Probabilities,
            memory_requirement: Some(1.0), // 1 GB
        },
        priority: Priority::High,
        target_backends: Some(vec![
            "qiskit_aer_simulator".to_string(),
            "aws_braket_sv1".to_string(),
        ]),
        submitted_at: Instant::now(),
        deadline: Some(Instant::now() + std::time::Duration::from_secs(300)),
    });

    // Job 3: Variational circuit
    let mut var_circuit = Circuit::<4>::new();
    for i in 0..4 {
        var_circuit.ry(Qubit(i), 0.5).unwrap();
    }
    for i in 0..3 {
        var_circuit.cnot(Qubit(i), Qubit(i + 1)).unwrap();
    }

    jobs.push(DistributedJob {
        id: "variational_job".to_string(),
        circuit: var_circuit,
        parameters: ExecutionParameters {
            shots: 10000,
            optimization_level: 3,
            error_mitigation: vec![
                ErrorMitigation::CliffordDataRegression,
                ErrorMitigation::SymmetryVerification,
            ],
            result_format: ResultFormat::ExpectationValues,
            memory_requirement: Some(2.0), // 2 GB
        },
        priority: Priority::Critical,
        target_backends: None,
        submitted_at: Instant::now(),
        deadline: None,
    });

    jobs
}

examples/qc_co_optimization_demo.rs (line 28)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🔄 Quantum-Classical Co-optimization Demo");
    println!("=========================================\n");

    // Example 1: Basic hybrid problem setup
    println!("1. Setting up a Hybrid Optimization Problem");
    println!("-------------------------------------------");

    let mut problem = HybridOptimizationProblem::<4>::new();

    // Set global parameters for the optimization
    problem.set_global_parameters(vec![0.1, 0.2, 0.3, 0.4, 0.5, 0.6]);
    println!("Set {} global parameters", problem.global_parameters.len());

    // Create a quantum circuit component
    let mut quantum_circuit = Circuit::<4>::new();
    quantum_circuit.h(Qubit(0))?;
    quantum_circuit.cnot(Qubit(0), Qubit(1))?;
    quantum_circuit.ry(Qubit(2), 0.0)?; // Will be parameterized
    quantum_circuit.cnot(Qubit(2), Qubit(3))?;

    // Add quantum component to the problem
    problem.add_quantum_component(
        "quantum_processor".to_string(),
        quantum_circuit,
        vec![0, 1, 2], // Use parameters 0, 1, 2 from global parameter vector
    )?;

    println!(
        "Added quantum circuit component with {} gates",
        problem.quantum_circuits[0].circuit.num_gates()
    );

    // Example 2: Adding classical processing steps
    println!("\n2. Adding Classical Processing Steps");
    println!("-----------------------------------");

    // Add a classical linear algebra step
    problem.add_classical_step(
        "matrix_operations".to_string(),
        ClassicalStepType::LinearAlgebra(LinearAlgebraOp::MatrixMultiplication),
        vec!["quantum_processor".to_string()],
        vec!["processed_measurements".to_string()],
    )?;

    // Add a machine learning inference step
    problem.add_classical_step(
        "ml_inference".to_string(),
        ClassicalStepType::MachineLearning(QCMLModelType::NeuralNetwork),
        vec!["processed_measurements".to_string()],
        vec!["ml_output".to_string()],
    )?;

    // Add a parameter update step
    problem.add_classical_step(
        "parameter_update".to_string(),
        ClassicalStepType::ParameterUpdate(UpdateRule::AdamOptimizer),
        vec!["ml_output".to_string()],
        vec!["updated_parameters".to_string()],
    )?;

    println!(
        "Added {} classical processing steps",
        problem.classical_steps.len()
    );

    // Print details of each classical step
    for (i, step) in problem.classical_steps.iter().enumerate() {
        println!("  Step {}: {} ({:?})", i + 1, step.id, step.step_type);
    }

    // Example 3: Setting up data flow
    println!("\n3. Setting up Data Flow");
    println!("-----------------------");

    // Connect quantum processor to matrix operations
    problem.add_data_flow(
        "quantum_processor".to_string(),
        "matrix_operations".to_string(),
        DataType::Measurements(vec![0.5, 0.3, 0.8, 0.1]),
    )?;

    // Connect matrix operations to ML inference
    problem.add_data_flow(
        "matrix_operations".to_string(),
        "ml_inference".to_string(),
        DataType::Matrix(vec![vec![1.0, 0.5], vec![0.3, 0.8]]),
    )?;

    // Connect ML inference to parameter update
    problem.add_data_flow(
        "ml_inference".to_string(),
        "parameter_update".to_string(),
        DataType::Scalar(0.75),
    )?;

    println!(
        "Set up {} data flow connections",
        problem.data_flow.edges.len()
    );

    // Print data flow details
    for (i, (source, target, data_type)) in problem.data_flow.edges.iter().enumerate() {
        println!(
            "  Flow {}: {} -> {} ({:?})",
            i + 1,
            source,
            target,
            data_type
        );
    }

    // Example 4: Adding regularization
    println!("\n4. Adding Regularization Terms");
    println!("------------------------------");

    // Add L2 regularization on parameters 0-2
    problem.add_regularization(RegularizationType::L2, 0.01, vec![0, 1, 2])?;

    // Add sparsity regularization on parameters 3-5
    problem.add_regularization(RegularizationType::Sparsity, 0.005, vec![3, 4, 5])?;

    println!(
        "Added {} regularization terms",
        problem.objective.regularization.len()
    );

    for (i, reg) in problem.objective.regularization.iter().enumerate() {
        println!(
            "  Regularization {}: {:?} (strength: {:.3})",
            i + 1,
            reg.reg_type,
            reg.strength
        );
    }

    // Example 5: Validating the problem
    println!("\n5. Problem Validation");
    println!("---------------------");

    match problem.validate() {
        Ok(()) => println!("✅ Problem validation passed"),
        Err(e) => println!("❌ Problem validation failed: {}", e),
    }

    println!("Total components: {}", problem.data_flow.nodes.len());
    println!("Total connections: {}", problem.data_flow.edges.len());

    // Example 6: Different optimization algorithms
    println!("\n6. Optimization Algorithms");
    println!("--------------------------");

    let algorithms = vec![
        (
            "Coordinate Descent",
            HybridOptimizationAlgorithm::CoordinateDescent,
        ),
        (
            "Simultaneous Optimization",
            HybridOptimizationAlgorithm::SimultaneousOptimization,
        ),
        (
            "Hierarchical Optimization",
            HybridOptimizationAlgorithm::HierarchicalOptimization,
        ),
        (
            "Adaptive Optimization",
            HybridOptimizationAlgorithm::AdaptiveOptimization,
        ),
    ];

    for (name, algorithm) in algorithms {
        let optimizer = HybridOptimizer::new(algorithm.clone());
        println!("  {}: {:?}", name, optimizer.algorithm);
        println!("    Max iterations: {}", optimizer.max_iterations);
        println!("    Tolerance: {:.2e}", optimizer.tolerance);
        println!(
            "    Initial learning rate: {}",
            optimizer.learning_rate_schedule.initial_rate
        );
    }

    // Example 7: Learning rate schedules
    println!("\n7. Learning Rate Schedules");
    println!("--------------------------");

    let mut optimizer = HybridOptimizer::new(HybridOptimizationAlgorithm::SimultaneousOptimization);

    // Set up different schedules
    let schedules = vec![
        ("Constant", ScheduleType::Constant),
        ("Linear Decay", ScheduleType::LinearDecay),
        ("Exponential Decay", ScheduleType::ExponentialDecay),
        ("Step Decay", ScheduleType::StepDecay),
        ("Cosine Annealing", ScheduleType::CosineAnnealing),
    ];

    for (name, schedule_type) in schedules {
        optimizer.learning_rate_schedule.schedule_type = schedule_type.clone();
        println!("  {}: {:?}", name, schedule_type);
    }

    // Example 8: Parallelization configuration
    println!("\n8. Parallelization Configuration");
    println!("--------------------------------");

    optimizer.parallelization.quantum_parallelism = 4;
    optimizer.parallelization.classical_parallelism = 8;
    optimizer.parallelization.asynchronous = true;
    optimizer.parallelization.load_balancing = LoadBalancingStrategy::WorkStealing;

    println!(
        "Quantum parallelism: {} circuits",
        optimizer.parallelization.quantum_parallelism
    );
    println!(
        "Classical parallelism: {} threads",
        optimizer.parallelization.classical_parallelism
    );
    println!(
        "Asynchronous execution: {}",
        optimizer.parallelization.asynchronous
    );
    println!(
        "Load balancing: {:?}",
        optimizer.parallelization.load_balancing
    );

    // Example 9: Running optimization (mock)
    println!("\n9. Running Optimization");
    println!("-----------------------");

    println!("Starting hybrid optimization...");
    let result = optimizer.optimize(&mut problem)?;

    println!("Optimization completed:");
    println!("  Optimal value: {:.6}", result.optimal_value);
    println!("  Converged: {}", result.converged);
    println!("  Iterations: {}", result.iterations);
    println!("  Final parameters: {:?}", result.optimal_parameters);

    // Print some history information
    if !result.history.objective_values.is_empty() {
        println!("  Objective value history (first 5):");
        for (i, &value) in result.history.objective_values.iter().take(5).enumerate() {
            println!("    Iteration {}: {:.6}", i, value);
        }
    }

    if !result.history.gradient_norms.is_empty() {
        let final_gradient = result.history.gradient_norms.last().unwrap();
        println!("  Final gradient norm: {:.2e}", final_gradient);
    }

    // Example 10: Specific hybrid algorithm patterns
    println!("\n10. Common Hybrid Algorithm Patterns");
    println!("------------------------------------");

    // QAOA-like pattern
    println!("QAOA-like pattern:");
    println!("  1. Prepare initial state (quantum)");
    println!("  2. Apply parameterized unitaries (quantum)");
    println!("  3. Measure expectation values (quantum)");
    println!("  4. Classical optimization step (classical)");
    println!("  5. Repeat until convergence");

    // VQE with neural network pattern
    println!("\nVQE with Neural Network pattern:");
    println!("  1. Prepare ansatz circuit (quantum)");
    println!("  2. Measure Pauli expectations (quantum)");
    println!("  3. Neural network post-processing (classical)");
    println!("  4. Gradient-based parameter update (classical)");
    println!("  5. Repeat until convergence");

    // Quantum-enhanced ML pattern
    println!("\nQuantum-enhanced ML pattern:");
    println!("  1. Classical feature encoding (classical)");
    println!("  2. Quantum feature mapping (quantum)");
    println!("  3. Quantum measurements (quantum)");
    println!("  4. Classical ML inference (classical)");
    println!("  5. End-to-end gradient updates (hybrid)");

    // Example 11: Data types and flow
    println!("\n11. Data Types in Hybrid Algorithms");
    println!("-----------------------------------");

    let data_types = vec![
        (
            "Quantum measurements",
            "Raw measurement outcomes from quantum circuits",
        ),
        (
            "Probability distributions",
            "Estimated probability distributions from measurements",
        ),
        (
            "Classical matrices",
            "Processed data in matrix form for linear algebra",
        ),
        (
            "Scalar values",
            "Single numerical values like energies or costs",
        ),
        (
            "Parameter vectors",
            "Optimization parameters for both quantum and classical components",
        ),
        (
            "Control signals",
            "Boolean flags for adaptive algorithm control",
        ),
    ];

    for (dtype, description) in data_types {
        println!("  {}: {}", dtype, description);
    }

    println!("\n✅ Quantum-Classical Co-optimization Demo completed!");
    println!("\nNote: This demo shows the framework structure for hybrid optimization.");
    println!("Real co-optimization requires actual quantum and classical execution engines.");

    Ok(())
}

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

Apply a Pauli-X gate to a qubit

Examples found in repository

examples/optimization_demo.rs (line 43)

fn create_sample_circuit() -> Circuit<4> {
    // Create a circuit that has optimization opportunities
    let mut circuit = Circuit::<4>::new();

    // Add some gates with optimization opportunities
    // Pattern 1: Redundant gates (H-H = I, X-X = I)
    let _ = circuit.h(0);
    let _ = circuit.h(0);

    // Pattern 2: Commutable gates
    let _ = circuit.x(1);
    let _ = circuit.z(0);
    let _ = circuit.cnot(0, 1);

    // Pattern 3: Mergeable rotations
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);

    // Pattern 4: Known patterns (H-X-H = Z)
    let _ = circuit.h(3);
    let _ = circuit.x(3);
    let _ = circuit.h(3);

    // Pattern 5: Decomposable gates
    let _ = circuit.toffoli(0, 1, 2);

    circuit
}

examples/equivalence_demo.rs (line 67)

fn demo_algebraic_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("2. Algebraic Equivalence Check");
    println!("   Different gate sequences that produce the same result");

    // Circuit 1: X followed by X (should equal identity)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.x(0)?;
    circuit1.x(0)?;

    // Circuit 2: Empty circuit (identity)
    let circuit2 = Circuit::<1>::new();

    // Check equivalence
    let mut checker = EquivalenceChecker::default();
    let result = checker.check_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: X(0), X(0)");
    println!("   Circuit 2: (empty)");
    println!("   Equivalent: {}", result.equivalent);
    println!("   Check type: {:?}", result.check_type);

    // Another example: HZH = X
    let mut circuit3 = Circuit::<1>::new();
    circuit3.h(0)?;
    circuit3.z(0)?;
    circuit3.h(0)?;

    let mut circuit4 = Circuit::<1>::new();
    circuit4.x(0)?;

    let result2 = checker.check_structural_equivalence(&circuit3, &circuit4)?;

    println!("\n   Circuit 3: H(0), Z(0), H(0)");
    println!("   Circuit 4: X(0)");
    println!("   Structurally equivalent: {}", result2.equivalent);
    println!("   (Note: They are algebraically equivalent but not structurally)");

    Ok(())
}

/// Demonstrate phase equivalence
fn demo_phase_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("3. Global Phase Equivalence");
    println!("   Circuits that differ only by a global phase");

    // Circuit 1: S gate (phase π/2)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.s(0)?;

    // Circuit 2: Z followed by T (phase π + π/4 = 5π/4)
    // This gives the same result up to global phase
    let mut circuit2 = Circuit::<1>::new();
    circuit2.z(0)?;
    circuit2.t(0)?;

    // Check with phase ignored
    let mut checker_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: true,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Check without phase ignored
    let mut checker_no_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: S(0)");
    println!("   Circuit 2: Z(0), T(0)");

    // Note: This example is simplified - actual phase relationship may differ
    println!("   With global phase ignored: (would check if implemented)");
    println!("   Without global phase: (would check if implemented)");

    Ok(())
}

/// Demonstrate detection of non-equivalent circuits
fn demo_non_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("4. Non-Equivalence Detection");
    println!("   Detecting when circuits are NOT equivalent");

    // Circuit 1: Bell state |00> + |11>
    let mut circuit1 = Circuit::<2>::new();
    circuit1.h(0)?;
    circuit1.cnot(0, 1)?;

    // Circuit 2: Different entangled state |01> + |10>
    let mut circuit2 = Circuit::<2>::new();
    circuit2.h(0)?;
    circuit2.x(1)?;
    circuit2.cnot(0, 1)?;

    let checker = EquivalenceChecker::default();
    let result = checker.check_structural_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: H(0), CNOT(0,1)");
    println!("   Circuit 2: H(0), X(1), CNOT(0,1)");
    println!("   Equivalent: {}", result.equivalent);
    println!("   Details: {}", result.details);

    Ok(())
}

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

Examples found in repository

examples/optimization_demo.rs (line 44)

fn create_sample_circuit() -> Circuit<4> {
    // Create a circuit that has optimization opportunities
    let mut circuit = Circuit::<4>::new();

    // Add some gates with optimization opportunities
    // Pattern 1: Redundant gates (H-H = I, X-X = I)
    let _ = circuit.h(0);
    let _ = circuit.h(0);

    // Pattern 2: Commutable gates
    let _ = circuit.x(1);
    let _ = circuit.z(0);
    let _ = circuit.cnot(0, 1);

    // Pattern 3: Mergeable rotations
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);

    // Pattern 4: Known patterns (H-X-H = Z)
    let _ = circuit.h(3);
    let _ = circuit.x(3);
    let _ = circuit.h(3);

    // Pattern 5: Decomposable gates
    let _ = circuit.toffoli(0, 1, 2);

    circuit
}

examples/equivalence_demo.rs (line 85)

fn demo_algebraic_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("2. Algebraic Equivalence Check");
    println!("   Different gate sequences that produce the same result");

    // Circuit 1: X followed by X (should equal identity)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.x(0)?;
    circuit1.x(0)?;

    // Circuit 2: Empty circuit (identity)
    let circuit2 = Circuit::<1>::new();

    // Check equivalence
    let mut checker = EquivalenceChecker::default();
    let result = checker.check_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: X(0), X(0)");
    println!("   Circuit 2: (empty)");
    println!("   Equivalent: {}", result.equivalent);
    println!("   Check type: {:?}", result.check_type);

    // Another example: HZH = X
    let mut circuit3 = Circuit::<1>::new();
    circuit3.h(0)?;
    circuit3.z(0)?;
    circuit3.h(0)?;

    let mut circuit4 = Circuit::<1>::new();
    circuit4.x(0)?;

    let result2 = checker.check_structural_equivalence(&circuit3, &circuit4)?;

    println!("\n   Circuit 3: H(0), Z(0), H(0)");
    println!("   Circuit 4: X(0)");
    println!("   Structurally equivalent: {}", result2.equivalent);
    println!("   (Note: They are algebraically equivalent but not structurally)");

    Ok(())
}

/// Demonstrate phase equivalence
fn demo_phase_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("3. Global Phase Equivalence");
    println!("   Circuits that differ only by a global phase");

    // Circuit 1: S gate (phase π/2)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.s(0)?;

    // Circuit 2: Z followed by T (phase π + π/4 = 5π/4)
    // This gives the same result up to global phase
    let mut circuit2 = Circuit::<1>::new();
    circuit2.z(0)?;
    circuit2.t(0)?;

    // Check with phase ignored
    let mut checker_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: true,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Check without phase ignored
    let mut checker_no_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: S(0)");
    println!("   Circuit 2: Z(0), T(0)");

    // Note: This example is simplified - actual phase relationship may differ
    println!("   With global phase ignored: (would check if implemented)");
    println!("   Without global phase: (would check if implemented)");

    Ok(())
}

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

Apply a rotation around X-axis

Examples found in repository

examples/equivalence_demo.rs (line 194)

fn demo_custom_tolerance() -> Result<(), Box<dyn std::error::Error>> {
    println!("5. Custom Tolerance Settings");
    println!("   Using different tolerance levels for approximate equivalence");

    // Create circuits that might have small numerical differences
    let mut circuit1 = Circuit::<1>::new();
    circuit1.rx(0, PI / 4.0)?;

    let mut circuit2 = Circuit::<1>::new();
    circuit2.rx(0, PI / 4.0 + 1e-12)?; // Tiny difference

    // Strict tolerance
    let mut strict_checker = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-15,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Relaxed tolerance
    let mut relaxed_checker = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: RX(0, π/4)");
    println!("   Circuit 2: RX(0, π/4 + 1e-12)");
    println!("   With strict tolerance (1e-15): (would check if implemented)");
    println!("   With relaxed tolerance (1e-10): (would check if implemented)");

    Ok(())
}

examples/qasm_example.rs (line 203)

fn round_trip_example() {
    println!("\n4. Round-trip conversion");
    println!("------------------------");

    // Create a variational circuit
    let mut builder = CircuitBuilder::<4>::new();

    // Layer 1: Single-qubit rotations
    for i in 0..4 {
        let _ = builder.ry(Qubit::new(i), 0.5);
        let _ = builder.rz(Qubit::new(i), 0.3);
    }

    // Layer 2: Entangling gates
    for i in 0..3 {
        let _ = builder.cx(Qubit::new(i), Qubit::new(i + 1));
    }
    let _ = builder.cx(Qubit::new(3), Qubit::new(0)); // Circular connectivity

    // Layer 3: More rotations
    for i in 0..4 {
        let _ = builder.rx(Qubit::new(i), -0.2);
    }

    // Measurements
    for i in 0..4 {
        let _ = builder.measure(Qubit::new(i));
    }

    let original = builder.build();

    println!(
        "Original circuit created with {} gates",
        original.gates().len()
    );

    // Export to QASM
    match export_qasm3(&original) {
        Ok(qasm) => {
            println!("\nExported QASM:");
            println!("{}", qasm);

            // Parse it back
            match parse_qasm3(&qasm) {
                Ok(program) => {
                    println!("\n✓ Successfully parsed the exported QASM!");

                    // Validate it
                    match validate_qasm3(&program) {
                        Ok(()) => println!("✓ Validation passed!"),
                        Err(e) => println!("✗ Validation error: {}", e),
                    }

                    // Count operations
                    let gate_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Gate(_))
                        })
                        .count();
                    let measure_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Measure(_))
                        })
                        .count();

                    println!("\nParsed circuit has:");
                    println!("  - {} gate operations", gate_count);
                    println!("  - {} measurements", measure_count);
                }
                Err(e) => println!("Parse error: {}", e),
            }
        }
        Err(e) => println!("Export error: {}", e),
    }
}

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

Apply a rotation around Y-axis

Examples found in repository

examples/qasm_example.rs (line 191)

fn round_trip_example() {
    println!("\n4. Round-trip conversion");
    println!("------------------------");

    // Create a variational circuit
    let mut builder = CircuitBuilder::<4>::new();

    // Layer 1: Single-qubit rotations
    for i in 0..4 {
        let _ = builder.ry(Qubit::new(i), 0.5);
        let _ = builder.rz(Qubit::new(i), 0.3);
    }

    // Layer 2: Entangling gates
    for i in 0..3 {
        let _ = builder.cx(Qubit::new(i), Qubit::new(i + 1));
    }
    let _ = builder.cx(Qubit::new(3), Qubit::new(0)); // Circular connectivity

    // Layer 3: More rotations
    for i in 0..4 {
        let _ = builder.rx(Qubit::new(i), -0.2);
    }

    // Measurements
    for i in 0..4 {
        let _ = builder.measure(Qubit::new(i));
    }

    let original = builder.build();

    println!(
        "Original circuit created with {} gates",
        original.gates().len()
    );

    // Export to QASM
    match export_qasm3(&original) {
        Ok(qasm) => {
            println!("\nExported QASM:");
            println!("{}", qasm);

            // Parse it back
            match parse_qasm3(&qasm) {
                Ok(program) => {
                    println!("\n✓ Successfully parsed the exported QASM!");

                    // Validate it
                    match validate_qasm3(&program) {
                        Ok(()) => println!("✓ Validation passed!"),
                        Err(e) => println!("✗ Validation error: {}", e),
                    }

                    // Count operations
                    let gate_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Gate(_))
                        })
                        .count();
                    let measure_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Measure(_))
                        })
                        .count();

                    println!("\nParsed circuit has:");
                    println!("  - {} gate operations", gate_count);
                    println!("  - {} measurements", measure_count);
                }
                Err(e) => println!("Parse error: {}", e),
            }
        }
        Err(e) => println!("Export error: {}", e),
    }
}

examples/distributed_demo.rs (line 814)

fn create_test_jobs() -> Vec<DistributedJob<4>> {
    let mut jobs = Vec::new();

    // Job 1: Simple Bell state circuit
    let mut bell_circuit = Circuit::<4>::new();
    bell_circuit.h(Qubit(0)).unwrap();
    bell_circuit.cnot(Qubit(0), Qubit(1)).unwrap();

    jobs.push(DistributedJob {
        id: "bell_state_job".to_string(),
        circuit: bell_circuit,
        parameters: ExecutionParameters {
            shots: 1000,
            optimization_level: 1,
            error_mitigation: vec![ErrorMitigation::ReadoutErrorMitigation],
            result_format: ResultFormat::Counts,
            memory_requirement: None,
        },
        priority: Priority::Normal,
        target_backends: None,
        submitted_at: Instant::now(),
        deadline: None,
    });

    // Job 2: GHZ state circuit
    let mut ghz_circuit = Circuit::<4>::new();
    ghz_circuit.h(Qubit(0)).unwrap();
    ghz_circuit.cnot(Qubit(0), Qubit(1)).unwrap();
    ghz_circuit.cnot(Qubit(1), Qubit(2)).unwrap();
    ghz_circuit.cnot(Qubit(2), Qubit(3)).unwrap();

    jobs.push(DistributedJob {
        id: "ghz_state_job".to_string(),
        circuit: ghz_circuit,
        parameters: ExecutionParameters {
            shots: 5000,
            optimization_level: 2,
            error_mitigation: vec![
                ErrorMitigation::ReadoutErrorMitigation,
                ErrorMitigation::ZeroNoiseExtrapolation,
            ],
            result_format: ResultFormat::Probabilities,
            memory_requirement: Some(1.0), // 1 GB
        },
        priority: Priority::High,
        target_backends: Some(vec![
            "qiskit_aer_simulator".to_string(),
            "aws_braket_sv1".to_string(),
        ]),
        submitted_at: Instant::now(),
        deadline: Some(Instant::now() + std::time::Duration::from_secs(300)),
    });

    // Job 3: Variational circuit
    let mut var_circuit = Circuit::<4>::new();
    for i in 0..4 {
        var_circuit.ry(Qubit(i), 0.5).unwrap();
    }
    for i in 0..3 {
        var_circuit.cnot(Qubit(i), Qubit(i + 1)).unwrap();
    }

    jobs.push(DistributedJob {
        id: "variational_job".to_string(),
        circuit: var_circuit,
        parameters: ExecutionParameters {
            shots: 10000,
            optimization_level: 3,
            error_mitigation: vec![
                ErrorMitigation::CliffordDataRegression,
                ErrorMitigation::SymmetryVerification,
            ],
            result_format: ResultFormat::ExpectationValues,
            memory_requirement: Some(2.0), // 2 GB
        },
        priority: Priority::Critical,
        target_backends: None,
        submitted_at: Instant::now(),
        deadline: None,
    });

    jobs
}

examples/qc_co_optimization_demo.rs (line 30)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🔄 Quantum-Classical Co-optimization Demo");
    println!("=========================================\n");

    // Example 1: Basic hybrid problem setup
    println!("1. Setting up a Hybrid Optimization Problem");
    println!("-------------------------------------------");

    let mut problem = HybridOptimizationProblem::<4>::new();

    // Set global parameters for the optimization
    problem.set_global_parameters(vec![0.1, 0.2, 0.3, 0.4, 0.5, 0.6]);
    println!("Set {} global parameters", problem.global_parameters.len());

    // Create a quantum circuit component
    let mut quantum_circuit = Circuit::<4>::new();
    quantum_circuit.h(Qubit(0))?;
    quantum_circuit.cnot(Qubit(0), Qubit(1))?;
    quantum_circuit.ry(Qubit(2), 0.0)?; // Will be parameterized
    quantum_circuit.cnot(Qubit(2), Qubit(3))?;

    // Add quantum component to the problem
    problem.add_quantum_component(
        "quantum_processor".to_string(),
        quantum_circuit,
        vec![0, 1, 2], // Use parameters 0, 1, 2 from global parameter vector
    )?;

    println!(
        "Added quantum circuit component with {} gates",
        problem.quantum_circuits[0].circuit.num_gates()
    );

    // Example 2: Adding classical processing steps
    println!("\n2. Adding Classical Processing Steps");
    println!("-----------------------------------");

    // Add a classical linear algebra step
    problem.add_classical_step(
        "matrix_operations".to_string(),
        ClassicalStepType::LinearAlgebra(LinearAlgebraOp::MatrixMultiplication),
        vec!["quantum_processor".to_string()],
        vec!["processed_measurements".to_string()],
    )?;

    // Add a machine learning inference step
    problem.add_classical_step(
        "ml_inference".to_string(),
        ClassicalStepType::MachineLearning(QCMLModelType::NeuralNetwork),
        vec!["processed_measurements".to_string()],
        vec!["ml_output".to_string()],
    )?;

    // Add a parameter update step
    problem.add_classical_step(
        "parameter_update".to_string(),
        ClassicalStepType::ParameterUpdate(UpdateRule::AdamOptimizer),
        vec!["ml_output".to_string()],
        vec!["updated_parameters".to_string()],
    )?;

    println!(
        "Added {} classical processing steps",
        problem.classical_steps.len()
    );

    // Print details of each classical step
    for (i, step) in problem.classical_steps.iter().enumerate() {
        println!("  Step {}: {} ({:?})", i + 1, step.id, step.step_type);
    }

    // Example 3: Setting up data flow
    println!("\n3. Setting up Data Flow");
    println!("-----------------------");

    // Connect quantum processor to matrix operations
    problem.add_data_flow(
        "quantum_processor".to_string(),
        "matrix_operations".to_string(),
        DataType::Measurements(vec![0.5, 0.3, 0.8, 0.1]),
    )?;

    // Connect matrix operations to ML inference
    problem.add_data_flow(
        "matrix_operations".to_string(),
        "ml_inference".to_string(),
        DataType::Matrix(vec![vec![1.0, 0.5], vec![0.3, 0.8]]),
    )?;

    // Connect ML inference to parameter update
    problem.add_data_flow(
        "ml_inference".to_string(),
        "parameter_update".to_string(),
        DataType::Scalar(0.75),
    )?;

    println!(
        "Set up {} data flow connections",
        problem.data_flow.edges.len()
    );

    // Print data flow details
    for (i, (source, target, data_type)) in problem.data_flow.edges.iter().enumerate() {
        println!(
            "  Flow {}: {} -> {} ({:?})",
            i + 1,
            source,
            target,
            data_type
        );
    }

    // Example 4: Adding regularization
    println!("\n4. Adding Regularization Terms");
    println!("------------------------------");

    // Add L2 regularization on parameters 0-2
    problem.add_regularization(RegularizationType::L2, 0.01, vec![0, 1, 2])?;

    // Add sparsity regularization on parameters 3-5
    problem.add_regularization(RegularizationType::Sparsity, 0.005, vec![3, 4, 5])?;

    println!(
        "Added {} regularization terms",
        problem.objective.regularization.len()
    );

    for (i, reg) in problem.objective.regularization.iter().enumerate() {
        println!(
            "  Regularization {}: {:?} (strength: {:.3})",
            i + 1,
            reg.reg_type,
            reg.strength
        );
    }

    // Example 5: Validating the problem
    println!("\n5. Problem Validation");
    println!("---------------------");

    match problem.validate() {
        Ok(()) => println!("✅ Problem validation passed"),
        Err(e) => println!("❌ Problem validation failed: {}", e),
    }

    println!("Total components: {}", problem.data_flow.nodes.len());
    println!("Total connections: {}", problem.data_flow.edges.len());

    // Example 6: Different optimization algorithms
    println!("\n6. Optimization Algorithms");
    println!("--------------------------");

    let algorithms = vec![
        (
            "Coordinate Descent",
            HybridOptimizationAlgorithm::CoordinateDescent,
        ),
        (
            "Simultaneous Optimization",
            HybridOptimizationAlgorithm::SimultaneousOptimization,
        ),
        (
            "Hierarchical Optimization",
            HybridOptimizationAlgorithm::HierarchicalOptimization,
        ),
        (
            "Adaptive Optimization",
            HybridOptimizationAlgorithm::AdaptiveOptimization,
        ),
    ];

    for (name, algorithm) in algorithms {
        let optimizer = HybridOptimizer::new(algorithm.clone());
        println!("  {}: {:?}", name, optimizer.algorithm);
        println!("    Max iterations: {}", optimizer.max_iterations);
        println!("    Tolerance: {:.2e}", optimizer.tolerance);
        println!(
            "    Initial learning rate: {}",
            optimizer.learning_rate_schedule.initial_rate
        );
    }

    // Example 7: Learning rate schedules
    println!("\n7. Learning Rate Schedules");
    println!("--------------------------");

    let mut optimizer = HybridOptimizer::new(HybridOptimizationAlgorithm::SimultaneousOptimization);

    // Set up different schedules
    let schedules = vec![
        ("Constant", ScheduleType::Constant),
        ("Linear Decay", ScheduleType::LinearDecay),
        ("Exponential Decay", ScheduleType::ExponentialDecay),
        ("Step Decay", ScheduleType::StepDecay),
        ("Cosine Annealing", ScheduleType::CosineAnnealing),
    ];

    for (name, schedule_type) in schedules {
        optimizer.learning_rate_schedule.schedule_type = schedule_type.clone();
        println!("  {}: {:?}", name, schedule_type);
    }

    // Example 8: Parallelization configuration
    println!("\n8. Parallelization Configuration");
    println!("--------------------------------");

    optimizer.parallelization.quantum_parallelism = 4;
    optimizer.parallelization.classical_parallelism = 8;
    optimizer.parallelization.asynchronous = true;
    optimizer.parallelization.load_balancing = LoadBalancingStrategy::WorkStealing;

    println!(
        "Quantum parallelism: {} circuits",
        optimizer.parallelization.quantum_parallelism
    );
    println!(
        "Classical parallelism: {} threads",
        optimizer.parallelization.classical_parallelism
    );
    println!(
        "Asynchronous execution: {}",
        optimizer.parallelization.asynchronous
    );
    println!(
        "Load balancing: {:?}",
        optimizer.parallelization.load_balancing
    );

    // Example 9: Running optimization (mock)
    println!("\n9. Running Optimization");
    println!("-----------------------");

    println!("Starting hybrid optimization...");
    let result = optimizer.optimize(&mut problem)?;

    println!("Optimization completed:");
    println!("  Optimal value: {:.6}", result.optimal_value);
    println!("  Converged: {}", result.converged);
    println!("  Iterations: {}", result.iterations);
    println!("  Final parameters: {:?}", result.optimal_parameters);

    // Print some history information
    if !result.history.objective_values.is_empty() {
        println!("  Objective value history (first 5):");
        for (i, &value) in result.history.objective_values.iter().take(5).enumerate() {
            println!("    Iteration {}: {:.6}", i, value);
        }
    }

    if !result.history.gradient_norms.is_empty() {
        let final_gradient = result.history.gradient_norms.last().unwrap();
        println!("  Final gradient norm: {:.2e}", final_gradient);
    }

    // Example 10: Specific hybrid algorithm patterns
    println!("\n10. Common Hybrid Algorithm Patterns");
    println!("------------------------------------");

    // QAOA-like pattern
    println!("QAOA-like pattern:");
    println!("  1. Prepare initial state (quantum)");
    println!("  2. Apply parameterized unitaries (quantum)");
    println!("  3. Measure expectation values (quantum)");
    println!("  4. Classical optimization step (classical)");
    println!("  5. Repeat until convergence");

    // VQE with neural network pattern
    println!("\nVQE with Neural Network pattern:");
    println!("  1. Prepare ansatz circuit (quantum)");
    println!("  2. Measure Pauli expectations (quantum)");
    println!("  3. Neural network post-processing (classical)");
    println!("  4. Gradient-based parameter update (classical)");
    println!("  5. Repeat until convergence");

    // Quantum-enhanced ML pattern
    println!("\nQuantum-enhanced ML pattern:");
    println!("  1. Classical feature encoding (classical)");
    println!("  2. Quantum feature mapping (quantum)");
    println!("  3. Quantum measurements (quantum)");
    println!("  4. Classical ML inference (classical)");
    println!("  5. End-to-end gradient updates (hybrid)");

    // Example 11: Data types and flow
    println!("\n11. Data Types in Hybrid Algorithms");
    println!("-----------------------------------");

    let data_types = vec![
        (
            "Quantum measurements",
            "Raw measurement outcomes from quantum circuits",
        ),
        (
            "Probability distributions",
            "Estimated probability distributions from measurements",
        ),
        (
            "Classical matrices",
            "Processed data in matrix form for linear algebra",
        ),
        (
            "Scalar values",
            "Single numerical values like energies or costs",
        ),
        (
            "Parameter vectors",
            "Optimization parameters for both quantum and classical components",
        ),
        (
            "Control signals",
            "Boolean flags for adaptive algorithm control",
        ),
    ];

    for (dtype, description) in data_types {
        println!("  {}: {}", dtype, description);
    }

    println!("\n✅ Quantum-Classical Co-optimization Demo completed!");
    println!("\nNote: This demo shows the framework structure for hybrid optimization.");
    println!("Real co-optimization requires actual quantum and classical execution engines.");

    Ok(())
}

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

Apply a rotation around Z-axis

Examples found in repository

examples/optimization_demo.rs (line 48)

fn create_sample_circuit() -> Circuit<4> {
    // Create a circuit that has optimization opportunities
    let mut circuit = Circuit::<4>::new();

    // Add some gates with optimization opportunities
    // Pattern 1: Redundant gates (H-H = I, X-X = I)
    let _ = circuit.h(0);
    let _ = circuit.h(0);

    // Pattern 2: Commutable gates
    let _ = circuit.x(1);
    let _ = circuit.z(0);
    let _ = circuit.cnot(0, 1);

    // Pattern 3: Mergeable rotations
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);

    // Pattern 4: Known patterns (H-X-H = Z)
    let _ = circuit.h(3);
    let _ = circuit.x(3);
    let _ = circuit.h(3);

    // Pattern 5: Decomposable gates
    let _ = circuit.toffoli(0, 1, 2);

    circuit
}

examples/qasm_example.rs (line 192)

fn round_trip_example() {
    println!("\n4. Round-trip conversion");
    println!("------------------------");

    // Create a variational circuit
    let mut builder = CircuitBuilder::<4>::new();

    // Layer 1: Single-qubit rotations
    for i in 0..4 {
        let _ = builder.ry(Qubit::new(i), 0.5);
        let _ = builder.rz(Qubit::new(i), 0.3);
    }

    // Layer 2: Entangling gates
    for i in 0..3 {
        let _ = builder.cx(Qubit::new(i), Qubit::new(i + 1));
    }
    let _ = builder.cx(Qubit::new(3), Qubit::new(0)); // Circular connectivity

    // Layer 3: More rotations
    for i in 0..4 {
        let _ = builder.rx(Qubit::new(i), -0.2);
    }

    // Measurements
    for i in 0..4 {
        let _ = builder.measure(Qubit::new(i));
    }

    let original = builder.build();

    println!(
        "Original circuit created with {} gates",
        original.gates().len()
    );

    // Export to QASM
    match export_qasm3(&original) {
        Ok(qasm) => {
            println!("\nExported QASM:");
            println!("{}", qasm);

            // Parse it back
            match parse_qasm3(&qasm) {
                Ok(program) => {
                    println!("\n✓ Successfully parsed the exported QASM!");

                    // Validate it
                    match validate_qasm3(&program) {
                        Ok(()) => println!("✓ Validation passed!"),
                        Err(e) => println!("✗ Validation error: {}", e),
                    }

                    // Count operations
                    let gate_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Gate(_))
                        })
                        .count();
                    let measure_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Measure(_))
                        })
                        .count();

                    println!("\nParsed circuit has:");
                    println!("  - {} gate operations", gate_count);
                    println!("  - {} measurements", measure_count);
                }
                Err(e) => println!("Parse error: {}", e),
            }
        }
        Err(e) => println!("Export error: {}", e),
    }
}

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

Apply a Phase gate (S gate)

Examples found in repository

examples/equivalence_demo.rs (line 108)

fn demo_phase_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("3. Global Phase Equivalence");
    println!("   Circuits that differ only by a global phase");

    // Circuit 1: S gate (phase π/2)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.s(0)?;

    // Circuit 2: Z followed by T (phase π + π/4 = 5π/4)
    // This gives the same result up to global phase
    let mut circuit2 = Circuit::<1>::new();
    circuit2.z(0)?;
    circuit2.t(0)?;

    // Check with phase ignored
    let mut checker_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: true,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Check without phase ignored
    let mut checker_no_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: S(0)");
    println!("   Circuit 2: Z(0), T(0)");

    // Note: This example is simplified - actual phase relationship may differ
    println!("   With global phase ignored: (would check if implemented)");
    println!("   Without global phase: (would check if implemented)");

    Ok(())
}

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

Examples found in repository

examples/equivalence_demo.rs (line 114)

fn demo_phase_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("3. Global Phase Equivalence");
    println!("   Circuits that differ only by a global phase");

    // Circuit 1: S gate (phase π/2)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.s(0)?;

    // Circuit 2: Z followed by T (phase π + π/4 = 5π/4)
    // This gives the same result up to global phase
    let mut circuit2 = Circuit::<1>::new();
    circuit2.z(0)?;
    circuit2.t(0)?;

    // Check with phase ignored
    let mut checker_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: true,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Check without phase ignored
    let mut checker_no_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: S(0)");
    println!("   Circuit 2: Z(0), T(0)");

    // Note: This example is simplified - actual phase relationship may differ
    println!("   With global phase ignored: (would check if implemented)");
    println!("   Without global phase: (would check if implemented)");

    Ok(())
}

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

Examples found in repository

examples/optimization_demo.rs (line 45)

fn create_sample_circuit() -> Circuit<4> {
    // Create a circuit that has optimization opportunities
    let mut circuit = Circuit::<4>::new();

    // Add some gates with optimization opportunities
    // Pattern 1: Redundant gates (H-H = I, X-X = I)
    let _ = circuit.h(0);
    let _ = circuit.h(0);

    // Pattern 2: Commutable gates
    let _ = circuit.x(1);
    let _ = circuit.z(0);
    let _ = circuit.cnot(0, 1);

    // Pattern 3: Mergeable rotations
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);

    // Pattern 4: Known patterns (H-X-H = Z)
    let _ = circuit.h(3);
    let _ = circuit.x(3);
    let _ = circuit.h(3);

    // Pattern 5: Decomposable gates
    let _ = circuit.toffoli(0, 1, 2);

    circuit
}

examples/equivalence_demo.rs (line 42)

fn demo_structural_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("1. Structural Equivalence Check");
    println!("   Checking if two circuits have identical gate sequences");

    // Create two identical Bell state circuits
    let mut circuit1 = Circuit::<2>::new();
    circuit1.h(0)?;
    circuit1.cnot(0, 1)?;

    let mut circuit2 = Circuit::<2>::new();
    circuit2.h(0)?;
    circuit2.cnot(0, 1)?;

    // Check structural equivalence
    let checker = EquivalenceChecker::default();
    let result = checker.check_structural_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: H(0), CNOT(0,1)");
    println!("   Circuit 2: H(0), CNOT(0,1)");
    println!("   Structurally equivalent: {}", result.equivalent);
    println!("   Details: {}", result.details);

    Ok(())
}

/// Demonstrate algebraic equivalence (different gates, same result)
fn demo_algebraic_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("2. Algebraic Equivalence Check");
    println!("   Different gate sequences that produce the same result");

    // Circuit 1: X followed by X (should equal identity)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.x(0)?;
    circuit1.x(0)?;

    // Circuit 2: Empty circuit (identity)
    let circuit2 = Circuit::<1>::new();

    // Check equivalence
    let mut checker = EquivalenceChecker::default();
    let result = checker.check_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: X(0), X(0)");
    println!("   Circuit 2: (empty)");
    println!("   Equivalent: {}", result.equivalent);
    println!("   Check type: {:?}", result.check_type);

    // Another example: HZH = X
    let mut circuit3 = Circuit::<1>::new();
    circuit3.h(0)?;
    circuit3.z(0)?;
    circuit3.h(0)?;

    let mut circuit4 = Circuit::<1>::new();
    circuit4.x(0)?;

    let result2 = checker.check_structural_equivalence(&circuit3, &circuit4)?;

    println!("\n   Circuit 3: H(0), Z(0), H(0)");
    println!("   Circuit 4: X(0)");
    println!("   Structurally equivalent: {}", result2.equivalent);
    println!("   (Note: They are algebraically equivalent but not structurally)");

    Ok(())
}

/// Demonstrate phase equivalence
fn demo_phase_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("3. Global Phase Equivalence");
    println!("   Circuits that differ only by a global phase");

    // Circuit 1: S gate (phase π/2)
    let mut circuit1 = Circuit::<1>::new();
    circuit1.s(0)?;

    // Circuit 2: Z followed by T (phase π + π/4 = 5π/4)
    // This gives the same result up to global phase
    let mut circuit2 = Circuit::<1>::new();
    circuit2.z(0)?;
    circuit2.t(0)?;

    // Check with phase ignored
    let mut checker_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: true,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Check without phase ignored
    let mut checker_no_phase = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: S(0)");
    println!("   Circuit 2: Z(0), T(0)");

    // Note: This example is simplified - actual phase relationship may differ
    println!("   With global phase ignored: (would check if implemented)");
    println!("   Without global phase: (would check if implemented)");

    Ok(())
}

/// Demonstrate detection of non-equivalent circuits
fn demo_non_equivalence() -> Result<(), Box<dyn std::error::Error>> {
    println!("4. Non-Equivalence Detection");
    println!("   Detecting when circuits are NOT equivalent");

    // Circuit 1: Bell state |00> + |11>
    let mut circuit1 = Circuit::<2>::new();
    circuit1.h(0)?;
    circuit1.cnot(0, 1)?;

    // Circuit 2: Different entangled state |01> + |10>
    let mut circuit2 = Circuit::<2>::new();
    circuit2.h(0)?;
    circuit2.x(1)?;
    circuit2.cnot(0, 1)?;

    let checker = EquivalenceChecker::default();
    let result = checker.check_structural_equivalence(&circuit1, &circuit2)?;

    println!("   Circuit 1: H(0), CNOT(0,1)");
    println!("   Circuit 2: H(0), X(1), CNOT(0,1)");
    println!("   Equivalent: {}", result.equivalent);
    println!("   Details: {}", result.details);

    Ok(())
}

/// Demonstrate custom tolerance settings
fn demo_custom_tolerance() -> Result<(), Box<dyn std::error::Error>> {
    println!("5. Custom Tolerance Settings");
    println!("   Using different tolerance levels for approximate equivalence");

    // Create circuits that might have small numerical differences
    let mut circuit1 = Circuit::<1>::new();
    circuit1.rx(0, PI / 4.0)?;

    let mut circuit2 = Circuit::<1>::new();
    circuit2.rx(0, PI / 4.0 + 1e-12)?; // Tiny difference

    // Strict tolerance
    let mut strict_checker = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-15,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    // Relaxed tolerance
    let mut relaxed_checker = EquivalenceChecker::new(EquivalenceOptions {
        tolerance: 1e-10,
        ignore_global_phase: false,
        check_all_states: true,
        max_unitary_qubits: 10,
        enable_adaptive_tolerance: true,
        enable_statistical_analysis: true,
        enable_stability_analysis: true,
        enable_graph_comparison: false,
        confidence_level: 0.95,
        max_condition_number: 1e12,
        scirs2_config: None,
        complex_tolerance: 1e-14,
        enable_parallel_computation: true,
    });

    println!("   Circuit 1: RX(0, π/4)");
    println!("   Circuit 2: RX(0, π/4 + 1e-12)");
    println!("   With strict tolerance (1e-15): (would check if implemented)");
    println!("   With relaxed tolerance (1e-10): (would check if implemented)");

    Ok(())
}

/// Additional example: Verify circuit optimization preserves behavior
fn verify_optimization_example() -> Result<(), Box<dyn std::error::Error>> {
    println!("\nBonus: Verifying Circuit Optimization");

    // Original circuit with redundant gates
    let mut original = Circuit::<2>::new();
    original.h(0)?;
    original.cnot(0, 1)?;
    original.cnot(0, 1)?; // This cancels the previous CNOT
    original.h(0)?;

    // Optimized circuit (manually optimized for this example)
    let optimized = Circuit::<2>::new();
    // Empty circuit since H-CNOT-CNOT-H = H-H = I

    let checker = EquivalenceChecker::default();
    println!("   Original: H(0), CNOT(0,1), CNOT(0,1), H(0)");
    println!("   Optimized: (empty)");

    // In practice, you would use the circuit optimizer and then verify:
    // let optimized = original.optimize()?;
    // let result = checker.check_equivalence(&original, &optimized)?;

    Ok(())
}

examples/classical_control_demo.rs (line 56)

fn quantum_teleportation() -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 2: Quantum Teleportation");
    println!("--------------------------------");

    // Create Bell pair between qubits 1 and 2
    let mut circuit = Circuit::<3>::new();
    circuit.h(1)?;
    circuit.cnot(1, 2)?;

    // Convert to classical circuit for measurements
    let mut classical_circuit = circuit.with_classical_control();
    classical_circuit.add_classical_register("alice", 2)?;

    // Alice's operations
    classical_circuit.add_gate(quantrs2_core::gate::multi::CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    classical_circuit.add_gate(Hadamard { target: QubitId(0) })?;

    // Alice measures her qubits
    classical_circuit.measure(QubitId(0), "alice", 0)?;
    classical_circuit.measure(QubitId(1), "alice", 1)?;

    // Bob applies corrections based on Alice's measurements
    classical_circuit.add_conditional(
        ClassicalCondition {
            lhs: ClassicalValue::Register("alice".to_string()),
            op: ComparisonOp::Equal,
            rhs: ClassicalValue::Integer(0b01),
        },
        PauliX { target: QubitId(2) },
    )?;

    classical_circuit.add_conditional(
        ClassicalCondition {
            lhs: ClassicalValue::Register("alice".to_string()),
            op: ComparisonOp::Equal,
            rhs: ClassicalValue::Integer(0b10),
        },
        PauliZ { target: QubitId(2) },
    )?;

    classical_circuit.add_conditional(
        ClassicalCondition {
            lhs: ClassicalValue::Register("alice".to_string()),
            op: ComparisonOp::Equal,
            rhs: ClassicalValue::Integer(0b11),
        },
        PauliX { target: QubitId(2) }, // In reality, this would be X then Z
    )?;

    println!(
        "Created teleportation circuit with {} operations",
        classical_circuit.num_operations()
    );
    println!("Bob's qubit 2 receives the state that was on Alice's qubit 0\n");

    Ok(())
}

examples/distributed_demo.rs (line 764)

fn create_test_jobs() -> Vec<DistributedJob<4>> {
    let mut jobs = Vec::new();

    // Job 1: Simple Bell state circuit
    let mut bell_circuit = Circuit::<4>::new();
    bell_circuit.h(Qubit(0)).unwrap();
    bell_circuit.cnot(Qubit(0), Qubit(1)).unwrap();

    jobs.push(DistributedJob {
        id: "bell_state_job".to_string(),
        circuit: bell_circuit,
        parameters: ExecutionParameters {
            shots: 1000,
            optimization_level: 1,
            error_mitigation: vec![ErrorMitigation::ReadoutErrorMitigation],
            result_format: ResultFormat::Counts,
            memory_requirement: None,
        },
        priority: Priority::Normal,
        target_backends: None,
        submitted_at: Instant::now(),
        deadline: None,
    });

    // Job 2: GHZ state circuit
    let mut ghz_circuit = Circuit::<4>::new();
    ghz_circuit.h(Qubit(0)).unwrap();
    ghz_circuit.cnot(Qubit(0), Qubit(1)).unwrap();
    ghz_circuit.cnot(Qubit(1), Qubit(2)).unwrap();
    ghz_circuit.cnot(Qubit(2), Qubit(3)).unwrap();

    jobs.push(DistributedJob {
        id: "ghz_state_job".to_string(),
        circuit: ghz_circuit,
        parameters: ExecutionParameters {
            shots: 5000,
            optimization_level: 2,
            error_mitigation: vec![
                ErrorMitigation::ReadoutErrorMitigation,
                ErrorMitigation::ZeroNoiseExtrapolation,
            ],
            result_format: ResultFormat::Probabilities,
            memory_requirement: Some(1.0), // 1 GB
        },
        priority: Priority::High,
        target_backends: Some(vec![
            "qiskit_aer_simulator".to_string(),
            "aws_braket_sv1".to_string(),
        ]),
        submitted_at: Instant::now(),
        deadline: Some(Instant::now() + std::time::Duration::from_secs(300)),
    });

    // Job 3: Variational circuit
    let mut var_circuit = Circuit::<4>::new();
    for i in 0..4 {
        var_circuit.ry(Qubit(i), 0.5).unwrap();
    }
    for i in 0..3 {
        var_circuit.cnot(Qubit(i), Qubit(i + 1)).unwrap();
    }

    jobs.push(DistributedJob {
        id: "variational_job".to_string(),
        circuit: var_circuit,
        parameters: ExecutionParameters {
            shots: 10000,
            optimization_level: 3,
            error_mitigation: vec![
                ErrorMitigation::CliffordDataRegression,
                ErrorMitigation::SymmetryVerification,
            ],
            result_format: ResultFormat::ExpectationValues,
            memory_requirement: Some(2.0), // 2 GB
        },
        priority: Priority::Critical,
        target_backends: None,
        submitted_at: Instant::now(),
        deadline: None,
    });

    jobs
}

examples/vqe_demo.rs (line 76)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🧮 Variational Quantum Eigensolver (VQE) Demo");
    println!("============================================\n");

    // Example 1: Hardware-efficient ansatz for small molecules
    println!("1. Hardware-Efficient Ansatz for 4-qubit system");
    println!("-----------------------------------------------");

    let mut vqe_circuit = VQECircuit::<4>::new(VQEAnsatz::HardwareEfficient { layers: 2 })?;
    println!(
        "Created VQE circuit with {} parameters",
        vqe_circuit.num_parameters()
    );

    // Set some example parameters
    let param_names = vqe_circuit.parameter_names.clone();
    for (i, param_name) in param_names.iter().enumerate() {
        vqe_circuit.set_parameter(param_name, 0.1 * i as f64)?;
    }

    println!("Set parameters: {:?}", vqe_circuit.parameters);
    println!("Parameter names: {:?}\n", vqe_circuit.parameter_names);

    // Example 2: UCCSD ansatz for quantum chemistry
    println!("2. UCCSD Ansatz for quantum chemistry");
    println!("--------------------------------------");

    let uccsd_circuit = VQECircuit::<6>::new(VQEAnsatz::UCCSD {
        occupied_orbitals: 2,
        virtual_orbitals: 4,
    })?;
    println!(
        "Created UCCSD circuit with {} parameters",
        uccsd_circuit.num_parameters()
    );
    println!("Circuit has {} gates", uccsd_circuit.circuit.num_gates());

    // Example 3: Observables for different Hamiltonians
    println!("\n3. Creating Observables");
    println!("----------------------");

    // Heisenberg model
    let heisenberg = VQEObservable::heisenberg_model(4, 1.0);
    println!("Heisenberg model with {} terms", heisenberg.terms.len());

    // Transverse Field Ising Model
    let tfim = VQEObservable::tfim(4, 1.0, 0.5);
    println!("TFIM model with {} terms", tfim.terms.len());

    // Custom observable
    let mut custom_obs = VQEObservable::new();
    custom_obs.add_pauli_term(1.0, vec![(0, PauliOperator::Z), (1, PauliOperator::Z)]);
    custom_obs.add_pauli_term(0.5, vec![(0, PauliOperator::X)]);
    custom_obs.add_pauli_term(0.5, vec![(1, PauliOperator::X)]);
    println!("Custom observable with {} terms", custom_obs.terms.len());

    // Example 4: Custom ansatz construction
    println!("\n4. Custom Ansatz Construction");
    println!("-----------------------------");

    let mut custom_vqe = VQECircuit::<3>::new(VQEAnsatz::Custom)?;

    // Add custom parameterized gates
    custom_vqe.add_parameterized_ry(Qubit(0), "theta_0")?;
    custom_vqe.add_parameterized_rz(Qubit(1), "phi_1")?;
    custom_vqe.add_parameterized_ry(Qubit(2), "theta_2")?;

    // Add fixed gates to the underlying circuit
    custom_vqe.circuit.cnot(Qubit(0), Qubit(1))?;
    custom_vqe.circuit.cnot(Qubit(1), Qubit(2))?;

    println!(
        "Custom VQE circuit with {} parameters",
        custom_vqe.num_parameters()
    );

    // Set parameter values
    custom_vqe.set_parameter("theta_0", std::f64::consts::PI / 4.0)?;
    custom_vqe.set_parameter("phi_1", std::f64::consts::PI / 2.0)?;
    custom_vqe.set_parameter("theta_2", std::f64::consts::PI / 6.0)?;

    println!(
        "theta_0 = {:.4}",
        custom_vqe.get_parameter("theta_0").unwrap()
    );
    println!("phi_1 = {:.4}", custom_vqe.get_parameter("phi_1").unwrap());
    println!(
        "theta_2 = {:.4}",
        custom_vqe.get_parameter("theta_2").unwrap()
    );

    // Example 5: VQE Optimization (mock demonstration)
    println!("\n5. VQE Optimization");
    println!("-------------------");

    let optimizer = VQEOptimizer::new(VQEOptimizerType::GradientDescent);
    println!(
        "Created optimizer with max iterations: {}",
        optimizer.max_iterations
    );
    println!("Tolerance: {:.2e}", optimizer.tolerance);
    println!("Learning rate: {}", optimizer.learning_rate);

    // In a real implementation, this would actually optimize the parameters
    let result = optimizer.optimize(&mut custom_vqe, &custom_obs)?;
    println!("Optimization result:");
    println!("  Ground state energy: {:.6}", result.ground_state_energy);
    println!("  Converged: {}", result.converged);
    println!("  Iterations: {}", result.iterations);
    println!("  Gradient norm: {:.2e}", result.gradient_norm);

    // Example 6: Different optimizer types
    println!("\n6. Different Optimizer Types");
    println!("----------------------------");

    let optimizers = vec![
        ("Gradient Descent", VQEOptimizerType::GradientDescent),
        (
            "Adam",
            VQEOptimizerType::Adam {
                beta1: 0.9,
                beta2: 0.999,
            },
        ),
        ("BFGS", VQEOptimizerType::BFGS),
        ("Nelder-Mead", VQEOptimizerType::NelderMead),
        (
            "SPSA",
            VQEOptimizerType::SPSA {
                alpha: 0.602,
                gamma: 0.101,
            },
        ),
    ];

    for (name, opt_type) in optimizers {
        let opt = VQEOptimizer::new(opt_type);
        println!("  {}: {:?}", name, opt.optimizer_type);
    }

    // Example 7: Real-space ansatz
    println!("\n7. Real-Space Ansatz");
    println!("--------------------");

    let geometry = vec![
        (0.0, 0.0, 0.0), // Site 0
        (1.0, 0.0, 0.0), // Site 1
        (0.0, 1.0, 0.0), // Site 2
        (1.0, 1.0, 0.0), // Site 3
    ];

    let real_space_circuit = VQECircuit::<4>::new(VQEAnsatz::RealSpace { geometry })?;
    println!(
        "Real-space circuit with {} parameters",
        real_space_circuit.num_parameters()
    );
    println!("Based on 2x2 square lattice geometry");

    // Example 8: Molecular Hamiltonian
    println!("\n8. Molecular Hamiltonian");
    println!("------------------------");

    // Example one-body and two-body integrals (simplified)
    let one_body = vec![
        (0, 0, -1.0), // h_00
        (1, 1, -1.0), // h_11
        (0, 1, -0.5), // h_01
    ];

    let two_body = vec![
        (0, 1, 0, 1, 0.5), // (00|11)
        (0, 0, 1, 1, 0.3), // (01|01)
    ];

    let molecular_ham = VQEObservable::molecular_hamiltonian(&one_body, &two_body);
    println!(
        "Molecular Hamiltonian with {} terms",
        molecular_ham.terms.len()
    );

    println!("\n✅ VQE Demo completed successfully!");
    println!("\nNote: This demo shows the VQE framework structure.");
    println!("Real VQE optimization requires quantum simulation or hardware execution.");

    Ok(())
}

examples/qc_co_optimization_demo.rs (line 29)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🔄 Quantum-Classical Co-optimization Demo");
    println!("=========================================\n");

    // Example 1: Basic hybrid problem setup
    println!("1. Setting up a Hybrid Optimization Problem");
    println!("-------------------------------------------");

    let mut problem = HybridOptimizationProblem::<4>::new();

    // Set global parameters for the optimization
    problem.set_global_parameters(vec![0.1, 0.2, 0.3, 0.4, 0.5, 0.6]);
    println!("Set {} global parameters", problem.global_parameters.len());

    // Create a quantum circuit component
    let mut quantum_circuit = Circuit::<4>::new();
    quantum_circuit.h(Qubit(0))?;
    quantum_circuit.cnot(Qubit(0), Qubit(1))?;
    quantum_circuit.ry(Qubit(2), 0.0)?; // Will be parameterized
    quantum_circuit.cnot(Qubit(2), Qubit(3))?;

    // Add quantum component to the problem
    problem.add_quantum_component(
        "quantum_processor".to_string(),
        quantum_circuit,
        vec![0, 1, 2], // Use parameters 0, 1, 2 from global parameter vector
    )?;

    println!(
        "Added quantum circuit component with {} gates",
        problem.quantum_circuits[0].circuit.num_gates()
    );

    // Example 2: Adding classical processing steps
    println!("\n2. Adding Classical Processing Steps");
    println!("-----------------------------------");

    // Add a classical linear algebra step
    problem.add_classical_step(
        "matrix_operations".to_string(),
        ClassicalStepType::LinearAlgebra(LinearAlgebraOp::MatrixMultiplication),
        vec!["quantum_processor".to_string()],
        vec!["processed_measurements".to_string()],
    )?;

    // Add a machine learning inference step
    problem.add_classical_step(
        "ml_inference".to_string(),
        ClassicalStepType::MachineLearning(QCMLModelType::NeuralNetwork),
        vec!["processed_measurements".to_string()],
        vec!["ml_output".to_string()],
    )?;

    // Add a parameter update step
    problem.add_classical_step(
        "parameter_update".to_string(),
        ClassicalStepType::ParameterUpdate(UpdateRule::AdamOptimizer),
        vec!["ml_output".to_string()],
        vec!["updated_parameters".to_string()],
    )?;

    println!(
        "Added {} classical processing steps",
        problem.classical_steps.len()
    );

    // Print details of each classical step
    for (i, step) in problem.classical_steps.iter().enumerate() {
        println!("  Step {}: {} ({:?})", i + 1, step.id, step.step_type);
    }

    // Example 3: Setting up data flow
    println!("\n3. Setting up Data Flow");
    println!("-----------------------");

    // Connect quantum processor to matrix operations
    problem.add_data_flow(
        "quantum_processor".to_string(),
        "matrix_operations".to_string(),
        DataType::Measurements(vec![0.5, 0.3, 0.8, 0.1]),
    )?;

    // Connect matrix operations to ML inference
    problem.add_data_flow(
        "matrix_operations".to_string(),
        "ml_inference".to_string(),
        DataType::Matrix(vec![vec![1.0, 0.5], vec![0.3, 0.8]]),
    )?;

    // Connect ML inference to parameter update
    problem.add_data_flow(
        "ml_inference".to_string(),
        "parameter_update".to_string(),
        DataType::Scalar(0.75),
    )?;

    println!(
        "Set up {} data flow connections",
        problem.data_flow.edges.len()
    );

    // Print data flow details
    for (i, (source, target, data_type)) in problem.data_flow.edges.iter().enumerate() {
        println!(
            "  Flow {}: {} -> {} ({:?})",
            i + 1,
            source,
            target,
            data_type
        );
    }

    // Example 4: Adding regularization
    println!("\n4. Adding Regularization Terms");
    println!("------------------------------");

    // Add L2 regularization on parameters 0-2
    problem.add_regularization(RegularizationType::L2, 0.01, vec![0, 1, 2])?;

    // Add sparsity regularization on parameters 3-5
    problem.add_regularization(RegularizationType::Sparsity, 0.005, vec![3, 4, 5])?;

    println!(
        "Added {} regularization terms",
        problem.objective.regularization.len()
    );

    for (i, reg) in problem.objective.regularization.iter().enumerate() {
        println!(
            "  Regularization {}: {:?} (strength: {:.3})",
            i + 1,
            reg.reg_type,
            reg.strength
        );
    }

    // Example 5: Validating the problem
    println!("\n5. Problem Validation");
    println!("---------------------");

    match problem.validate() {
        Ok(()) => println!("✅ Problem validation passed"),
        Err(e) => println!("❌ Problem validation failed: {}", e),
    }

    println!("Total components: {}", problem.data_flow.nodes.len());
    println!("Total connections: {}", problem.data_flow.edges.len());

    // Example 6: Different optimization algorithms
    println!("\n6. Optimization Algorithms");
    println!("--------------------------");

    let algorithms = vec![
        (
            "Coordinate Descent",
            HybridOptimizationAlgorithm::CoordinateDescent,
        ),
        (
            "Simultaneous Optimization",
            HybridOptimizationAlgorithm::SimultaneousOptimization,
        ),
        (
            "Hierarchical Optimization",
            HybridOptimizationAlgorithm::HierarchicalOptimization,
        ),
        (
            "Adaptive Optimization",
            HybridOptimizationAlgorithm::AdaptiveOptimization,
        ),
    ];

    for (name, algorithm) in algorithms {
        let optimizer = HybridOptimizer::new(algorithm.clone());
        println!("  {}: {:?}", name, optimizer.algorithm);
        println!("    Max iterations: {}", optimizer.max_iterations);
        println!("    Tolerance: {:.2e}", optimizer.tolerance);
        println!(
            "    Initial learning rate: {}",
            optimizer.learning_rate_schedule.initial_rate
        );
    }

    // Example 7: Learning rate schedules
    println!("\n7. Learning Rate Schedules");
    println!("--------------------------");

    let mut optimizer = HybridOptimizer::new(HybridOptimizationAlgorithm::SimultaneousOptimization);

    // Set up different schedules
    let schedules = vec![
        ("Constant", ScheduleType::Constant),
        ("Linear Decay", ScheduleType::LinearDecay),
        ("Exponential Decay", ScheduleType::ExponentialDecay),
        ("Step Decay", ScheduleType::StepDecay),
        ("Cosine Annealing", ScheduleType::CosineAnnealing),
    ];

    for (name, schedule_type) in schedules {
        optimizer.learning_rate_schedule.schedule_type = schedule_type.clone();
        println!("  {}: {:?}", name, schedule_type);
    }

    // Example 8: Parallelization configuration
    println!("\n8. Parallelization Configuration");
    println!("--------------------------------");

    optimizer.parallelization.quantum_parallelism = 4;
    optimizer.parallelization.classical_parallelism = 8;
    optimizer.parallelization.asynchronous = true;
    optimizer.parallelization.load_balancing = LoadBalancingStrategy::WorkStealing;

    println!(
        "Quantum parallelism: {} circuits",
        optimizer.parallelization.quantum_parallelism
    );
    println!(
        "Classical parallelism: {} threads",
        optimizer.parallelization.classical_parallelism
    );
    println!(
        "Asynchronous execution: {}",
        optimizer.parallelization.asynchronous
    );
    println!(
        "Load balancing: {:?}",
        optimizer.parallelization.load_balancing
    );

    // Example 9: Running optimization (mock)
    println!("\n9. Running Optimization");
    println!("-----------------------");

    println!("Starting hybrid optimization...");
    let result = optimizer.optimize(&mut problem)?;

    println!("Optimization completed:");
    println!("  Optimal value: {:.6}", result.optimal_value);
    println!("  Converged: {}", result.converged);
    println!("  Iterations: {}", result.iterations);
    println!("  Final parameters: {:?}", result.optimal_parameters);

    // Print some history information
    if !result.history.objective_values.is_empty() {
        println!("  Objective value history (first 5):");
        for (i, &value) in result.history.objective_values.iter().take(5).enumerate() {
            println!("    Iteration {}: {:.6}", i, value);
        }
    }

    if !result.history.gradient_norms.is_empty() {
        let final_gradient = result.history.gradient_norms.last().unwrap();
        println!("  Final gradient norm: {:.2e}", final_gradient);
    }

    // Example 10: Specific hybrid algorithm patterns
    println!("\n10. Common Hybrid Algorithm Patterns");
    println!("------------------------------------");

    // QAOA-like pattern
    println!("QAOA-like pattern:");
    println!("  1. Prepare initial state (quantum)");
    println!("  2. Apply parameterized unitaries (quantum)");
    println!("  3. Measure expectation values (quantum)");
    println!("  4. Classical optimization step (classical)");
    println!("  5. Repeat until convergence");

    // VQE with neural network pattern
    println!("\nVQE with Neural Network pattern:");
    println!("  1. Prepare ansatz circuit (quantum)");
    println!("  2. Measure Pauli expectations (quantum)");
    println!("  3. Neural network post-processing (classical)");
    println!("  4. Gradient-based parameter update (classical)");
    println!("  5. Repeat until convergence");

    // Quantum-enhanced ML pattern
    println!("\nQuantum-enhanced ML pattern:");
    println!("  1. Classical feature encoding (classical)");
    println!("  2. Quantum feature mapping (quantum)");
    println!("  3. Quantum measurements (quantum)");
    println!("  4. Classical ML inference (classical)");
    println!("  5. End-to-end gradient updates (hybrid)");

    // Example 11: Data types and flow
    println!("\n11. Data Types in Hybrid Algorithms");
    println!("-----------------------------------");

    let data_types = vec![
        (
            "Quantum measurements",
            "Raw measurement outcomes from quantum circuits",
        ),
        (
            "Probability distributions",
            "Estimated probability distributions from measurements",
        ),
        (
            "Classical matrices",
            "Processed data in matrix form for linear algebra",
        ),
        (
            "Scalar values",
            "Single numerical values like energies or costs",
        ),
        (
            "Parameter vectors",
            "Optimization parameters for both quantum and classical components",
        ),
        (
            "Control signals",
            "Boolean flags for adaptive algorithm control",
        ),
    ];

    for (dtype, description) in data_types {
        println!("  {}: {}", dtype, description);
    }

    println!("\n✅ Quantum-Classical Co-optimization Demo completed!");
    println!("\nNote: This demo shows the framework structure for hybrid optimization.");
    println!("Real co-optimization requires actual quantum and classical execution engines.");

    Ok(())
}

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

Apply a CNOT gate (alias for cnot)

Examples found in repository

examples/qasm_example.rs (line 32)

fn export_example() {
    println!("1. Exporting a circuit to OpenQASM 3.0");
    println!("--------------------------------------");

    // Create a quantum teleportation circuit
    let mut builder = CircuitBuilder::<3>::new();

    // Create Bell pair between Alice and Bob
    let _ = builder.h(Qubit::new(1));
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));

    // Alice's operations
    let _ = builder.cx(Qubit::new(0), Qubit::new(1));
    let _ = builder.h(Qubit::new(0));

    // Measurements (in real teleportation, these would be mid-circuit)
    let _ = builder.measure(Qubit::new(0));
    let _ = builder.measure(Qubit::new(1));

    // Bob's corrections (would be conditional in real circuit)
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));
    let _ = builder.cz(Qubit::new(0), Qubit::new(2));

    let circuit = builder.build();

    // Export with default options
    match export_qasm3(&circuit) {
        Ok(qasm) => {
            println!("Teleportation circuit in OpenQASM 3.0:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }

    // Export with custom options
    let options = ExportOptions {
        include_stdgates: true,
        decompose_custom: true,
        include_gate_comments: true,
        optimize: true,
        pretty_print: true,
    };

    let mut exporter = QasmExporter::new(options);
    match exporter.export(&circuit) {
        Ok(qasm) => {
            println!("\nWith custom options:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }
}

fn parse_example() {
    println!("\n2. Parsing OpenQASM 3.0 code");
    println!("----------------------------");

    let qasm_code = r#"
OPENQASM 3.0;
include "stdgates.inc";

// Quantum registers
qubit[5] q;
bit[5] c;

// Create W state
reset q;
ry(1.91063) q[0];  // arccos(1/sqrt(5))
cx q[0], q[1];

// Controlled rotations to distribute amplitude
cry(1.10715) q[1], q[2];  // arccos(1/2)
cx q[1], q[2];

cry(0.95532) q[2], q[3];  // arccos(1/sqrt(3))
cx q[2], q[3];

cry(pi/4) q[3], q[4];
cx q[3], q[4];

// Measure all qubits
measure q -> c;
"#;

    match parse_qasm3(qasm_code) {
        Ok(program) => {
            println!("Successfully parsed QASM program!");
            println!("Version: {}", program.version);
            println!("Includes: {:?}", program.includes);
            println!("Declarations: {} items", program.declarations.len());
            println!("Statements: {} operations", program.statements.len());

            // Pretty print the parsed program
            println!("\nReconstructed QASM:");
            println!("{}", program);
        }
        Err(e) => println!("Parse error: {}", e),
    }
}

fn validation_example() {
    println!("\n3. Validating QASM programs");
    println!("---------------------------");

    // Valid program
    let valid_qasm = r#"
OPENQASM 3.0;

gate mybell a, b {
    h a;
    cx a, b;
}

qubit[4] q;
bit[2] c;

mybell q[0], q[1];
mybell q[2], q[3];

measure q[0] -> c[0];
measure q[2] -> c[1];
"#;

    println!("Validating correct program...");
    match parse_qasm3(valid_qasm) {
        Ok(program) => match validate_qasm3(&program) {
            Ok(()) => println!("✓ Program is valid!"),
            Err(e) => println!("✗ Validation error: {}", e),
        },
        Err(e) => println!("Parse error: {}", e),
    }

    // Program with errors
    let invalid_qasm = r#"
OPENQASM 3.0;

qubit[2] q;
bit[2] c;

// Error: using undefined register
h r[0];

// Error: index out of bounds
cx q[0], q[5];

// Error: wrong number of parameters
rx q[0];  // Missing angle parameter
"#;

    println!("\nValidating program with errors...");
    match parse_qasm3(invalid_qasm) {
        Ok(program) => match validate_qasm3(&program) {
            Ok(()) => println!("Program is valid (unexpected!)"),
            Err(e) => println!("✓ Caught validation error: {}", e),
        },
        Err(e) => println!("Parse error: {}", e),
    }
}

fn round_trip_example() {
    println!("\n4. Round-trip conversion");
    println!("------------------------");

    // Create a variational circuit
    let mut builder = CircuitBuilder::<4>::new();

    // Layer 1: Single-qubit rotations
    for i in 0..4 {
        let _ = builder.ry(Qubit::new(i), 0.5);
        let _ = builder.rz(Qubit::new(i), 0.3);
    }

    // Layer 2: Entangling gates
    for i in 0..3 {
        let _ = builder.cx(Qubit::new(i), Qubit::new(i + 1));
    }
    let _ = builder.cx(Qubit::new(3), Qubit::new(0)); // Circular connectivity

    // Layer 3: More rotations
    for i in 0..4 {
        let _ = builder.rx(Qubit::new(i), -0.2);
    }

    // Measurements
    for i in 0..4 {
        let _ = builder.measure(Qubit::new(i));
    }

    let original = builder.build();

    println!(
        "Original circuit created with {} gates",
        original.gates().len()
    );

    // Export to QASM
    match export_qasm3(&original) {
        Ok(qasm) => {
            println!("\nExported QASM:");
            println!("{}", qasm);

            // Parse it back
            match parse_qasm3(&qasm) {
                Ok(program) => {
                    println!("\n✓ Successfully parsed the exported QASM!");

                    // Validate it
                    match validate_qasm3(&program) {
                        Ok(()) => println!("✓ Validation passed!"),
                        Err(e) => println!("✗ Validation error: {}", e),
                    }

                    // Count operations
                    let gate_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Gate(_))
                        })
                        .count();
                    let measure_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Measure(_))
                        })
                        .count();

                    println!("\nParsed circuit has:");
                    println!("  - {} gate operations", gate_count);
                    println!("  - {} measurements", measure_count);
                }
                Err(e) => println!("Parse error: {}", e),
            }
        }
        Err(e) => println!("Export error: {}", e),
    }
}

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)

Examples found in repository

examples/qasm_example.rs (line 44)

fn export_example() {
    println!("1. Exporting a circuit to OpenQASM 3.0");
    println!("--------------------------------------");

    // Create a quantum teleportation circuit
    let mut builder = CircuitBuilder::<3>::new();

    // Create Bell pair between Alice and Bob
    let _ = builder.h(Qubit::new(1));
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));

    // Alice's operations
    let _ = builder.cx(Qubit::new(0), Qubit::new(1));
    let _ = builder.h(Qubit::new(0));

    // Measurements (in real teleportation, these would be mid-circuit)
    let _ = builder.measure(Qubit::new(0));
    let _ = builder.measure(Qubit::new(1));

    // Bob's corrections (would be conditional in real circuit)
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));
    let _ = builder.cz(Qubit::new(0), Qubit::new(2));

    let circuit = builder.build();

    // Export with default options
    match export_qasm3(&circuit) {
        Ok(qasm) => {
            println!("Teleportation circuit in OpenQASM 3.0:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }

    // Export with custom options
    let options = ExportOptions {
        include_stdgates: true,
        decompose_custom: true,
        include_gate_comments: true,
        optimize: true,
        pretty_print: true,
    };

    let mut exporter = QasmExporter::new(options);
    match exporter.export(&circuit) {
        Ok(qasm) => {
            println!("\nWith custom options:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }
}

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

Examples found in repository

examples/optimization_demo.rs (line 57)

fn create_sample_circuit() -> Circuit<4> {
    // Create a circuit that has optimization opportunities
    let mut circuit = Circuit::<4>::new();

    // Add some gates with optimization opportunities
    // Pattern 1: Redundant gates (H-H = I, X-X = I)
    let _ = circuit.h(0);
    let _ = circuit.h(0);

    // Pattern 2: Commutable gates
    let _ = circuit.x(1);
    let _ = circuit.z(0);
    let _ = circuit.cnot(0, 1);

    // Pattern 3: Mergeable rotations
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);
    let _ = circuit.rz(2, std::f64::consts::PI / 4.0);

    // Pattern 4: Known patterns (H-X-H = Z)
    let _ = circuit.h(3);
    let _ = circuit.x(3);
    let _ = circuit.h(3);

    // Pattern 5: Decomposable gates
    let _ = circuit.toffoli(0, 1, 2);

    circuit
}

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 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.

Examples found in repository

examples/qasm_example.rs (line 39)

fn export_example() {
    println!("1. Exporting a circuit to OpenQASM 3.0");
    println!("--------------------------------------");

    // Create a quantum teleportation circuit
    let mut builder = CircuitBuilder::<3>::new();

    // Create Bell pair between Alice and Bob
    let _ = builder.h(Qubit::new(1));
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));

    // Alice's operations
    let _ = builder.cx(Qubit::new(0), Qubit::new(1));
    let _ = builder.h(Qubit::new(0));

    // Measurements (in real teleportation, these would be mid-circuit)
    let _ = builder.measure(Qubit::new(0));
    let _ = builder.measure(Qubit::new(1));

    // Bob's corrections (would be conditional in real circuit)
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));
    let _ = builder.cz(Qubit::new(0), Qubit::new(2));

    let circuit = builder.build();

    // Export with default options
    match export_qasm3(&circuit) {
        Ok(qasm) => {
            println!("Teleportation circuit in OpenQASM 3.0:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }

    // Export with custom options
    let options = ExportOptions {
        include_stdgates: true,
        decompose_custom: true,
        include_gate_comments: true,
        optimize: true,
        pretty_print: true,
    };

    let mut exporter = QasmExporter::new(options);
    match exporter.export(&circuit) {
        Ok(qasm) => {
            println!("\nWith custom options:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }
}

fn parse_example() {
    println!("\n2. Parsing OpenQASM 3.0 code");
    println!("----------------------------");

    let qasm_code = r#"
OPENQASM 3.0;
include "stdgates.inc";

// Quantum registers
qubit[5] q;
bit[5] c;

// Create W state
reset q;
ry(1.91063) q[0];  // arccos(1/sqrt(5))
cx q[0], q[1];

// Controlled rotations to distribute amplitude
cry(1.10715) q[1], q[2];  // arccos(1/2)
cx q[1], q[2];

cry(0.95532) q[2], q[3];  // arccos(1/sqrt(3))
cx q[2], q[3];

cry(pi/4) q[3], q[4];
cx q[3], q[4];

// Measure all qubits
measure q -> c;
"#;

    match parse_qasm3(qasm_code) {
        Ok(program) => {
            println!("Successfully parsed QASM program!");
            println!("Version: {}", program.version);
            println!("Includes: {:?}", program.includes);
            println!("Declarations: {} items", program.declarations.len());
            println!("Statements: {} operations", program.statements.len());

            // Pretty print the parsed program
            println!("\nReconstructed QASM:");
            println!("{}", program);
        }
        Err(e) => println!("Parse error: {}", e),
    }
}

fn validation_example() {
    println!("\n3. Validating QASM programs");
    println!("---------------------------");

    // Valid program
    let valid_qasm = r#"
OPENQASM 3.0;

gate mybell a, b {
    h a;
    cx a, b;
}

qubit[4] q;
bit[2] c;

mybell q[0], q[1];
mybell q[2], q[3];

measure q[0] -> c[0];
measure q[2] -> c[1];
"#;

    println!("Validating correct program...");
    match parse_qasm3(valid_qasm) {
        Ok(program) => match validate_qasm3(&program) {
            Ok(()) => println!("✓ Program is valid!"),
            Err(e) => println!("✗ Validation error: {}", e),
        },
        Err(e) => println!("Parse error: {}", e),
    }

    // Program with errors
    let invalid_qasm = r#"
OPENQASM 3.0;

qubit[2] q;
bit[2] c;

// Error: using undefined register
h r[0];

// Error: index out of bounds
cx q[0], q[5];

// Error: wrong number of parameters
rx q[0];  // Missing angle parameter
"#;

    println!("\nValidating program with errors...");
    match parse_qasm3(invalid_qasm) {
        Ok(program) => match validate_qasm3(&program) {
            Ok(()) => println!("Program is valid (unexpected!)"),
            Err(e) => println!("✓ Caught validation error: {}", e),
        },
        Err(e) => println!("Parse error: {}", e),
    }
}

fn round_trip_example() {
    println!("\n4. Round-trip conversion");
    println!("------------------------");

    // Create a variational circuit
    let mut builder = CircuitBuilder::<4>::new();

    // Layer 1: Single-qubit rotations
    for i in 0..4 {
        let _ = builder.ry(Qubit::new(i), 0.5);
        let _ = builder.rz(Qubit::new(i), 0.3);
    }

    // Layer 2: Entangling gates
    for i in 0..3 {
        let _ = builder.cx(Qubit::new(i), Qubit::new(i + 1));
    }
    let _ = builder.cx(Qubit::new(3), Qubit::new(0)); // Circular connectivity

    // Layer 3: More rotations
    for i in 0..4 {
        let _ = builder.rx(Qubit::new(i), -0.2);
    }

    // Measurements
    for i in 0..4 {
        let _ = builder.measure(Qubit::new(i));
    }

    let original = builder.build();

    println!(
        "Original circuit created with {} gates",
        original.gates().len()
    );

    // Export to QASM
    match export_qasm3(&original) {
        Ok(qasm) => {
            println!("\nExported QASM:");
            println!("{}", qasm);

            // Parse it back
            match parse_qasm3(&qasm) {
                Ok(program) => {
                    println!("\n✓ Successfully parsed the exported QASM!");

                    // Validate it
                    match validate_qasm3(&program) {
                        Ok(()) => println!("✓ Validation passed!"),
                        Err(e) => println!("✗ Validation error: {}", e),
                    }

                    // Count operations
                    let gate_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Gate(_))
                        })
                        .count();
                    let measure_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Measure(_))
                        })
                        .count();

                    println!("\nParsed circuit has:");
                    println!("  - {} gate operations", gate_count);
                    println!("  - {} measurements", measure_count);
                }
                Err(e) => println!("Parse error: {}", e),
            }
        }
        Err(e) => println!("Export error: {}", e),
    }
}

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 fn build(self) -> Self

Build the circuit (for compatibility - returns self)

Examples found in repository

examples/qasm_example.rs (line 46)

fn export_example() {
    println!("1. Exporting a circuit to OpenQASM 3.0");
    println!("--------------------------------------");

    // Create a quantum teleportation circuit
    let mut builder = CircuitBuilder::<3>::new();

    // Create Bell pair between Alice and Bob
    let _ = builder.h(Qubit::new(1));
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));

    // Alice's operations
    let _ = builder.cx(Qubit::new(0), Qubit::new(1));
    let _ = builder.h(Qubit::new(0));

    // Measurements (in real teleportation, these would be mid-circuit)
    let _ = builder.measure(Qubit::new(0));
    let _ = builder.measure(Qubit::new(1));

    // Bob's corrections (would be conditional in real circuit)
    let _ = builder.cx(Qubit::new(1), Qubit::new(2));
    let _ = builder.cz(Qubit::new(0), Qubit::new(2));

    let circuit = builder.build();

    // Export with default options
    match export_qasm3(&circuit) {
        Ok(qasm) => {
            println!("Teleportation circuit in OpenQASM 3.0:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }

    // Export with custom options
    let options = ExportOptions {
        include_stdgates: true,
        decompose_custom: true,
        include_gate_comments: true,
        optimize: true,
        pretty_print: true,
    };

    let mut exporter = QasmExporter::new(options);
    match exporter.export(&circuit) {
        Ok(qasm) => {
            println!("\nWith custom options:");
            println!("{}", qasm);
        }
        Err(e) => println!("Export error: {}", e),
    }
}

fn parse_example() {
    println!("\n2. Parsing OpenQASM 3.0 code");
    println!("----------------------------");

    let qasm_code = r#"
OPENQASM 3.0;
include "stdgates.inc";

// Quantum registers
qubit[5] q;
bit[5] c;

// Create W state
reset q;
ry(1.91063) q[0];  // arccos(1/sqrt(5))
cx q[0], q[1];

// Controlled rotations to distribute amplitude
cry(1.10715) q[1], q[2];  // arccos(1/2)
cx q[1], q[2];

cry(0.95532) q[2], q[3];  // arccos(1/sqrt(3))
cx q[2], q[3];

cry(pi/4) q[3], q[4];
cx q[3], q[4];

// Measure all qubits
measure q -> c;
"#;

    match parse_qasm3(qasm_code) {
        Ok(program) => {
            println!("Successfully parsed QASM program!");
            println!("Version: {}", program.version);
            println!("Includes: {:?}", program.includes);
            println!("Declarations: {} items", program.declarations.len());
            println!("Statements: {} operations", program.statements.len());

            // Pretty print the parsed program
            println!("\nReconstructed QASM:");
            println!("{}", program);
        }
        Err(e) => println!("Parse error: {}", e),
    }
}

fn validation_example() {
    println!("\n3. Validating QASM programs");
    println!("---------------------------");

    // Valid program
    let valid_qasm = r#"
OPENQASM 3.0;

gate mybell a, b {
    h a;
    cx a, b;
}

qubit[4] q;
bit[2] c;

mybell q[0], q[1];
mybell q[2], q[3];

measure q[0] -> c[0];
measure q[2] -> c[1];
"#;

    println!("Validating correct program...");
    match parse_qasm3(valid_qasm) {
        Ok(program) => match validate_qasm3(&program) {
            Ok(()) => println!("✓ Program is valid!"),
            Err(e) => println!("✗ Validation error: {}", e),
        },
        Err(e) => println!("Parse error: {}", e),
    }

    // Program with errors
    let invalid_qasm = r#"
OPENQASM 3.0;

qubit[2] q;
bit[2] c;

// Error: using undefined register
h r[0];

// Error: index out of bounds
cx q[0], q[5];

// Error: wrong number of parameters
rx q[0];  // Missing angle parameter
"#;

    println!("\nValidating program with errors...");
    match parse_qasm3(invalid_qasm) {
        Ok(program) => match validate_qasm3(&program) {
            Ok(()) => println!("Program is valid (unexpected!)"),
            Err(e) => println!("✓ Caught validation error: {}", e),
        },
        Err(e) => println!("Parse error: {}", e),
    }
}

fn round_trip_example() {
    println!("\n4. Round-trip conversion");
    println!("------------------------");

    // Create a variational circuit
    let mut builder = CircuitBuilder::<4>::new();

    // Layer 1: Single-qubit rotations
    for i in 0..4 {
        let _ = builder.ry(Qubit::new(i), 0.5);
        let _ = builder.rz(Qubit::new(i), 0.3);
    }

    // Layer 2: Entangling gates
    for i in 0..3 {
        let _ = builder.cx(Qubit::new(i), Qubit::new(i + 1));
    }
    let _ = builder.cx(Qubit::new(3), Qubit::new(0)); // Circular connectivity

    // Layer 3: More rotations
    for i in 0..4 {
        let _ = builder.rx(Qubit::new(i), -0.2);
    }

    // Measurements
    for i in 0..4 {
        let _ = builder.measure(Qubit::new(i));
    }

    let original = builder.build();

    println!(
        "Original circuit created with {} gates",
        original.gates().len()
    );

    // Export to QASM
    match export_qasm3(&original) {
        Ok(qasm) => {
            println!("\nExported QASM:");
            println!("{}", qasm);

            // Parse it back
            match parse_qasm3(&qasm) {
                Ok(program) => {
                    println!("\n✓ Successfully parsed the exported QASM!");

                    // Validate it
                    match validate_qasm3(&program) {
                        Ok(()) => println!("✓ Validation passed!"),
                        Err(e) => println!("✗ Validation error: {}", e),
                    }

                    // Count operations
                    let gate_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Gate(_))
                        })
                        .count();
                    let measure_count = program
                        .statements
                        .iter()
                        .filter(|s| {
                            matches!(s, quantrs2_circuit::qasm::ast::QasmStatement::Measure(_))
                        })
                        .count();

                    println!("\nParsed circuit has:");
                    println!("  - {} gate operations", gate_count);
                    println!("  - {} measurements", measure_count);
                }
                Err(e) => println!("Parse error: {}", e),
            }
        }
        Err(e) => println!("Export error: {}", e),
    }
}

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

Examples found in repository

examples/classical_control_demo.rs (line 59)

fn quantum_teleportation() -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 2: Quantum Teleportation");
    println!("--------------------------------");

    // Create Bell pair between qubits 1 and 2
    let mut circuit = Circuit::<3>::new();
    circuit.h(1)?;
    circuit.cnot(1, 2)?;

    // Convert to classical circuit for measurements
    let mut classical_circuit = circuit.with_classical_control();
    classical_circuit.add_classical_register("alice", 2)?;

    // Alice's operations
    classical_circuit.add_gate(quantrs2_core::gate::multi::CNOT {
        control: QubitId(0),
        target: QubitId(1),
    })?;
    classical_circuit.add_gate(Hadamard { target: QubitId(0) })?;

    // Alice measures her qubits
    classical_circuit.measure(QubitId(0), "alice", 0)?;
    classical_circuit.measure(QubitId(1), "alice", 1)?;

    // Bob applies corrections based on Alice's measurements
    classical_circuit.add_conditional(
        ClassicalCondition {
            lhs: ClassicalValue::Register("alice".to_string()),
            op: ComparisonOp::Equal,
            rhs: ClassicalValue::Integer(0b01),
        },
        PauliX { target: QubitId(2) },
    )?;

    classical_circuit.add_conditional(
        ClassicalCondition {
            lhs: ClassicalValue::Register("alice".to_string()),
            op: ComparisonOp::Equal,
            rhs: ClassicalValue::Integer(0b10),
        },
        PauliZ { target: QubitId(2) },
    )?;

    classical_circuit.add_conditional(
        ClassicalCondition {
            lhs: ClassicalValue::Register("alice".to_string()),
            op: ComparisonOp::Equal,
            rhs: ClassicalValue::Integer(0b11),
        },
        PauliX { target: QubitId(2) }, // In reality, this would be X then Z
    )?;

    println!(
        "Created teleportation circuit with {} operations",
        classical_circuit.num_operations()
    );
    println!("Bob's qubit 2 receives the state that was on Alice's qubit 0\n");

    Ok(())
}

/// Adaptive phase estimation using conditional rotations
fn adaptive_phase_estimation() -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 3: Adaptive Phase Estimation");
    println!("-----------------------------------");

    let circuit = ClassicalCircuitBuilder::<4>::new()
        .classical_register("phase_bits", 3)?
        // First estimation round
        .gate(Hadamard { target: QubitId(0) })?
        .gate(quantrs2_core::gate::multi::CRZ {
            control: QubitId(0),
            target: QubitId(3),
            theta: std::f64::consts::PI,
        })?
        .gate(Hadamard { target: QubitId(0) })?
        .measure(QubitId(0), "phase_bits", 0)?
        // Second round (adaptive based on first measurement)
        .gate(Hadamard { target: QubitId(1) })?
        .conditional(
            ClassicalCondition::register_equals("phase_bits", 1),
            quantrs2_core::gate::single::Phase { target: QubitId(1) }
        )?
        .gate(quantrs2_core::gate::multi::CRZ {
            control: QubitId(1),
            target: QubitId(3),
            theta: std::f64::consts::PI / 2.0,
        })?
        .gate(Hadamard { target: QubitId(1) })?
        .measure(QubitId(1), "phase_bits", 1)?
        // Third round (adaptive based on previous measurements)
        .gate(Hadamard { target: QubitId(2) })?
        // Apply phase corrections based on previous measurements
        .conditional(
            ClassicalCondition {
                lhs: ClassicalValue::Register("phase_bits".to_string()),
                op: ComparisonOp::GreaterEqual,
                rhs: ClassicalValue::Integer(1),
            },
            quantrs2_core::gate::single::RotationZ {
                target: QubitId(2),
                theta: -std::f64::consts::PI / 4.0,
            }
        )?
        .gate(quantrs2_core::gate::multi::CRZ {
            control: QubitId(2),
            target: QubitId(3),
            theta: std::f64::consts::PI / 4.0,
        })?
        .gate(Hadamard { target: QubitId(2) })?
        .measure(QubitId(2), "phase_bits", 2)?
        .build();

    println!(
        "Created adaptive phase estimation circuit with {} operations",
        circuit.num_operations()
    );
    println!("The circuit adaptively estimates the phase using 3 rounds of measurement\n");

    // Demonstrate builder pattern
    println!("Alternative: Using standard circuit with conversion");
    let mut standard_circuit = Circuit::<4>::new();
    standard_circuit.h(0)?;
    standard_circuit.h(1)?;
    standard_circuit.h(2)?;

    let classical = standard_circuit.with_classical_control();
    println!("Converted standard circuit to classical control\n");

    Ok(())
}

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.