medical_cache/

config.rs

//! Study Cache Configuration
//!
//! Provides adaptive cache configuration based on hardware profiles.
//! The cache system uses a three-tier architecture:
//! - Hot Tier: GPU memory for active series (instant access)
//! - Warm Tier: RAM cache for metadata/thumbnails (fast access)
//! - Cold Tier: Disk/lazy loading (on-demand)

use serde::{Deserialize, Serialize};

/// Performance profile tier for cache settings.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PerformanceProfile {
    /// High-end system (discrete GPU, many cores, 32GB+ RAM)
    High,
    /// Mid-range system (modern iGPU, 16GB RAM)
    Medium,
    /// Budget system (older CPU, 8GB RAM)
    Low,
    /// Very old or embedded hardware (4GB RAM)
    UltraLow,
}

/// Prefetch strategy based on hardware capabilities
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PrefetchStrategy {
    /// No prefetching - load on demand only
    None,
    /// Only prefetch thumbnails (256×256)
    ThumbnailsOnly,
    /// Prefetch metadata and mid-resolution images (512×512)
    #[default]
    MetadataAndMidRes,
    /// Full prefetching - load everything ahead of time
    Full,
}

impl PrefetchStrategy {
    /// Get display name for UI
    pub fn display_name(&self) -> &'static str {
        match self {
            Self::None => "On-Demand Only",
            Self::ThumbnailsOnly => "Thumbnails Only",
            Self::MetadataAndMidRes => "Balanced (Thumbnails + Preview)",
            Self::Full => "Aggressive (Full Quality)",
        }
    }

    /// Get description for UI
    pub fn description(&self) -> &'static str {
        match self {
            Self::None => "Load images only when requested. Slowest but lowest memory usage.",
            Self::ThumbnailsOnly => "Preload small previews. Good for very low memory systems.",
            Self::MetadataAndMidRes => "Preload medium quality previews. Best balance of speed and memory.",
            Self::Full => "Preload full quality images. Fastest but requires more memory.",
        }
    }
}

/// Cache retention policy - what to keep cached per study
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CacheRetentionPolicy {
    /// Always keep thumbnails (256×256) in memory
    pub retain_thumbnails: bool,
    /// Keep mid-resolution (512×512) in warm cache
    pub retain_mid_res: bool,
    /// Keep full-resolution in hot cache
    pub retain_full_res: bool,
}

impl Default for CacheRetentionPolicy {
    fn default() -> Self {
        Self {
            retain_thumbnails: true,
            retain_mid_res: true,
            retain_full_res: false,
        }
    }
}

impl CacheRetentionPolicy {
    /// High-end systems: keep everything
    pub fn aggressive() -> Self {
        Self {
            retain_thumbnails: true,
            retain_mid_res: true,
            retain_full_res: true,
        }
    }

    /// Mid-range systems: thumbnails and mid-res
    pub fn balanced() -> Self {
        Self {
            retain_thumbnails: true,
            retain_mid_res: true,
            retain_full_res: false,
        }
    }

    /// Low-end systems: thumbnails only, mid-res on demand
    pub fn conservative() -> Self {
        Self {
            retain_thumbnails: true,
            retain_mid_res: true,
            retain_full_res: false,
        }
    }

    /// Ultra-low systems: minimal caching
    pub fn minimal() -> Self {
        Self {
            retain_thumbnails: true,
            retain_mid_res: false,
            retain_full_res: false,
        }
    }
}

/// Image quality level for progressive loading
/// Order: Thumbnail < MidRes < Full (for comparison operators)
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ImageQuality {
    /// 256×256 thumbnail - instant feedback
    Thumbnail,
    /// 512×512 mid-resolution - acceptable quality
    MidRes,
    /// Original resolution - diagnostic quality
    Full,
}

impl ImageQuality {
    /// Get target dimension for this quality level
    pub fn target_dimension(&self) -> usize {
        match self {
            Self::Thumbnail => 256,
            Self::MidRes => 512,
            Self::Full => 0, // 0 = original size
        }
    }

    /// Get display name
    pub fn display_name(&self) -> &'static str {
        match self {
            Self::Thumbnail => "Preview",
            Self::MidRes => "Loading HD...",
            Self::Full => "HD Ready",
        }
    }

    /// Is this quality sufficient for diagnosis?
    pub fn is_diagnostic(&self) -> bool {
        matches!(self, Self::Full)
    }
}

/// Study cache configuration based on hardware profile
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StudyCacheConfig {
    /// Total memory budget in MB
    pub total_budget_mb: usize,
    /// Hot tier (GPU memory) budget in MB
    pub hot_tier_mb: usize,
    /// Warm tier (RAM) budget in MB
    pub warm_tier_mb: usize,
    /// Maximum number of studies to keep in memory
    pub max_studies: usize,
    /// Maximum studies with full-resolution data
    pub max_full_res_studies: usize,
    /// Prefetch strategy
    pub prefetch_strategy: PrefetchStrategy,
    /// Eviction timeout in seconds (how long before inactive studies are evicted)
    pub eviction_timeout_secs: u64,
    /// Cache retention policy
    pub retention: CacheRetentionPolicy,
}

impl Default for StudyCacheConfig {
    fn default() -> Self {
        Self::for_profile(PerformanceProfile::Medium)
    }
}

impl StudyCacheConfig {
    /// Create cache configuration for a performance profile
    pub fn for_profile(profile: PerformanceProfile) -> Self {
        match profile {
            PerformanceProfile::High => Self::high_profile(),
            PerformanceProfile::Medium => Self::medium_profile(),
            PerformanceProfile::Low => Self::low_profile(),
            PerformanceProfile::UltraLow => Self::ultra_low_profile(),
        }
    }

    /// High-end system configuration
    /// Target: RTX 3060+, 32GB+ RAM, 8+ cores
    fn high_profile() -> Self {
        Self {
            total_budget_mb: 4096,        // 4 GB total
            hot_tier_mb: 1024,            // 1 GB GPU
            warm_tier_mb: 3072,           // 3 GB RAM
            max_studies: 10,
            max_full_res_studies: 5,
            prefetch_strategy: PrefetchStrategy::Full,
            eviction_timeout_secs: 1800,  // 30 minutes
            retention: CacheRetentionPolicy::aggressive(),
        }
    }

    /// Medium system configuration
    /// Target: Intel Iris Xe, Apple M1, 16GB RAM
    fn medium_profile() -> Self {
        Self {
            total_budget_mb: 2048,        // 2 GB total
            hot_tier_mb: 512,             // 512 MB GPU
            warm_tier_mb: 1536,           // 1.5 GB RAM
            max_studies: 5,
            max_full_res_studies: 2,
            prefetch_strategy: PrefetchStrategy::MetadataAndMidRes,
            eviction_timeout_secs: 900,   // 15 minutes
            retention: CacheRetentionPolicy::balanced(),
        }
    }

    /// Low-end system configuration
    /// Target: Intel UHD 630, 8GB RAM, 4-6 cores (2019 systems)
    fn low_profile() -> Self {
        Self {
            total_budget_mb: 800,         // 800 MB total (~10% of 8GB)
            hot_tier_mb: 256,             // 256 MB GPU
            warm_tier_mb: 544,            // 544 MB RAM
            max_studies: 3,
            max_full_res_studies: 1,      // Only active study
            prefetch_strategy: PrefetchStrategy::MetadataAndMidRes,
            eviction_timeout_secs: 600,   // 10 minutes
            retention: CacheRetentionPolicy::conservative(),
        }
    }

    /// Ultra-low system configuration
    /// Target: Intel HD 4000, 4GB RAM, 2 cores (2012-2015 systems)
    fn ultra_low_profile() -> Self {
        Self {
            total_budget_mb: 400,         // 400 MB total
            hot_tier_mb: 128,             // 128 MB GPU
            warm_tier_mb: 272,            // 272 MB RAM
            max_studies: 2,
            max_full_res_studies: 1,
            prefetch_strategy: PrefetchStrategy::ThumbnailsOnly,
            eviction_timeout_secs: 300,   // 5 minutes
            retention: CacheRetentionPolicy::minimal(),
        }
    }

    /// Calculate cache budget based on RAM size
    ///
    /// Formula:
    /// - High: 3% of RAM, max 4096 MB
    /// - Medium: 2% of RAM, max 2048 MB
    /// - Low: 10% of RAM, max 1024 MB
    /// - UltraLow: 10% of RAM, max 512 MB
    pub fn calculate_budget(ram_gb: u32, profile: PerformanceProfile) -> usize {
        let (percentage, max_cap_mb) = match profile {
            PerformanceProfile::High => (0.03, 4096),
            PerformanceProfile::Medium => (0.02, 2048),
            PerformanceProfile::Low => (0.10, 1024),
            PerformanceProfile::UltraLow => (0.10, 512),
        };

        let calculated = ((ram_gb as f64) * percentage * 1024.0) as usize;
        calculated.min(max_cap_mb)
    }

    /// Get description of this configuration
    pub fn description(&self) -> String {
        format!(
            "{}MB total ({} MB hot + {} MB warm), {} studies max, {} prefetch",
            self.total_budget_mb,
            self.hot_tier_mb,
            self.warm_tier_mb,
            self.max_studies,
            self.prefetch_strategy.display_name()
        )
    }

    /// Get cold tier budget (remaining from total after hot+warm)
    pub fn cold_tier_mb(&self) -> usize {
        self.total_budget_mb.saturating_sub(self.hot_tier_mb + self.warm_tier_mb)
    }

    /// Check if full-res caching is enabled
    pub fn caches_full_res(&self) -> bool {
        self.retention.retain_full_res
    }

    /// Check if mid-res caching is enabled
    pub fn caches_mid_res(&self) -> bool {
        self.retention.retain_mid_res
    }
}

/// Expected performance characteristics for a cache configuration
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExpectedPerformance {
    /// Initial study load time in ms
    pub initial_load_ms: u32,
    /// Cached (hot) to active switch time in ms
    pub cached_switch_ms: u32,
    /// Warm to active switch time in ms
    pub warm_switch_ms: u32,
    /// Cold to active load time in ms
    pub cold_load_ms: u32,
    /// MPR render time in ms
    pub mpr_render_ms: u32,
    /// 3D volume render time in ms
    pub volume_render_ms: u32,
    /// Target scroll FPS
    pub scroll_fps: u32,
}

impl ExpectedPerformance {
    /// Get expected performance for a profile
    pub fn for_profile(profile: PerformanceProfile) -> Self {
        match profile {
            PerformanceProfile::High => Self {
                initial_load_ms: 800,
                cached_switch_ms: 50,
                warm_switch_ms: 100,
                cold_load_ms: 800,
                mpr_render_ms: 200,
                volume_render_ms: 500,
                scroll_fps: 60,
            },
            PerformanceProfile::Medium => Self {
                initial_load_ms: 1200,
                cached_switch_ms: 80,
                warm_switch_ms: 300,
                cold_load_ms: 1200,
                mpr_render_ms: 400,
                volume_render_ms: 1000,
                scroll_fps: 30,
            },
            PerformanceProfile::Low => Self {
                initial_load_ms: 2000,
                cached_switch_ms: 50,
                warm_switch_ms: 450,
                cold_load_ms: 2000,
                mpr_render_ms: 800,
                volume_render_ms: 2000,
                scroll_fps: 30,
            },
            PerformanceProfile::UltraLow => Self {
                initial_load_ms: 4000,
                cached_switch_ms: 100,
                warm_switch_ms: 900,
                cold_load_ms: 4000,
                mpr_render_ms: 2000,
                volume_render_ms: 5000,
                scroll_fps: 15,
            },
        }
    }

    /// Get UX rating (1-5 stars)
    pub fn ux_rating(&self) -> u8 {
        if self.cached_switch_ms <= 50 && self.scroll_fps >= 60 {
            5 // Excellent
        } else if self.cached_switch_ms <= 100 && self.scroll_fps >= 30 {
            4 // Good
        } else if self.cached_switch_ms <= 200 && self.scroll_fps >= 20 {
            3 // Acceptable
        } else if self.scroll_fps >= 15 {
            2 // Slow but works
        } else {
            1 // Problematic
        }
    }
}

/// Cache tier for tracking where data is stored
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CacheTier {
    /// GPU memory - instant access
    Hot,
    /// RAM cache - fast access
    Warm,
    /// Disk/lazy - needs loading
    Cold,
}

impl CacheTier {
    /// Get expected access time in ms
    pub fn expected_access_ms(&self) -> u32 {
        match self {
            Self::Hot => 0,
            Self::Warm => 100,
            Self::Cold => 1000,
        }
    }

    /// Get display name
    pub fn display_name(&self) -> &'static str {
        match self {
            Self::Hot => "GPU Memory (Instant)",
            Self::Warm => "RAM Cache (Fast)",
            Self::Cold => "Disk (Loading...)",
        }
    }
}

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

    #[test]
    fn test_cache_config_for_profiles() {
        let high = StudyCacheConfig::for_profile(PerformanceProfile::High);
        let medium = StudyCacheConfig::for_profile(PerformanceProfile::Medium);
        let low = StudyCacheConfig::for_profile(PerformanceProfile::Low);
        let ultra_low = StudyCacheConfig::for_profile(PerformanceProfile::UltraLow);

        // High should have more resources than medium
        assert!(high.total_budget_mb > medium.total_budget_mb);
        assert!(high.max_studies > medium.max_studies);

        // Medium should have more resources than low
        assert!(medium.total_budget_mb > low.total_budget_mb);

        // Low should have more resources than ultra-low
        assert!(low.total_budget_mb > ultra_low.total_budget_mb);
    }

    #[test]
    fn test_budget_calculation() {
        // 32GB RAM, High profile
        let budget = StudyCacheConfig::calculate_budget(32, PerformanceProfile::High);
        assert_eq!(budget, 983); // 32 * 0.03 * 1024 = 983, capped at 4096

        // 16GB RAM, Medium profile
        let budget = StudyCacheConfig::calculate_budget(16, PerformanceProfile::Medium);
        assert_eq!(budget, 327); // 16 * 0.02 * 1024 = 327

        // 8GB RAM, Low profile
        let budget = StudyCacheConfig::calculate_budget(8, PerformanceProfile::Low);
        assert_eq!(budget, 819); // 8 * 0.10 * 1024 = 819

        // 4GB RAM, UltraLow profile
        let budget = StudyCacheConfig::calculate_budget(4, PerformanceProfile::UltraLow);
        assert_eq!(budget, 409); // 4 * 0.10 * 1024 = 409
    }

    #[test]
    fn test_prefetch_strategy() {
        assert_eq!(PrefetchStrategy::Full.display_name(), "Aggressive (Full Quality)");
        assert_eq!(PrefetchStrategy::None.display_name(), "On-Demand Only");
    }

    #[test]
    fn test_image_quality_dimensions() {
        assert_eq!(ImageQuality::Thumbnail.target_dimension(), 256);
        assert_eq!(ImageQuality::MidRes.target_dimension(), 512);
        assert_eq!(ImageQuality::Full.target_dimension(), 0);
    }

    #[test]
    fn test_expected_performance() {
        let high_perf = ExpectedPerformance::for_profile(PerformanceProfile::High);
        let low_perf = ExpectedPerformance::for_profile(PerformanceProfile::Low);

        // High profile should be faster
        assert!(high_perf.initial_load_ms < low_perf.initial_load_ms);
        assert!(high_perf.scroll_fps > low_perf.scroll_fps);

        // UX rating should reflect performance
        assert!(high_perf.ux_rating() >= low_perf.ux_rating());
    }

    #[test]
    fn test_cache_tier_access_times() {
        assert_eq!(CacheTier::Hot.expected_access_ms(), 0);
        assert!(CacheTier::Warm.expected_access_ms() < CacheTier::Cold.expected_access_ms());
    }

    #[test]
    fn test_retention_policies() {
        let aggressive = CacheRetentionPolicy::aggressive();
        assert!(aggressive.retain_full_res);
        assert!(aggressive.retain_mid_res);
        assert!(aggressive.retain_thumbnails);

        let minimal = CacheRetentionPolicy::minimal();
        assert!(!minimal.retain_full_res);
        assert!(!minimal.retain_mid_res);
        assert!(minimal.retain_thumbnails);
    }
}