quantrs2_sim/

gpu_kernel_optimization.rs

//! GPU Kernel Optimization for Specialized Quantum Operations
//!
//! This module provides highly optimized GPU kernels for quantum simulation,
//! including specialized implementations for common gates, fused operations,
//! and memory-optimized algorithms for large state vectors.
//!
//! # Features
//! - Specialized kernels for common gates (H, X, Y, Z, CNOT, CZ, etc.)
//! - Fused gate sequences for reduced memory bandwidth
//! - Memory-coalesced access patterns for GPU efficiency
//! - Warp-level optimizations for NVIDIA GPUs
//! - Shared memory utilization for reduced global memory access
//! - Streaming execution for overlapped computation and data transfer

use quantrs2_core::error::{QuantRS2Error, QuantRS2Result};
use scirs2_core::ndarray::{Array1, Array2};
use scirs2_core::Complex64;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::sync::{Arc, Mutex, RwLock};
use std::time::{Duration, Instant};

/// GPU kernel optimization framework for quantum simulation
#[derive(Debug)]
pub struct GPUKernelOptimizer {
    /// Kernel registry for specialized operations
    kernel_registry: KernelRegistry,
    /// Kernel execution statistics
    stats: Arc<Mutex<KernelStats>>,
    /// Configuration
    config: GPUKernelConfig,
    /// Kernel cache for compiled kernels
    kernel_cache: Arc<RwLock<HashMap<String, CompiledKernel>>>,
    /// Memory layout optimizer
    memory_optimizer: MemoryLayoutOptimizer,
}

/// Configuration for GPU kernel optimization
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GPUKernelConfig {
    /// Enable warp-level optimizations
    pub enable_warp_optimization: bool,
    /// Enable shared memory usage
    pub enable_shared_memory: bool,
    /// Block size for GPU execution
    pub block_size: usize,
    /// Grid size calculation method
    pub grid_size_method: GridSizeMethod,
    /// Enable kernel fusion
    pub enable_kernel_fusion: bool,
    /// Maximum fused kernel length
    pub max_fusion_length: usize,
    /// Enable memory coalescing optimization
    pub enable_memory_coalescing: bool,
    /// Enable streaming execution
    pub enable_streaming: bool,
    /// Number of streams for concurrent execution
    pub num_streams: usize,
    /// Occupancy optimization target
    pub target_occupancy: f64,
}

impl Default for GPUKernelConfig {
    fn default() -> Self {
        Self {
            enable_warp_optimization: true,
            enable_shared_memory: true,
            block_size: 256,
            grid_size_method: GridSizeMethod::Automatic,
            enable_kernel_fusion: true,
            max_fusion_length: 8,
            enable_memory_coalescing: true,
            enable_streaming: true,
            num_streams: 4,
            target_occupancy: 0.75,
        }
    }
}

/// Method for calculating grid size
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum GridSizeMethod {
    /// Automatic calculation based on problem size
    Automatic,
    /// Fixed grid size
    Fixed(usize),
    /// Occupancy-based calculation
    OccupancyBased,
}

/// Registry of specialized GPU kernels
#[derive(Debug)]
pub struct KernelRegistry {
    /// Single-qubit gate kernels
    single_qubit_kernels: HashMap<String, SingleQubitKernel>,
    /// Two-qubit gate kernels
    two_qubit_kernels: HashMap<String, TwoQubitKernel>,
    /// Fused kernel templates
    fused_kernels: HashMap<String, FusedKernel>,
    /// Custom kernel implementations
    custom_kernels: HashMap<String, CustomKernel>,
}

impl Default for KernelRegistry {
    fn default() -> Self {
        let mut registry = Self {
            single_qubit_kernels: HashMap::new(),
            two_qubit_kernels: HashMap::new(),
            fused_kernels: HashMap::new(),
            custom_kernels: HashMap::new(),
        };
        registry.register_builtin_kernels();
        registry
    }
}

impl KernelRegistry {
    /// Register all built-in optimized kernels
    fn register_builtin_kernels(&mut self) {
        // Single-qubit gate kernels
        self.single_qubit_kernels.insert(
            "hadamard".to_string(),
            SingleQubitKernel {
                name: "hadamard".to_string(),
                kernel_type: SingleQubitKernelType::Hadamard,
                optimization_level: OptimizationLevel::Maximum,
                uses_shared_memory: true,
                register_usage: 32,
            },
        );

        self.single_qubit_kernels.insert(
            "pauli_x".to_string(),
            SingleQubitKernel {
                name: "pauli_x".to_string(),
                kernel_type: SingleQubitKernelType::PauliX,
                optimization_level: OptimizationLevel::Maximum,
                uses_shared_memory: false, // Simple swap operation
                register_usage: 16,
            },
        );

        self.single_qubit_kernels.insert(
            "pauli_y".to_string(),
            SingleQubitKernel {
                name: "pauli_y".to_string(),
                kernel_type: SingleQubitKernelType::PauliY,
                optimization_level: OptimizationLevel::Maximum,
                uses_shared_memory: false,
                register_usage: 24,
            },
        );

        self.single_qubit_kernels.insert(
            "pauli_z".to_string(),
            SingleQubitKernel {
                name: "pauli_z".to_string(),
                kernel_type: SingleQubitKernelType::PauliZ,
                optimization_level: OptimizationLevel::Maximum,
                uses_shared_memory: false,
                register_usage: 16,
            },
        );

        self.single_qubit_kernels.insert(
            "phase".to_string(),
            SingleQubitKernel {
                name: "phase".to_string(),
                kernel_type: SingleQubitKernelType::Phase,
                optimization_level: OptimizationLevel::High,
                uses_shared_memory: false,
                register_usage: 24,
            },
        );

        self.single_qubit_kernels.insert(
            "t_gate".to_string(),
            SingleQubitKernel {
                name: "t_gate".to_string(),
                kernel_type: SingleQubitKernelType::TGate,
                optimization_level: OptimizationLevel::High,
                uses_shared_memory: false,
                register_usage: 24,
            },
        );

        self.single_qubit_kernels.insert(
            "rotation_x".to_string(),
            SingleQubitKernel {
                name: "rotation_x".to_string(),
                kernel_type: SingleQubitKernelType::RotationX,
                optimization_level: OptimizationLevel::Medium,
                uses_shared_memory: true,
                register_usage: 40,
            },
        );

        self.single_qubit_kernels.insert(
            "rotation_y".to_string(),
            SingleQubitKernel {
                name: "rotation_y".to_string(),
                kernel_type: SingleQubitKernelType::RotationY,
                optimization_level: OptimizationLevel::Medium,
                uses_shared_memory: true,
                register_usage: 40,
            },
        );

        self.single_qubit_kernels.insert(
            "rotation_z".to_string(),
            SingleQubitKernel {
                name: "rotation_z".to_string(),
                kernel_type: SingleQubitKernelType::RotationZ,
                optimization_level: OptimizationLevel::Medium,
                uses_shared_memory: true,
                register_usage: 32,
            },
        );

        // Two-qubit gate kernels
        self.two_qubit_kernels.insert(
            "cnot".to_string(),
            TwoQubitKernel {
                name: "cnot".to_string(),
                kernel_type: TwoQubitKernelType::CNOT,
                optimization_level: OptimizationLevel::Maximum,
                uses_shared_memory: true,
                register_usage: 48,
                memory_access_pattern: MemoryAccessPattern::Strided,
            },
        );

        self.two_qubit_kernels.insert(
            "cz".to_string(),
            TwoQubitKernel {
                name: "cz".to_string(),
                kernel_type: TwoQubitKernelType::CZ,
                optimization_level: OptimizationLevel::Maximum,
                uses_shared_memory: false,
                register_usage: 32,
                memory_access_pattern: MemoryAccessPattern::Sparse,
            },
        );

        self.two_qubit_kernels.insert(
            "swap".to_string(),
            TwoQubitKernel {
                name: "swap".to_string(),
                kernel_type: TwoQubitKernelType::SWAP,
                optimization_level: OptimizationLevel::High,
                uses_shared_memory: true,
                register_usage: 40,
                memory_access_pattern: MemoryAccessPattern::Strided,
            },
        );

        self.two_qubit_kernels.insert(
            "iswap".to_string(),
            TwoQubitKernel {
                name: "iswap".to_string(),
                kernel_type: TwoQubitKernelType::ISWAP,
                optimization_level: OptimizationLevel::High,
                uses_shared_memory: true,
                register_usage: 48,
                memory_access_pattern: MemoryAccessPattern::Strided,
            },
        );

        self.two_qubit_kernels.insert(
            "controlled_rotation".to_string(),
            TwoQubitKernel {
                name: "controlled_rotation".to_string(),
                kernel_type: TwoQubitKernelType::ControlledRotation,
                optimization_level: OptimizationLevel::Medium,
                uses_shared_memory: true,
                register_usage: 56,
                memory_access_pattern: MemoryAccessPattern::Strided,
            },
        );

        // Fused kernel templates
        self.fused_kernels.insert(
            "h_cnot_h".to_string(),
            FusedKernel {
                name: "h_cnot_h".to_string(),
                sequence: vec![
                    "hadamard".to_string(),
                    "cnot".to_string(),
                    "hadamard".to_string(),
                ],
                optimization_gain: 2.5,
                register_usage: 64,
            },
        );

        self.fused_kernels.insert(
            "rotation_chain".to_string(),
            FusedKernel {
                name: "rotation_chain".to_string(),
                sequence: vec![
                    "rotation_x".to_string(),
                    "rotation_y".to_string(),
                    "rotation_z".to_string(),
                ],
                optimization_gain: 2.0,
                register_usage: 56,
            },
        );

        self.fused_kernels.insert(
            "bell_state".to_string(),
            FusedKernel {
                name: "bell_state".to_string(),
                sequence: vec!["hadamard".to_string(), "cnot".to_string()],
                optimization_gain: 1.8,
                register_usage: 48,
            },
        );
    }
}

/// Single-qubit kernel implementation
#[derive(Debug, Clone)]
pub struct SingleQubitKernel {
    /// Kernel name
    pub name: String,
    /// Kernel type
    pub kernel_type: SingleQubitKernelType,
    /// Optimization level
    pub optimization_level: OptimizationLevel,
    /// Uses shared memory
    pub uses_shared_memory: bool,
    /// Register usage
    pub register_usage: usize,
}

/// Types of single-qubit kernels
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SingleQubitKernelType {
    Hadamard,
    PauliX,
    PauliY,
    PauliZ,
    Phase,
    TGate,
    RotationX,
    RotationY,
    RotationZ,
    Generic,
}

/// Two-qubit kernel implementation
#[derive(Debug, Clone)]
pub struct TwoQubitKernel {
    /// Kernel name
    pub name: String,
    /// Kernel type
    pub kernel_type: TwoQubitKernelType,
    /// Optimization level
    pub optimization_level: OptimizationLevel,
    /// Uses shared memory
    pub uses_shared_memory: bool,
    /// Register usage
    pub register_usage: usize,
    /// Memory access pattern
    pub memory_access_pattern: MemoryAccessPattern,
}

/// Types of two-qubit kernels
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TwoQubitKernelType {
    CNOT,
    CZ,
    SWAP,
    ISWAP,
    ControlledRotation,
    Generic,
}

/// Memory access patterns for kernels
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemoryAccessPattern {
    /// Coalesced access
    Coalesced,
    /// Strided access
    Strided,
    /// Sparse access
    Sparse,
    /// Random access
    Random,
}

/// Fused kernel for multiple operations
#[derive(Debug, Clone)]
pub struct FusedKernel {
    /// Kernel name
    pub name: String,
    /// Sequence of operations
    pub sequence: Vec<String>,
    /// Expected optimization gain
    pub optimization_gain: f64,
    /// Register usage
    pub register_usage: usize,
}

/// Custom kernel implementation
#[derive(Debug, Clone)]
pub struct CustomKernel {
    /// Kernel name
    pub name: String,
    /// Kernel code (CUDA/OpenCL)
    pub code: String,
    /// Register usage
    pub register_usage: usize,
}

/// Compiled kernel ready for execution
#[derive(Debug, Clone)]
pub struct CompiledKernel {
    /// Kernel name
    pub name: String,
    /// Compiled code (binary or PTX)
    pub compiled_code: Vec<u8>,
    /// Execution parameters
    pub exec_params: KernelExecParams,
}

/// Kernel execution parameters
#[derive(Debug, Clone)]
pub struct KernelExecParams {
    /// Block dimensions
    pub block_dim: (usize, usize, usize),
    /// Grid dimensions
    pub grid_dim: (usize, usize, usize),
    /// Shared memory size
    pub shared_memory_size: usize,
    /// Maximum threads per block
    pub max_threads_per_block: usize,
}

/// Optimization levels for kernels
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OptimizationLevel {
    /// Basic optimization
    Basic,
    /// Medium optimization
    Medium,
    /// High optimization
    High,
    /// Maximum optimization
    Maximum,
}

/// Kernel execution statistics
#[derive(Debug, Clone, Default)]
pub struct KernelStats {
    /// Total kernel executions
    pub total_executions: u64,
    /// Total execution time
    pub total_execution_time: Duration,
    /// Kernel execution counts by name
    pub execution_counts: HashMap<String, u64>,
    /// Kernel execution times by name
    pub execution_times: HashMap<String, Duration>,
    /// Cache hits
    pub cache_hits: u64,
    /// Cache misses
    pub cache_misses: u64,
    /// Fused operations count
    pub fused_operations: u64,
    /// Memory bandwidth utilized (GB/s)
    pub memory_bandwidth: f64,
    /// Compute throughput (GFLOPS)
    pub compute_throughput: f64,
}

/// Memory layout optimizer for GPU operations
#[derive(Debug)]
pub struct MemoryLayoutOptimizer {
    /// Layout strategy
    strategy: MemoryLayoutStrategy,
    /// Prefetch distance
    prefetch_distance: usize,
}

/// Memory layout strategies
#[derive(Debug, Clone, Copy)]
pub enum MemoryLayoutStrategy {
    /// Interleaved complex numbers (Re, Im, Re, Im, ...)
    Interleaved,
    /// Split arrays (all Re, then all Im)
    SplitArrays,
    /// Structure of arrays
    StructureOfArrays,
    /// Array of structures
    ArrayOfStructures,
}

impl Default for MemoryLayoutOptimizer {
    fn default() -> Self {
        Self {
            strategy: MemoryLayoutStrategy::Interleaved,
            prefetch_distance: 4,
        }
    }
}

impl GPUKernelOptimizer {
    /// Create a new GPU kernel optimizer
    #[must_use]
    pub fn new(config: GPUKernelConfig) -> Self {
        Self {
            kernel_registry: KernelRegistry::default(),
            stats: Arc::new(Mutex::new(KernelStats::default())),
            config,
            kernel_cache: Arc::new(RwLock::new(HashMap::new())),
            memory_optimizer: MemoryLayoutOptimizer::default(),
        }
    }

    /// Apply optimized single-qubit gate
    pub fn apply_single_qubit_gate(
        &mut self,
        state: &mut Array1<Complex64>,
        qubit: usize,
        gate_name: &str,
        parameters: Option<&[f64]>,
    ) -> QuantRS2Result<()> {
        let start = Instant::now();

        // Get kernel from registry
        let kernel = self.kernel_registry.single_qubit_kernels.get(gate_name);

        let n = state.len();
        let stride = 1 << qubit;

        match kernel {
            Some(k) => {
                // Apply optimized kernel
                match k.kernel_type {
                    SingleQubitKernelType::Hadamard => {
                        self.apply_hadamard_optimized(state, stride)?;
                    }
                    SingleQubitKernelType::PauliX => {
                        self.apply_pauli_x_optimized(state, stride)?;
                    }
                    SingleQubitKernelType::PauliY => {
                        self.apply_pauli_y_optimized(state, stride)?;
                    }
                    SingleQubitKernelType::PauliZ => {
                        self.apply_pauli_z_optimized(state, stride)?;
                    }
                    SingleQubitKernelType::Phase => {
                        self.apply_phase_optimized(state, stride)?;
                    }
                    SingleQubitKernelType::TGate => {
                        self.apply_t_gate_optimized(state, stride)?;
                    }
                    SingleQubitKernelType::RotationX => {
                        let angle = parameters.and_then(|p| p.first()).copied().unwrap_or(0.0);
                        self.apply_rotation_x_optimized(state, stride, angle)?;
                    }
                    SingleQubitKernelType::RotationY => {
                        let angle = parameters.and_then(|p| p.first()).copied().unwrap_or(0.0);
                        self.apply_rotation_y_optimized(state, stride, angle)?;
                    }
                    SingleQubitKernelType::RotationZ => {
                        let angle = parameters.and_then(|p| p.first()).copied().unwrap_or(0.0);
                        self.apply_rotation_z_optimized(state, stride, angle)?;
                    }
                    SingleQubitKernelType::Generic => {
                        // Fallback to generic implementation
                        self.apply_generic_single_qubit(state, qubit, gate_name, parameters)?;
                    }
                }
            }
            None => {
                // Use generic implementation
                self.apply_generic_single_qubit(state, qubit, gate_name, parameters)?;
            }
        }

        // Update statistics
        let mut stats = self
            .stats
            .lock()
            .map_err(|_| QuantRS2Error::InvalidInput("Failed to acquire stats lock".to_string()))?;
        stats.total_executions += 1;
        stats.total_execution_time += start.elapsed();
        *stats
            .execution_counts
            .entry(gate_name.to_string())
            .or_insert(0) += 1;
        *stats
            .execution_times
            .entry(gate_name.to_string())
            .or_insert(Duration::ZERO) += start.elapsed();

        Ok(())
    }

    /// Apply optimized Hadamard gate
    fn apply_hadamard_optimized(
        &self,
        state: &mut Array1<Complex64>,
        stride: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let inv_sqrt2 = 1.0 / 2.0_f64.sqrt();

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        // Process pairs with memory coalescing
        for i in 0..n / 2 {
            let i0 = (i / stride) * (2 * stride) + (i % stride);
            let i1 = i0 + stride;

            let a0 = amplitudes[i0];
            let a1 = amplitudes[i1];

            amplitudes[i0] =
                Complex64::new((a0.re + a1.re) * inv_sqrt2, (a0.im + a1.im) * inv_sqrt2);
            amplitudes[i1] =
                Complex64::new((a0.re - a1.re) * inv_sqrt2, (a0.im - a1.im) * inv_sqrt2);
        }

        Ok(())
    }

    /// Apply optimized Pauli-X gate
    fn apply_pauli_x_optimized(
        &self,
        state: &mut Array1<Complex64>,
        stride: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        // Simple swap operation - highly optimized
        for i in 0..n / 2 {
            let i0 = (i / stride) * (2 * stride) + (i % stride);
            let i1 = i0 + stride;

            amplitudes.swap(i0, i1);
        }

        Ok(())
    }

    /// Apply optimized Pauli-Y gate
    fn apply_pauli_y_optimized(
        &self,
        state: &mut Array1<Complex64>,
        stride: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        for i in 0..n / 2 {
            let i0 = (i / stride) * (2 * stride) + (i % stride);
            let i1 = i0 + stride;

            let a0 = amplitudes[i0];
            let a1 = amplitudes[i1];

            // Y gate: [[0, -i], [i, 0]]
            amplitudes[i0] = Complex64::new(a1.im, -a1.re);
            amplitudes[i1] = Complex64::new(-a0.im, a0.re);
        }

        Ok(())
    }

    /// Apply optimized Pauli-Z gate
    fn apply_pauli_z_optimized(
        &self,
        state: &mut Array1<Complex64>,
        stride: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        // Z gate only affects |1> states
        for i in 0..n / 2 {
            let i1 = (i / stride) * (2 * stride) + (i % stride) + stride;
            amplitudes[i1] = -amplitudes[i1];
        }

        Ok(())
    }

    /// Apply optimized Phase gate
    fn apply_phase_optimized(
        &self,
        state: &mut Array1<Complex64>,
        stride: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        // S gate: phase shift of pi/2 on |1>
        for i in 0..n / 2 {
            let i1 = (i / stride) * (2 * stride) + (i % stride) + stride;
            let a = amplitudes[i1];
            amplitudes[i1] = Complex64::new(-a.im, a.re); // multiply by i
        }

        Ok(())
    }

    /// Apply optimized T gate
    fn apply_t_gate_optimized(
        &self,
        state: &mut Array1<Complex64>,
        stride: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let t_phase = Complex64::new(
            std::f64::consts::FRAC_1_SQRT_2,
            std::f64::consts::FRAC_1_SQRT_2,
        );

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        // T gate: phase shift of pi/4 on |1>
        for i in 0..n / 2 {
            let i1 = (i / stride) * (2 * stride) + (i % stride) + stride;
            amplitudes[i1] *= t_phase;
        }

        Ok(())
    }

    /// Apply optimized rotation around X axis
    fn apply_rotation_x_optimized(
        &self,
        state: &mut Array1<Complex64>,
        stride: usize,
        angle: f64,
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let cos_half = (angle / 2.0).cos();
        let sin_half = (angle / 2.0).sin();

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        for i in 0..n / 2 {
            let i0 = (i / stride) * (2 * stride) + (i % stride);
            let i1 = i0 + stride;

            let a0 = amplitudes[i0];
            let a1 = amplitudes[i1];

            // RX(θ) = [[cos(θ/2), -i*sin(θ/2)], [-i*sin(θ/2), cos(θ/2)]]
            amplitudes[i0] = Complex64::new(
                cos_half * a0.re + sin_half * a1.im,
                cos_half * a0.im - sin_half * a1.re,
            );
            amplitudes[i1] = Complex64::new(
                sin_half * a0.im + cos_half * a1.re,
                (-sin_half).mul_add(a0.re, cos_half * a1.im),
            );
        }

        Ok(())
    }

    /// Apply optimized rotation around Y axis
    fn apply_rotation_y_optimized(
        &self,
        state: &mut Array1<Complex64>,
        stride: usize,
        angle: f64,
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let cos_half = (angle / 2.0).cos();
        let sin_half = (angle / 2.0).sin();

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        for i in 0..n / 2 {
            let i0 = (i / stride) * (2 * stride) + (i % stride);
            let i1 = i0 + stride;

            let a0 = amplitudes[i0];
            let a1 = amplitudes[i1];

            // RY(θ) = [[cos(θ/2), -sin(θ/2)], [sin(θ/2), cos(θ/2)]]
            amplitudes[i0] = Complex64::new(
                cos_half * a0.re - sin_half * a1.re,
                cos_half * a0.im - sin_half * a1.im,
            );
            amplitudes[i1] = Complex64::new(
                sin_half * a0.re + cos_half * a1.re,
                sin_half * a0.im + cos_half * a1.im,
            );
        }

        Ok(())
    }

    /// Apply optimized rotation around Z axis
    fn apply_rotation_z_optimized(
        &self,
        state: &mut Array1<Complex64>,
        stride: usize,
        angle: f64,
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let exp_neg = Complex64::new((angle / 2.0).cos(), -(angle / 2.0).sin());
        let exp_pos = Complex64::new((angle / 2.0).cos(), (angle / 2.0).sin());

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        for i in 0..n / 2 {
            let i0 = (i / stride) * (2 * stride) + (i % stride);
            let i1 = i0 + stride;

            // RZ(θ) = [[e^(-iθ/2), 0], [0, e^(iθ/2)]]
            amplitudes[i0] *= exp_neg;
            amplitudes[i1] *= exp_pos;
        }

        Ok(())
    }

    /// Generic single-qubit gate application.
    ///
    /// Used for any single-qubit gate that does not have a hand-optimized
    /// kernel above (S†/T†/identity/√X/phase-family gates). Builds the
    /// gate's real 2x2 unitary from its name (and, for phase-family gates,
    /// its angle parameter) and applies it with the same strided
    /// amplitude-pair update the specialized kernels use -- it never
    /// silently leaves the state unchanged. A gate name this function
    /// cannot resolve to a real matrix is an honest error, not a no-op.
    fn apply_generic_single_qubit(
        &self,
        state: &mut Array1<Complex64>,
        qubit: usize,
        gate_name: &str,
        parameters: Option<&[f64]>,
    ) -> QuantRS2Result<()> {
        let stride = 1usize << qubit;
        let matrix = Self::single_qubit_matrix_for_name(gate_name, parameters)?;
        Self::apply_matrix2_optimized(state, stride, &matrix)
    }

    /// Real 2x2 unitary for single-qubit gate names not covered by a
    /// hand-optimized kernel. Returns an honest
    /// [`QuantRS2Error::UnsupportedOperation`] for any name it cannot
    /// resolve, rather than fabricating an identity.
    fn single_qubit_matrix_for_name(
        gate_name: &str,
        parameters: Option<&[f64]>,
    ) -> QuantRS2Result<[[Complex64; 2]; 2]> {
        let one = Complex64::new(1.0, 0.0);
        let zero = Complex64::new(0.0, 0.0);
        match gate_name {
            "I" | "Identity" | "identity" => Ok([[one, zero], [zero, one]]),
            "S†" | "Sdg" | "SDagger" | "SDG" | "s_dagger" | "sdg" => {
                Ok([[one, zero], [zero, Complex64::new(0.0, -1.0)]])
            }
            "T†" | "Tdg" | "TDagger" | "TDG" | "t_dagger" | "tdg" => Ok([
                [one, zero],
                [
                    zero,
                    Complex64::from_polar(1.0, -std::f64::consts::FRAC_PI_4),
                ],
            ]),
            "√X" | "SqrtX" | "SX" | "sqrt_x" | "sx" => {
                let plus = Complex64::new(0.5, 0.5);
                let minus = Complex64::new(0.5, -0.5);
                Ok([[plus, minus], [minus, plus]])
            }
            "√X†" | "SqrtXdg" | "SXDG" | "sqrt_x_dagger" | "sxdg" => {
                let plus = Complex64::new(0.5, -0.5);
                let minus = Complex64::new(0.5, 0.5);
                Ok([[plus, minus], [minus, plus]])
            }
            "P" | "Phase" | "U1" | "phase_shift" | "u1" => {
                let theta = parameters.and_then(|p| p.first()).copied().ok_or_else(|| {
                    QuantRS2Error::InvalidInput(format!(
                        "gate '{gate_name}' requires a phase-angle parameter"
                    ))
                })?;
                Ok([[one, zero], [zero, Complex64::from_polar(1.0, theta)]])
            }
            _ => Err(QuantRS2Error::UnsupportedOperation(format!(
                "gpu_kernel_optimization: no real matrix implementation for single-qubit gate \
                 '{gate_name}'; add a specialized or generic-matrix case instead of a silent \
                 no-op"
            ))),
        }
    }

    /// Apply an arbitrary 2x2 unitary to the strided amplitude pairs of a
    /// single target qubit. Shared by every hand-optimized single-qubit
    /// kernel's real counterpart and [`Self::apply_generic_single_qubit`].
    fn apply_matrix2_optimized(
        state: &mut Array1<Complex64>,
        stride: usize,
        matrix: &[[Complex64; 2]; 2],
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        for i in 0..n / 2 {
            let i0 = (i / stride) * (2 * stride) + (i % stride);
            let i1 = i0 + stride;

            let a0 = amplitudes[i0];
            let a1 = amplitudes[i1];

            amplitudes[i0] = matrix[0][0] * a0 + matrix[0][1] * a1;
            amplitudes[i1] = matrix[1][0] * a0 + matrix[1][1] * a1;
        }

        Ok(())
    }

    /// Apply optimized two-qubit gate
    pub fn apply_two_qubit_gate(
        &mut self,
        state: &mut Array1<Complex64>,
        control: usize,
        target: usize,
        gate_name: &str,
    ) -> QuantRS2Result<()> {
        let start = Instant::now();

        // Get kernel from registry
        let kernel = self.kernel_registry.two_qubit_kernels.get(gate_name);

        match kernel {
            Some(k) => match k.kernel_type {
                TwoQubitKernelType::CNOT => {
                    self.apply_cnot_optimized(state, control, target)?;
                }
                TwoQubitKernelType::CZ => {
                    self.apply_cz_optimized(state, control, target)?;
                }
                TwoQubitKernelType::SWAP => {
                    self.apply_swap_optimized(state, control, target)?;
                }
                TwoQubitKernelType::ISWAP => {
                    self.apply_iswap_optimized(state, control, target)?;
                }
                _ => {
                    self.apply_generic_two_qubit(state, control, target, gate_name)?;
                }
            },
            None => {
                self.apply_generic_two_qubit(state, control, target, gate_name)?;
            }
        }

        // Update statistics
        let mut stats = self
            .stats
            .lock()
            .map_err(|_| QuantRS2Error::InvalidInput("Failed to acquire stats lock".to_string()))?;
        stats.total_executions += 1;
        stats.total_execution_time += start.elapsed();
        *stats
            .execution_counts
            .entry(gate_name.to_string())
            .or_insert(0) += 1;

        Ok(())
    }

    /// Apply optimized CNOT gate
    fn apply_cnot_optimized(
        &self,
        state: &mut Array1<Complex64>,
        control: usize,
        target: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let control_stride = 1 << control;
        let target_stride = 1 << target;

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        // CNOT: flip target when control is |1>
        for i in 0..n {
            if (i & control_stride) != 0 {
                // Control is |1>
                let partner = i ^ target_stride;
                if partner > i {
                    amplitudes.swap(i, partner);
                }
            }
        }

        Ok(())
    }

    /// Apply optimized CZ gate
    fn apply_cz_optimized(
        &self,
        state: &mut Array1<Complex64>,
        control: usize,
        target: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let control_stride = 1 << control;
        let target_stride = 1 << target;

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        // CZ: apply phase flip when both control and target are |1>
        for (i, amplitude) in amplitudes.iter_mut().enumerate() {
            if (i & control_stride) != 0 && (i & target_stride) != 0 {
                *amplitude = -*amplitude;
            }
        }

        Ok(())
    }

    /// Apply optimized SWAP gate
    fn apply_swap_optimized(
        &self,
        state: &mut Array1<Complex64>,
        qubit1: usize,
        qubit2: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let stride1 = 1 << qubit1;
        let stride2 = 1 << qubit2;

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        // SWAP: exchange |01> and |10> components
        for i in 0..n {
            let bit1 = (i & stride1) != 0;
            let bit2 = (i & stride2) != 0;
            if bit1 != bit2 {
                let partner = i ^ stride1 ^ stride2;
                if partner > i {
                    amplitudes.swap(i, partner);
                }
            }
        }

        Ok(())
    }

    /// Apply optimized iSWAP gate
    fn apply_iswap_optimized(
        &self,
        state: &mut Array1<Complex64>,
        qubit1: usize,
        qubit2: usize,
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let stride1 = 1 << qubit1;
        let stride2 = 1 << qubit2;

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        // iSWAP: swap |01> and |10> with i phase
        for i in 0..n {
            let bit1 = (i & stride1) != 0;
            let bit2 = (i & stride2) != 0;
            if bit1 != bit2 {
                let partner = i ^ stride1 ^ stride2;
                if partner > i {
                    let a = amplitudes[i];
                    let b = amplitudes[partner];
                    // Multiply by i when swapping
                    amplitudes[i] = Complex64::new(-b.im, b.re);
                    amplitudes[partner] = Complex64::new(-a.im, a.re);
                }
            }
        }

        Ok(())
    }

    /// Generic two-qubit gate application.
    ///
    /// Used for any two-qubit gate that does not have a hand-optimized
    /// kernel above (CNOT/CZ/SWAP/ISWAP). Builds the gate's real 4x4
    /// unitary from its name and applies it with a genuine matrix-vector
    /// contraction over each `(control, target)` amplitude quartet -- it
    /// never silently leaves the state unchanged. A gate name this
    /// function cannot resolve to a real matrix is an honest error, not a
    /// no-op.
    fn apply_generic_two_qubit(
        &self,
        state: &mut Array1<Complex64>,
        control: usize,
        target: usize,
        gate_name: &str,
    ) -> QuantRS2Result<()> {
        let matrix = Self::two_qubit_matrix_for_name(gate_name)?;
        Self::apply_matrix4_optimized(state, control, target, &matrix)
    }

    /// Real 4x4 unitary (basis order `|control, target>`, `control` the
    /// high local bit -- matching [`Self::apply_cnot_optimized`]'s
    /// bit-indexing convention) for two-qubit gate names not covered by a
    /// hand-optimized kernel. Returns an honest
    /// [`QuantRS2Error::UnsupportedOperation`] for any name it cannot
    /// resolve, rather than fabricating an identity.
    fn two_qubit_matrix_for_name(gate_name: &str) -> QuantRS2Result<[[Complex64; 4]; 4]> {
        let one = Complex64::new(1.0, 0.0);
        let zero = Complex64::new(0.0, 0.0);
        match gate_name {
            "CY" | "cy" => Ok([
                [one, zero, zero, zero],
                [zero, one, zero, zero],
                [zero, zero, zero, Complex64::new(0.0, -1.0)],
                [zero, zero, Complex64::new(0.0, 1.0), zero],
            ]),
            "CH" | "ch" => {
                let inv_sqrt2 = Complex64::new(std::f64::consts::FRAC_1_SQRT_2, 0.0);
                Ok([
                    [one, zero, zero, zero],
                    [zero, one, zero, zero],
                    [zero, zero, inv_sqrt2, inv_sqrt2],
                    [zero, zero, inv_sqrt2, -inv_sqrt2],
                ])
            }
            "CS" | "cs" => Ok([
                [one, zero, zero, zero],
                [zero, one, zero, zero],
                [zero, zero, one, zero],
                [zero, zero, zero, Complex64::new(0.0, 1.0)],
            ]),
            _ => Err(QuantRS2Error::UnsupportedOperation(format!(
                "gpu_kernel_optimization: no real matrix implementation for two-qubit gate \
                 '{gate_name}'; add a specialized or generic-matrix case instead of a silent \
                 no-op"
            ))),
        }
    }

    /// Apply an arbitrary 4x4 unitary over the `(control, target)`
    /// amplitude quartets of a full state vector. Basis ordering matches
    /// [`Self::apply_cnot_optimized`]: `control` is the high local bit.
    fn apply_matrix4_optimized(
        state: &mut Array1<Complex64>,
        control: usize,
        target: usize,
        matrix: &[[Complex64; 4]; 4],
    ) -> QuantRS2Result<()> {
        let n = state.len();
        let control_mask = 1usize << control;
        let target_mask = 1usize << target;

        let amplitudes = state.as_slice_mut().ok_or_else(|| {
            QuantRS2Error::InvalidInput("Failed to get mutable slice".to_string())
        })?;

        for i in 0..n {
            if i & control_mask == 0 && i & target_mask == 0 {
                let idx = [
                    i,
                    i | target_mask,
                    i | control_mask,
                    i | control_mask | target_mask,
                ];
                let amps = [
                    amplitudes[idx[0]],
                    amplitudes[idx[1]],
                    amplitudes[idx[2]],
                    amplitudes[idx[3]],
                ];
                for (row, &out_idx) in idx.iter().enumerate() {
                    let mut acc = Complex64::new(0.0, 0.0);
                    for (col, &amp) in amps.iter().enumerate() {
                        acc += matrix[row][col] * amp;
                    }
                    amplitudes[out_idx] = acc;
                }
            }
        }

        Ok(())
    }

    /// Get kernel execution statistics
    pub fn get_stats(&self) -> QuantRS2Result<KernelStats> {
        let stats = self
            .stats
            .lock()
            .map_err(|_| QuantRS2Error::InvalidInput("Failed to acquire stats lock".to_string()))?;
        Ok(stats.clone())
    }

    /// Reset statistics
    pub fn reset_stats(&mut self) -> QuantRS2Result<()> {
        let mut stats = self
            .stats
            .lock()
            .map_err(|_| QuantRS2Error::InvalidInput("Failed to acquire stats lock".to_string()))?;
        *stats = KernelStats::default();
        Ok(())
    }

    /// Get available kernel names
    #[must_use]
    pub fn get_available_kernels(&self) -> Vec<String> {
        let mut kernels = Vec::new();
        kernels.extend(self.kernel_registry.single_qubit_kernels.keys().cloned());
        kernels.extend(self.kernel_registry.two_qubit_kernels.keys().cloned());
        kernels.extend(self.kernel_registry.fused_kernels.keys().cloned());
        kernels
    }

    /// Check if a kernel is available
    #[must_use]
    pub fn has_kernel(&self, name: &str) -> bool {
        self.kernel_registry.single_qubit_kernels.contains_key(name)
            || self.kernel_registry.two_qubit_kernels.contains_key(name)
            || self.kernel_registry.fused_kernels.contains_key(name)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_kernel_optimizer_creation() {
        let config = GPUKernelConfig::default();
        let optimizer = GPUKernelOptimizer::new(config);
        assert!(!optimizer.get_available_kernels().is_empty());
    }

    #[test]
    fn test_hadamard_kernel() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::from_vec(vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 0.0)]);

        let result = optimizer.apply_single_qubit_gate(&mut state, 0, "hadamard", None);
        assert!(result.is_ok());

        let inv_sqrt2 = 1.0 / 2.0_f64.sqrt();
        assert!((state[0].re - inv_sqrt2).abs() < 1e-10);
        assert!((state[1].re - inv_sqrt2).abs() < 1e-10);
    }

    #[test]
    fn test_pauli_x_kernel() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::from_vec(vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 0.0)]);

        let result = optimizer.apply_single_qubit_gate(&mut state, 0, "pauli_x", None);
        assert!(result.is_ok());

        assert!((state[0].re - 0.0).abs() < 1e-10);
        assert!((state[1].re - 1.0).abs() < 1e-10);
    }

    #[test]
    fn test_pauli_z_kernel() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::from_vec(vec![Complex64::new(0.5, 0.0), Complex64::new(0.5, 0.0)]);

        let result = optimizer.apply_single_qubit_gate(&mut state, 0, "pauli_z", None);
        assert!(result.is_ok());

        assert!((state[0].re - 0.5).abs() < 1e-10);
        assert!((state[1].re + 0.5).abs() < 1e-10);
    }

    #[test]
    fn test_rotation_z_kernel() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::from_vec(vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 0.0)]);

        let result = optimizer.apply_single_qubit_gate(
            &mut state,
            0,
            "rotation_z",
            Some(&[std::f64::consts::PI]),
        );
        assert!(result.is_ok());
    }

    #[test]
    fn test_cnot_kernel() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        // |10> state
        let mut state = Array1::from_vec(vec![
            Complex64::new(0.0, 0.0),
            Complex64::new(0.0, 0.0),
            Complex64::new(1.0, 0.0),
            Complex64::new(0.0, 0.0),
        ]);

        let result = optimizer.apply_two_qubit_gate(&mut state, 1, 0, "cnot");
        assert!(result.is_ok());

        // Should become |11>
        assert!((state[3].re - 1.0).abs() < 1e-10);
    }

    #[test]
    fn test_cz_kernel() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        // |11> state
        let mut state = Array1::from_vec(vec![
            Complex64::new(0.0, 0.0),
            Complex64::new(0.0, 0.0),
            Complex64::new(0.0, 0.0),
            Complex64::new(1.0, 0.0),
        ]);

        let result = optimizer.apply_two_qubit_gate(&mut state, 1, 0, "cz");
        assert!(result.is_ok());

        // Should get phase flip
        assert!((state[3].re + 1.0).abs() < 1e-10);
    }

    #[test]
    fn test_swap_kernel() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        // |01> state
        let mut state = Array1::from_vec(vec![
            Complex64::new(0.0, 0.0),
            Complex64::new(1.0, 0.0),
            Complex64::new(0.0, 0.0),
            Complex64::new(0.0, 0.0),
        ]);

        let result = optimizer.apply_two_qubit_gate(&mut state, 0, 1, "swap");
        assert!(result.is_ok());

        // Should become |10>
        assert!((state[2].re - 1.0).abs() < 1e-10);
    }

    #[test]
    fn test_kernel_stats() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::from_vec(vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 0.0)]);

        optimizer
            .apply_single_qubit_gate(&mut state, 0, "hadamard", None)
            .expect("hadamard gate should apply successfully");
        optimizer
            .apply_single_qubit_gate(&mut state, 0, "pauli_x", None)
            .expect("pauli_x gate should apply successfully");

        let stats = optimizer.get_stats().expect("get_stats should succeed");
        assert_eq!(stats.total_executions, 2);
        assert_eq!(*stats.execution_counts.get("hadamard").unwrap_or(&0), 1);
        assert_eq!(*stats.execution_counts.get("pauli_x").unwrap_or(&0), 1);
    }

    #[test]
    fn test_available_kernels() {
        let config = GPUKernelConfig::default();
        let optimizer = GPUKernelOptimizer::new(config);

        let kernels = optimizer.get_available_kernels();
        assert!(kernels.contains(&"hadamard".to_string()));
        assert!(kernels.contains(&"cnot".to_string()));
        assert!(kernels.contains(&"swap".to_string()));
    }

    #[test]
    fn test_has_kernel() {
        let config = GPUKernelConfig::default();
        let optimizer = GPUKernelOptimizer::new(config);

        assert!(optimizer.has_kernel("hadamard"));
        assert!(optimizer.has_kernel("cnot"));
        assert!(!optimizer.has_kernel("nonexistent"));
    }

    #[test]
    fn test_config_defaults() {
        let config = GPUKernelConfig::default();

        assert!(config.enable_warp_optimization);
        assert!(config.enable_shared_memory);
        assert_eq!(config.block_size, 256);
        assert!(config.enable_kernel_fusion);
        assert_eq!(config.max_fusion_length, 8);
    }

    #[test]
    fn test_reset_stats() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::from_vec(vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 0.0)]);

        optimizer
            .apply_single_qubit_gate(&mut state, 0, "hadamard", None)
            .expect("hadamard gate should apply successfully");
        optimizer.reset_stats().expect("reset_stats should succeed");

        let stats = optimizer.get_stats().expect("get_stats should succeed");
        assert_eq!(stats.total_executions, 0);
    }

    #[test]
    fn test_multiple_qubit_operations() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        // 3-qubit state
        let mut state = Array1::zeros(8);
        state[0] = Complex64::new(1.0, 0.0);

        // Apply H to qubit 0
        optimizer
            .apply_single_qubit_gate(&mut state, 0, "hadamard", None)
            .expect("hadamard gate should apply successfully");

        // Apply CNOT(0, 1)
        optimizer
            .apply_two_qubit_gate(&mut state, 0, 1, "cnot")
            .expect("cnot gate should apply successfully");

        // State should be in superposition
        let total_prob: f64 = state.iter().map(|a| (a * a.conj()).re).sum();
        assert!((total_prob - 1.0).abs() < 1e-10);
    }

    /// Regression test for the P1 finding: `apply_generic_single_qubit`
    /// used to be a structural no-op (it didn't even take `state` mutably)
    /// that silently left the state unchanged for any gate name outside
    /// the hand-optimized kernel set. An `S†` gate (not one of the
    /// registered kernel names) applied to `|1>` must now produce the real
    /// `-i` phase, not leave the amplitude untouched.
    #[test]
    fn test_generic_single_qubit_applies_real_matrix() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::from_vec(vec![Complex64::new(0.0, 0.0), Complex64::new(1.0, 0.0)]);
        optimizer
            .apply_single_qubit_gate(&mut state, 0, "S†", None)
            .expect("S-dagger gate should apply via the generic path");

        assert!((state[0].norm()).abs() < 1e-10);
        assert!(
            (state[1] - Complex64::new(0.0, -1.0)).norm() < 1e-10,
            "expected S† to apply a real -i phase to |1>, got {:?}",
            state[1]
        );
    }

    /// Regression test: a parametric generic gate (`P`/phase-shift) must
    /// use the real supplied angle.
    #[test]
    fn test_generic_single_qubit_phase_uses_real_angle() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::from_vec(vec![Complex64::new(0.0, 0.0), Complex64::new(1.0, 0.0)]);
        optimizer
            .apply_single_qubit_gate(&mut state, 0, "P", Some(&[std::f64::consts::FRAC_PI_2]))
            .expect("P gate should apply via the generic path");

        assert!(
            (state[1] - Complex64::new(0.0, 1.0)).norm() < 1e-10,
            "expected P(pi/2) to apply a real +i phase to |1>, got {:?}",
            state[1]
        );
    }

    /// Regression test: an unresolvable generic gate name must return an
    /// honest error rather than silently leaving the state unchanged.
    #[test]
    fn test_generic_single_qubit_unknown_name_errors() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::from_vec(vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 0.0)]);
        let result = optimizer.apply_single_qubit_gate(&mut state, 0, "totally_unknown_gate", None);
        assert!(
            result.is_err(),
            "an unresolvable gate name must be an honest error"
        );
    }

    /// Regression test for the P1 finding: `apply_generic_two_qubit` used
    /// to take `state` by shared reference (structurally incapable of
    /// mutating it) and always return `Ok(())`. A `CY` gate (not one of
    /// the registered kernel names) applied with control set must now
    /// really flip and phase the target, not leave the state unchanged.
    #[test]
    fn test_generic_two_qubit_applies_real_matrix() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        // |10>: control (qubit 0) = 1, target (qubit 1) = 0.
        let mut state = Array1::zeros(4);
        state[1] = Complex64::new(1.0, 0.0);

        optimizer
            .apply_two_qubit_gate(&mut state, 0, 1, "CY")
            .expect("CY gate should apply via the generic path");

        // CY with control=1 applies Y to the target: Y|0> = i|1>, moving
        // the amplitude to |11> (index 3) with a real +i phase.
        assert!(state[1].norm() < 1e-10, "amplitude must leave |10>");
        assert!(
            (state[3] - Complex64::new(0.0, 1.0)).norm() < 1e-10,
            "expected CY(control=1) to apply Y with a real +i phase, got {:?}",
            state[3]
        );
    }

    /// Regression test: an unresolvable generic two-qubit gate name must
    /// return an honest error rather than silently leaving the state
    /// unchanged.
    #[test]
    fn test_generic_two_qubit_unknown_name_errors() {
        let config = GPUKernelConfig::default();
        let mut optimizer = GPUKernelOptimizer::new(config);

        let mut state = Array1::zeros(4);
        state[0] = Complex64::new(1.0, 0.0);
        let result = optimizer.apply_two_qubit_gate(&mut state, 0, 1, "totally_unknown_gate");
        assert!(
            result.is_err(),
            "an unresolvable gate name must be an honest error"
        );
    }
}