foxhunt/ml/tests/volatility_epsilon_adaptation_test.rs

/// AGENT 39: Volatility-Based Epsilon Adaptation Tests
///
/// Tests that epsilon adapts to market volatility regimes:
/// - Low volatility (< 0.01): Lower epsilon for exploitation (0.5× multiplier)
/// - High volatility (> 0.05): Higher epsilon for exploration (2.0× multiplier)
/// - Medium volatility (0.01-0.05): Linear scaling (0.5-2.0× multiplier)
/// - Smooth transitions between regimes
/// - Clamping prevents extreme values (0.05-0.95 range)

use ml::dqn::hyperparameters::DQNHyperparameters;
use ml::dqn::state::TradingState;
use ml::trainers::dqn::DQNTrainer;
use ml::trainers::Trainer;
use anyhow::Result;

/// Helper: Create TradingState with returns volatility
fn create_state_with_volatility(returns: Vec<f64>) -> TradingState {
    let mut state = TradingState::default();

    // Use price features to simulate returns
    // Features 0-3 are OHLC log returns (see dqn.rs:2230)
    if returns.len() >= 4 {
        state.price_features[0] = returns[0] as f32;
        state.price_features[1] = returns[1] as f32;
        state.price_features[2] = returns[2] as f32;
        state.price_features[3] = returns[3] as f32;
    }

    state
}

#[tokio::test]
async fn test_low_volatility_reduces_epsilon() -> Result<()> {
    // Setup: Very low volatility (0.005 = 0.5% daily vol)
    let returns: Vec<f64> = (0..20).map(|_| 0.005).collect();
    let state = create_state_with_volatility(returns);

    let mut hyperparams = DQNHyperparameters::default();
    hyperparams.epsilon_start = 0.3;
    hyperparams.epsilon_end = 0.3; // Fixed epsilon for testing
    hyperparams.epsilon_decay = 1.0; // No decay

    let trainer = DQNTrainer::new(hyperparams)?;

    // Act: Get volatility-adjusted epsilon
    let adjusted_epsilon = trainer.calculate_volatility_adjusted_epsilon().await?;

    // Assert: Low volatility → 0.5× multiplier → epsilon=0.15
    assert!(adjusted_epsilon < 0.2, "Expected epsilon < 0.2, got {}", adjusted_epsilon);
    assert!(adjusted_epsilon >= 0.05, "Epsilon should not go below 0.05 floor");

    Ok(())
}

#[tokio::test]
async fn test_high_volatility_increases_epsilon() -> Result<()> {
    // Setup: High volatility (0.08 = 8% daily vol)
    let returns: Vec<f64> = vec![
        0.08, -0.06, 0.10, -0.05, 0.12, -0.08, 0.09, -0.07,
        0.11, -0.09, 0.08, -0.06, 0.10, -0.05, 0.12, -0.08,
        0.09, -0.07, 0.11, -0.09,
    ];
    let state = create_state_with_volatility(returns);

    let mut hyperparams = DQNHyperparameters::default();
    hyperparams.epsilon_start = 0.3;
    hyperparams.epsilon_end = 0.3;
    hyperparams.epsilon_decay = 1.0;

    let trainer = DQNTrainer::new(hyperparams)?;

    // Act: Get volatility-adjusted epsilon
    let adjusted_epsilon = trainer.calculate_volatility_adjusted_epsilon().await?;

    // Assert: High volatility → 2.0× multiplier → epsilon=0.6
    assert!(adjusted_epsilon > 0.5, "Expected epsilon > 0.5, got {}", adjusted_epsilon);
    assert!(adjusted_epsilon <= 0.95, "Epsilon should not exceed 0.95 ceiling");

    Ok(())
}

#[tokio::test]
async fn test_medium_volatility_linear_scaling() -> Result<()> {
    // Setup: Medium volatility (0.03 = 3% daily vol, halfway between 1-5%)
    let returns: Vec<f64> = vec![
        0.03, -0.02, 0.04, -0.01, 0.03, -0.02, 0.04, -0.01,
        0.03, -0.02, 0.04, -0.01, 0.03, -0.02, 0.04, -0.01,
        0.03, -0.02, 0.04, -0.01,
    ];
    let state = create_state_with_volatility(returns);

    let mut hyperparams = DQNHyperparameters::default();
    hyperparams.epsilon_start = 0.3;
    hyperparams.epsilon_end = 0.3;
    hyperparams.epsilon_decay = 1.0;

    let trainer = DQNTrainer::new(hyperparams)?;

    // Act: Get volatility-adjusted epsilon
    let adjusted_epsilon = trainer.calculate_volatility_adjusted_epsilon().await?;

    // Assert: Medium volatility → ~1.25× multiplier → epsilon≈0.375
    assert!(adjusted_epsilon > 0.3, "Expected epsilon > base (0.3), got {}", adjusted_epsilon);
    assert!(adjusted_epsilon < 0.5, "Expected epsilon < 0.5, got {}", adjusted_epsilon);

    Ok(())
}

#[tokio::test]
async fn test_epsilon_floor_clamping() -> Result<()> {
    // Setup: Extremely low volatility (0.001)
    let returns: Vec<f64> = (0..20).map(|_| 0.001).collect();
    let state = create_state_with_volatility(returns);

    let mut hyperparams = DQNHyperparameters::default();
    hyperparams.epsilon_start = 0.08; // Very low base epsilon
    hyperparams.epsilon_end = 0.08;
    hyperparams.epsilon_decay = 1.0;

    let trainer = DQNTrainer::new(hyperparams)?;

    // Act: Get volatility-adjusted epsilon
    let adjusted_epsilon = trainer.calculate_volatility_adjusted_epsilon().await?;

    // Assert: Should clamp at 0.05 floor
    assert_eq!(adjusted_epsilon, 0.05, "Epsilon should be clamped to 0.05 floor");

    Ok(())
}

#[tokio::test]
async fn test_epsilon_ceiling_clamping() -> Result<()> {
    // Setup: Extremely high volatility (0.20 = 20% daily vol)
    let returns: Vec<f64> = vec![
        0.20, -0.18, 0.25, -0.15, 0.22, -0.19, 0.21, -0.17,
        0.24, -0.16, 0.20, -0.18, 0.25, -0.15, 0.22, -0.19,
        0.21, -0.17, 0.24, -0.16,
    ];
    let state = create_state_with_volatility(returns);

    let mut hyperparams = DQNHyperparameters::default();
    hyperparams.epsilon_start = 0.6; // High base epsilon
    hyperparams.epsilon_end = 0.6;
    hyperparams.epsilon_decay = 1.0;

    let trainer = DQNTrainer::new(hyperparams)?;

    // Act: Get volatility-adjusted epsilon
    let adjusted_epsilon = trainer.calculate_volatility_adjusted_epsilon().await?;

    // Assert: Should clamp at 0.95 ceiling
    assert_eq!(adjusted_epsilon, 0.95, "Epsilon should be clamped to 0.95 ceiling");

    Ok(())
}

#[tokio::test]
async fn test_insufficient_history_defaults_to_medium_vol() -> Result<()> {
    // Setup: Only 10 returns (need 20 for calculation)
    let returns: Vec<f64> = (0..10).map(|_| 0.005).collect();
    let state = create_state_with_volatility(returns);

    let mut hyperparams = DQNHyperparameters::default();
    hyperparams.epsilon_start = 0.3;
    hyperparams.epsilon_end = 0.3;
    hyperparams.epsilon_decay = 1.0;

    let trainer = DQNTrainer::new(hyperparams)?;

    // Act: Get volatility-adjusted epsilon
    let adjusted_epsilon = trainer.calculate_volatility_adjusted_epsilon().await?;

    // Assert: Should use default 0.02 volatility → ~1.0× multiplier → epsilon≈0.3
    assert!((adjusted_epsilon - 0.3).abs() < 0.1,
        "Expected epsilon near base (0.3) with insufficient history, got {}", adjusted_epsilon);

    Ok(())
}

#[tokio::test]
async fn test_smooth_transition_across_regimes() -> Result<()> {
    // Test that epsilon smoothly transitions as volatility changes
    let mut hyperparams = DQNHyperparameters::default();
    hyperparams.epsilon_start = 0.3;
    hyperparams.epsilon_end = 0.3;
    hyperparams.epsilon_decay = 1.0;

    let trainer = DQNTrainer::new(hyperparams)?;

    // Test three regimes
    let test_cases = vec![
        (0.005, 0.5),   // Low vol → 0.5× multiplier
        (0.03, 1.25),   // Medium vol → 1.25× multiplier
        (0.08, 2.0),    // High vol → 2.0× multiplier
    ];

    let mut prev_epsilon = 0.0;
    for (vol, expected_mult) in test_cases {
        let returns: Vec<f64> = (0..20).map(|_| vol).collect();
        let state = create_state_with_volatility(returns);

        // Simulate trainer updating volatility history
        trainer.update_returns_volatility(vol).await?;

        let adjusted_epsilon = trainer.calculate_volatility_adjusted_epsilon().await?;

        // Check multiplier is approximately correct
        let actual_mult = adjusted_epsilon / 0.3;
        assert!((actual_mult - expected_mult).abs() < 0.2,
            "Vol {}: expected mult {}, got {}", vol, expected_mult, actual_mult);

        // Check monotonic increase
        if prev_epsilon > 0.0 {
            assert!(adjusted_epsilon > prev_epsilon,
                "Epsilon should increase with volatility: {} -> {}", prev_epsilon, adjusted_epsilon);
        }
        prev_epsilon = adjusted_epsilon;
    }

    Ok(())
}

#[tokio::test]
async fn test_volatility_calculation_accuracy() -> Result<()> {
    // Setup: Known volatility pattern
    // Returns: [0.01, 0.02, 0.01, 0.02, ...] → mean=0.015, variance=0.00025, std=0.005
    let returns: Vec<f64> = (0..20)
        .map(|i| if i % 2 == 0 { 0.01 } else { 0.02 })
        .collect();

    let mut hyperparams = DQNHyperparameters::default();
    hyperparams.epsilon_start = 0.3;
    hyperparams.epsilon_end = 0.3;
    hyperparams.epsilon_decay = 1.0;

    let trainer = DQNTrainer::new(hyperparams)?;

    // Update volatility history
    for &ret in &returns {
        trainer.update_returns_volatility(ret).await?;
    }

    // Act: Calculate volatility
    let vol = trainer.calculate_returns_volatility().await?;

    // Assert: Should be close to 0.005
    assert!((vol - 0.005).abs() < 0.001,
        "Expected volatility ≈ 0.005, got {}", vol);

    Ok(())
}