trustformers_optim/

hardware_aware.rs

// reason: research-stage module — reserved API/scaffolding fields and methods
// retained intentionally for in-progress features; not yet on active call paths.
#![allow(dead_code)]

use crate::{
    adam::{Adam, AdamW},
    sgd::SGD,
};
/// Hardware-Aware Optimizers
///
/// This module provides optimizers specifically designed for different hardware targets:
/// - GPU optimizers with CUDA/ROCm optimizations
/// - TPU optimizers with reduced precision and specific kernels
/// - Mobile optimizers with memory and computation constraints
/// - Edge computing optimizers for IoT devices
use std::collections::HashMap;
use trustformers_core::{errors::Result, tensor::Tensor, traits::Optimizer};

/// Hardware target for optimization
#[derive(Debug, Clone, PartialEq)]
pub enum HardwareTarget {
    GPU {
        memory_gb: f32,
        compute_capability: f32,
        use_tensor_cores: bool,
    },
    TPU {
        version: TPUVersion,
        num_cores: usize,
        use_bfloat16: bool,
    },
    Mobile {
        memory_mb: usize,
        cpu_cores: usize,
        target_latency_ms: f32,
    },
    Edge {
        memory_mb: usize,
        power_budget_mw: f32,
        quantization_bits: u8,
    },
}

#[derive(Debug, Clone, PartialEq)]
pub enum TPUVersion {
    V2,
    V3,
    V4,
    V5,
}

/// Hardware-aware optimizer configuration
#[derive(Debug, Clone)]
pub struct HardwareAwareConfig {
    pub target: HardwareTarget,
    pub base_learning_rate: f32,
    pub enable_fusion: bool,
    pub memory_efficient: bool,
    pub use_mixed_precision: bool,
    pub gradient_compression: Option<CompressionRatio>,
    pub custom_kernels: bool,
}

#[derive(Debug, Clone)]
pub enum CompressionRatio {
    Half,    // 16-bit
    Quarter, // 8-bit
    Eighth,  // 4-bit
}

/// GPU-optimized Adam optimizer
pub struct GPUAdam {
    base_adam: Adam,
    config: HardwareAwareConfig,
    use_tensor_cores: bool,
    memory_pool: Option<GPUMemoryPool>,
    kernel_fusion_cache: HashMap<String, ComputeKernel>,
}

impl GPUAdam {
    pub fn new(config: HardwareAwareConfig) -> Result<Self> {
        if let HardwareTarget::GPU {
            use_tensor_cores, ..
        } = config.target
        {
            let base_adam = Adam::new(config.base_learning_rate, (0.9, 0.999), 1e-8, 0.0);

            let memory_pool =
                if config.memory_efficient { Some(GPUMemoryPool::new()?) } else { None };

            Ok(Self {
                base_adam,
                config,
                use_tensor_cores,
                memory_pool,
                kernel_fusion_cache: HashMap::new(),
            })
        } else {
            Err(
                trustformers_core::errors::TrustformersError::invalid_config(
                    "GPUAdam requires GPU target".to_string(),
                ),
            )
        }
    }

    /// Optimize for specific GPU architecture
    pub fn optimize_for_gpu(&mut self, compute_capability: f32) -> Result<()> {
        // Enable specific optimizations based on compute capability
        match compute_capability {
            cc if cc >= 8.0 => {
                // Ampere and newer: enable advanced tensor core features
                self.enable_sparse_tensor_cores()?;
                self.enable_async_copy()?;
            },
            cc if cc >= 7.0 => {
                // Turing/Volta: enable basic tensor cores
                self.enable_tensor_cores()?;
            },
            _ => {
                // Older architectures: use standard optimizations
                self.enable_memory_coalescing()?;
            },
        }
        Ok(())
    }

    fn enable_sparse_tensor_cores(&mut self) -> Result<()> {
        // Enable sparse matrix optimizations for Ampere
        // This would interface with cuSPARSE or similar libraries
        Ok(())
    }

    fn enable_async_copy(&mut self) -> Result<()> {
        // Enable asynchronous memory transfers
        Ok(())
    }

    fn enable_tensor_cores(&mut self) -> Result<()> {
        // Enable mixed-precision with tensor cores
        self.use_tensor_cores = true;
        Ok(())
    }

    fn enable_memory_coalescing(&mut self) -> Result<()> {
        // Optimize memory access patterns
        Ok(())
    }
}

impl Optimizer for GPUAdam {
    fn update(&mut self, parameter: &mut Tensor, grad: &Tensor) -> Result<()> {
        self.base_adam.update(parameter, grad)
    }

    fn zero_grad(&mut self) {
        self.base_adam.zero_grad()
    }

    fn step(&mut self) {
        self.base_adam.step()
    }

    fn get_lr(&self) -> f32 {
        self.base_adam.get_lr()
    }

    fn set_lr(&mut self, lr: f32) {
        self.base_adam.set_lr(lr)
    }
}

impl GPUAdam {
    fn can_fuse_operations(&self, parameters: &[Tensor]) -> bool {
        // Check if parameters are suitable for kernel fusion
        parameters.len() < 100 && self.config.enable_fusion
    }

    fn fused_adam_step(&mut self, parameters: &mut [Tensor], gradients: &[Tensor]) -> Result<()> {
        // Implement fused Adam kernel
        // This would call optimized CUDA/ROCm kernels
        for (param, grad) in parameters.iter_mut().zip(gradients.iter()) {
            self.base_adam.update(param, grad)?;
        }
        self.base_adam.step();
        Ok(())
    }
}

/// TPU-optimized optimizer
pub struct TPUOptimizer {
    base_optimizer: Box<dyn Optimizer>,
    config: HardwareAwareConfig,
    tpu_version: TPUVersion,
    use_bfloat16: bool,
    sharding_strategy: TPUShardingStrategy,
}

#[derive(Debug, Clone)]
pub enum TPUShardingStrategy {
    FullySharded,
    GradientSharded,
    ParameterSharded,
}

impl TPUOptimizer {
    pub fn new(base_optimizer: Box<dyn Optimizer>, config: HardwareAwareConfig) -> Result<Self> {
        if let HardwareTarget::TPU {
            ref version,
            use_bfloat16,
            ..
        } = config.target
        {
            let tpu_version = version.clone();
            Ok(Self {
                base_optimizer,
                config,
                tpu_version,
                use_bfloat16,
                sharding_strategy: TPUShardingStrategy::FullySharded,
            })
        } else {
            Err(
                trustformers_core::errors::TrustformersError::invalid_config(
                    "TPUOptimizer requires TPU target".to_string(),
                ),
            )
        }
    }

    /// Optimize gradient computation for TPU
    fn tpu_optimized_gradients(&self, gradients: &[Tensor]) -> Result<Vec<Tensor>> {
        let mut optimized = Vec::new();

        for grad in gradients {
            let mut opt_grad = grad.clone();

            // Convert to bfloat16 if enabled
            if self.use_bfloat16 {
                opt_grad = self.convert_to_bfloat16(&opt_grad)?;
            }

            // Apply TPU-specific optimizations
            opt_grad = self.optimize_for_tpu_memory_layout(&opt_grad)?;

            optimized.push(opt_grad);
        }

        Ok(optimized)
    }

    fn convert_to_bfloat16(&self, tensor: &Tensor) -> Result<Tensor> {
        // Convert to bfloat16 for TPU efficiency
        // This would use specialized TPU libraries
        Ok(tensor.clone())
    }

    fn optimize_for_tpu_memory_layout(&self, tensor: &Tensor) -> Result<Tensor> {
        // Optimize tensor layout for TPU memory hierarchy
        Ok(tensor.clone())
    }
}

impl Optimizer for TPUOptimizer {
    fn update(&mut self, parameter: &mut Tensor, grad: &Tensor) -> Result<()> {
        self.base_optimizer.update(parameter, grad)
    }

    fn zero_grad(&mut self) {
        self.base_optimizer.zero_grad()
    }

    fn step(&mut self) {
        self.base_optimizer.step()
    }

    fn get_lr(&self) -> f32 {
        self.base_optimizer.get_lr()
    }

    fn set_lr(&mut self, lr: f32) {
        self.base_optimizer.set_lr(lr)
    }
}

/// Mobile-optimized optimizer with memory and latency constraints
pub struct MobileOptimizer {
    base_optimizer: Box<dyn Optimizer>,
    config: HardwareAwareConfig,
    memory_budget_mb: usize,
    target_latency_ms: f32,
    quantized_states: bool,
    gradient_compression: CompressionRatio,
}

impl MobileOptimizer {
    pub fn new(base_optimizer: Box<dyn Optimizer>, config: HardwareAwareConfig) -> Result<Self> {
        if let HardwareTarget::Mobile {
            memory_mb,
            target_latency_ms,
            ..
        } = config.target
        {
            let gradient_compression =
                config.gradient_compression.clone().unwrap_or(CompressionRatio::Half);

            Ok(Self {
                base_optimizer,
                config,
                memory_budget_mb: memory_mb,
                target_latency_ms,
                quantized_states: true,
                gradient_compression,
            })
        } else {
            Err(
                trustformers_core::errors::TrustformersError::invalid_config(
                    "MobileOptimizer requires Mobile target".to_string(),
                ),
            )
        }
    }

    /// Compresses gradients to the configured precision for mobile deployment.
    ///
    /// The returned tensors carry the reduced dtype (`F16` for
    /// [`CompressionRatio::Half`]), so the memory saving is real and observable via
    /// [`Tensor::size_bytes`].
    ///
    /// # Errors
    ///
    /// Returns an error when a gradient's dtype cannot be converted.
    pub fn compress_gradients(&self, gradients: &[Tensor]) -> Result<Vec<Tensor>> {
        let mut compressed = Vec::new();

        for grad in gradients {
            let compressed_grad = match self.gradient_compression {
                CompressionRatio::Half => self.to_fp16(grad)?,
                CompressionRatio::Quarter => self.to_int8(grad)?,
                CompressionRatio::Eighth => self.to_int4(grad)?,
            };
            compressed.push(compressed_grad);
        }

        Ok(compressed)
    }

    /// Converts an `f32` tensor to a genuine IEEE-754 binary16 tensor.
    ///
    /// The result is a [`Tensor::F16`], so the storage really is halved and the
    /// mantissa really is reduced. `half::f16::from_f32` performs round-to-nearest-even
    /// and preserves NaN and ±∞ (an overflowing finite value becomes ±∞, as IEEE-754
    /// requires) instead of the previous clamp to ±65504.
    fn to_fp16(&self, tensor: &Tensor) -> Result<Tensor> {
        match tensor {
            Tensor::F32(data) => Ok(Tensor::F16(data.mapv(half::f16::from_f32))),
            // Already half precision: nothing to do.
            Tensor::F16(_) => Ok(tensor.clone()),
            Tensor::F64(data) => Ok(Tensor::F16(data.mapv(half::f16::from_f64))),
            other => Err(
                trustformers_core::errors::TrustformersError::tensor_op_error(
                    &format!("cannot convert dtype {:?} to f16", other.dtype()),
                    "MixedPrecisionOptimizer::to_fp16",
                ),
            ),
        }
    }

    fn to_int8(&self, tensor: &Tensor) -> Result<Tensor> {
        // Quantize to 8-bit integers using dynamic range quantization
        match tensor {
            Tensor::F32(data) => {
                if data.is_empty() {
                    return Ok(tensor.clone());
                }

                // Find min and max values for dynamic range quantization
                let min_val = data.iter().fold(f32::INFINITY, |a, &b| a.min(b));
                let max_val = data.iter().fold(f32::NEG_INFINITY, |a, &b| a.max(b));

                // Avoid division by zero
                if (max_val - min_val).abs() < f32::EPSILON {
                    return Ok(tensor.clone());
                }

                // Scale factor for quantization
                let scale = (max_val - min_val) / 255.0;

                // Quantize to 8-bit and dequantize back to f32
                let quantized_data: Vec<f32> = data
                    .iter()
                    .map(|&x| {
                        let quantized = ((x - min_val) / scale).round().clamp(0.0, 255.0) as u8;
                        min_val + (quantized as f32) * scale
                    })
                    .collect();

                Ok(Tensor::new(quantized_data)?)
            },
            _ => Ok(tensor.clone()),
        }
    }

    fn to_int4(&self, tensor: &Tensor) -> Result<Tensor> {
        // Quantize to 4-bit integers using dynamic range quantization
        match tensor {
            Tensor::F32(data) => {
                if data.is_empty() {
                    return Ok(tensor.clone());
                }

                // Find min and max values for dynamic range quantization
                let min_val = data.iter().fold(f32::INFINITY, |a, &b| a.min(b));
                let max_val = data.iter().fold(f32::NEG_INFINITY, |a, &b| a.max(b));

                // Avoid division by zero
                if (max_val - min_val).abs() < f32::EPSILON {
                    return Ok(tensor.clone());
                }

                // Scale factor for 4-bit quantization (0-15 range)
                let scale = (max_val - min_val) / 15.0;

                // Quantize to 4-bit and dequantize back to f32
                let quantized_data: Vec<f32> = data
                    .iter()
                    .map(|&x| {
                        let quantized = ((x - min_val) / scale).round().clamp(0.0, 15.0) as u8;
                        min_val + (quantized as f32) * scale
                    })
                    .collect();

                Ok(Tensor::new(quantized_data)?)
            },
            _ => Ok(tensor.clone()),
        }
    }

    /// Check if memory usage is within budget
    fn check_memory_budget(&self, parameters: &[Tensor]) -> Result<bool> {
        // Calculate current memory usage and compare to budget
        let mut total_memory_bytes = 0;

        for tensor in parameters {
            match tensor {
                Tensor::F32(data) => {
                    total_memory_bytes += data.len() * 4; // 4 bytes per f32
                },
                // For other tensor types, provide realistic memory estimation based on common sizes
                _ => {
                    // Conservative estimation: assume average tensor has 1000 elements of f32 size
                    // This accounts for various tensor types (I8, I16, I32, F64, etc.)
                    total_memory_bytes += 1000 * 4; // 4KB per unknown tensor (reasonable estimation)
                },
            }
        }

        // Add optimizer state memory overhead (estimated)
        total_memory_bytes += total_memory_bytes; // Assume optimizer state is same size as parameters

        // Convert to MB for comparison
        let total_memory_mb = total_memory_bytes as f32 / (1024.0 * 1024.0);

        // Check against mobile memory budget
        Ok(total_memory_mb <= self.memory_budget_mb as f32 * 0.8) // Use 80% of available memory
    }
}

impl Optimizer for MobileOptimizer {
    fn update(&mut self, parameter: &mut Tensor, grad: &Tensor) -> Result<()> {
        self.base_optimizer.update(parameter, grad)
    }

    fn zero_grad(&mut self) {
        self.base_optimizer.zero_grad()
    }

    fn step(&mut self) {
        self.base_optimizer.step()
    }

    fn get_lr(&self) -> f32 {
        self.base_optimizer.get_lr()
    }

    fn set_lr(&mut self, lr: f32) {
        self.base_optimizer.set_lr(lr)
    }
}

/// Edge computing optimizer for IoT devices
pub struct EdgeOptimizer {
    base_optimizer: Box<dyn Optimizer>,
    config: HardwareAwareConfig,
    power_budget_mw: f32,
    quantization_bits: u8,
    adaptive_precision: bool,
}

impl EdgeOptimizer {
    pub fn new(base_optimizer: Box<dyn Optimizer>, config: HardwareAwareConfig) -> Result<Self> {
        if let HardwareTarget::Edge {
            power_budget_mw,
            quantization_bits,
            ..
        } = config.target
        {
            Ok(Self {
                base_optimizer,
                config,
                power_budget_mw,
                quantization_bits,
                adaptive_precision: true,
            })
        } else {
            Err(
                trustformers_core::errors::TrustformersError::invalid_config(
                    "EdgeOptimizer requires Edge target".to_string(),
                ),
            )
        }
    }

    /// Adapt precision based on power constraints
    fn adapt_precision(&mut self, current_power_mw: f32) -> Result<()> {
        if current_power_mw > self.power_budget_mw * 0.9 {
            // Reduce precision to save power
            self.quantization_bits = std::cmp::max(4, self.quantization_bits - 1);
        } else if current_power_mw < self.power_budget_mw * 0.5 {
            // Increase precision when power budget allows
            self.quantization_bits = std::cmp::min(16, self.quantization_bits + 1);
        }
        Ok(())
    }

    /// Quantize gradients to specified bit width
    fn quantize_gradients(&self, gradients: &[Tensor]) -> Result<Vec<Tensor>> {
        let mut quantized = Vec::new();

        for grad in gradients {
            let quantized_grad = self.quantize_tensor(grad, self.quantization_bits)?;
            quantized.push(quantized_grad);
        }

        Ok(quantized)
    }

    fn quantize_tensor(&self, tensor: &Tensor, bits: u8) -> Result<Tensor> {
        // Implement quantization to specified bit width using dynamic range quantization
        match tensor {
            Tensor::F32(data) => {
                if data.is_empty() || bits == 0 || bits > 8 {
                    return Ok(tensor.clone());
                }

                // Find min and max values for dynamic range quantization
                let min_val = data.iter().fold(f32::INFINITY, |a, &b| a.min(b));
                let max_val = data.iter().fold(f32::NEG_INFINITY, |a, &b| a.max(b));

                // Avoid division by zero
                if (max_val - min_val).abs() < f32::EPSILON {
                    return Ok(tensor.clone());
                }

                // Calculate quantization levels
                let levels = (1 << bits) - 1; // 2^bits - 1
                let scale = (max_val - min_val) / levels as f32;

                // Quantize and dequantize
                let quantized_data: Vec<f32> = data
                    .iter()
                    .map(|&x| {
                        let quantized =
                            ((x - min_val) / scale).round().clamp(0.0, levels as f32) as u32;
                        min_val + (quantized as f32) * scale
                    })
                    .collect();

                Ok(Tensor::new(quantized_data)?)
            },
            _ => Ok(tensor.clone()),
        }
    }
}

impl Optimizer for EdgeOptimizer {
    fn update(&mut self, parameter: &mut Tensor, grad: &Tensor) -> Result<()> {
        self.base_optimizer.update(parameter, grad)
    }

    fn zero_grad(&mut self) {
        self.base_optimizer.zero_grad()
    }

    fn step(&mut self) {
        self.base_optimizer.step()
    }

    fn get_lr(&self) -> f32 {
        self.base_optimizer.get_lr()
    }

    fn set_lr(&mut self, lr: f32) {
        self.base_optimizer.set_lr(lr)
    }
}

impl EdgeOptimizer {
    fn estimate_power_usage(&self, gradients: &[Tensor]) -> Result<f32> {
        // Estimate power consumption based on computation complexity
        let mut total_operations = 0;

        // Count operations needed for gradient updates
        for tensor in gradients {
            match tensor {
                Tensor::F32(data) => {
                    // Each parameter update involves: gradient computation, momentum update, parameter update
                    total_operations += data.len() * 3;
                },
                _ => {
                    // For unknown tensor types, estimate based on typical tensor size
                    // Conservative estimation: assume 1000 elements per tensor with 3 operations each
                    total_operations += 1000 * 3; // 3000 operations per unknown tensor
                },
            }
        }

        // Base power consumption per operation (estimated for edge devices)
        let power_per_operation_mw = 0.001; // 1 microWatt per operation
        let computational_power = total_operations as f32 * power_per_operation_mw;

        // Add base power consumption for memory access and control
        let base_power = self.power_budget_mw * 0.2; // 20% base power

        // Add power for quantization overhead
        let quantization_power = if self.quantization_bits < 8 {
            self.power_budget_mw * 0.1 // 10% overhead for quantization
        } else {
            0.0
        };

        let total_estimated_power = base_power + computational_power + quantization_power;

        // Ensure we don't exceed the power budget
        Ok(total_estimated_power.min(self.power_budget_mw))
    }
}

/// Helper structures
struct GPUMemoryPool {
    // GPU memory pool for efficient allocation
}

impl GPUMemoryPool {
    fn new() -> Result<Self> {
        Ok(Self {})
    }
}

struct ComputeKernel {
    // Cached compute kernels for GPU
}

/// Factory functions for creating hardware-aware optimizers
pub fn create_gpu_adam(memory_gb: f32, compute_capability: f32) -> Result<GPUAdam> {
    let config = HardwareAwareConfig {
        target: HardwareTarget::GPU {
            memory_gb,
            compute_capability,
            use_tensor_cores: compute_capability >= 7.0,
        },
        base_learning_rate: 1e-4,
        enable_fusion: true,
        memory_efficient: true,
        use_mixed_precision: true,
        gradient_compression: Some(CompressionRatio::Half),
        custom_kernels: true,
    };

    GPUAdam::new(config)
}

pub fn create_tpu_optimizer(version: TPUVersion, num_cores: usize) -> Result<TPUOptimizer> {
    let config = HardwareAwareConfig {
        target: HardwareTarget::TPU {
            version: version.clone(),
            num_cores,
            use_bfloat16: true,
        },
        base_learning_rate: 1e-4,
        enable_fusion: true,
        memory_efficient: true,
        use_mixed_precision: true,
        gradient_compression: None,
        custom_kernels: true,
    };

    let base_optimizer = Box::new(AdamW::new(1e-4, (0.9, 0.999), 1e-8, 0.01));
    TPUOptimizer::new(base_optimizer, config)
}

pub fn create_mobile_optimizer(
    memory_mb: usize,
    target_latency_ms: f32,
) -> Result<MobileOptimizer> {
    let config = HardwareAwareConfig {
        target: HardwareTarget::Mobile {
            memory_mb,
            cpu_cores: 4,
            target_latency_ms,
        },
        base_learning_rate: 1e-4,
        enable_fusion: false,
        memory_efficient: true,
        use_mixed_precision: true,
        gradient_compression: Some(CompressionRatio::Quarter),
        custom_kernels: false,
    };

    let base_optimizer = Box::new(SGD::new(1e-3, 0.9, 0.0, false));
    MobileOptimizer::new(base_optimizer, config)
}

pub fn create_edge_optimizer(memory_mb: usize, power_budget_mw: f32) -> Result<EdgeOptimizer> {
    let config = HardwareAwareConfig {
        target: HardwareTarget::Edge {
            memory_mb,
            power_budget_mw,
            quantization_bits: 8,
        },
        base_learning_rate: 1e-3,
        enable_fusion: false,
        memory_efficient: true,
        use_mixed_precision: false,
        gradient_compression: Some(CompressionRatio::Eighth),
        custom_kernels: false,
    };

    let base_optimizer = Box::new(SGD::new(1e-3, 0.5, 0.0, false));
    EdgeOptimizer::new(base_optimizer, config)
}

#[cfg(test)]
#[path = "hardware_aware_tests.rs"]
mod hardware_aware_tests;