feat(backtest): scheduled deposits in vector backtest

Vector backtest engine now honours BrokerBalanceTracker schedules so
DCA-style accumulation strategies can be backtested with realistic
external cash flows. Adds scenario test for deposit schedules.

Author: MDUYN

docusaurus/docs/Advanced Concepts/vector-backtesting.md

@@ -40,6 +40,20 @@ Use vector backtesting when:
 - Needing to complete backtests quickly
 - Working with large strategy sets (100+ strategies)
 
+:::warning Order types not modelled in vector backtests
+Vector backtesting evaluates strategy **signals** (`generate_buy_signals`, `generate_sell_signals`) against the price series. It does **not** simulate the order book, intra-bar price paths, partial fills, or order-type semantics.
+
+This means the following are **only evaluated in event-driven backtests** and live trading:
+
+- `OrderType.MARKET` slippage and next-bar fill behaviour
+- `OrderType.LIMIT` resting fill logic
+- `OrderType.STOP` and `OrderType.STOP_LIMIT` trigger logic
+- Take-profit / stop-loss rules attached to trades
+- Blotter slippage / commission / volume-based fill models
+
+The recommended workflow is to use vector backtests to **screen parameter combinations quickly** based on signal quality, then promote the survivors to **event-driven backtests** where realistic execution is simulated. See [Orders](../Getting%20Started/orders) for the full order-type reference.
+:::
+
 ## Basic Usage
 
 ### Single Strategy, Single Date Range

investing_algorithm_framework/infrastructure/services/backtesting/vector_backtest_service.py

@@ -257,6 +257,20 @@ def run(
         total_allocated = 0.0  # Track total allocated in static mode
         open_trades_value = {}  # Track value of open trades per symbol
 
+        # Pre-compute scheduled external deposits (e.g. monthly paychecks)
+        # for the backtest window. Vector backtests are single-pass and
+        # have no Context, so we eagerly resolve the full schedule into a
+        # sorted (timestamp, amount) list and credit ``current_unallocated``
+        # the first bar at-or-after each timestamp. Net effect for the
+        # strategy: the simulated broker balance grows on cadence, and the
+        # equity curve / metrics include the external cash flows just like
+        # the event backtest does after a sync_portfolio call.
+        deposit_events = self._resolve_deposit_schedule(
+            portfolio_configuration=portfolio_configuration,
+            backtest_date_range=backtest_date_range,
+        )
+        deposit_event_idx = 0
+
         def _close_trade(sym, sym_data, price, date):
             """Helper to close an open trade for a symbol."""
             nonlocal current_unallocated, total_realized_gains, \
@@ -537,6 +551,17 @@ def _partial_close(sym, sym_data, price, date, sell_pct):
             if current_date.tzinfo is None:
                 current_date = current_date.replace(tzinfo=timezone.utc)
 
+            # Apply any scheduled external deposits whose timestamp has
+            # been reached by ``current_date``. Each event fires exactly
+            # once at the first bar at-or-after its scheduled time.
+            while (
+                deposit_event_idx < len(deposit_events)
+                and deposit_events[deposit_event_idx][0] <= current_date
+            ):
+                _, deposit_amount = deposit_events[deposit_event_idx]
+                current_unallocated += deposit_amount
+                deposit_event_idx += 1
+
             # Process each symbol at this timestamp
             for symbol, data in symbol_data.items():
                 current_price = float(data['close'].iloc[i])
@@ -728,13 +753,31 @@ def _partial_close(sym, sym_data, price, date, sell_pct):
         unallocated = initial_amount
         total_net_gain = 0.0
         open_trades = []
+        # Replay deposit events for snapshot bookkeeping. Each snapshot
+        # gets ``cash_flow`` set to whatever external cash landed between
+        # the previous snapshot and this one — this is what enables
+        # TWR-aware return metrics (CAGR, monthly/yearly returns) to
+        # subtract external deposits before computing returns.
+        deposit_replay_idx = 0
 
         # Create portfolio snapshots
         for ts in index:
             allocated = 0
             interval_datetime = pd.Timestamp(ts).to_pydatetime()
             interval_datetime = interval_datetime.replace(tzinfo=timezone.utc)
 
+            # Apply any deposits that fired between the previous snapshot
+            # and this one, accumulating them into snapshot_cash_flow.
+            snapshot_cash_flow = 0.0
+            while (
+                deposit_replay_idx < len(deposit_events)
+                and deposit_events[deposit_replay_idx][0] <= interval_datetime
+            ):
+                _, deposit_amount = deposit_events[deposit_replay_idx]
+                unallocated += deposit_amount
+                snapshot_cash_flow += deposit_amount
+                deposit_replay_idx += 1
+
             for trade in trades:
 
                 if trade.opened_at == interval_datetime:
@@ -761,14 +804,15 @@ def _partial_close(sym, sym_data, price, date, sell_pct):
                 allocated += open_trade.filled_amount * price
 
             # total_value = invested_value + unallocated
-            # total_net_gain = total_value - initial_amount
+            # total_net_gain = total_value - initial_amount - sum(cash_flow)
             snapshots.append(
                 PortfolioSnapshot(
                     portfolio_id=portfolio.identifier,
                     created_at=interval_datetime,
                     unallocated=unallocated,
                     total_value=unallocated + allocated,
-                    total_net_gain=total_net_gain
+                    total_net_gain=total_net_gain,
+                    cash_flow=snapshot_cash_flow,
                 )
             )
 
@@ -830,6 +874,34 @@ def _partial_close(sym, sym_data, price, date, sell_pct):
         )
         return run
 
+    @staticmethod
+    def _resolve_deposit_schedule(
+        portfolio_configuration,
+        backtest_date_range,
+    ):
+        """Materialise a portfolio's deposit schedule for the backtest window.
+
+        Returns a chronologically sorted list of ``(timestamp, amount)``
+        tuples. Empty when the configuration has no schedule.
+        """
+        schedule = list(
+            getattr(portfolio_configuration, "deposit_schedule", []) or []
+        )
+        if not schedule:
+            return []
+        # Local import to avoid a circular import between domain and
+        # infrastructure layers.
+        from investing_algorithm_framework.services.portfolios \
+            .broker_balance_tracker import BrokerBalanceTracker
+        tracker = BrokerBalanceTracker()
+        market = portfolio_configuration.market
+        tracker.set_schedule(market, schedule)
+        return tracker.project_total(
+            market=market,
+            start=backtest_date_range.start_date,
+            end=backtest_date_range.end_date,
+        )
+
     @staticmethod
     def _convert_recorded_values(raw_recorded):
         """

investing_algorithm_framework/services/trade_order_evaluator/backtest_trade_oder_evaluator.py

@@ -132,7 +132,64 @@ def _check_has_executed(self, order, ohlcv_df):
             )
             return
 
-        # Limit orders: check if OHLCV data triggers a fill
+        # Stop / Stop-Limit orders: first check whether the trigger
+        # condition is met. Once triggered, a STOP becomes a market
+        # order (fill at trigger price) and a STOP_LIMIT becomes a
+        # limit order at the configured limit price.
+        is_stop = OrderType.STOP.equals(order.order_type)
+        is_stop_limit = OrderType.STOP_LIMIT.equals(order.order_type)
+
+        if (is_stop or is_stop_limit) and not order.is_triggered():
+            stop_price = order.get_stop_price()
+
+            if stop_price is None:
+                return
+
+            # SELL stop triggers when price drops to or below stop_price;
+            # BUY stop triggers when price rises to or above stop_price.
+            if OrderSide.SELL.equals(order_side):
+                trigger_candles = ohlcv_data_after_order.filter(
+                    pl.col('Low') <= stop_price
+                )
+            elif OrderSide.BUY.equals(order_side):
+                trigger_candles = ohlcv_data_after_order.filter(
+                    pl.col('High') >= stop_price
+                )
+            else:
+                return
+
+            if trigger_candles.is_empty():
+                return
+
+            triggered_candle = trigger_candles.head(1)
+            order.set_triggered_at(triggered_candle["Datetime"][0])
+
+            if is_stop:
+                # STOP becomes a market order — fill at the stop price
+                # using the triggering candle's volume.
+                volume = (
+                    triggered_candle["Volume"][0]
+                    if "Volume" in triggered_candle.columns
+                    else None
+                )
+                self._apply_fill(
+                    order, stop_price, order_side, volume,
+                    is_market_order=True
+                )
+                return
+
+            # STOP_LIMIT: continue and fall through to limit-fill logic
+            # using the configured limit price (`order.price`). Restrict
+            # the fill search to candles at or after the trigger.
+            ohlcv_data_after_order = ohlcv_data_after_order.filter(
+                pl.col('Datetime') >= order.get_triggered_at()
+            )
+
+            if ohlcv_data_after_order.is_empty():
+                return
+
+        # Limit orders (including triggered STOP_LIMIT):
+        # check if OHLCV data triggers a fill
         if OrderSide.BUY.equals(order_side):
             fill_candles = ohlcv_data_after_order.filter(
                 pl.col('Low') <= order_price
@@ -233,6 +290,11 @@ def _apply_fill(
                 'order_fee': accumulated_fee,
             }
 
+        # Persist trigger timestamp for stop / stop-limit orders so
+        # subsequent evaluations don't re-trigger.
+        if order.is_triggered():
+            update_data['triggered_at'] = order.get_triggered_at()
+
         # Market order portfolio reconciliation
         if is_market_order and new_remaining <= 0:
             estimated_price = order.estimated_price

tests/scenarios/vectorized_backtests/test_deposit_schedule.py

@@ -0,0 +1,61 @@
+"""Unit test for VectorBacktestService._resolve_deposit_schedule."""
+from datetime import datetime, timezone
+from unittest import TestCase
+
+from investing_algorithm_framework import (
+    BacktestDateRange,
+    PortfolioConfiguration,
+    ScheduledDeposit,
+    TimeUnit,
+)
+from investing_algorithm_framework.infrastructure.services.backtesting \
+    .vector_backtest_service import VectorBacktestService
+
+
+def _utc(year, month, day):
+    return datetime(year, month, day, tzinfo=timezone.utc)
+
+
+class TestVectorBacktestDepositSchedule(TestCase):
+
+    def test_no_schedule_returns_empty(self):
+        config = PortfolioConfiguration(
+            market="BITVAVO", trading_symbol="EUR", initial_balance=1000
+        )
+        events = VectorBacktestService._resolve_deposit_schedule(
+            portfolio_configuration=config,
+            backtest_date_range=BacktestDateRange(
+                start_date=_utc(2024, 1, 1),
+                end_date=_utc(2024, 6, 1),
+            ),
+        )
+        self.assertEqual([], events)
+
+    def test_recurring_and_one_shot_combined(self):
+        config = PortfolioConfiguration(
+            market="BITVAVO",
+            trading_symbol="EUR",
+            initial_balance=1000,
+            deposit_schedule=[
+                ScheduledDeposit(
+                    amount=100.0, time_unit=TimeUnit.DAY, interval=30
+                ),
+                ScheduledDeposit(amount=500.0, on=_utc(2024, 2, 15)),
+            ],
+        )
+        events = VectorBacktestService._resolve_deposit_schedule(
+            portfolio_configuration=config,
+            backtest_date_range=BacktestDateRange(
+                start_date=_utc(2024, 1, 1),
+                end_date=_utc(2024, 4, 1),
+            ),
+        )
+        self.assertEqual(
+            [
+                (_utc(2024, 1, 31), 100.0),
+                (_utc(2024, 2, 15), 500.0),
+                (_utc(2024, 3, 1), 100.0),
+                (_utc(2024, 3, 31), 100.0),
+            ],
+            events,
+        )