engine/strategies/

avellaneda_stoikov_bilateral_hawkes_order_flow_imbalance.rs

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

/// Parameters for the bilateral Hawkes with order flow imbalance FDM strategy.
///
/// The strategy uses two precomputed FDM lookup tables indexed by
/// [inventory q, buy intensity lambda+, sell intensity lambda-, time remaining tau].
/// The tables are generated by solving the `BilateralHawkesOrderFlowImbalance` HJB PDE offline.
///
/// The key behavioral difference from plain `BilateralHawkes`:
/// - Spreads adapt to order flow imbalance (lambda+ vs lambda-) with sensitivity parameter eta
/// - When lambda+ > lambda- (toxic buying): widens ask, narrows bid
/// - When lambda- > lambda+ (toxic selling): narrows ask, widens bid
#[derive(Clone, Debug)]
pub struct AvellanedaStoikovBilateralHawkesOrderFlowImbalanceParameters {
    /// Trading horizon in model seconds -- must match the tau axis of the tables.
    pub t_horizon: f64,
    /// Fallback buy-side intensity when `hawkes_buy_intensity` is absent.
    pub base_intensity_buy: f64,
    /// Fallback sell-side intensity when `hawkes_sell_intensity` is absent.
    pub base_intensity_sell: f64,
}

/// Avellaneda-Stoikov strategy driven by precomputed FDM bilateral-Hawkes-with-OFI spreads.
///
/// On every tick the strategy:
///   1. Reads `hawkes_buy_intensity` (lambda+) and `hawkes_sell_intensity` (lambda-)
///      from `obs.parameters`.
///   2. Interpolates the 4-D FDM spread tables at `(q, lambda+, lambda-, tau)`.
///   3. Places bid/ask orders at `mid -/+ interpolated_spread`.
///
/// The spreads embed the adverse-selection response to order flow imbalance,
/// automatically skewing quotes when one side is more toxic than the other.
///
/// # Table format
/// Both tables must be 4-dimensional with axes `[q, lambda+, lambda-, tau]`:
///   - axis 0: inventory grid (e.g. -10..10, 21 points)
///   - axis 1: buy-side intensity grid (e.g. 0.0..8.0, 40 points)
///   - axis 2: sell-side intensity grid (e.g. 0.0..8.0, 40 points)
///   - axis 3: time remaining in seconds (0.0..T_HORIZON)
#[derive(Clone)]
pub struct AvellanedaStoikovBilateralHawkesOrderFlowImbalanceStrategy {
    pub params: AvellanedaStoikovBilateralHawkesOrderFlowImbalanceParameters,
    /// 4D lookup table for the bid half-spread: axes [q, lambda+, lambda-, tau].
    pub bid_spread_table: Arc<LookupTable>,
    /// 4D lookup table for the ask half-spread: axes [q, lambda+, lambda-, tau].
    pub ask_spread_table: Arc<LookupTable>,
    q_min: f64,
    q_max: f64,
    start_time: Option<f64>,
    order_counter: u64,
}

impl AvellanedaStoikovBilateralHawkesOrderFlowImbalanceStrategy {
    pub fn new(
        params: AvellanedaStoikovBilateralHawkesOrderFlowImbalanceParameters,
        bid_spread_table: Arc<LookupTable>,
        ask_spread_table: Arc<LookupTable>,
    ) -> Self {
        assert_eq!(
            bid_spread_table.axes.len(),
            4,
            "bid table must be 4D [q, lambda+, lambda-, tau]"
        );
        assert_eq!(
            ask_spread_table.axes.len(),
            4,
            "ask table must be 4D [q, lambda+, lambda-, tau]"
        );
        let q_axis = &bid_spread_table.axes[0];
        assert!(!q_axis.is_empty(), "q axis must not be empty");
        let q_min = q_axis[0];
        let q_max = q_axis[q_axis.len() - 1];
        Self {
            params,
            bid_spread_table,
            ask_spread_table,
            q_min,
            q_max,
            start_time: None,
            order_counter: 0,
        }
    }
}

impl Strategy for AvellanedaStoikovBilateralHawkesOrderFlowImbalanceStrategy {
    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;

        let params = obs.parameters.as_ref();

        // lambda+ = buy market-order intensity (drives ask fills)
        let lambda_plus = params
            .and_then(|p| p.get("hawkes_buy_intensity").copied())
            .unwrap_or(self.params.base_intensity_buy);

        // lambda- = sell market-order intensity (drives bid fills)
        let lambda_minus = params
            .and_then(|p| p.get("hawkes_sell_intensity").copied())
            .unwrap_or(self.params.base_intensity_sell);

        // Clamp to 1e-9 rather than 0.0 -- see avellaneda_stoikov_heston.rs.
        let delta_bid = self
            .bid_spread_table
            .interpolate(&[q, lambda_plus, lambda_minus, tau])
            .max(1e-9);
        let delta_ask = self
            .ask_spread_table
            .interpolate(&[q, lambda_plus, lambda_minus, tau])
            .max(1e-9);

        // Use exact prices (no tick rounding). See avellaneda_stoikov_heston.rs.
        let bid_price = mid - delta_bid;
        let ask_price = mid + delta_ask;
        // Mirror the HJB calibration boundary enforcement:
        //   lambda_bid_fill = 0 when q >= q_max  =>  no bid at or above q_max
        //   lambda_ask_fill = 0 when q <= q_min  =>  no ask at or below q_min
        let place_bid = q < self.q_max;
        let place_ask = q > self.q_min;

        requests.push(OrderRequest::CancelAll);
        if place_bid {
            self.order_counter += 1;
            let bid_id = self.order_counter;
            requests.push(OrderRequest::New(Order::new(
                bid_id,
                Side::Buy,
                bid_price,
                1.0,
            )));
        }
        if place_ask {
            self.order_counter += 1;
            let ask_id = self.order_counter;
            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_4d(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)
    }

    #[allow(dead_code)]
    fn make_obs_ofi(position: f64, lambda_plus: f64, lambda_minus: f64) -> Observation {
        let mut params = std::collections::HashMap::new();
        params.insert("hawkes_buy_intensity".to_string(), lambda_plus);
        params.insert("hawkes_sell_intensity".to_string(), lambda_minus);
        Observation {
            timestamp: 0.0,
            best_bid: 99.95,
            best_ask: 100.05,
            last_price: Some(100.0),
            portfolio: PortfolioSnapshot {
                cash: 10_000.0,
                position: position,
            },
            volatility: None,
            drift: None,
            parameters: Some(params),
        }
    }

    #[test]
    fn test_ofi_strategy_creation() {
        let axes = vec![
            vec![-10.0, 0.0, 10.0],
            vec![0.0, 1.0, 2.0],
            vec![0.0, 1.0, 2.0],
            vec![0.0, 500.0, 1000.0],
        ];
        let bid_tbl = flat_table_4d(axes.clone(), 0.05);
        let ask_tbl = flat_table_4d(axes, 0.05);

        let params = AvellanedaStoikovBilateralHawkesOrderFlowImbalanceParameters {
            t_horizon: 1000.0,
            base_intensity_buy: 1.0,
            base_intensity_sell: 1.0,
        };

        let strategy = AvellanedaStoikovBilateralHawkesOrderFlowImbalanceStrategy::new(
            params,
            Arc::new(bid_tbl),
            Arc::new(ask_tbl),
        );

        assert_eq!(strategy.params.t_horizon, 1000.0);
    }
}