Skip to main content
Version: latest

Backtest

The backtest subpackage groups components relating to backtesting.

This module provides a data client for backtesting.

class BacktestDataClient​

Bases: DataClient

BacktestDataClient(ClientId client_id, MessageBus msgbus, Cache cache, Clock clock, config: PoseiConfig | None = None) -> None Provides an implementation of DataClient for backtesting.

  • Parameters:
    • client_id (ClientId) – The data client ID.
    • msgbus (MessageBus) – The message bus for the client.
    • cache (Cache) – The cache for the client.
    • clock (Clock) – The clock for the client.
    • config (PoseiConfig , optional) – The configuration for the instance.

degrade(self) → void​

Degrade the component.

While executing on_degrade() any exception will be logged and reraised, then the component will remain in a DEGRADING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

dispose(self) → void​

Dispose of the component.

While executing on_dispose() any exception will be logged and reraised, then the component will remain in a DISPOSING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

fault(self) → void​

Fault the component.

Calling this method multiple times has the same effect as calling it once (it is idempotent). Once called, it cannot be reversed, and no other methods should be called on this instance.

While executing on_fault() any exception will be logged and reraised, then the component will remain in a FAULTING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

classmethod fully_qualified_name(cls) → str​

Return the fully qualified name for the components class.

  • Return type: str

id​

The components ID.

  • Returns: ComponentId

is_connected​

If the client is connected.

  • Returns: bool

is_degraded​

bool Return whether the current component state is DEGRADED.

  • Return type: bool
  • Type: Component.is_degraded

is_disposed​

bool Return whether the current component state is DISPOSED.

  • Return type: bool
  • Type: Component.is_disposed

is_faulted​

bool Return whether the current component state is FAULTED.

  • Return type: bool
  • Type: Component.is_faulted

is_initialized​

bool Return whether the component has been initialized (component.state >= INITIALIZED).

  • Return type: bool
  • Type: Component.is_initialized

is_running​

bool Return whether the current component state is RUNNING.

  • Return type: bool
  • Type: Component.is_running

is_stopped​

bool Return whether the current component state is STOPPED.

  • Return type: bool
  • Type: Component.is_stopped

request(self, RequestData request) → void​

reset(self) → void​

Reset the component.

All stateful fields are reset to their initial value.

While executing on_reset() any exception will be logged and reraised, then the component will remain in a RESETTING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

resume(self) → void​

Resume the component.

While executing on_resume() any exception will be logged and reraised, then the component will remain in a RESUMING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

shutdown_system(self, str reason=None) → void​

Initiate a system-wide shutdown by generating and publishing a ShutdownSystem command.

The command is handled by the system’s PoseiKernel, which will invoke either stop (synchronously) or stop_async (asynchronously) depending on the execution context and the presence of an active event loop.

  • Parameters: reason (str , optional) – The reason for issuing the shutdown command.

start(self) → void​

Start the component.

While executing on_start() any exception will be logged and reraised, then the component will remain in a STARTING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

state​

ComponentState Return the components current state.

  • Return type: ComponentState
  • Type: Component.state

stop(self) → void​

Stop the component.

While executing on_stop() any exception will be logged and reraised, then the component will remain in a STOPPING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

subscribe(self, SubscribeData command) → void​

subscribed_custom_data(self) → list​

Return the custom data types subscribed to.

trader_id​

The trader ID associated with the component.

  • Returns: TraderId

type​

The components type.

  • Returns: type

unsubscribe(self, UnsubscribeData command) → void​

venue​

The clients venue ID (if applicable).

  • Returns: Venue or None

class BacktestMarketDataClient​

Bases: MarketDataClient

BacktestMarketDataClient(ClientId client_id, MessageBus msgbus, Cache cache, Clock clock) Provides an implementation of MarketDataClient for backtesting.

  • Parameters:
    • client_id (ClientId) – The data client ID.
    • msgbus (MessageBus) – The message bus for the client.
    • cache (Cache) – The cache for the client.
    • clock (Clock) – The clock for the client.

degrade(self) → void​

Degrade the component.

While executing on_degrade() any exception will be logged and reraised, then the component will remain in a DEGRADING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

dispose(self) → void​

Dispose of the component.

While executing on_dispose() any exception will be logged and reraised, then the component will remain in a DISPOSING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

fault(self) → void​

Fault the component.

Calling this method multiple times has the same effect as calling it once (it is idempotent). Once called, it cannot be reversed, and no other methods should be called on this instance.

While executing on_fault() any exception will be logged and reraised, then the component will remain in a FAULTING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

classmethod fully_qualified_name(cls) → str​

Return the fully qualified name for the components class.

  • Return type: str

id​

The components ID.

  • Returns: ComponentId

is_connected​

If the client is connected.

  • Returns: bool

is_degraded​

bool Return whether the current component state is DEGRADED.

  • Return type: bool
  • Type: Component.is_degraded

is_disposed​

bool Return whether the current component state is DISPOSED.

  • Return type: bool
  • Type: Component.is_disposed

is_faulted​

bool Return whether the current component state is FAULTED.

  • Return type: bool
  • Type: Component.is_faulted

is_initialized​

bool Return whether the component has been initialized (component.state >= INITIALIZED).

  • Return type: bool
  • Type: Component.is_initialized

is_running​

bool Return whether the current component state is RUNNING.

  • Return type: bool
  • Type: Component.is_running

is_stopped​

bool Return whether the current component state is STOPPED.

  • Return type: bool
  • Type: Component.is_stopped

request(self, RequestData request) → void​

Request data for the given data type.

  • Parameters: request (RequestData) – The message for the data request.

request_bars(self, RequestBars request) → void​

request_instrument(self, RequestInstrument request) → void​

request_instruments(self, RequestInstruments request) → void​

request_order_book_snapshot(self, RequestOrderBookSnapshot request) → void​

request_quote_ticks(self, RequestQuoteTicks request) → void​

request_trade_ticks(self, RequestTradeTicks request) → void​

reset(self) → void​

Reset the component.

All stateful fields are reset to their initial value.

While executing on_reset() any exception will be logged and reraised, then the component will remain in a RESETTING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

resume(self) → void​

Resume the component.

While executing on_resume() any exception will be logged and reraised, then the component will remain in a RESUMING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

shutdown_system(self, str reason=None) → void​

Initiate a system-wide shutdown by generating and publishing a ShutdownSystem command.

The command is handled by the system’s PoseiKernel, which will invoke either stop (synchronously) or stop_async (asynchronously) depending on the execution context and the presence of an active event loop.

  • Parameters: reason (str , optional) – The reason for issuing the shutdown command.

start(self) → void​

Start the component.

While executing on_start() any exception will be logged and reraised, then the component will remain in a STARTING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

state​

ComponentState Return the components current state.

  • Return type: ComponentState
  • Type: Component.state

stop(self) → void​

Stop the component.

While executing on_stop() any exception will be logged and reraised, then the component will remain in a STOPPING state.

WARNING​

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

subscribe(self, SubscribeData command) → void​

Subscribe to data for the given data type.

  • Parameters:
    • data_type (DataType) – The data type for the subscription.
    • params (dict *[*str , Any ] , optional) – Additional params for the subscription.

subscribe_bars(self, SubscribeBars command) → void​

subscribe_index_prices(self, SubscribeIndexPrices command) → void​

subscribe_instrument(self, SubscribeInstrument command) → void​

subscribe_instrument_close(self, SubscribeInstrumentClose command) → void​

subscribe_instrument_status(self, SubscribeInstrumentStatus command) → void​

subscribe_instruments(self, SubscribeInstruments command) → void​

subscribe_mark_prices(self, SubscribeMarkPrices command) → void​

subscribe_order_book_deltas(self, SubscribeOrderBook command) → void​

subscribe_order_book_snapshots(self, SubscribeOrderBook command) → void​

subscribe_quote_ticks(self, SubscribeQuoteTicks command) → void​

subscribe_trade_ticks(self, SubscribeTradeTicks command) → void​

subscribed_bars(self) → list​

Return the bar types subscribed to.

subscribed_custom_data(self) → list​

Return the custom data types subscribed to.

subscribed_index_prices(self) → list​

Return the index price update instruments subscribed to.

subscribed_instrument_close(self) → list​

Return the instrument closes subscribed to.

subscribed_instrument_status(self) → list​

Return the status update instruments subscribed to.

subscribed_instruments(self) → list​

Return the instruments subscribed to.

subscribed_mark_prices(self) → list​

Return the mark price update instruments subscribed to.

subscribed_order_book_deltas(self) → list​

Return the order book delta instruments subscribed to.

subscribed_order_book_snapshots(self) → list​

Return the order book snapshot instruments subscribed to.

subscribed_quote_ticks(self) → list​

Return the quote tick instruments subscribed to.

subscribed_trade_ticks(self) → list​

Return the trade tick instruments subscribed to.

trader_id​

The trader ID associated with the component.

  • Returns: TraderId

type​

The components type.

  • Returns: type

unsubscribe(self, UnsubscribeData command) → void​

Unsubscribe from data for the given data type.

  • Parameters:
    • data_type (DataType) – The data type for the subscription.
    • params (dict *[*str , Any ] , optional) – Additional params for the subscription.

unsubscribe_bars(self, UnsubscribeBars command) → void​

unsubscribe_index_prices(self, UnsubscribeIndexPrices command) → void​

unsubscribe_instrument(self, UnsubscribeInstrument command) → void​

unsubscribe_instrument_close(self, UnsubscribeInstrumentClose command) → void​

unsubscribe_instrument_status(self, UnsubscribeInstrumentStatus command) → void​

unsubscribe_instruments(self, UnsubscribeInstruments command) → void​

unsubscribe_mark_prices(self, UnsubscribeMarkPrices command) → void​

unsubscribe_order_book_deltas(self, UnsubscribeOrderBook command) → void​

unsubscribe_order_book_snapshots(self, UnsubscribeOrderBook command) → void​

unsubscribe_quote_ticks(self, UnsubscribeQuoteTicks command) → void​

unsubscribe_trade_ticks(self, UnsubscribeTradeTicks command) → void​

venue​

The clients venue ID (if applicable).

  • Returns: Venue or None

class BacktestDataIterator​

Bases: object

BacktestDataIterator(empty_data_callback: Callable[[str, uint64_t], None] | None = None) -> None

add_data(self, str data_name, list data_list, bool append_data=True) → void​

all_data(self) → dict​

data(self, str data_name) → list​

is_done(self) → bool​

next(self) → Data​

remove_data(self, str data_name) → void​

reset(self) → void​

set_index(self, str data_name, int index) → void​

class BacktestEngine​

Bases: object

BacktestEngine(config: BacktestEngineConfig | None = None) -> None Provides a backtest engine to run a portfolio of strategies over historical data.

  • Parameters: config (BacktestEngineConfig , optional) – The configuration for the instance.
  • Raises: TypeError – If config is not of type BacktestEngineConfig.

add_actor(self, Actor actor: Actor) → None​

Add the given actor to the backtest engine.

  • Parameters: actor (Actor) – The actor to add.

add_actors(self, list actors: list[Actor]) → None​

Add the given list of actors to the backtest engine.

  • Parameters: actors (list [Actor ]) – The actors to add.

add_data(self, list data, ClientId client_id=None, bool validate=True, bool sort=True) → None​

Add the given data to the backtest engine.

  • Parameters:
    • data (list [Data ]) – The data to add.
    • client_id (ClientId , optional) – The client ID to associate with the data.
    • validate (bool , default True) – If data should be validated (recommended when adding data directly to the engine).
    • sort (bool , default True) – If data should be sorted by ts_init with the rest of the stream after adding (recommended when adding data directly to the engine).
  • Raises:
    • ValueError – If data is empty.
    • ValueError – If data contains objects which are not a type of Data.
    • ValueError – If instrument_id for the data is not found in the cache.
    • ValueError – If data elements do not have an instrument_id and client_id is None.
    • TypeError – If data is a Rust PyO3 data type (cannot add directly to engine yet).

WARNING​

Assumes all data elements are of the same type. Adding lists of varying data types could result in incorrect backtest logic.

Caution if adding data without sort being True, as this could lead to running backtests on a stream which does not have monotonically increasing timestamps.

add_exec_algorithm(self, ExecAlgorithm exec_algorithm: ExecAlgorithm) → None​

Add the given execution algorithm to the backtest engine.

  • Parameters: exec_algorithm (ExecAlgorithm) – The execution algorithm to add.

add_exec_algorithms(self, list exec_algorithms: list[ExecAlgorithm]) → None​

Add the given list of execution algorithms to the backtest engine.

  • Parameters: exec_algorithms (list [ExecAlgorithm ]) – The execution algorithms to add.

add_instrument(self, Instrument instrument) → None​

Add the instrument to the backtest engine.

The instrument must be valid for its associated venue. For instance, derivative instruments which would trade on margin cannot be added to a venue with a CASH account.

add_strategies(self, list strategies: list[Strategy]) → None​

Add the given list of strategies to the backtest engine.

  • Parameters: strategies (list [Strategy ]) – The strategies to add.

add_strategy(self, Strategy strategy: Strategy) → None​

Add the given strategy to the backtest engine.

  • Parameters: strategy (Strategy) – The strategy to add.

add_venue(self, Venue venue: Venue, OmsType oms_type: OmsType, AccountType account_type: AccountType, list starting_balances: list[Money], Currency base_currency: Currency | None = None, default_leverage: Decimal | None = None, dict leverages: dict[InstrumentId, Decimal] | None = None, list modules: list[SimulationModule] | None = None, FillModel fill_model: FillModel | None = None, FeeModel fee_model: FeeModel | None = None, LatencyModel latency_model: LatencyModel | None = None, BookType book_type: BookType = BookType.L1_MBP, routing: bool = False, frozen_account: bool = False, reject_stop_orders: bool = True, support_gtd_orders: bool = True, support_contingent_orders: bool = True, use_position_ids: bool = True, use_random_ids: bool = False, use_reduce_only: bool = True, use_message_queue: bool = True, bar_execution: bool = True, bar_adaptive_high_low_ordering: bool = False, trade_execution: bool = False) → None​

Add a SimulatedExchange with the given parameters to the backtest engine.

  • Parameters:
    • venue (Venue) – The venue ID.
    • oms_type (OmsType {HEDGING, NETTING}) – The order management system type for the exchange. If HEDGING will generate new position IDs.
    • account_type (AccountType) – The account type for the exchange.
    • starting_balances (list [Money ]) – The starting account balances (specify one for a single asset account).
    • base_currency (Currency , optional) – The account base currency for the client. Use None for multi-currency accounts.
    • default_leverage (Decimal , optional) – The account default leverage (for margin accounts).
    • leverages (dict [InstrumentId , Decimal ] , optional) – The instrument specific leverage configuration (for margin accounts).
    • modules (list [SimulationModule ] , optional) – The simulation modules to load into the exchange.
    • fill_model (FillModel , optional) – The fill model for the exchange.
    • fee_model (FeeModel , optional) – The fee model for the venue.
    • latency_model (LatencyModel , optional) – The latency model for the exchange.
    • book_type (BookType, default BookType.L1_MBP) – The default order book type.
    • routing (bool , default False) – If multi-venue routing should be enabled for the execution client.
    • frozen_account (bool , default False) – If the account for this exchange is frozen (balances will not change).
    • reject_stop_orders (bool , default True) – If stop orders are rejected on submission if trigger price is in the market.
    • support_gtd_orders (bool , default True) – If orders with GTD time in force will be supported by the venue.
    • support_contingent_orders (bool , default True) – If contingent orders will be supported/respected by the venue. If False, then it’s expected the strategy will be managing any contingent orders.
    • use_position_ids (bool , default True) – If venue position IDs will be generated on order fills.
    • use_random_ids (bool , default False) – If all venue generated identifiers will be random UUID4’s.
    • use_reduce_only (bool , default True) – If the reduce_only execution instruction on orders will be honored.
    • use_message_queue (bool , default True) – If an internal message queue should be used to process trading commands in sequence after they have initially arrived. Setting this to False would be appropriate for real-time sandbox environments, where we don’t want to introduce additional latency of waiting for the next data event before processing the trading command.
    • bar_execution (bool , default True) – If bars should be processed by the matching engine(s) (and move the market).
    • bar_adaptive_high_low_ordering (bool , default False) – Determines whether the processing order of bar prices is adaptive based on a heuristic. This setting is only relevant when bar_execution is True. If False, bar prices are always processed in the fixed order: Open, High, Low, Close. If True, the processing order adapts with the heuristic:
      • If High is closer to Open than Low then the processing order is Open, High, Low, Close.
      • If Low is closer to Open than High then the processing order is Open, Low, High, Close.
    • trade_execution (bool , default False) – If trades should be processed by the matching engine(s) (and move the market).
  • Raises: ValueError – If venue is already registered with the engine.

backtest_end​

pd.Timestamp | None Return the last backtest run time range end (if run).

  • Return type: pd.Timestamp or None
  • Type: BacktestEngine.backtest_end

backtest_start​

pd.Timestamp | None Return the last backtest run time range start (if run).

  • Return type: pd.Timestamp or None
  • Type: BacktestEngine.backtest_start

cache​

CacheFacade Return the engines internal read-only cache.

change_fill_model(self, Venue venue, FillModel model) → None​

Change the fill model for the exchange of the given venue.

  • Parameters:
    • venue (Venue) – The venue of the simulated exchange.
    • model (FillModel) – The fill model to change to.

clear_actors(self) → None​

Clear all actors from the engines internal trader.

clear_data(self) → None​

Clear the engines internal data stream.

Does not clear added instruments.

clear_exec_algorithms(self) → None​

Clear all execution algorithms from the engines internal trader.

clear_strategies(self) → None​

Clear all trading strategies from the engines internal trader.

data​

list[Data] Return the engines internal data stream.

  • Return type: list[Data]
  • Type: BacktestEngine.data

dispose(self) → None​

Dispose of the backtest engine by disposing the trader and releasing system resources.

Calling this method multiple times has the same effect as calling it once (it is idempotent). Once called, it cannot be reversed, and no other methods should be called on this instance.

dump_pickled_data(self) → bytes​

Return the internal data stream pickled.

  • Return type: bytes

end(self)​

Manually end the backtest.

get_log_guard(self) → posei_pyo3.LogGuard | LogGuard | None​

Return the global logging systems log guard.

May return None if the logging system was already initialized.

  • Return type: posei_pyo3.LogGuard | LogGuard | None

get_result(self)​

Return the backtest result from the last run.

instance_id​

UUID4 Return the engines instance ID.

This is a unique identifier per initialized engine.

  • Return type: UUID4
  • Type: BacktestEngine.instance_id

iteration​

int Return the backtest engine iteration count.

  • Return type: int
  • Type: BacktestEngine.iteration

kernel​

NautilusKernel Return the internal kernel for the engine.

list_venues(self) → list[Venue]​

Return the venues contained within the engine.

  • Return type: list[Venue]

load_pickled_data(self, bytes data) → None​

Load the given pickled data directly into the internal data stream.

It is highly advised to only pass data to this method which was obtained through a call to .dump_pickled_data().

WARNING​

This low-level direct access method makes the following assumptions: : - The data contains valid Nautilus objects only, which inherit from Data.

  • The data was successfully pickled from a call to pickle.dumps().
  • The data was sorted prior to pickling.
  • All required instruments have been added to the engine.

logger​

Logger Return the internal logger for the engine.

  • Return type: Logger
  • Type: BacktestEngine.logger

machine_id​

str Return the engines machine ID.

  • Return type: str
  • Type: BacktestEngine.machine_id

portfolio​

PortfolioFacade Return the engines internal read-only portfolio.

reset(self) → None​

Reset the backtest engine.

All stateful fields are reset to their initial value.

Note: instruments and data are not dropped/reset, this can be done through a separate call to .clear_data() if desired.

run(self, start: datetime | str | int | None = None, end: datetime | str | int | None = None, str run_config_id: str | None = None, streaming: bool = False) → None​

Run a backtest.

At the end of the run the trader and strategies will be stopped, then post-run analysis performed.

For datasets larger than available memory, use streaming mode with the following sequence:

    1. Add initial data batch and strategies
    1. Call run(streaming=True)
    1. Call clear_data()
    1. Add next batch of data stream
    1. Call run(streaming=False) or end() when processing the final batch
  • Parameters:

    • start (datetime or str or int , optional) – The start datetime (UTC) for the backtest run. If None engine runs from the start of the data.

    • end (datetime or str or int , optional) – The end datetime (UTC) for the backtest run. If None engine runs to the end of the data.

    • run_config_id (str , optional) – The tokenized BacktestRunConfig ID.

    • streaming (bool , default False) –

      Controls data loading and processing mode:

      • If False (default): Loads all data at once.

      This is currently the only supported mode for custom data (e.g., option Greeks).

      • If True, loads data in chunks for memory-efficient processing of large datasets.
  • Raises:
    • ValueError – If no data has been added to the engine.
    • ValueError – If the start is >= the end datetime.

run_config_id​

str Return the last backtest engine run config ID.

  • Return type: str or None
  • Type: BacktestEngine.run_config_id

run_finished​

pd.Timestamp | None Return when the last backtest run finished (if run).

  • Return type: pd.Timestamp or None
  • Type: BacktestEngine.run_finished

run_id​

UUID4 Return the last backtest engine run ID (if run).

  • Return type: UUID4 or None
  • Type: BacktestEngine.run_id

run_started​

pd.Timestamp | None Return when the last backtest run started (if run).

  • Return type: pd.Timestamp or None
  • Type: BacktestEngine.run_started

trader​

Trader Return the engines internal trader.

  • Return type: Trader
  • Type: BacktestEngine.trader

trader_id​

TraderId Return the engines trader ID.

  • Return type: TraderId
  • Type: BacktestEngine.trader_id

class SimulatedExchange