scirs2_datasets/

gpu_optimization.rs

//! Advanced GPU Optimization Engine
//!
//! This module provides GPU-aware optimization heuristics and *genuinely
//! measured* execution paths for dataset operations: adaptive kernel
//! selection, auto-tuning, and benchmarking that report only what was
//! actually dispatched and timed on this process — never a fabricated
//! speedup.
//!
//! ## Backend model
//!
//! [`AdvancedGpuOptimizer`] keeps this crate's own [`crate::gpu::GpuBackend`]
//! / [`crate::gpu::GpuContext`] as its public backend-selection type: it is
//! also the type used throughout the rest of this crate's GPU-flavored
//! dataset generators and is re-exported at the crate root, so replacing it
//! with `scirs2_core::gpu`'s (differently shaped, unit-variant-only) backend
//! type would ripple far beyond this module.
//!
//! Requesting `GpuBackend::Cuda` or `GpuBackend::OpenCl` here does **not**
//! dispatch vendor-specific kernels — both route through the same real,
//! backend-agnostic `wgpu`/`GpuNdarray` compute path used by this crate's
//! (crate-private) `generators::gpu_dispatch` module — see that module for
//! the canonical pattern this file follows — with an honest, silent
//! fallback to the CPU path whenever no adapter is present, the workload is
//! too small to be worth transferring, or the `wgpu` feature is disabled at
//! compile time. `GpuBackend::Cpu` never attempts a GPU dispatch, by design.
//!
//! For genuine vendor-specific NVIDIA CUDA execution via the pure-Rust
//! `oxicuda-*` stack, see [`crate::gpu_cuda`] (feature = `"cuda"`) — a
//! separate, additive path not currently wired into this optimizer.

use crate::error::{DatasetsError, Result};
use crate::gpu::{GpuBackend, GpuContext};
use scirs2_core::ndarray::Array2;
use scirs2_core::parallel_ops::*;
use scirs2_core::random::prelude::*;
use scirs2_core::random::{Distribution, Uniform};
use std::collections::HashMap;
use std::sync::Arc;

/// Advanced-advanced GPU performance optimizer
#[derive(Debug, Clone)]
pub struct AdvancedGpuOptimizer {
    /// Adaptive kernel selection enabled
    adaptive_kernels: bool,
    /// Intelligent memory prefetching
    memory_prefetch: bool,
    /// Multi-GPU coordination
    multi_gpu: bool,
    /// Auto-tuning parameters
    auto_tuning: bool,
    /// Performance cache
    performance_cache: Arc<std::sync::Mutex<HashMap<String, GpuPerformanceProfile>>>,
}

/// GPU performance profiling data
#[derive(Debug, Clone)]
#[allow(dead_code)]
pub struct GpuPerformanceProfile {
    /// Optimal block size for kernels
    optimal_block_size: usize,
    /// Memory bandwidth utilization
    memory_bandwidth: f64,
    /// Compute utilization
    compute_utilization: f64,
    /// Optimal data layout
    optimal_layout: DataLayout,
    /// Performance score (higher is better)
    performance_score: f64,
}

/// Data layout optimization strategies
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum DataLayout {
    /// Row-major layout (C-style)
    RowMajor,
    /// Column-major layout (Fortran-style)
    ColumnMajor,
    /// Tiled layout for cache efficiency
    Tiled {
        /// Size of each tile
        tile_size: usize,
    },
    /// Adaptive layout based on access patterns
    Adaptive,
}

/// Advanced-advanced GPU kernel configuration
#[derive(Debug, Clone)]
#[allow(dead_code)]
pub struct AdvancedKernelConfig {
    /// Kernel specialization level
    specialization_level: SpecializationLevel,
    /// Memory access pattern optimization
    memory_pattern: MemoryAccessPattern,
    /// Vectorization strategy
    vectorization: VectorizationStrategy,
    /// Load balancing method
    load_balancing: LoadBalancingMethod,
    /// Optimal block size for GPU kernels
    block_size: usize,
}

/// Kernel specialization levels
#[derive(Debug, Clone, Copy)]
pub enum SpecializationLevel {
    /// Basic kernels
    Basic,
    /// Hardware-optimized kernels
    HardwareOptimized,
    /// Advanced-specialized kernels
    AdvancedSpecialized,
    /// AI-optimized kernels
    AIOptimized,
}

/// Memory access pattern optimization
#[derive(Debug, Clone, Copy)]
pub enum MemoryAccessPattern {
    /// Sequential access pattern
    Sequential,
    /// Random access pattern
    Random,
    /// Strided access pattern
    Strided {
        /// Stride size for access pattern
        stride: usize,
    },
    /// Blocked access pattern
    Blocked {
        /// Size of each block
        block_size: usize,
    },
}

/// Vectorization strategies
#[derive(Debug, Clone, Copy)]
pub enum VectorizationStrategy {
    /// Scalar operations
    Scalar,
    /// Vector2 operations
    Vector2,
    /// Vector4 operations
    Vector4,
    /// Vector8 operations
    Vector8,
    /// Adaptive vectorization
    Adaptive,
}

/// Load balancing methods
#[derive(Debug, Clone, Copy)]
pub enum LoadBalancingMethod {
    /// Static load balancing
    Static,
    /// Dynamic load balancing
    Dynamic,
    /// Work-stealing approach
    WorkStealing,
    /// Adaptive balancing
    Adaptive,
}

/// Minimum element count to attempt a real GPU round trip; below this the
/// host↔device transfer overhead dominates and CPU is both faster and
/// simpler. Mirrors [`crate::generators::gpu_dispatch::GPU_DATASET_THRESHOLD`].
const GPU_OPT_THRESHOLD: usize = 4096;

/// Attempts one genuine wgpu upload → elementwise-scalar-multiply(×1.0) →
/// download round trip for `data`, returning the real wall-clock duration of
/// the attempt when it actually executed on a real adapter.
///
/// Mirrors the fallback contract used throughout this crate's real GPU
/// paths (see [`crate::generators::gpu_dispatch`]): below
/// [`GPU_OPT_THRESHOLD`], with no adapter present, or on any dispatch error,
/// this returns `None` and the caller must treat the operation as CPU-only
/// — it must never fabricate a GPU timing or speedup number from this
/// result.
#[cfg(feature = "wgpu")]
fn attempt_gpu_round_trip(data: &[f64]) -> Option<std::time::Duration> {
    use scirs2_core::array_protocol::gpu_ndarray::{global_context, is_gpu_available, GpuNdarray};
    use std::time::Instant;

    if data.len() < GPU_OPT_THRESHOLD || !is_gpu_available() {
        return None;
    }
    let ctx = global_context()?;

    let host: Vec<f32> = data.iter().map(|&v| v as f32).collect();
    let expected_len = host.len();
    let start = Instant::now();
    let run = || -> std::result::Result<usize, scirs2_core::gpu::GpuError> {
        let gpu =
            GpuNdarray::<f32>::from_ndarray_data(&host, vec![expected_len], Arc::clone(&ctx))?;
        let refined = gpu.multiply_by_scalar_f32(1.0)?;
        let out = refined.to_vec()?;
        Ok(out.len())
    };
    match run() {
        Ok(len) if len == expected_len => Some(start.elapsed()),
        _ => None,
    }
}

/// CPU-only stub used when the `wgpu` feature is disabled: always reports
/// "no GPU ran" rather than fabricating a timing.
#[cfg(not(feature = "wgpu"))]
fn attempt_gpu_round_trip(data: &[f64]) -> Option<std::time::Duration> {
    let _ = data;
    None
}

impl Default for AdvancedGpuOptimizer {
    fn default() -> Self {
        Self {
            adaptive_kernels: true,
            memory_prefetch: true,
            multi_gpu: true,
            auto_tuning: true,
            performance_cache: Arc::new(std::sync::Mutex::new(HashMap::new())),
        }
    }
}

impl AdvancedGpuOptimizer {
    /// Create a new advanced GPU optimizer
    pub fn new() -> Self {
        Self::default()
    }

    /// Configure adaptive kernel selection
    pub fn with_adaptive_kernels(mut self, enabled: bool) -> Self {
        self.adaptive_kernels = enabled;
        self
    }

    /// Configure memory prefetching
    pub fn with_memory_prefetch(mut self, enabled: bool) -> Self {
        self.memory_prefetch = enabled;
        self
    }

    /// Configure multi-GPU coordination
    pub fn with_multi_gpu(mut self, enabled: bool) -> Self {
        self.multi_gpu = enabled;
        self
    }

    /// Configure auto-tuning
    pub fn with_auto_tuning(mut self, enabled: bool) -> Self {
        self.auto_tuning = enabled;
        self
    }

    /// Optimize GPU execution for a specific operation
    pub fn optimize_execution(
        &self,
        gpu_context: &GpuContext,
        operation: &str,
        datashape: (usize, usize),
    ) -> Result<AdvancedKernelConfig> {
        // Check performance cache first
        let cache_key = format!(
            "{}_{}_{}_{}",
            gpu_context.backend(),
            operation,
            datashape.0,
            datashape.1
        );

        if let Ok(cache) = self.performance_cache.lock() {
            if let Some(profile) = cache.get(&cache_key) {
                return Ok(self.profile_to_kernel_config(profile));
            }
        }

        // Perform auto-tuning if enabled
        if self.auto_tuning {
            let profile = self.auto_tune_operation(gpu_context, operation, datashape)?;

            // Cache the result
            if let Ok(mut cache) = self.performance_cache.lock() {
                cache.insert(cache_key, profile.clone());
            }

            Ok(self.profile_to_kernel_config(&profile))
        } else {
            // Use default configuration
            Ok(self.default_kernel_config(gpu_context.backend().clone()))
        }
    }

    /// Auto-tune GPU operation for optimal performance
    ///
    /// Block-size/work-group selection remains a pre-dispatch *planning*
    /// heuristic (see [`Self::tune_cuda_block_size`] /
    /// [`Self::tune_opencl_work_group_size`]) — `GpuNdarray`'s real kernels
    /// use fixed internal workgroup sizes, so these values are advisory
    /// metadata rather than something threaded into the actual dispatch.
    /// `memory_bandwidth` and `compute_utilization`, however, now come from
    /// [`Self::calibrate_backend_throughput`], a genuine timed dispatch —
    /// they are never read from a per-operation-name lookup table.
    fn auto_tune_operation(
        &self,
        gpu_context: &GpuContext,
        operation: &str,
        datashape: (usize, usize),
    ) -> Result<GpuPerformanceProfile> {
        let backend = gpu_context.backend();

        // Determine optimal block size based on GPU architecture
        let optimal_block_size = match backend {
            GpuBackend::Cuda { .. } => self.tune_cuda_block_size(datashape),
            GpuBackend::OpenCl { .. } => self.tune_opencl_work_group_size(datashape),
            GpuBackend::Cpu => 256, // Default for the CPU-only backend
        };

        // Genuinely measure backend throughput (real CPU generation, plus a
        // real GPU round trip when the backend requests one and an adapter
        // is present); never a fabricated formula.
        let (memory_bandwidth, compute_utilization) = self.calibrate_backend_throughput(backend)?;

        // Determine optimal data layout
        let optimal_layout = self.determine_optimal_layout(operation, datashape);

        // Calculate overall performance score
        let performance_score = self.calculate_performance_score(
            optimal_block_size,
            memory_bandwidth,
            compute_utilization,
        );

        Ok(GpuPerformanceProfile {
            optimal_block_size,
            memory_bandwidth,
            compute_utilization,
            optimal_layout,
            performance_score,
        })
    }

    /// Fixed calibration problem size (elements) used to genuinely measure
    /// backend throughput once per (backend, operation, shape) cache entry.
    ///
    /// Deliberately shape-independent and bounded: measuring achieved
    /// GB/s and elements/sec is a hardware-throughput characterization, not
    /// something that needs to scale with the caller's requested matrix
    /// size (mirroring how real benchmarking tools report a GB/s constant
    /// for a device rather than reporting a number proportional to problem
    /// size). It is comfortably above
    /// [`crate::generators::gpu_dispatch::GPU_DATASET_THRESHOLD`] so the
    /// real wgpu path is genuinely exercised whenever an adapter is present.
    const CALIBRATION_SIDE: usize = 128;

    /// Run one genuine, timed dispatch — real CPU generation, plus (for a
    /// non-CPU backend) a real GPU upload/kernel/download round trip when an
    /// adapter is available — and derive `(memory_bandwidth_gb_s,
    /// compute_utilization)` from the *actual* elapsed time.
    ///
    /// Replaces the historical per-operation-name lookup tables entirely.
    /// On any GPU error, this silently falls back to reporting the CPU-only
    /// measurement rather than propagating an error or fabricating a number
    /// — consistent with the "never panic, never invent a metric" contract
    /// used by [`crate::generators::gpu_dispatch`].
    fn calibrate_backend_throughput(&self, backend: &GpuBackend) -> Result<(f64, f64)> {
        use std::time::Instant;

        let side = Self::CALIBRATION_SIDE;
        let elements = side * side;

        let start = Instant::now();
        let sample = self.execute_advanced_cpu_generation(side, side, "uniform")?;
        if !matches!(backend, GpuBackend::Cpu) {
            // Best-effort: a failed/unavailable GPU round trip simply means
            // the elapsed time below reflects the CPU-only calibration,
            // which is still an honest measurement.
            let _ = attempt_gpu_round_trip(sample.as_slice().unwrap_or(&[]));
        }
        let elapsed = start.elapsed();

        let memory_bandwidth = self.calculate_memory_bandwidth(elements, elapsed);
        let compute_utilization = self.utilization_from_timing(elements, elapsed);
        Ok((memory_bandwidth, compute_utilization))
    }

    /// Normalizes a genuinely measured elements/second rate into a `[0, 1]`
    /// utilization score, using the same 100M-elements/sec reference
    /// constant that [`Self::calculate_performance_score_from_timing`]
    /// already applies to cached results (100M elements/sec == fully
    /// saturated for scoring purposes). This is a documented scoring
    /// convention derived from a real timing, never a per-operation-name
    /// lookup disconnected from any measurement.
    fn utilization_from_timing(&self, elements: usize, duration: std::time::Duration) -> f64 {
        let elements_per_second = if duration.as_secs_f64() > 0.0 {
            elements as f64 / duration.as_secs_f64()
        } else {
            0.0
        };
        (elements_per_second / 100_000_000.0).min(1.0)
    }

    /// Tune CUDA block size for optimal performance
    fn tune_cuda_block_size(&self, datashape: (usize, usize)) -> usize {
        let total_elements = datashape.0 * datashape.1;

        // Use heuristics based on problem size
        match total_elements {
            0..=1_000 => 32,
            1_001..=10_000 => 64,
            10_001..=100_000 => 128,
            100_001..=1_000_000 => 256,
            _ => 512,
        }
    }

    /// Tune OpenCL work group size
    fn tune_opencl_work_group_size(&self, datashape: (usize, usize)) -> usize {
        // OpenCL typically prefers smaller work group sizes
        let total_elements = datashape.0 * datashape.1;

        match total_elements {
            0..=1_000 => 16,
            1_001..=10_000 => 32,
            10_001..=100_000 => 64,
            100_001..=1_000_000 => 128,
            _ => 256,
        }
    }

    /// Heuristic compute-intensity feature for the simplified linear AI
    /// predictor ([`AIPerformancePredictor`]) used by
    /// [`AdvancedGpuOptimizer::predict_optimal_config`] below.
    ///
    /// This is deliberately **not** used anywhere in the genuinely-measured
    /// path ([`Self::calibrate_backend_throughput`] /
    /// [`Self::auto_tune_operation`] / [`Self::benchmark_performance`]) — it
    /// is a hand-engineered ML *input feature* (same spirit as feature
    /// engineering for any small predictive model), not a claimed
    /// measurement of real hardware behavior.
    fn estimate_compute_utilization(&self, operation: &str, datashape: (usize, usize)) -> f64 {
        let total_elements = datashape.0 * datashape.1;

        // Different operations have different compute intensities
        let compute_intensity = match operation {
            "matrix_multiply" => 2.0 * datashape.0 as f64, // O(n^3) for n x n matrices
            "element_wise" => 1.0,                         // O(n) operations
            "reduction" => (total_elements as f64).log2(), // O(log n) depth
            "trigonometric" => 10.0,                       // High compute intensity
            _ => 1.0,                                      // Default
        };

        // Normalize to [0, 1] range
        (compute_intensity / (compute_intensity + 1.0)).min(1.0)
    }

    /// Determine optimal data layout
    fn determine_optimal_layout(&self, operation: &str, datashape: (usize, usize)) -> DataLayout {
        match operation {
            "matrix_multiply" => {
                // For matrix multiplication, consider cache efficiency
                if datashape.0 * datashape.1 > 100_000 {
                    DataLayout::Tiled { tile_size: 64 }
                } else {
                    DataLayout::RowMajor
                }
            }
            "transpose" => DataLayout::ColumnMajor,
            "element_wise" => DataLayout::RowMajor,
            _ => DataLayout::Adaptive,
        }
    }

    /// Calculate overall performance score
    fn calculate_performance_score(
        &self,
        block_size: usize,
        memory_bandwidth: f64,
        compute_utilization: f64,
    ) -> f64 {
        // Heuristic scoring based on multiple factors
        let block_efficiency = match block_size {
            32..=256 => 1.0,
            257..=512 => 0.9,
            _ => 0.7,
        };

        let bandwidth_efficiency = (memory_bandwidth / (memory_bandwidth + 1e9)).min(1.0);

        // Weighted combination
        block_efficiency * 0.3 + bandwidth_efficiency * 0.3 + compute_utilization * 0.4
    }

    /// Convert performance profile to kernel configuration
    fn profile_to_kernel_config(&self, profile: &GpuPerformanceProfile) -> AdvancedKernelConfig {
        let specialization_level = if profile.performance_score > 0.8 {
            SpecializationLevel::AdvancedSpecialized
        } else if profile.performance_score > 0.6 {
            SpecializationLevel::HardwareOptimized
        } else {
            SpecializationLevel::Basic
        };

        let memory_pattern = match profile.optimal_layout {
            DataLayout::RowMajor => MemoryAccessPattern::Sequential,
            DataLayout::ColumnMajor => MemoryAccessPattern::Strided { stride: 1 },
            DataLayout::Tiled { tile_size } => MemoryAccessPattern::Blocked {
                block_size: tile_size,
            },
            DataLayout::Adaptive => MemoryAccessPattern::Sequential,
        };

        let vectorization = if profile.compute_utilization > 0.7 {
            VectorizationStrategy::Vector4
        } else if profile.compute_utilization > 0.5 {
            VectorizationStrategy::Vector2
        } else {
            VectorizationStrategy::Scalar
        };

        let load_balancing = if profile.performance_score > 0.8 {
            LoadBalancingMethod::Adaptive
        } else {
            LoadBalancingMethod::Dynamic
        };

        AdvancedKernelConfig {
            specialization_level,
            memory_pattern,
            vectorization,
            load_balancing,
            // Use the actually-tuned block size (previously this hardcoded
            // 256 regardless of `profile.optimal_block_size`, silently
            // discarding the auto-tuner's recommendation).
            block_size: profile.optimal_block_size,
        }
    }

    /// Get default kernel configuration for a backend
    fn default_kernel_config(&self, backend: GpuBackend) -> AdvancedKernelConfig {
        match backend {
            GpuBackend::Cuda { .. } => AdvancedKernelConfig {
                specialization_level: SpecializationLevel::HardwareOptimized,
                memory_pattern: MemoryAccessPattern::Sequential,
                vectorization: VectorizationStrategy::Vector4,
                load_balancing: LoadBalancingMethod::Dynamic,
                block_size: 512,
            },
            GpuBackend::OpenCl { .. } => AdvancedKernelConfig {
                specialization_level: SpecializationLevel::Basic,
                memory_pattern: MemoryAccessPattern::Sequential,
                vectorization: VectorizationStrategy::Vector2,
                load_balancing: LoadBalancingMethod::Static,
                block_size: 256,
            },
            _ => AdvancedKernelConfig {
                specialization_level: SpecializationLevel::Basic,
                memory_pattern: MemoryAccessPattern::Sequential,
                vectorization: VectorizationStrategy::Scalar,
                load_balancing: LoadBalancingMethod::Static,
                block_size: 128,
            },
        }
    }

    /// Advanced-optimized matrix generation on GPU
    pub fn generate_advanced_optimized_matrix(
        &self,
        gpu_context: &GpuContext,
        rows: usize,
        cols: usize,
        distribution: &str,
    ) -> Result<Array2<f64>> {
        // Get optimal configuration
        let config = self.optimize_execution(gpu_context, "matrix_generation", (rows, cols))?;

        // Generate matrix using optimized kernel
        self.execute_optimized_generation(gpu_context, rows, cols, distribution, &config)
    }

    /// Execute optimized matrix generation
    ///
    /// Random draws always happen host-side (matching the documented
    /// convention in [`crate::generators::gpu_dispatch`]: distribution
    /// semantics require the RNG to run on the CPU). When the configured
    /// backend is not [`GpuBackend::Cpu`], this additionally performs a
    /// genuine wgpu upload/kernel/download round trip over the freshly
    /// generated data — real hardware exercise and real timing, contributing
    /// to the honest performance cache — and gracefully (silently) continues
    /// with the CPU-generated values if no adapter is available or the
    /// dispatch errors. `GpuBackend::Cpu` never attempts this.
    fn execute_optimized_generation(
        &self,
        gpu_context: &GpuContext,
        rows: usize,
        cols: usize,
        distribution: &str,
        _config: &AdvancedKernelConfig,
    ) -> Result<Array2<f64>> {
        use std::time::Instant;

        let total_elements = rows * cols;
        let start_time = Instant::now();

        let matrix = self.execute_advanced_cpu_generation(rows, cols, distribution)?;

        let used_gpu = !matches!(gpu_context.backend(), GpuBackend::Cpu)
            && attempt_gpu_round_trip(matrix.as_slice().unwrap_or(&[])).is_some();

        let label = if used_gpu {
            "gpu_generation"
        } else {
            "cpu_generation"
        };
        self.cache_gpu_performance(label, total_elements, start_time.elapsed());

        Ok(matrix)
    }

    /// Cache GPU performance data for adaptive optimization
    fn cache_gpu_performance(
        &self,
        operation: &str,
        elements: usize,
        duration: std::time::Duration,
    ) {
        if let Ok(mut cache) = self.performance_cache.lock() {
            let key = format!("{operation}_{elements}");
            let profile = GpuPerformanceProfile {
                optimal_block_size: self.calculate_optimal_block_size(elements),
                memory_bandwidth: self.calculate_memory_bandwidth(elements, duration),
                compute_utilization: self.utilization_from_timing(elements, duration),
                optimal_layout: DataLayout::RowMajor, // Default for most operations
                performance_score: self.calculate_performance_score_from_timing(elements, duration),
            };
            cache.insert(key, profile);
        }
    }

    /// Calculate optimal block size based on problem size
    fn calculate_optimal_block_size(&self, elements: usize) -> usize {
        match elements {
            0..=1024 => 32,
            1025..=16384 => 64,
            16385..=262144 => 128,
            262145..=1048576 => 256,
            _ => 512,
        }
    }

    /// Calculate memory bandwidth utilization
    fn calculate_memory_bandwidth(&self, elements: usize, duration: std::time::Duration) -> f64 {
        let bytes_transferred = elements * std::mem::size_of::<f64>() * 2; // Read + Write
        let duration_secs = duration.as_secs_f64();
        if duration_secs > 0.0 {
            bytes_transferred as f64 / duration_secs / (1024.0 * 1024.0 * 1024.0)
        // GB/s
        } else {
            0.0
        }
    }

    /// Calculate performance score from actual timing
    fn calculate_performance_score_from_timing(
        &self,
        elements: usize,
        duration: std::time::Duration,
    ) -> f64 {
        let elements_per_second = if duration.as_secs_f64() > 0.0 {
            elements as f64 / duration.as_secs_f64()
        } else {
            0.0
        };

        // Normalize to a 0-100 score (100M elements/sec = 100 points)
        (elements_per_second / 1_000_000.0).min(100.0)
    }

    /// Execute advanced-optimized CPU generation with SIMD
    fn execute_advanced_cpu_generation(
        &self,
        rows: usize,
        cols: usize,
        distribution: &str,
    ) -> Result<Array2<f64>> {
        use scirs2_core::random::{rng, Rng};
        use scirs2_core::random::{Distribution, Normal, Uniform};

        let _rng = thread_rng();
        let total_elements = rows * cols;

        // Generate data in parallel chunks
        let chunk_size = (total_elements / num_cpus::get()).max(1000);

        let data: Vec<f64> = (0..total_elements)
            .into_par_iter()
            .chunks(chunk_size)
            .flat_map(|chunk| {
                let mut local_rng = thread_rng();
                chunk
                    .into_iter()
                    .map(|_| match distribution {
                        "normal" => {
                            let normal = Normal::new(0.0, 1.0).expect("Operation failed");
                            normal.sample(&mut local_rng)
                        }
                        "uniform" => {
                            let uniform = Uniform::new(0.0, 1.0).expect("Operation failed");
                            uniform.sample(&mut local_rng)
                        }
                        _ => local_rng.random::<f64>(),
                    })
                    .collect::<Vec<_>>()
            })
            .collect();

        Array2::from_shape_vec((rows, cols), data)
            .map_err(|e| DatasetsError::Other(format!("Failed to create array: {e}")))
    }

    /// Benchmark GPU vs CPU performance
    ///
    /// Every timing in the returned [`BenchmarkResult`] is a genuine
    /// `Instant`-measured wall-clock duration. `gpu_time_ms` / `speedup` are
    /// `None` whenever the configured backend is [`GpuBackend::Cpu`] or no
    /// adapter accepted the workload — this crate never reports a
    /// fabricated ratio (the historical implementation hardcoded a hard
    /// 0.1×/0.2× "10x/5x speedup" factor for Cuda/OpenCl regardless of
    /// whether any GPU work actually happened).
    pub fn benchmark_performance(
        &self,
        gpu_context: &GpuContext,
        operation: &str,
        datashapes: &[(usize, usize)],
    ) -> Result<PerformanceBenchmarkResults> {
        use std::time::Instant;

        let mut results = Vec::new();

        for &shape in datashapes {
            // Keep the auto-tuning cache populated for this shape (existing
            // contract); the tuned config itself isn't needed further here
            // since dispatch below is unified across backends.
            let _config = self.optimize_execution(gpu_context, operation, shape)?;

            let cpu_start = Instant::now();
            let cpu_matrix = self.execute_advanced_cpu_generation(shape.0, shape.1, "uniform")?;
            let cpu_time_ms = cpu_start.elapsed().as_secs_f64() * 1000.0;

            let gpu_time_ms = if matches!(gpu_context.backend(), GpuBackend::Cpu) {
                None
            } else {
                attempt_gpu_round_trip(cpu_matrix.as_slice().unwrap_or(&[]))
                    .map(|d| d.as_secs_f64() * 1000.0)
            };

            // Only ever a real ratio of two measured durations, and only
            // when the GPU genuinely ran (guarding against division by a
            // measured-zero duration too).
            let speedup = gpu_time_ms.filter(|&g| g > 0.0).map(|g| cpu_time_ms / g);

            results.push(BenchmarkResult {
                datashape: shape,
                cpu_time_ms,
                gpu_time_ms,
                speedup,
                memory_usage_mb: self.estimate_memory_usage(shape),
            });
        }

        Ok(PerformanceBenchmarkResults { results })
    }

    /// Estimate memory usage
    fn estimate_memory_usage(&self, shape: (usize, usize)) -> f64 {
        let total_elements = shape.0 * shape.1;
        let bytes_per_element = 8; // f64
        (total_elements * bytes_per_element) as f64 / (1024.0 * 1024.0) // Convert to MB
    }
}

/// Performance benchmark results
#[derive(Debug, Clone)]
pub struct PerformanceBenchmarkResults {
    /// Individual benchmark results
    pub results: Vec<BenchmarkResult>,
}

/// Individual benchmark result
#[derive(Debug, Clone)]
pub struct BenchmarkResult {
    /// Data shape (rows, cols)
    pub datashape: (usize, usize),
    /// CPU execution time in milliseconds — always measured, since the
    /// baseline generation always genuinely runs on the host.
    pub cpu_time_ms: f64,
    /// GPU execution time in milliseconds, present only when a real GPU
    /// dispatch actually executed (the configured backend was not
    /// [`GpuBackend::Cpu`] *and* a wgpu adapter genuinely accepted the
    /// workload). `None` — never a fabricated number — otherwise.
    pub gpu_time_ms: Option<f64>,
    /// Speedup factor (`cpu_time_ms / gpu_time_ms`), present only alongside
    /// `gpu_time_ms`. `None` on CPU-only runs or when no adapter was
    /// available: this crate never reports an invented ratio when no GPU
    /// dispatch actually happened.
    pub speedup: Option<f64>,
    /// Memory usage in MB
    pub memory_usage_mb: f64,
}

impl PerformanceBenchmarkResults {
    /// Best speedup actually measured across all benchmarked shapes.
    ///
    /// `None` if no shape triggered a real GPU dispatch (CPU-only backend,
    /// or no adapter was available at run time) — never a fabricated
    /// fallback value such as `1.0`.
    pub fn best_speedup(&self) -> Option<f64> {
        self.results
            .iter()
            .filter_map(|r| r.speedup)
            .fold(None, |acc, s| Some(acc.map_or(s, |a: f64| a.max(s))))
    }

    /// Average of the actually-measured speedups.
    ///
    /// `None` if none of the benchmarked shapes triggered a real GPU
    /// dispatch.
    pub fn average_speedup(&self) -> Option<f64> {
        let (total, count) = self
            .results
            .iter()
            .filter_map(|r| r.speedup)
            .fold((0.0, 0usize), |(total, count), s| (total + s, count + 1));

        if count == 0 {
            None
        } else {
            Some(total / count as f64)
        }
    }

    /// Get total memory usage
    pub fn total_memory_usage(&self) -> f64 {
        self.results.iter().map(|r| r.memory_usage_mb).sum()
    }
}

/// Convenience function for advanced-optimized matrix generation
#[allow(dead_code)]
pub fn generate_advanced_matrix(
    gpu_context: &GpuContext,
    rows: usize,
    cols: usize,
    distribution: &str,
) -> Result<Array2<f64>> {
    let optimizer = AdvancedGpuOptimizer::new();
    optimizer.generate_advanced_optimized_matrix(gpu_context, rows, cols, distribution)
}

/// Convenience function for performance benchmarking
#[allow(dead_code)]
pub fn benchmark_advanced_performance(
    gpu_context: &GpuContext,
    operation: &str,
    datashapes: &[(usize, usize)],
) -> Result<PerformanceBenchmarkResults> {
    let optimizer = AdvancedGpuOptimizer::new();
    optimizer.benchmark_performance(gpu_context, operation, datashapes)
}

impl std::fmt::Display for GpuBackend {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            GpuBackend::Cuda { .. } => write!(f, "cuda"),
            GpuBackend::OpenCl { .. } => write!(f, "opencl"),
            GpuBackend::Cpu => write!(f, "cpu"),
        }
    }
}

/// Advanced MODE ENHANCEMENTS
/// Advanced AI-driven optimization and real-time monitoring capabilities
/// AI-driven performance predictor using machine learning
#[derive(Debug, Clone)]
pub struct AIPerformancePredictor {
    /// Historical performance data for training
    training_data: Vec<PerformanceDataPoint>,
    /// Model parameters (simplified neural network weights)
    model_weights: Vec<f64>,
    /// Feature normalization parameters
    feature_means: Vec<f64>,
    feature_stds: Vec<f64>,
    /// Prediction accuracy metrics
    accuracy_metrics: PredictionAccuracy,
}

/// Performance data point for ML training
#[derive(Debug, Clone)]
#[allow(dead_code)]
pub struct PerformanceDataPoint {
    /// Input features: [problem_size, memory_access_pattern, compute_intensity, parallelism_factor]
    features: Vec<f64>,
    /// Target performance score
    target_performance: f64,
    /// Measured execution time
    execution_time: f64,
}

/// Prediction accuracy metrics
#[derive(Debug, Clone)]
pub struct PredictionAccuracy {
    /// Mean absolute error
    mae: f64,
    /// Root mean squared error
    rmse: f64,
    /// R-squared score
    r_squared: f64,
    /// Number of training samples
    sample_count: usize,
}

impl Default for AIPerformancePredictor {
    fn default() -> Self {
        Self {
            training_data: Vec::new(),
            model_weights: vec![0.1, 0.2, 0.3, 0.4, 0.5], // Simple linear model
            feature_means: vec![0.0; 4],
            feature_stds: vec![1.0; 4],
            accuracy_metrics: PredictionAccuracy {
                mae: 0.0,
                rmse: 0.0,
                r_squared: 0.0,
                sample_count: 0,
            },
        }
    }
}

impl AIPerformancePredictor {
    /// Create a new AI performance predictor
    pub fn new() -> Self {
        Self::default()
    }

    /// Add training data point
    pub fn add_training_data(&mut self, datapoint: PerformanceDataPoint) {
        self.training_data.push(datapoint);

        // Retrain model if we have enough data
        if self.training_data.len().is_multiple_of(100) && self.training_data.len() > 50 {
            self.retrain_model();
        }
    }

    /// Predict performance for given configuration
    pub fn predict_performance(&self, features: &[f64]) -> f64 {
        if features.len() != 4 {
            return 0.5; // Default prediction
        }

        // Normalize features
        let normalized_features: Vec<f64> = features
            .iter()
            .zip(&self.feature_means)
            .zip(&self.feature_stds)
            .map(|((feat, mean), std)| (feat - mean) / std)
            .collect();

        // Simple linear prediction
        let prediction: f64 = normalized_features
            .iter()
            .zip(&self.model_weights)
            .map(|(feat, weight)| feat * weight)
            .sum();

        // Apply sigmoid activation and clamp to [0, 1]
        (1.0 / (1.0 + (-prediction).exp())).clamp(0.0, 1.0)
    }

    /// Retrain the model using accumulated data
    fn retrain_model(&mut self) {
        if self.training_data.len() < 10 {
            return;
        }

        // Calculate feature normalization parameters
        self.update_normalization_params();

        // Simple gradient descent training
        let learning_rate = 0.01;
        let epochs = 100;

        for _ in 0..epochs {
            let mut gradients = [0.0; 5];

            for data_point in &self.training_data {
                let prediction = self.predict_performance(&data_point.features);
                let error = prediction - data_point.target_performance;

                // Calculate gradients
                for (i, gradient) in gradients.iter_mut().enumerate().take(4) {
                    *gradient += error * data_point.features[i] / self.training_data.len() as f64;
                }
                gradients[4] += error / self.training_data.len() as f64; // Bias term
            }

            // Update weights
            for (weight, gradient) in self.model_weights.iter_mut().zip(gradients.iter()) {
                *weight -= learning_rate * gradient;
            }
        }

        // Update accuracy metrics
        self.update_accuracy_metrics();
    }

    /// Update feature normalization parameters
    fn update_normalization_params(&mut self) {
        let n = self.training_data.len() as f64;

        // Calculate means
        for i in 0..4 {
            self.feature_means[i] = self
                .training_data
                .iter()
                .map(|dp| dp.features[i])
                .sum::<f64>()
                / n;
        }

        // Calculate standard deviations
        for i in 0..4 {
            let variance = self
                .training_data
                .iter()
                .map(|dp| (dp.features[i] - self.feature_means[i]).powi(2))
                .sum::<f64>()
                / n;
            self.feature_stds[i] = variance.sqrt().max(1e-8); // Avoid division by zero
        }
    }

    /// Update accuracy metrics
    fn update_accuracy_metrics(&mut self) {
        let predictions: Vec<f64> = self
            .training_data
            .iter()
            .map(|dp| self.predict_performance(&dp.features))
            .collect();

        let targets: Vec<f64> = self
            .training_data
            .iter()
            .map(|dp| dp.target_performance)
            .collect();

        // Calculate MAE
        self.accuracy_metrics.mae = predictions
            .iter()
            .zip(&targets)
            .map(|(pred, target)| (pred - target).abs())
            .sum::<f64>()
            / predictions.len() as f64;

        // Calculate RMSE
        let mse = predictions
            .iter()
            .zip(&targets)
            .map(|(pred, target)| (pred - target).powi(2))
            .sum::<f64>()
            / predictions.len() as f64;
        self.accuracy_metrics.rmse = mse.sqrt();

        // Calculate R-squared
        let target_mean = targets.iter().sum::<f64>() / targets.len() as f64;
        let ss_tot = targets
            .iter()
            .map(|target| (target - target_mean).powi(2))
            .sum::<f64>();
        let ss_res = predictions
            .iter()
            .zip(&targets)
            .map(|(pred, target)| (target - pred).powi(2))
            .sum::<f64>();

        self.accuracy_metrics.r_squared = if ss_tot > 0.0 {
            1.0 - (ss_res / ss_tot)
        } else {
            0.0
        };

        self.accuracy_metrics.sample_count = self.training_data.len();
    }

    /// Get model accuracy metrics
    pub fn get_accuracy_metrics(&self) -> &PredictionAccuracy {
        &self.accuracy_metrics
    }
}

/// Real-time performance monitor with adaptive optimization
#[derive(Debug)]
pub struct RealTimePerformanceMonitor {
    /// Performance history
    performance_history: std::collections::VecDeque<PerformanceSnapshot>,
    /// Current optimization state
    current_optimization: AdaptiveOptimizationState,
    /// Monitoring configuration
    config: MonitoringConfig,
    /// AI predictor
    ai_predictor: AIPerformancePredictor,
}

/// Performance snapshot at a specific point in time
#[derive(Debug, Clone)]
#[allow(dead_code)]
pub struct PerformanceSnapshot {
    /// Timestamp
    timestamp: std::time::Instant,
    /// Execution time in milliseconds
    execution_time_ms: f64,
    /// Memory usage in bytes
    memory_usage_bytes: usize,
    /// GPU utilization percentage
    gpu_utilization: f64,
    /// Memory bandwidth utilization
    memory_bandwidth_utilization: f64,
    /// Operation being performed
    operation: String,
    /// Data shape
    datashape: (usize, usize),
}

/// Adaptive optimization state
#[derive(Debug, Clone)]
#[allow(dead_code)]
pub struct AdaptiveOptimizationState {
    /// Current performance trend
    trend: PerformanceTrend,
    /// Optimization adjustments made
    adjustments: Vec<OptimizationAdjustment>,
    /// Learning rate for adaptation
    learning_rate: f64,
    /// Stability threshold
    stability_threshold: f64,
}

/// Performance trend analysis
#[derive(Debug, Clone, Copy)]
pub enum PerformanceTrend {
    /// Performance is improving
    Improving,
    /// Performance is degrading
    Degrading,
    /// Performance is stable
    Stable,
    /// Insufficient data for trend analysis
    Unknown,
}

/// Optimization adjustment made by the adaptive system
#[derive(Debug, Clone)]
#[allow(dead_code)]
pub struct OptimizationAdjustment {
    /// Type of adjustment
    adjustment_type: AdjustmentType,
    /// Previous value
    previous_value: f64,
    /// New value
    new_value: f64,
    /// Impact on performance (positive = improvement)
    performance_impact: f64,
    /// Timestamp of adjustment
    timestamp: std::time::Instant,
}

/// Types of optimization adjustments
#[derive(Debug, Clone, Copy)]
pub enum AdjustmentType {
    /// Block size adjustment
    BlockSize,
    /// Memory access pattern change
    MemoryPattern,
    /// Vectorization strategy change
    Vectorization,
    /// Load balancing method change
    LoadBalancing,
}

/// Monitoring configuration
#[derive(Debug, Clone)]
#[allow(dead_code)]
pub struct MonitoringConfig {
    /// Maximum history size
    max_history_size: usize,
    /// Minimum samples for trend analysis
    min_samples_for_trend: usize,
    /// Performance degradation threshold
    degradation_threshold: f64,
    /// Adaptation enabled
    adaptive_optimization_enabled: bool,
}

impl Default for MonitoringConfig {
    fn default() -> Self {
        Self {
            max_history_size: 1000,
            min_samples_for_trend: 10,
            degradation_threshold: 0.05, // 5% degradation triggers adaptation
            adaptive_optimization_enabled: true,
        }
    }
}

impl Default for RealTimePerformanceMonitor {
    fn default() -> Self {
        Self::with_config(MonitoringConfig::default())
    }
}

impl RealTimePerformanceMonitor {
    /// Create a new real-time performance monitor
    pub fn new() -> Self {
        Self::default()
    }

    /// Create with custom configuration
    pub fn with_config(config: MonitoringConfig) -> Self {
        Self {
            performance_history: std::collections::VecDeque::with_capacity(config.max_history_size),
            current_optimization: AdaptiveOptimizationState {
                trend: PerformanceTrend::Unknown,
                adjustments: Vec::new(),
                learning_rate: 0.1,
                stability_threshold: 0.02,
            },
            config,
            ai_predictor: AIPerformancePredictor::new(),
        }
    }

    /// Record a performance snapshot
    pub fn record_performance(&mut self, snapshot: PerformanceSnapshot) {
        // Add to history
        if self.performance_history.len() >= self.config.max_history_size {
            self.performance_history.pop_front();
        }
        self.performance_history.push_back(snapshot.clone());

        // Add training data to AI predictor
        let features = vec![
            (snapshot.datashape.0 * snapshot.datashape.1) as f64, // Problem size
            snapshot.memory_bandwidth_utilization,                // Memory access pattern
            snapshot.gpu_utilization,                             // Compute intensity
            1.0,                                                  // Parallelism factor (simplified)
        ];

        let performance_score = 1.0 / (1.0 + snapshot.execution_time_ms / 1000.0); // Normalized performance

        self.ai_predictor.add_training_data(PerformanceDataPoint {
            features,
            target_performance: performance_score,
            execution_time: snapshot.execution_time_ms,
        });

        // Analyze trend and adapt if necessary
        self.analyze_trend_and_adapt();
    }

    /// Analyze performance trend and trigger adaptive optimization
    fn analyze_trend_and_adapt(&mut self) {
        if self.performance_history.len() < self.config.min_samples_for_trend {
            return;
        }

        // Calculate recent performance trend
        let recent_samples = self.performance_history.len().min(20);
        let recent_performances: Vec<f64> = self
            .performance_history
            .iter()
            .rev()
            .take(recent_samples)
            .map(|snapshot| 1.0 / (1.0 + snapshot.execution_time_ms / 1000.0))
            .collect();

        let trend = self.calculate_trend(&recent_performances);
        self.current_optimization.trend = trend;

        // Trigger adaptation if performance is degrading
        if matches!(trend, PerformanceTrend::Degrading) && self.config.adaptive_optimization_enabled
        {
            self.trigger_adaptive_optimization();
        }
    }

    /// Calculate performance trend from recent samples
    fn calculate_trend(&self, performances: &[f64]) -> PerformanceTrend {
        if performances.len() < 3 {
            return PerformanceTrend::Unknown;
        }

        // Simple linear regression to detect trend
        let n = performances.len() as f64;
        let x_mean = (n - 1.0) / 2.0; // Mean of indices
        let y_mean = performances.iter().sum::<f64>() / n;

        let mut numerator = 0.0;
        let mut denominator = 0.0;

        for (i, &y) in performances.iter().enumerate() {
            let x = i as f64;
            numerator += (x - x_mean) * (y - y_mean);
            denominator += (x - x_mean).powi(2);
        }

        let slope = if denominator != 0.0 {
            numerator / denominator
        } else {
            0.0
        };

        if slope > self.current_optimization.stability_threshold {
            PerformanceTrend::Improving
        } else if slope < -self.current_optimization.stability_threshold {
            PerformanceTrend::Degrading
        } else {
            PerformanceTrend::Stable
        }
    }

    /// Trigger adaptive optimization to improve performance
    fn trigger_adaptive_optimization(&mut self) {
        // Use AI predictor to suggest optimizations
        if let Some(latest_snapshot) = self.performance_history.back() {
            let current_features = vec![
                (latest_snapshot.datashape.0 * latest_snapshot.datashape.1) as f64,
                latest_snapshot.memory_bandwidth_utilization,
                latest_snapshot.gpu_utilization,
                1.0,
            ];

            let predicted_performance = self.ai_predictor.predict_performance(&current_features);

            // If predicted performance is low, suggest adjustments
            if predicted_performance < 0.7 {
                let adjustment = OptimizationAdjustment {
                    adjustment_type: AdjustmentType::BlockSize,
                    previous_value: 256.0,
                    new_value: 512.0,        // Increase block size
                    performance_impact: 0.0, // Will be measured later
                    timestamp: std::time::Instant::now(),
                };

                self.current_optimization.adjustments.push(adjustment);
            }
        }
    }

    /// Get current performance trend
    pub fn get_current_trend(&self) -> PerformanceTrend {
        self.current_optimization.trend
    }

    /// Get recent performance statistics
    pub fn get_performance_stats(&self) -> PerformanceStats {
        if self.performance_history.is_empty() {
            return PerformanceStats::default();
        }

        let execution_times: Vec<f64> = self
            .performance_history
            .iter()
            .map(|snapshot| snapshot.execution_time_ms)
            .collect();

        let mean_execution_time =
            execution_times.iter().sum::<f64>() / execution_times.len() as f64;
        let min_execution_time = execution_times.iter().fold(f64::INFINITY, |a, &b| a.min(b));
        let max_execution_time = execution_times.iter().fold(0.0f64, |a, &b| a.max(b));

        let mean_gpu_utilization = self
            .performance_history
            .iter()
            .map(|snapshot| snapshot.gpu_utilization)
            .sum::<f64>()
            / self.performance_history.len() as f64;

        PerformanceStats {
            mean_execution_time_ms: mean_execution_time,
            min_execution_time_ms: min_execution_time,
            max_execution_time_ms: max_execution_time,
            mean_gpu_utilization,
            sample_count: self.performance_history.len(),
            ai_model_accuracy: self.ai_predictor.get_accuracy_metrics().r_squared,
        }
    }
}

/// Performance statistics summary
#[derive(Debug, Clone)]
pub struct PerformanceStats {
    /// Mean execution time in milliseconds
    pub mean_execution_time_ms: f64,
    /// Minimum execution time in milliseconds
    pub min_execution_time_ms: f64,
    /// Maximum execution time in milliseconds
    pub max_execution_time_ms: f64,
    /// Mean GPU utilization percentage
    pub mean_gpu_utilization: f64,
    /// Number of samples
    pub sample_count: usize,
    /// AI model prediction accuracy (R-squared)
    pub ai_model_accuracy: f64,
}

impl Default for PerformanceStats {
    fn default() -> Self {
        Self {
            mean_execution_time_ms: 0.0,
            min_execution_time_ms: 0.0,
            max_execution_time_ms: 0.0,
            mean_gpu_utilization: 0.0,
            sample_count: 0,
            ai_model_accuracy: 0.0,
        }
    }
}

/// Enhanced AdvancedGpuOptimizer with AI and real-time monitoring
impl AdvancedGpuOptimizer {
    /// Create optimizer with AI-driven optimization and real-time monitoring
    pub fn with_ai_monitoring() -> Self {
        // In a full implementation, this would integrate the AI predictor and monitor
        Self::new()
    }

    /// Predict optimal configuration using AI
    pub fn predict_optimal_config(
        &self,
        operation: &str,
        datashape: (usize, usize),
        historical_data: &[PerformanceDataPoint],
    ) -> Result<AdvancedKernelConfig> {
        let mut ai_predictor = AIPerformancePredictor::new();

        // Train on historical _data
        for data_point in historical_data {
            ai_predictor.add_training_data(data_point.clone());
        }

        // Generate features for current scenario
        let features = vec![
            (datashape.0 * datashape.1) as f64,
            1.0, // Default memory access pattern
            self.estimate_compute_utilization(operation, datashape),
            1.0, // Default parallelism factor
        ];

        let predicted_performance = ai_predictor.predict_performance(&features);

        // Convert prediction to kernel configuration
        let specialization_level = if predicted_performance > 0.8 {
            SpecializationLevel::AIOptimized
        } else if predicted_performance > 0.6 {
            SpecializationLevel::AdvancedSpecialized
        } else {
            SpecializationLevel::HardwareOptimized
        };

        Ok(AdvancedKernelConfig {
            specialization_level,
            memory_pattern: MemoryAccessPattern::Sequential,
            vectorization: VectorizationStrategy::Adaptive,
            load_balancing: LoadBalancingMethod::Adaptive,
            block_size: 256,
        })
    }
}

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

    #[test]
    fn test_advanced_gpu_optimizer_creation() {
        let optimizer = AdvancedGpuOptimizer::new();
        assert!(optimizer.adaptive_kernels);
        assert!(optimizer.auto_tuning);
    }

    #[test]
    fn test_performance_calculation() {
        let optimizer = AdvancedGpuOptimizer::new();
        let score = optimizer.calculate_performance_score(256, 1e6, 0.8);
        assert!((0.0..=1.0).contains(&score));
    }

    #[test]
    fn test_advanced_cpu_generation() {
        let optimizer = AdvancedGpuOptimizer::new();
        let result = optimizer.execute_advanced_cpu_generation(10, 10, "normal");
        assert!(result.is_ok());
        let matrix = result.expect("Operation failed");
        assert_eq!(matrix.shape(), &[10, 10]);
    }

    /// Regression test for a latent bug found while removing the
    /// simulation: `profile_to_kernel_config` used to hardcode
    /// `block_size: 256` unconditionally, silently discarding
    /// `profile.optimal_block_size`. A tuned profile recommending 512 must
    /// now actually propagate into the returned config.
    #[test]
    fn test_profile_to_kernel_config_uses_tuned_block_size_not_hardcoded() {
        let optimizer = AdvancedGpuOptimizer::new();
        let profile = GpuPerformanceProfile {
            optimal_block_size: 512,
            memory_bandwidth: 1e9,
            compute_utilization: 0.9,
            optimal_layout: DataLayout::RowMajor,
            performance_score: 0.9,
        };
        let config = optimizer.profile_to_kernel_config(&profile);
        assert_eq!(config.block_size, 512);

        let profile_small = GpuPerformanceProfile {
            optimal_block_size: 32,
            ..profile
        };
        let config_small = optimizer.profile_to_kernel_config(&profile_small);
        assert_eq!(config_small.block_size, 32);
        assert_ne!(config_small.block_size, config.block_size);
    }

    /// Confirms `benchmark_performance` never fabricates a speedup: on an
    /// explicitly CPU-only backend no GPU dispatch is ever attempted, so
    /// every result must honestly report `None` — not the historical
    /// hardcoded 0.1/0.2 CUDA/OpenCL "10x/5x speedup" factors, nor a
    /// disguised `1.0`. Also confirms reported numbers genuinely scale with
    /// the workload (memory usage) rather than being fixed constants.
    #[test]
    fn test_benchmark_performance_reports_real_measurements_not_fabricated_speedup() {
        let optimizer = AdvancedGpuOptimizer::new();
        let gpu_context = GpuContext::new(GpuConfig {
            backend: GpuBackend::Cpu,
            threads_per_block: 1,
            ..Default::default()
        })
        .expect("CPU GpuContext should always construct");

        let shapes = [(20, 20), (300, 300)];
        let results = optimizer
            .benchmark_performance(&gpu_context, "matrix_generation", &shapes)
            .expect("benchmark_performance should succeed");

        assert_eq!(results.results.len(), 2);
        for r in &results.results {
            assert!(
                r.gpu_time_ms.is_none(),
                "CPU-only backend must never report a GPU time"
            );
            assert!(
                r.speedup.is_none(),
                "CPU-only backend must never report a fabricated speedup"
            );
            assert!(r.cpu_time_ms >= 0.0 && r.cpu_time_ms.is_finite());
        }
        assert!(results.best_speedup().is_none());
        assert!(results.average_speedup().is_none());

        // memory_usage_mb is a deterministic function of shape (not
        // timing), so this is a flake-free way to prove the two results
        // genuinely differ with the workload rather than being constants.
        let small_mem = results.results[0].memory_usage_mb;
        let large_mem = results.results[1].memory_usage_mb;
        assert!(large_mem > small_mem * 100.0);
    }

    /// `auto_tune_operation` used to synthesize `memory_bandwidth` and
    /// `compute_utilization` from static per-operation-name lookup tables
    /// (e.g. `"trigonometric" => 10.0` compute intensity, regardless of any
    /// real dispatch). Both now come from a genuinely timed calibration;
    /// sanity-check the results are real, finite, in-range numbers, and
    /// that the operation/shape-sensitive planning fields
    /// (`optimal_layout`) still vary as they did before.
    #[test]
    fn test_auto_tuned_profile_is_internally_consistent_real_measurement() {
        let optimizer = AdvancedGpuOptimizer::new();
        let gpu_context = GpuContext::new(GpuConfig {
            backend: GpuBackend::Cpu,
            threads_per_block: 1,
            ..Default::default()
        })
        .expect("CPU GpuContext should always construct");

        let profile_matmul = optimizer
            .auto_tune_operation(&gpu_context, "matrix_multiply", (64, 64))
            .expect("auto_tune_operation should succeed");
        let profile_trig = optimizer
            .auto_tune_operation(&gpu_context, "trigonometric", (64, 64))
            .expect("auto_tune_operation should succeed");

        for profile in [&profile_matmul, &profile_trig] {
            assert!(profile.memory_bandwidth.is_finite());
            assert!(profile.memory_bandwidth >= 0.0);
            assert!((0.0..=1.0).contains(&profile.compute_utilization));
            assert!((0.0..=1.0).contains(&profile.performance_score));
        }

        // Planning (not measurement) still legitimately varies by
        // operation name: "matrix_multiply" at this shape recommends
        // RowMajor, while an unrecognized operation like "trigonometric"
        // falls back to Adaptive.
        assert!(matches!(
            profile_matmul.optimal_layout,
            DataLayout::RowMajor
        ));
        assert!(matches!(profile_trig.optimal_layout, DataLayout::Adaptive));
    }

    /// When a real wgpu adapter is present (verified via the same probe the
    /// production path uses), requesting a non-CPU backend for a
    /// large-enough workload must produce a genuinely measured speedup —
    /// never one of the historical hardcoded 0.1×/0.2× factors (whose
    /// exact reciprocals are 10.0/5.0). When no adapter is available this
    /// degrades gracefully to `None`, per the crate-wide fallback contract.
    #[test]
    fn test_gpu_backend_speedup_reflects_real_dispatch_when_available() {
        #[cfg(feature = "wgpu")]
        {
            use scirs2_core::array_protocol::gpu_ndarray::is_gpu_available;
            if !is_gpu_available() {
                eprintln!("skipping: no wgpu adapter available in this environment");
                return;
            }

            let optimizer = AdvancedGpuOptimizer::new();
            let gpu_context = GpuContext::new(GpuConfig {
                backend: GpuBackend::Cuda { device_id: 0 },
                ..Default::default()
            })
            .expect("Cuda-flavored GpuContext should construct (query is simulated device info, no real NVIDIA driver required)");

            // 128 x 128 = 16,384 elements: above GPU_OPT_THRESHOLD (4096).
            let shapes = [(128, 128)];
            let results = optimizer
                .benchmark_performance(&gpu_context, "matrix_generation", &shapes)
                .expect("benchmark_performance should succeed");

            let r = &results.results[0];
            assert!(
                r.gpu_time_ms.is_some(),
                "expected a real GPU dispatch to have run"
            );
            assert!(r.gpu_time_ms.expect("checked above") > 0.0);
            if let Some(speedup) = r.speedup {
                assert!(speedup > 0.0 && speedup.is_finite());
                assert!(
                    (speedup - 10.0).abs() > 1e-9,
                    "matches old hardcoded CUDA factor"
                );
                assert!(
                    (speedup - 5.0).abs() > 1e-9,
                    "matches old hardcoded OpenCL factor"
                );
            }
        }
    }
}