foxhunt/ml/tests/dqn_gradient_threshold_tests.rs

/// DQN Gradient Warning Threshold Tests
///
/// This test suite validates the gradient warning threshold behavior in the DQN training system.
///
/// # Current Gradient Warning Thresholds
///
/// ## 1. WorkingDQN (`ml/src/dqn/dqn.rs:773`)
/// - **Threshold**: `grad_norm < 1.0` triggers collapse warning
/// - **Purpose**: Detects gradient collapse (vanishing gradients)
/// - **Logged**: Every 100 training steps (line 691)
/// - **Warning message**: "⚠️  GRADIENT COLLAPSE: norm={:.6} at step {}"
///
/// ## 2. Hyperopt Adapter (`ml/src/hyperopt/adapters/dqn.rs:1176`)
/// - **Threshold**: `grad_norm > 20000.0` triggers explosion penalty
/// - **Purpose**: Detects gradient explosion (unstable training)
/// - **Penalty formula**: `(gradient_norm - 20000.0) / 20000.0`
/// - **Weight**: 10% of final objective function (0.20 * penalty * 0.50 stability weight)
///
/// ## 3. Gradient Clipping (`ml/src/dqn/dqn.rs:113, 362`)
/// - **Clip threshold**: `gradient_clip_norm = 10.0`
/// - **Purpose**: Prevents gradient explosion during backpropagation
/// - **Applied**: Before optimizer step (via `backward_step_with_monitoring`)
///
/// # Healthy Gradient Ranges (from hyperopt docs)
/// - **Normal**: 0.1 to 10.0 (healthy gradients)
/// - **Warning**: 10.0 to 20,000.0 (elevated but acceptable)
/// - **Collapse**: < 1.0 (vanishing gradients, training likely stalled)
/// - **Explosion**: > 20,000.0 (unstable training, likely to diverge)
///
/// # Why These Tests Matter
/// - Gradient collapse detection prevents silent training failures
/// - Hyperopt explosion penalty guides search away from unstable regions
/// - Tests ensure threshold constants match documented behavior
/// - Regression protection if thresholds are changed without review

#[cfg(test)]
mod gradient_threshold_tests {
    /// Test gradient collapse warning threshold (1.0)
    ///
    /// Location: `ml/src/dqn/dqn.rs:773`
    /// Condition: `if grad_norm < 1.0`
    #[test]
    fn test_collapse_threshold_is_one() {
        let threshold = 1.0_f32;

        // Below threshold - should trigger warning
        let grad_norm_below = 0.999_f32;
        assert!(grad_norm_below < threshold, "0.999 should be below collapse threshold");

        // At threshold - should NOT trigger warning
        let grad_norm_at = 1.0_f32;
        assert!(!(grad_norm_at < threshold), "1.0 should NOT trigger collapse warning");

        // Above threshold - should NOT trigger warning
        let grad_norm_above = 1.001_f32;
        assert!(!(grad_norm_above < threshold), "1.001 should NOT trigger collapse warning");
    }

    /// Test gradient explosion penalty threshold (20,000.0)
    ///
    /// Location: `ml/src/hyperopt/adapters/dqn.rs:1176`
    /// Condition: `if gradient_norm > 20000.0`
    /// Penalty: `(gradient_norm - 20000.0) / 20000.0`
    #[test]
    fn test_explosion_threshold_is_twenty_thousand() {
        let threshold = 20000.0_f64;

        // Below threshold - no penalty
        let grad_norm_below = 19999.9_f64;
        let penalty_below = if grad_norm_below > threshold {
            (grad_norm_below - threshold) / threshold
        } else {
            0.0
        };
        assert_eq!(penalty_below, 0.0, "19999.9 should have zero explosion penalty");

        // At threshold - no penalty (condition is > not >=)
        let grad_norm_at = 20000.0_f64;
        let penalty_at = if grad_norm_at > threshold {
            (grad_norm_at - threshold) / threshold
        } else {
            0.0
        };
        assert_eq!(penalty_at, 0.0, "20000.0 should have zero explosion penalty");

        // Just above threshold - minimal penalty
        let grad_norm_above = 20000.1_f64;
        let penalty_above = if grad_norm_above > threshold {
            (grad_norm_above - threshold) / threshold
        } else {
            0.0
        };
        assert!((penalty_above - 0.000005).abs() < 1e-6, "20000.1 should have penalty ~0.000005");

        // Far above threshold - significant penalty
        let grad_norm_far = 40000.0_f64;
        let penalty_far = if grad_norm_far > threshold {
            (grad_norm_far - threshold) / threshold
        } else {
            0.0
        };
        assert_eq!(penalty_far, 1.0, "40000.0 should have penalty 1.0 (20000/20000)");
    }

    /// Test gradient clipping threshold (10.0)
    ///
    /// Location: `ml/src/dqn/dqn.rs:113, 362`
    /// Field: `gradient_clip_norm`
    #[test]
    fn test_clipping_threshold_is_ten() {
        let clip_threshold = 10.0_f64;

        // Normal range (should not be clipped)
        let grad_norm_normal = 5.0_f64;
        assert!(grad_norm_normal < clip_threshold, "5.0 should be below clip threshold");

        // At threshold (boundary case)
        let grad_norm_at = 10.0_f64;
        assert!(grad_norm_at <= clip_threshold, "10.0 should be at clip threshold");

        // Above threshold (should be clipped)
        let grad_norm_above = 15.0_f64;
        assert!(grad_norm_above > clip_threshold, "15.0 should exceed clip threshold");
    }

    /// Test healthy gradient ranges documentation consistency
    ///
    /// Validates that documented ranges align with actual thresholds
    #[test]
    fn test_gradient_range_boundaries() {
        // Normal range: 0.1 to 10.0
        let normal_min = 0.1_f64;
        let normal_max = 10.0_f64;

        // Warning range: 10.0 to 20,000.0
        let warning_min = 10.0_f64;
        let warning_max = 20000.0_f64;

        // Collapse threshold: < 1.0
        let collapse_threshold = 1.0_f64;

        // Explosion threshold: > 20,000.0
        let explosion_threshold = 20000.0_f64;

        // Verify ranges are consistent
        assert!(normal_max == warning_min, "Normal max should equal warning min");
        assert!(warning_max == explosion_threshold, "Warning max should equal explosion threshold");
        assert!(collapse_threshold < normal_max, "Collapse threshold should be within normal range");
        assert!(normal_min < collapse_threshold, "Normal min should be below collapse threshold");
    }

    /// Test edge cases for threshold comparisons
    #[test]
    fn test_threshold_edge_cases() {
        // Collapse threshold edge cases
        assert!(0.0_f32 < 1.0_f32, "Zero gradient triggers collapse");
        assert!(0.9999_f32 < 1.0_f32, "Just below 1.0 triggers collapse");
        assert!(!(1.0_f32 < 1.0_f32), "Exactly 1.0 does NOT trigger collapse");
        assert!(!(1.0001_f32 < 1.0_f32), "Just above 1.0 does NOT trigger collapse");

        // Explosion threshold edge cases
        assert!(!(20000.0_f64 > 20000.0_f64), "Exactly 20000.0 does NOT trigger explosion penalty");
        assert!(20000.00001_f64 > 20000.0_f64, "Just above 20000.0 triggers explosion penalty");
        assert!(!(19999.9999_f64 > 20000.0_f64), "Just below 20000.0 does NOT trigger explosion penalty");
    }
}