engine/strategies/

avellaneda_stoikov_hawkes.rs

use super::Strategy;
use crate::types::{Observation, Order, OrderRequest, Side};
use solver::lookup::LookupTable;
use std::path::Path;
use std::sync::Arc;

/// Parameters for the Hawkes-aware Avellaneda-Stoikov strategy.
///
/// The strategy uses two precomputed FDM lookup tables (bid spread, ask spread)
/// indexed by [inventory q, Hawkes intensity lambda, time remaining tau].
/// Tables are generated offline via `examples/gen_hawkes_table.rs`.
#[derive(Clone, Debug, Default)]
pub struct AvellanedaStoikovHawkesParameters {
    /// Trading horizon in seconds -- must match the tau axis of the loaded tables.
    pub t_horizon: f64,
    /// Simulation time step in seconds (used only for elapsed-time calculation).
    pub dt: f64,
    /// Fallback arrival rate when `hawkes_intensity` is absent from the observation.
    /// Typically set to the baseline mu of the Hawkes process.
    pub base_intensity: f64,
}

/// Avellaneda-Stoikov strategy driven by precomputed FDM Hawkes spreads.
///
/// On every tick the strategy:
///   1. Reads `hawkes_intensity` from `obs.parameters` (injected by the engine
///      from `StochasticMatcher::augment_parameters`).
///   2. Interpolates the FDM spread tables at `(q, lambda, tau)`.
///   3. Places bid/ask orders at `mid +/- interpolated_spread`.
///
/// # Table format
/// Both tables must be 3-dimensional with axes `[q, lambda, tau]`:
///   - axis 0: inventory grid (same range used by the FDM solver, e.g. -10..10)
///   - axis 1: Hawkes intensity grid (e.g. 0.0 .. lambda_max)
///   - axis 2: time remaining in seconds (0.0 .. T, increasing)
///
/// Use `examples/gen_hawkes_table.rs` to generate compatible `.bin` files.
#[derive(Clone)]
pub struct AvellanedaStoikovHawkesStrategy {
    pub params: AvellanedaStoikovHawkesParameters,
    /// 3D lookup table for the bid half-spread: axes [q, lambda, tau].
    pub bid_spread_table: Arc<LookupTable>,
    /// 3D lookup table for the ask half-spread: axes [q, lambda, tau].
    pub ask_spread_table: Arc<LookupTable>,
    start_time: Option<f64>,
    order_counter: u64,
}

impl AvellanedaStoikovHawkesStrategy {
    pub fn new(
        params: AvellanedaStoikovHawkesParameters,
        bid_spread_table: Arc<LookupTable>,
        ask_spread_table: Arc<LookupTable>,
    ) -> Self {
        assert_eq!(
            bid_spread_table.axes.len(),
            3,
            "bid table must be 3D [q, lambda, tau]"
        );
        assert_eq!(
            ask_spread_table.axes.len(),
            3,
            "ask table must be 3D [q, lambda, tau]"
        );
        Self {
            params,
            bid_spread_table,
            ask_spread_table,
            start_time: None,
            order_counter: 0,
        }
    }

    /// Load both spread tables from `.bin` files produced by the table
    /// generation example.
    pub fn load(
        params: AvellanedaStoikovHawkesParameters,
        bid_path: &Path,
        ask_path: &Path,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        let bid_spread_table = Arc::new(LookupTable::load(bid_path)?);
        let ask_spread_table = Arc::new(LookupTable::load(ask_path)?);
        Ok(Self::new(params, bid_spread_table, ask_spread_table))
    }
}

impl Strategy for AvellanedaStoikovHawkesStrategy {
    fn on_tick(&mut self, obs: &Observation, requests: &mut Vec<OrderRequest>) {
        if self.start_time.is_none() {
            self.start_time = Some(obs.timestamp);
        }

        let elapsed = obs.timestamp - self.start_time.unwrap();
        let tau = (self.params.t_horizon - elapsed).max(0.0);

        if tau <= 0.0 {
            requests.push(OrderRequest::CancelAll);
            return;
        }

        let mid = obs.mid_price();
        let q = obs.portfolio.position;

        // In regular Hawkes mode the engine publishes a single "hawkes_intensity".
        // In bilateral mode it publishes "hawkes_buy_intensity" (lambda+, buy MOs
        // arrive and hit the ask) and "hawkes_sell_intensity" (lambda-, sell MOs
        // arrive and hit the bid).
        //
        // Mapping to the 3-D tables [q, lambda, tau]:
        //   bid spread -- driven by sell-side market order flow (lambda-)
        //   ask spread -- driven by buy-side  market order flow (lambda+)
        let params = obs.parameters.as_ref();
        let unified = params.and_then(|p| p.get("hawkes_intensity").copied());
        let lambda_bid = params
            .and_then(|p| p.get("hawkes_sell_intensity").copied())
            .or(unified)
            .unwrap_or(self.params.base_intensity);
        let lambda_ask = params
            .and_then(|p| p.get("hawkes_buy_intensity").copied())
            .or(unified)
            .unwrap_or(self.params.base_intensity);

        let delta_bid = self
            .bid_spread_table
            .interpolate(&[q, lambda_bid, tau])
            .max(0.0);
        let delta_ask = self
            .ask_spread_table
            .interpolate(&[q, lambda_ask, tau])
            .max(0.0);

        let bid_price = ((mid - delta_bid) * 100.0).round() / 100.0;
        let ask_price = ((mid + delta_ask) * 100.0).round() / 100.0;

        self.order_counter += 1;
        let bid_id = self.order_counter;
        self.order_counter += 1;
        let ask_id = self.order_counter;

        requests.push(OrderRequest::CancelAll);
        requests.push(OrderRequest::New(Order::new(
            bid_id,
            Side::Buy,
            bid_price,
            1.0,
        )));
        requests.push(OrderRequest::New(Order::new(
            ask_id,
            Side::Sell,
            ask_price,
            1.0,
        )));
    }

    fn as_any(&self) -> &dyn std::any::Any {
        self
    }
    fn as_any_mut(&mut self) -> &mut dyn std::any::Any {
        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::PortfolioSnapshot;
    use ndarray::{ArrayD, IxDyn};
    use solver::lookup::LookupTable;

    fn flat_table(axes: Vec<Vec<f64>>, value: f64) -> LookupTable {
        let shape: Vec<usize> = axes.iter().map(|a| a.len()).collect();
        let n: usize = shape.iter().product();
        let data = ArrayD::from_shape_vec(IxDyn(&shape), vec![value; n]).unwrap();
        LookupTable::new(axes, data)
    }

    fn make_obs(position: f64, intensity: f64) -> Observation {
        let mut params = std::collections::HashMap::new();
        params.insert("hawkes_intensity".to_string(), intensity);
        Observation {
            timestamp: 0.0,
            best_bid: 99.95,
            best_ask: 100.05,
            last_price: Some(100.0),
            portfolio: PortfolioSnapshot {
                cash: 10000.0,
                position,
            },
            volatility: None,
            drift: None,
            parameters: Some(params),
        }
    }

    #[test]
    fn test_places_quotes_at_flat_spread() {
        let axes = vec![
            vec![-1.0, 0.0, 1.0],     // q
            vec![0.5, 1.0, 2.0],      // lambda
            vec![0.0, 500.0, 1000.0], // tau
        ];
        let bid_table = flat_table(axes.clone(), 0.05);
        let ask_table = flat_table(axes, 0.05);
        let params = AvellanedaStoikovHawkesParameters {
            t_horizon: 1000.0,
            dt: 1.0,
            base_intensity: 1.0,
        };
        let mut strategy =
            AvellanedaStoikovHawkesStrategy::new(params, Arc::new(bid_table), Arc::new(ask_table));
        let obs = make_obs(0.0, 1.0);

        let mut requests = Vec::new();
        strategy.on_tick(&obs, &mut requests);

        assert_eq!(requests.len(), 3); // CancelAll + 2 orders
        let bid = match &requests[1] {
            OrderRequest::New(o) => {
                assert_eq!(o.side, Side::Buy);
                o.limit_price
            }
            _ => panic!("expected bid order"),
        };
        let ask = match &requests[2] {
            OrderRequest::New(o) => {
                assert_eq!(o.side, Side::Sell);
                o.limit_price
            }
            _ => panic!("expected ask order"),
        };
        assert!((bid - 99.95).abs() < 0.01);
        assert!((ask - 100.05).abs() < 0.01);
    }

    #[test]
    fn test_fallback_to_base_intensity_when_params_absent() {
        let axes = vec![vec![0.0], vec![1.0], vec![0.0, 1000.0]];
        let bid_table = flat_table(axes.clone(), 0.03);
        let ask_table = flat_table(axes, 0.03);
        let params = AvellanedaStoikovHawkesParameters {
            t_horizon: 1000.0,
            dt: 1.0,
            base_intensity: 1.0,
        };
        let mut strategy =
            AvellanedaStoikovHawkesStrategy::new(params, Arc::new(bid_table), Arc::new(ask_table));
        let obs_no_params = Observation {
            timestamp: 0.0,
            best_bid: 99.95,
            best_ask: 100.05,
            last_price: None,
            portfolio: PortfolioSnapshot {
                cash: 10000.0,
                position: 0.0,
            },
            volatility: None,
            drift: None,
            parameters: None,
        };
        let mut requests = Vec::new();
        strategy.on_tick(&obs_no_params, &mut requests);
        assert_eq!(requests.len(), 3);
    }

    #[test]
    fn test_cancels_at_end_of_horizon() {
        let axes = vec![vec![0.0], vec![1.0], vec![0.0]];
        let t = Arc::new(flat_table(axes.clone(), 0.05));
        let params = AvellanedaStoikovHawkesParameters {
            t_horizon: 0.0,
            dt: 1.0,
            base_intensity: 1.0,
        };
        let mut strategy = AvellanedaStoikovHawkesStrategy::new(params, Arc::clone(&t), t);
        let obs = make_obs(0.0, 1.0);
        let mut requests = Vec::new();
        strategy.on_tick(&obs, &mut requests);
        assert_eq!(requests.len(), 1);
        assert!(matches!(requests[0], OrderRequest::CancelAll));
    }

    #[test]
    fn test_bilateral_hawkes_uses_side_specific_intensities() {
        // bid spread table has value 0.10, ask spread table has value 0.20.
        // In bilateral mode the bid spread is driven by lambda- (sell intensity = 0.5)
        // and the ask spread is driven by lambda+ (buy intensity = 2.0).
        // Both use the same flat tables so the spread values should be 0.10 / 0.20.
        let axes = vec![
            vec![-1.0, 0.0, 1.0],
            vec![0.0, 1.0, 3.0],
            vec![0.0, 500.0, 1000.0],
        ];
        let bid_table = Arc::new(flat_table(axes.clone(), 0.10));
        let ask_table = Arc::new(flat_table(axes, 0.20));
        let params = AvellanedaStoikovHawkesParameters {
            t_horizon: 1000.0,
            dt: 1.0,
            base_intensity: 1.0,
        };
        let mut strategy = AvellanedaStoikovHawkesStrategy::new(params, bid_table, ask_table);

        let mut bilateral_params = std::collections::HashMap::new();
        bilateral_params.insert("hawkes_buy_intensity".to_string(), 2.0);
        bilateral_params.insert("hawkes_sell_intensity".to_string(), 0.5);
        let obs = Observation {
            timestamp: 0.0,
            best_bid: 99.95,
            best_ask: 100.05,
            last_price: Some(100.0),
            portfolio: PortfolioSnapshot {
                cash: 10000.0,
                position: 0.0,
            },
            volatility: None,
            drift: None,
            parameters: Some(bilateral_params),
        };

        let mut requests = Vec::new();
        strategy.on_tick(&obs, &mut requests);

        let bid_price = match &requests[1] {
            OrderRequest::New(o) => o.limit_price,
            _ => panic!("expected bid order"),
        };
        let ask_price = match &requests[2] {
            OrderRequest::New(o) => o.limit_price,
            _ => panic!("expected ask order"),
        };
        // mid=100.0; bid = 100.0 - 0.10 = 99.90; ask = 100.0 + 0.20 = 100.20
        assert!((bid_price - 99.90).abs() < 0.01, "bid_price={bid_price}");
        assert!((ask_price - 100.20).abs() < 0.01, "ask_price={ask_price}");
    }
}