Overhaul backtesting engine

1.

A `Decision` no longer only represents a set of weights in a target
portfolio. It is now an extensible union of actions that can be taken as
part of a strategy, with differing layers of abstraction.

The original `Decision` -- which was mainly parameterised by a set of
normalised weights and a cash weight -- is now known as a
`TargetWeightsDecision`. Other decisions involve a `MakeTradeDecision`,
or a `ReallocateDecision`.

The public API for creating these decision objects is intended to be one
of the free functions provided in backtest_lib.engine.decision. See the
updated notebooks for examples on how a decision should be constructed
by the end-user.

TODO: Re-export the free decision functions into the top-level library
import.

2.

The application of the strategy to the portfolio is now handled by an
`Engine`. An `Engine` consists of a `PlanGenerator` and a
`PlanExecutor`.

A `PlanGenerator` takes a `Decision` as input (along with some market
context) and returns a `Plan` which holds sequence of `PlanOp`s. The
exact union of ops that can constitute a plan generated by a
`PlanGenerator[T]` (that is, a `Plan[T]`) is T. This allows for varying
levels of realism, the highest of which possibly being a plan that
generates nothing except `MakeTradeOp`s, wherein the generator would
have type `PlanGenerator[MakeTradeOp]`.

Similarly, a `PlanExecutor[T]` will take a `Plan[T]`, as well as a
portfolio on which to execute (and market conditions), and produce an
artifact containing an "after" portfolio as well as a summary of the
effects of executing the plan (possibly with data representing "fees
paid" and actual fills etc.). This allows, again, for increasing levels
of realism (sophisticated slippage modelling etc.), and the ability to
pair any executor to any planner as long as they work with compatible
ops. This compatibility is statically checked at type-checking time.

Currently, the result of this execution is stored as an
`ExecutionResult`.

3.

This commit also fixes some typechecker errors and touches a bunch of
extra parts of the codebase because I got distracted.

Author: jathoms

src/backtest_lib/__init__.py

@@ -5,7 +5,7 @@
     QuantityPortfolio,
     WeightedPortfolio,
 )
-from backtest_lib.strategy import Decision, Strategy
+from backtest_lib.strategy import Strategy
 from backtest_lib.universe import PastUniversePrices
 
 __all__ = [
@@ -16,5 +16,4 @@
     "QuantityPortfolio",
     "FractionalQuantityPortfolio",
     "Strategy",
-    "Decision",
 ]

src/backtest_lib/backtest/__init__.py

@@ -5,15 +5,18 @@
 import warnings
 from typing import TYPE_CHECKING
 
-import numpy as np
-
 from backtest_lib.backtest._helpers import _to_pydt
 from backtest_lib.backtest.results import BacktestResults
 from backtest_lib.backtest.schedule import DecisionSchedule, make_decision_schedule
 from backtest_lib.backtest.settings import BacktestSettings
-from backtest_lib.market import MarketView, get_pastview_from_mapping
-from backtest_lib.portfolio import WeightedPortfolio
-from backtest_lib.strategy import Decision, Strategy
+from backtest_lib.engine import Engine, make_engine
+from backtest_lib.engine.execute.perfect_world import PerfectWorldPlanExecutor
+from backtest_lib.engine.plan.perfect_world import (
+    PerfectWorldPlanGenerator,
+)
+from backtest_lib.market import MarketView, get_pastview_type_from_backend
+from backtest_lib.portfolio import CashPortfolio, Portfolio, WeightedPortfolio
+from backtest_lib.strategy import Strategy
 from backtest_lib.strategy.context import StrategyContext
 
 if TYPE_CHECKING:
@@ -115,21 +118,27 @@ class Backtest:
     settings: BacktestSettings
     _schedule: DecisionSchedule
     _backend: type[PastView]
+    _engine: Engine
 
     def __init__(
         self,
         strategy: Strategy,
-        universe: Universe,
         market_view: MarketView,
         initial_portfolio: WeightedPortfolio,
+        universe: Universe | None = None,
         settings: BacktestSettings = _DEFAULT_BACKTEST_SETTINGS,
         *,
+        engine: Engine | None = None,
         decision_schedule: str | DecisionSchedule | None = None,
         backend="polars",
     ):
         self.strategy = strategy
-        self.universe = universe
+        self.universe = universe or tuple(market_view.securities)
         self.market_view = market_view
+        if isinstance(initial_portfolio, CashPortfolio):
+            initial_portfolio = initial_portfolio.materialize(
+                universe=self.universe, backend=backend
+            )
         self.initial_portfolio = initial_portfolio
         self.settings = settings
         if isinstance(decision_schedule, str):
@@ -142,25 +151,30 @@ def __init__(
             self._schedule = make_decision_schedule(market_view.periods)
         else:
             self._schedule = decision_schedule
-        self._backend = get_pastview_from_mapping(backend)
+        self._backend = get_pastview_type_from_backend(backend)
+
+        self._engine = engine or make_engine(
+            PerfectWorldPlanGenerator(),
+            PerfectWorldPlanExecutor(backend, self.universe),
+            self.universe,
+        )
 
     def run(self, ctx: StrategyContext | None = None) -> BacktestResults:
         schedule_it = iter(self._schedule)
         next_decision_period = next(schedule_it)
-        current_uni = None
         if ctx is None:
             ctx = StrategyContext()
-        output_weights: list[VectorMapping[str, float]] = []
-        returns_contribution: list[VectorMapping[str, float]] = []
+        output_holdings: list[VectorMapping[str, float]] = []
 
         self._current_portfolio = self.initial_portfolio
         yesterday_prices = self.market_view.prices.close.by_period[0]
 
         for i in range(1, len(self.market_view.periods) + 1):
             past_market_view = self.market_view.truncated_to(i)
+            today_prices = past_market_view.prices.close.by_period[-1]
             ctx.now = _to_pydt(self.market_view.periods[i - 1])
             logger.debug(
-                f"Starting period {i} ({ctx.now}). Current total growth:"
+                f"Starting period {i} ({ctx.now}). Current total portfolio value:"
                 f" {self._current_portfolio.total_value}",
             )
             if ctx.now >= _to_pydt(next_decision_period):
@@ -173,88 +187,58 @@ def run(self, ctx: StrategyContext | None = None) -> BacktestResults:
                     )
                     break
 
-                decision = self.strategy(
-                    universe=self.universe,
-                    current_portfolio=self._current_portfolio,
-                    market=past_market_view,
+                # NOTE: we are using close prices here. this is an implicit assumption.
+                # the user may want to use (low+high)/2, mid price, VWAP/TWAP.
+                result = self._engine.execute_strategy(
+                    strategy=self.strategy,
+                    portfolio=self._current_portfolio,
+                    market=self.market_view,
                     ctx=ctx,
+                    prices=yesterday_prices,
                 )
-                if len(decision.target.holdings) < len(self.universe):
-                    # pad out the unnaccounted-for securities with 0.
-                    # NOTE: this is some extra allocation we might not need
-                    # as * 0 allocates, and so does + in the case where
-                    # keys are not equal.
-                    # maybe a .merge() method on the VectorMapping would make
-                    # more sense.
-                    logger.debug(
-                        "Incomplete universe returned by strategy (decision had"
-                        f" {len(decision.target.holdings)}, full universe has"
-                        f" {len(self.universe)}), filling remaining securities with 0.",
-                    )
-                    object.__setattr__(
-                        decision.target,
-                        "holdings",
-                        (
-                            (self.market_view.prices.close.by_period[0] * 0)
-                            + decision.target.holdings
-                        ),
-                    )
 
-                if current_uni is not None and set(
-                    decision.target.holdings.keys(),
-                ) ^ set(current_uni):
-                    logger.debug(
-                        f"{ctx.now}: Universe changed! len:"
-                        f" {len(current_uni)}->{len(decision.target.holdings.keys())},"
-                        " diff:"
-                        f" {set(current_uni) ^ set(decision.target.holdings.keys())}",
-                    )
+                # problem: we convert into quantities a lot even when we may not have
+                # to. i.e when the user is using a PerfectWorldGenerator/Executor and
+                # only wants to pass target weights.
+                # idea: allow a decorator or something on the user's strategy to say:
+                # @weight_based or @quantity_based or something else so we can optimize
+                # our backtesting behaviour due to not neeeding constant conversions.
+                portfolio_after_decision = result.after.into_quantities(
+                    yesterday_prices
+                )
+                logger.debug(
+                    f"engine output for {ctx.now}: {result.after.holdings}, "
+                    f"cash: {result.after.cash}"
+                )
 
                 if past_market_view.tradable is not None:
                     _check_tradable(
-                        decision,
+                        portfolio_after_decision,
                         past_market_view.tradable.by_period[-1],
                         ctx.now,
                     )
-
-                target_portfolio = decision.target
-                if not isinstance(target_portfolio, WeightedPortfolio):
-                    target_portfolio = target_portfolio.into_weighted()
-                total_weight_after_decision = (
-                    decision.target.holdings.sum() + decision.target.cash
-                )
-
-                assert np.isclose(total_weight_after_decision, 1.0), (
-                    "Total weight after making a decision cannot exceed 1.0, "
-                    f"weight on period {i} was {total_weight_after_decision}"
-                )
-
-                if not self.settings.allow_short and any(
-                    x < 0 for x in target_portfolio.holdings.values()
-                ):
-                    target_portfolio = target_portfolio.into_long_only()
-
-                # assume we can perfectly track the target portfolio for now
-                portfolio_after_decision = target_portfolio
             else:
-                portfolio_after_decision = self._current_portfolio
-            output_weights.append(portfolio_after_decision.holdings)
+                portfolio_after_decision = self._current_portfolio.into_quantities(
+                    yesterday_prices
+                )
+            # TODO: the weights can be calculated as part of the results calculation,
+            pf_as_weights = portfolio_after_decision.into_weighted(
+                prices=yesterday_prices
+            )
+            output_holdings.append(pf_as_weights.holdings)
 
-            today_prices = past_market_view.prices.close.by_period[-1]
             pct_change = today_prices / yesterday_prices
-            returns_contribution.append(pct_change * portfolio_after_decision.holdings)
 
             inter_day_adjusted_portfolio = _apply_inter_period_price_changes(
-                portfolio_after_decision,
+                pf_as_weights,
                 pct_change,
             )
 
             self._current_portfolio = inter_day_adjusted_portfolio
             yesterday_prices = today_prices
-            current_uni = list(portfolio_after_decision.holdings.keys())
 
-        allocation_history = self._backend.from_security_mappings(
-            output_weights,
+        allocation_history: PastView = self._backend.from_security_mappings(
+            output_holdings,
             self.market_view.periods[: i - 1],
         )
         results = BacktestResults.from_weights_market_initial_capital(
@@ -285,24 +269,28 @@ def _apply_inter_period_price_changes(
     return WeightedPortfolio(
         cash=new_cash,
         holdings=new_holdings,
+        universe=new_holdings.keys(),  # brittle, review this
         total_value=portfolio.total_value * new_total_weight,
+        constructor_backend=portfolio._backend,
     )
 
 
 def _check_tradable(
-    decision: Decision,
+    portfolio_after_decision: Portfolio,
     tradable_mapping: UniverseMapping,
     now: dt.datetime,
 ):
     tradable = {
         security for security, is_tradable in tradable_mapping.items() if is_tradable
     }
     logger.debug(f"Tradable len: {len(tradable)}")
-    logger.debug(f"Decision weights len: {len(decision.target.holdings.keys())}")
+    logger.debug(
+        f"New portfolio weights len:  {len(portfolio_after_decision.holdings.keys())}"
+    )
     msgs = [
         f"Security '{sec}' is marked as non-tradable on period {now} but is given a"
         f" value of {val}."
-        for sec, val in decision.target.holdings.items()
+        for sec, val in portfolio_after_decision.holdings.items()
         if val > 0 and sec not in tradable
     ]
     if msgs:

src/backtest_lib/backtest/results.py

@@ -19,8 +19,6 @@
 class BacktestResults[IndexT: Comparable]:
     """
     Snapshot of a backtest's results, with key statistics pre-computed.
-
-    This is a continuous-weight (no integer position rounding) model.
     """
 
     periods: Sequence[IndexT] = field(repr=False)
@@ -246,7 +244,7 @@ def from_weights_market_initial_capital(
             .collect()
         )
 
-        asset_returns = backend.from_dataframe(asset_returns_df)
+        asset_returns: PastView = backend.from_dataframe(asset_returns_df)
 
         results = BacktestResults.from_weights_and_returns(
             weights=weights,

src/backtest_lib/engine/__init__.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from backtest_lib.engine.execute import PlanExecutor
+from backtest_lib.engine.plan import PlanGenerator
+from backtest_lib.market import MarketView
+from backtest_lib.strategy import Strategy
+from backtest_lib.strategy.context import StrategyContext
+from backtest_lib.universe.universe_mapping import UniverseMapping
+
+if TYPE_CHECKING:
+    from backtest_lib.engine.execute import ExecutionResult
+    from backtest_lib.engine.plan import PlanOp
+    from backtest_lib.portfolio import Portfolio
+
+
+class Engine[TPlanOp: PlanOp]:
+    _planner: PlanGenerator[TPlanOp]
+    _executor: PlanExecutor[TPlanOp]
+    _universe: tuple[str, ...]
+
+    def __init__(
+        self,
+        planner: PlanGenerator[TPlanOp],
+        executor: PlanExecutor[TPlanOp],
+        universe: Iterable[str],
+    ):
+        self._planner = planner
+        self._executor = executor
+        self._universe = tuple(universe)
+
+    def execute_strategy(
+        self,
+        strategy: Strategy,
+        portfolio: Portfolio,
+        market: MarketView,
+        ctx: StrategyContext,
+        prices: UniverseMapping,
+    ) -> ExecutionResult:
+        decision = strategy(
+            universe=self._universe,
+            current_portfolio=portfolio,
+            market=market,
+            ctx=ctx,
+        )
+        return self._executor.execute_plan(
+            self._planner.generate_plan(decision, prices),
+            portfolio=portfolio,
+            prices=prices,
+            market=market,
+        )
+
+
+def make_engine[TPlanOp: PlanOp](
+    planner: PlanGenerator[TPlanOp],
+    executor: PlanExecutor[TPlanOp],
+    universe: Iterable[str],
+) -> Engine[TPlanOp]:
+    return Engine(planner, executor, universe)