Backtest

class backtest_lib.Backtest(strategy: Strategy, market_view: MarketView, initial_portfolio: Portfolio | Cash, universe: Universe | None = None, settings: BacktestSettings = BacktestSettings(allow_short=False), *, engine: Engine | None = None, decision_schedule: str | DecisionSchedule | None = None, backend='polars')

Runs a historical simulation of a Strategy over a MarketView and a Universe.

Backtest is a lightweight orchestration object that iterates through market periods, invokes the strategy on configured decision dates, and updates the simulated portfolio by applying inter-period price changes. The resulting allocation history is materialized via a configurable PastView backend and converted into BacktestResults.

The simulation model is intentionally simple:

• Decisions are evaluated on a DecisionSchedule. Between decision points, the portfolio weights drift only due to price movements.

• The backtest assumes the portfolio can be rebalanced to the strategy’s target portfolio exactly at decision times (i.e., no slippage/fees unless incorporated elsewhere).

• Strategies may return an incomplete set of holdings; missing securities are padded with zero weight to match the full universe.

• If BacktestSettings.allow_short is False and the target contains negative weights, the target is coerced into a long-only portfolio.

Parameters:

• strategy – Callable strategy that produces a Decision given the current universe, portfolio, market view, and optional context.

• universe – The tradable security set defining the expected holdings keys. See Universe.

• market_view – Historical market data used for pricing and period iteration. See MarketView. The decision schedule defaults to market_view.periods when not provided.

• initial_portfolio – Starting WeightedPortfolio used to initialize the simulation state.

• settings – Controls simulation constraints (e.g., shorting). Defaults to BacktestSettings.default.

• decision_schedule –

  Rebalance schedule. May be:

  • A DecisionSchedule instance,

  • A string specification consumed by make_decision_schedule(), or

  • None, in which case a schedule is constructed from market_view.periods.

• backend – Backend identifier used to select the PastView implementation used for data manipulation, memory allocation, and results view. Default (and currently only implemented) backend is “polars”.

strategy

Strategy under test.

Type:

Strategy

universe

Universe used for padding/consistency checks.

Type:

Universe

market_view

Market data used during the run.

Type:

MarketView

initial_portfolio

Starting portfolio at the beginning of the run.

Type:

Portfolio

settings

Backtest configuration settings.

Type:

BacktestSettings

Example

>>> import backtest_lib as btl
>>> from polars import read_csv
>>> spot_prices = read_csv("docs/assets/data/spot_prices.csv")
>>> market = btl.MarketView(spot_prices)
>>> universe = market.securities
>>> def hold_strategy(universe, current_portfolio, market, ctx):
...     return btl.hold()
>>> bt = btl.Backtest(hold_strategy, market, btl.uniform_portfolio(universe))
>>> results = bt.run()
>>> results.annualized_return
-0.00035649...