foxhunt/crates/ml/tests/dqn_epsilon_decay_validation_test.rs

#![allow(
    clippy::assertions_on_constants,
    clippy::assertions_on_result_states,
    clippy::clone_on_copy,
    clippy::decimal_literal_representation,
    clippy::doc_markdown,
    clippy::empty_line_after_doc_comments,
    clippy::field_reassign_with_default,
    clippy::get_unwrap,
    clippy::identity_op,
    clippy::inconsistent_digit_grouping,
    clippy::indexing_slicing,
    clippy::integer_division,
    clippy::len_zero,
    clippy::let_underscore_must_use,
    clippy::manual_div_ceil,
    clippy::manual_let_else,
    clippy::manual_range_contains,
    clippy::modulo_arithmetic,
    clippy::needless_range_loop,
    clippy::non_ascii_literal,
    clippy::redundant_clone,
    clippy::shadow_reuse,
    clippy::shadow_same,
    clippy::shadow_unrelated,
    clippy::single_match_else,
    clippy::str_to_string,
    clippy::string_slice,
    clippy::tests_outside_test_module,
    clippy::too_many_lines,
    clippy::unnecessary_wraps,
    clippy::unseparated_literal_suffix,
    clippy::use_debug,
    clippy::useless_vec,
    clippy::wildcard_enum_match_arm,
    clippy::else_if_without_else,
    clippy::expect_used,
    clippy::missing_const_for_fn,
    clippy::similar_names,
    clippy::type_complexity,
    clippy::collapsible_else_if,
    clippy::doc_lazy_continuation,
    clippy::items_after_test_module,
    clippy::map_clone,
    clippy::multiple_unsafe_ops_per_block,
    clippy::unwrap_or_default,
    clippy::assign_op_pattern,
    clippy::needless_borrow,
    clippy::println_empty_string,
    clippy::unnecessary_cast,
    clippy::used_underscore_binding,
    clippy::create_dir,
    clippy::implicit_saturating_sub,
    clippy::exit,
    clippy::expect_fun_call,
    clippy::too_many_arguments,
    clippy::unnecessary_map_or,
    clippy::unwrap_used,
    dead_code,
    unused_imports,
    unused_variables,
    clippy::cloned_ref_to_slice_refs,
    clippy::neg_multiply,
    clippy::while_let_loop,
    clippy::bool_assert_comparison,
    clippy::excessive_precision,
    clippy::trivially_copy_pass_by_ref,
    clippy::op_ref,
    clippy::redundant_closure,
    clippy::unnecessary_lazy_evaluations,
    clippy::if_then_some_else_none,
    clippy::unnecessary_to_owned,
    clippy::single_component_path_imports,
)]
//! Unit tests for DQN epsilon decay schedule validation.
//!
//! Verifies Fix #2: Epsilon decay range adjustment from 0.99-0.9999 to 0.999-0.9999
//! to maintain proper exploration (ε>0.1) for ≥50% of training episodes.

#[cfg(test)]
mod dqn_epsilon_decay_validation_tests {
    use approx::assert_relative_eq;
    use tracing::info;

    /// Calculate number of episodes required to reach a threshold epsilon value.
    ///
    /// Formula: episodes = ln(threshold / initial) / ln(decay)
    ///
    /// # Arguments
    /// * `initial` - Initial epsilon value (typically 1.0)
    /// * `decay` - Decay rate per episode (e.g., 0.999)
    /// * `threshold` - Target epsilon threshold (e.g., 0.1)
    ///
    /// # Returns
    /// Number of episodes to reach threshold (rounded up)
    fn calculate_episodes_to_threshold(initial: f64, decay: f64, threshold: f64) -> usize {
        ((threshold / initial).ln() / decay.ln()).ceil() as usize
    }

    /// Simulate epsilon decay and calculate percentage of episodes above threshold.
    ///
    /// # Arguments
    /// * `initial` - Initial epsilon value
    /// * `decay` - Decay rate per episode
    /// * `total_episodes` - Total training episodes
    /// * `threshold` - Epsilon threshold to track
    ///
    /// # Returns
    /// Percentage of episodes where epsilon > threshold (0.0-1.0)
    fn calculate_exploration_percentage(
        initial: f64,
        decay: f64,
        total_episodes: usize,
        threshold: f64,
    ) -> f64 {
        let mut epsilon = initial;
        let mut episodes_above_threshold = 0;

        for _ in 0..total_episodes {
            if epsilon > threshold {
                episodes_above_threshold += 1;
            }
            epsilon *= decay;
        }

        episodes_above_threshold as f64 / total_episodes as f64
    }

    #[test]
    fn test_epsilon_decay_lower_bound() {
        // Fix #2: Lower bound of hyperopt range (0.999)
        let decay = 0.999;
        let initial_epsilon = 1.0;

        // Calculate episodes to ε=0.1
        let episodes_to_01 = calculate_episodes_to_threshold(initial_epsilon, decay, 0.1);

        // Mathematical expectation: ln(0.1 / 1.0) / ln(0.999) ≈ 2,302.6 episodes
        assert!(
            episodes_to_01 >= 2_300 && episodes_to_01 <= 2_400,
            "Expected ~2,302 episodes to reach ε=0.1, got {}",
            episodes_to_01
        );

        // Calculate episodes to ε=0.01
        let episodes_to_001 = calculate_episodes_to_threshold(initial_epsilon, decay, 0.01);

        // Mathematical expectation: ln(0.01 / 1.0) / ln(0.999) ≈ 4,605.2 episodes
        assert!(
            episodes_to_001 >= 4_600 && episodes_to_001 <= 4_700,
            "Expected ~4,605 episodes to reach ε=0.01, got {}",
            episodes_to_001
        );

        // Verify exploration percentage over 5,000 episodes
        let exploration_pct = calculate_exploration_percentage(initial_epsilon, decay, 5_000, 0.1);

        // At lower bound (0.999), should maintain ε>0.1 for ~46% of training
        assert!(
            exploration_pct >= 0.45 && exploration_pct <= 0.47,
            "Expected 46% exploration time, got {:.1}%",
            exploration_pct * 100.0
        );

        info!(exploration_pct = exploration_pct * 100.0, "Lower bound (0.999): epsilon>0.1 for pct% of 5,000 episodes");
    }

    #[test]
    fn test_epsilon_decay_upper_bound() {
        // Fix #2: Upper bound of hyperopt range (0.9999)
        let decay = 0.9999;
        let initial_epsilon = 1.0;

        // Calculate episodes to ε=0.1
        let episodes_to_01 = calculate_episodes_to_threshold(initial_epsilon, decay, 0.1);

        // Mathematical expectation: ln(0.1 / 1.0) / ln(0.9999) ≈ 23,025.9 episodes
        assert!(
            episodes_to_01 >= 23_000 && episodes_to_01 <= 23_100,
            "Expected ~23,026 episodes to reach ε=0.1, got {}",
            episodes_to_01
        );

        // Verify exploration percentage over 25,000 episodes
        let exploration_pct = calculate_exploration_percentage(initial_epsilon, decay, 25_000, 0.1);

        // At upper bound (0.9999), should maintain ε>0.1 for ~92% of training
        assert!(
            exploration_pct >= 0.91 && exploration_pct <= 0.93,
            "Expected 92% exploration time, got {:.1}%",
            exploration_pct * 100.0
        );

        info!(exploration_pct = exploration_pct * 100.0, "Upper bound (0.9999): epsilon>0.1 for pct% of 25,000 episodes");
    }

    #[test]
    fn test_epsilon_decay_midpoint() {
        // Fix #2: Midpoint of hyperopt range (0.9995)
        let decay = 0.9995;
        let initial_epsilon = 1.0;

        // Calculate episodes to ε=0.1
        let episodes_to_01 = calculate_episodes_to_threshold(initial_epsilon, decay, 0.1);

        // Mathematical expectation: ln(0.1 / 1.0) / ln(0.9995) ≈ 4,605.2 episodes
        assert!(
            episodes_to_01 >= 4_600 && episodes_to_01 <= 4_700,
            "Expected ~4,605 episodes to reach ε=0.1, got {}",
            episodes_to_01
        );

        // For 5,000 episode training budget, verify ε>0.1 for ≥90% of training
        // Mathematical: episodes_to_01 = 4606, so 4606/5000 = 92.1%
        let exploration_pct_5k =
            calculate_exploration_percentage(initial_epsilon, decay, 5_000, 0.1);

        assert!(
            exploration_pct_5k >= 0.90,
            "Expected ≥90% exploration time for 5,000 episodes, got {:.1}%",
            exploration_pct_5k * 100.0
        );

        // For 10,000 episode training budget
        // Mathematical: 4606/10000 = 46.1%
        let exploration_pct_10k =
            calculate_exploration_percentage(initial_epsilon, decay, 10_000, 0.1);

        assert!(
            exploration_pct_10k >= 0.45,
            "Expected ≥45% exploration time for 10,000 episodes, got {:.1}%",
            exploration_pct_10k * 100.0
        );

        info!(episodes_to_01, exploration_pct_5k = exploration_pct_5k * 100.0, exploration_pct_10k = exploration_pct_10k * 100.0, "Midpoint (0.9995): episodes to epsilon=0.1 computed");
    }

    #[test]
    fn test_hyperopt_range_all_valid() {
        // Fix #2: Verify ALL values in hyperopt range [0.999, 0.9999] maintain ≥45% exploration
        use rand::Rng;

        let mut rng = rand::thread_rng();
        let min_decay = 0.999;
        let max_decay = 0.9999;
        let total_episodes = 5_000;
        let min_exploration_pct = 0.45; // 45% minimum

        let mut all_valid = true;
        let mut min_observed = 1.0;
        let mut max_observed = 0.0;

        info!(min_decay, max_decay, "Sampling 100 random decay values");

        for i in 0..100 {
            // Sample random decay value in range
            let decay = rng.gen_range(min_decay..=max_decay);

            // Calculate exploration percentage
            let exploration_pct = calculate_exploration_percentage(1.0, decay, total_episodes, 0.1);

            // Track min/max
            if exploration_pct < min_observed {
                min_observed = exploration_pct;
            }
            if exploration_pct > max_observed {
                max_observed = exploration_pct;
            }

            // Verify meets minimum threshold
            if exploration_pct < min_exploration_pct {
                info!(sample = i + 1, decay, exploration_pct = exploration_pct * 100.0, min_exploration_pct = min_exploration_pct * 100.0, "Sample failed minimum exploration threshold");
                all_valid = false;
            }
        }

        info!(min_observed = min_observed * 100.0, max_observed = max_observed * 100.0, "Exploration range validated");

        assert!(
            all_valid,
            "Some decay values failed to maintain ≥{:.1}% exploration",
            min_exploration_pct * 100.0
        );
    }

    #[test]
    fn test_mathematical_formula_precision() {
        // Verify mathematical formula accuracy against known values

        // Test case 1: decay=0.999, ε=0.1
        let episodes_1 = calculate_episodes_to_threshold(1.0, 0.999, 0.1);
        let expected_1 = ((0.1_f64 / 1.0).ln() / 0.999_f64.ln()).ceil() as usize;
        assert_eq!(episodes_1, expected_1, "Formula mismatch for decay=0.999");
        assert_eq!(
            episodes_1, 2302,
            "Expected exactly 2,302 episodes for decay=0.999 to ε=0.1"
        );

        // Test case 2: decay=0.9999, ε=0.1
        let episodes_2 = calculate_episodes_to_threshold(1.0, 0.9999, 0.1);
        let expected_2 = ((0.1_f64 / 1.0).ln() / 0.9999_f64.ln()).ceil() as usize;
        assert_eq!(episodes_2, expected_2, "Formula mismatch for decay=0.9999");
        assert_eq!(
            episodes_2, 23025,
            "Expected exactly 23,025 episodes for decay=0.9999 to ε=0.1"
        );

        // Test case 3: decay=0.9995, ε=0.1
        let episodes_3 = calculate_episodes_to_threshold(1.0, 0.9995, 0.1);
        let expected_3 = ((0.1_f64 / 1.0).ln() / 0.9995_f64.ln()).ceil() as usize;
        assert_eq!(episodes_3, expected_3, "Formula mismatch for decay=0.9995");
        assert_eq!(
            episodes_3, 4605,
            "Expected exactly 4,605 episodes for decay=0.9995 to ε=0.1"
        );

        info!(episodes_1, episodes_2, episodes_3, "Mathematical formula precision verified");
    }

    #[test]
    fn test_edge_cases() {
        // Edge case 1: Minimum valid decay (0.999) with very long training
        let decay_min = 0.999;
        let exploration_pct_long = calculate_exploration_percentage(1.0, decay_min, 50_000, 0.1);
        assert!(
            exploration_pct_long >= 0.04 && exploration_pct_long <= 0.06,
            "Expected ~5% exploration for 50,000 episodes at decay=0.999, got {:.1}%",
            exploration_pct_long * 100.0
        );

        // Edge case 2: Maximum valid decay (0.9999) with short training
        let decay_max = 0.9999;
        let exploration_pct_short = calculate_exploration_percentage(1.0, decay_max, 1_000, 0.1);
        assert!(
            exploration_pct_short >= 0.95,
            "Expected ≥95% exploration for 1,000 episodes at decay=0.9999, got {:.1}%",
            exploration_pct_short * 100.0
        );

        // Edge case 3: Verify epsilon never goes below min_epsilon (typically 0.01)
        let mut epsilon: f64 = 1.0;
        let decay: f64 = 0.999;
        let min_epsilon: f64 = 0.01;

        for _ in 0..100_000 {
            epsilon = (epsilon * decay).max(min_epsilon);
        }

        assert_relative_eq!(epsilon, min_epsilon, epsilon = 1e-6);

        info!(exploration_pct_long = exploration_pct_long * 100.0, exploration_pct_short = exploration_pct_short * 100.0, epsilon, "Edge cases validated");
    }
}