rusty_backtest/

latency.rs

//! Simple Latency Models - Clean and accurate latency simulation
//!
//! Provides simple but realistic latency models for backtesting without
//! excessive complexity. All latencies are in nanoseconds for precision.

use parking_lot::Mutex;
use rand::SeedableRng;
use rand::rngs::StdRng;
use rusty_common::collections::FxHashMap;
use std::sync::Arc;

/// Trait for latency models
pub trait LatencyModel: Send + Sync {
    /// Get the next latency value in nanoseconds
    fn get_latency_ns(&self) -> u64;

    /// Get the average latency
    fn avg_latency_ns(&self) -> u64;

    /// Clone the latency model
    fn clone_box(&self) -> Box<dyn LatencyModel>;
}

/// Fixed latency model - Always returns the same value
#[derive(Debug, Clone)]
pub struct FixedLatency {
    latency_ns: u64,
}

impl FixedLatency {
    /// Create a new fixed latency model with latency in nanoseconds
    #[must_use]
    pub const fn new(latency_ns: u64) -> Self {
        Self { latency_ns }
    }

    /// Create a fixed latency model from microseconds
    #[must_use]
    pub const fn from_micros(latency_us: u64) -> Self {
        Self {
            latency_ns: latency_us * 1000,
        }
    }

    /// Create a fixed latency model from milliseconds
    #[must_use]
    pub const fn from_millis(latency_ms: u64) -> Self {
        Self {
            latency_ns: latency_ms * 1_000_000,
        }
    }
}

impl LatencyModel for FixedLatency {
    fn get_latency_ns(&self) -> u64 {
        self.latency_ns
    }

    fn avg_latency_ns(&self) -> u64 {
        self.latency_ns
    }

    fn clone_box(&self) -> Box<dyn LatencyModel> {
        Box::new(self.clone())
    }
}

/// Gaussian (normal distribution) latency model
pub struct GaussianLatency {
    mean_ns: u64,
    std_dev_ns: u64,
    rng: Arc<Mutex<StdRng>>,
}

impl GaussianLatency {
    /// Create a new Gaussian latency model with mean and standard deviation in nanoseconds
    #[must_use]
    pub fn new(mean_ns: u64, std_dev_ns: u64) -> Self {
        Self {
            mean_ns,
            std_dev_ns,
            rng: Arc::new(Mutex::new(StdRng::from_seed([0; 32]))),
        }
    }

    /// Create a Gaussian latency model from microseconds
    #[must_use]
    pub fn from_micros(mean_us: u64, std_dev_us: u64) -> Self {
        Self::new(mean_us * 1000, std_dev_us * 1000)
    }

    /// Create a Gaussian latency model with a specific seed for reproducibility
    #[must_use]
    pub fn with_seed(mean_ns: u64, std_dev_ns: u64, seed: u64) -> Self {
        Self {
            mean_ns,
            std_dev_ns,
            rng: Arc::new(Mutex::new(StdRng::seed_from_u64(seed))),
        }
    }

    /// Box-Muller transform for normal distribution
    fn sample_normal(&self, rng: &mut StdRng) -> f64 {
        use rand::Rng;
        use std::f64::consts::PI;

        let u1: f64 = rng.random();
        let u2: f64 = rng.random();

        let z0 = (-2.0 * u1.ln()).sqrt() * (2.0 * PI * u2).cos();
        self.mean_ns as f64 + z0 * self.std_dev_ns as f64
    }
}

impl LatencyModel for GaussianLatency {
    fn get_latency_ns(&self) -> u64 {
        let mut rng = self.rng.lock();
        let sample = self.sample_normal(&mut rng);
        // Ensure non-negative latency
        sample.max(0.0) as u64
    }

    fn avg_latency_ns(&self) -> u64 {
        self.mean_ns
    }

    fn clone_box(&self) -> Box<dyn LatencyModel> {
        Box::new(GaussianLatency {
            mean_ns: self.mean_ns,
            std_dev_ns: self.std_dev_ns,
            rng: Arc::new(Mutex::new(StdRng::from_seed([0; 32]))),
        })
    }
}

/// Uniform random latency model
pub struct UniformLatency {
    min_ns: u64,
    max_ns: u64,
    rng: Arc<Mutex<StdRng>>,
}

impl UniformLatency {
    /// Create a new uniform latency model with min and max in nanoseconds
    #[must_use]
    pub fn new(min_ns: u64, max_ns: u64) -> Self {
        Self {
            min_ns,
            max_ns,
            rng: Arc::new(Mutex::new(StdRng::from_seed([0; 32]))),
        }
    }

    /// Create a uniform latency model from microseconds
    #[must_use]
    pub fn from_micros(min_us: u64, max_us: u64) -> Self {
        Self::new(min_us * 1000, max_us * 1000)
    }

    /// Create a uniform latency model with a specific seed for reproducibility
    #[must_use]
    pub fn with_seed(min_ns: u64, max_ns: u64, seed: u64) -> Self {
        Self {
            min_ns,
            max_ns,
            rng: Arc::new(Mutex::new(StdRng::seed_from_u64(seed))),
        }
    }
}

impl LatencyModel for UniformLatency {
    fn get_latency_ns(&self) -> u64 {
        use rand::Rng;
        let mut rng = self.rng.lock();
        rng.random_range(self.min_ns..=self.max_ns)
    }

    fn avg_latency_ns(&self) -> u64 {
        (self.min_ns + self.max_ns) / 2
    }

    fn clone_box(&self) -> Box<dyn LatencyModel> {
        Box::new(UniformLatency {
            min_ns: self.min_ns,
            max_ns: self.max_ns,
            rng: Arc::new(Mutex::new(StdRng::from_seed([0; 32]))),
        })
    }
}

/// Bimodal latency model - Models fast path and slow path
pub struct BimodalLatency {
    fast_latency: Box<dyn LatencyModel>,
    slow_latency: Box<dyn LatencyModel>,
    fast_probability: f64,
    rng: Arc<Mutex<StdRng>>,
}

impl BimodalLatency {
    /// Create a new bimodal latency model with fast and slow paths
    #[must_use]
    pub fn new(
        fast_latency: Box<dyn LatencyModel>,
        slow_latency: Box<dyn LatencyModel>,
        fast_probability: f64,
    ) -> Self {
        Self {
            fast_latency,
            slow_latency,
            fast_probability,
            rng: Arc::new(Mutex::new(StdRng::from_seed([0; 32]))),
        }
    }

    /// Create a bimodal latency model with a specific seed for reproducibility
    pub fn with_seed(
        fast_latency: Box<dyn LatencyModel>,
        slow_latency: Box<dyn LatencyModel>,
        fast_probability: f64,
        seed: u64,
    ) -> Self {
        Self {
            fast_latency,
            slow_latency,
            fast_probability,
            rng: Arc::new(Mutex::new(StdRng::seed_from_u64(seed))),
        }
    }
}

impl LatencyModel for BimodalLatency {
    fn get_latency_ns(&self) -> u64 {
        use rand::Rng;
        let mut rng = self.rng.lock();
        if rng.random::<f64>() < self.fast_probability {
            self.fast_latency.get_latency_ns()
        } else {
            self.slow_latency.get_latency_ns()
        }
    }

    fn avg_latency_ns(&self) -> u64 {
        let fast_avg = self.fast_latency.avg_latency_ns() as f64;
        let slow_avg = self.slow_latency.avg_latency_ns() as f64;
        (fast_avg * self.fast_probability + slow_avg * (1.0 - self.fast_probability)) as u64
    }

    fn clone_box(&self) -> Box<dyn LatencyModel> {
        Box::new(BimodalLatency {
            fast_latency: self.fast_latency.clone_box(),
            slow_latency: self.slow_latency.clone_box(),
            fast_probability: self.fast_probability,
            rng: Arc::new(Mutex::new(StdRng::from_seed([0; 32]))),
        })
    }
}

/// Asset-specific latency model that can vary by symbol
pub struct AssetLatency {
    default_model: Box<dyn LatencyModel>,
    asset_models: Arc<Mutex<FxHashMap<String, Box<dyn LatencyModel>>>>,
}

impl AssetLatency {
    /// Create a new asset-specific latency model with a default fallback
    #[must_use]
    pub fn new(default_model: Box<dyn LatencyModel>) -> Self {
        Self {
            default_model,
            asset_models: Arc::new(Mutex::new(FxHashMap::default())),
        }
    }

    /// Add a symbol-specific latency model
    pub fn add_asset(&self, symbol: String, model: Box<dyn LatencyModel>) {
        self.asset_models.lock().insert(symbol, model);
    }
    /// Get latency for a specific asset, falling back to default if not found
    pub fn get_latency_for_asset(&self, symbol: &str) -> u64 {
        let models = self.asset_models.lock();
        if let Some(model) = models.get(symbol) {
            model.get_latency_ns()
        } else {
            self.default_model.get_latency_ns()
        }
    }
}

impl LatencyModel for AssetLatency {
    fn get_latency_ns(&self) -> u64 {
        self.default_model.get_latency_ns()
    }

    fn avg_latency_ns(&self) -> u64 {
        self.default_model.avg_latency_ns()
    }

    fn clone_box(&self) -> Box<dyn LatencyModel> {
        let new_models = Arc::new(Mutex::new(FxHashMap::default()));
        let models = self.asset_models.lock();
        for (symbol, model) in models.iter() {
            new_models.lock().insert(symbol.clone(), model.clone_box());
        }

        Box::new(AssetLatency {
            default_model: self.default_model.clone_box(),
            asset_models: new_models,
        })
    }
}

/// Common latency presets for different network conditions
pub mod presets {
    use super::*;

    /// Local/Colocation latency (< 100μs)
    #[must_use]
    pub fn colocation() -> Box<dyn LatencyModel> {
        Box::new(GaussianLatency::new(50_000, 10_000)) // 50μs ± 10μs
    }

    /// Same datacenter latency (100-500μs)
    #[must_use]
    pub fn datacenter() -> Box<dyn LatencyModel> {
        Box::new(GaussianLatency::new(250_000, 50_000)) // 250μs ± 50μs
    }

    /// Cross-region latency (1-10ms)
    #[must_use]
    pub fn cross_region() -> Box<dyn LatencyModel> {
        Box::new(GaussianLatency::new(5_000_000, 1_000_000)) // 5ms ± 1ms
    }

    /// Internet latency (10-100ms)
    #[must_use]
    pub fn internet() -> Box<dyn LatencyModel> {
        Box::new(BimodalLatency::new(
            Box::new(GaussianLatency::new(20_000_000, 5_000_000)), // Fast: 20ms ± 5ms
            Box::new(GaussianLatency::new(80_000_000, 20_000_000)), // Slow: 80ms ± 20ms
            0.8,                                                   // 80% fast path
        ))
    }

    /// Realistic exchange latency with jitter
    #[must_use]
    pub fn exchange_realistic() -> Box<dyn LatencyModel> {
        Box::new(BimodalLatency::new(
            Box::new(UniformLatency::new(100_000, 500_000)), // Fast: 100-500μs
            Box::new(GaussianLatency::new(2_000_000, 500_000)), // Slow: 2ms ± 0.5ms
            0.95,                                            // 95% fast path
        ))
    }
}

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

    #[test]
    fn test_fixed_latency() {
        let model = FixedLatency::from_micros(100);
        assert_eq!(model.get_latency_ns(), 100_000);
        assert_eq!(model.avg_latency_ns(), 100_000);
    }

    #[test]
    fn test_gaussian_latency() {
        let model = GaussianLatency::with_seed(1_000_000, 100_000, 42);
        let samples: Vec<u64> = (0..1000).map(|_| model.get_latency_ns()).collect();

        // Check that values are reasonable
        let avg: u64 = samples.iter().sum::<u64>() / samples.len() as u64;
        assert!(avg > 800_000 && avg < 1_200_000); // Within 20% of mean
    }

    #[test]
    fn test_bimodal_latency() {
        let fast = Box::new(FixedLatency::new(100_000));
        let slow = Box::new(FixedLatency::new(1_000_000));
        let model = BimodalLatency::with_seed(fast, slow, 0.8, 42);

        let samples: Vec<u64> = (0..1000).map(|_| model.get_latency_ns()).collect();
        let fast_count = samples.iter().filter(|&&x| x == 100_000).count();
        let slow_count = samples.iter().filter(|&&x| x == 1_000_000).count();

        assert_eq!(fast_count + slow_count, 1000);
        // Should be roughly 80% fast
        assert!(fast_count > 700 && fast_count < 900);
    }
}