Struct BacktestEngine 

pub struct BacktestEngine { /* private fields */ }

Core backtesting engine for running event-driven strategy backtests on historical data.

The BacktestEngine provides a high-fidelity simulation environment that processes historical market data chronologically through an event-driven architecture. It maintains simulated exchanges with realistic order matching and execution, allowing strategies to be tested exactly as they would run in live trading:

• Event-driven data replay with configurable latency models.
• Multi-venue and multi-asset support.
• Realistic order matching and execution simulation.
• Strategy and portfolio performance analysis.
• Transition from backtesting to live trading.

Implementations

impl BacktestEngine

pub fn new(config: BacktestEngineConfig) -> Result<Self>

Create a new BacktestEngine instance.

Errors

Returns an error if the core NautilusKernel fails to initialize.

pub const fn kernel(&self) -> &NautilusKernel

Returns a reference to the underlying kernel.

pub fn kernel_mut(&mut self) -> &mut NautilusKernel

Returns a mutable reference to the underlying kernel.

pub fn trader_id(&self) -> TraderId

Returns the trader ID for this engine.

pub fn machine_id(&self) -> &str

Returns the machine ID for this engine.

pub fn instance_id(&self) -> UUID4

Returns the unique instance ID for this engine.

pub fn iteration(&self) -> usize

Returns the current iteration count.

pub fn run_config_id(&self) -> Option<&str>

Returns the last run config ID, if any.

pub const fn run_id(&self) -> Option<UUID4>

Returns the last run ID, if any.

pub const fn run_started(&self) -> Option<UnixNanos>

Returns when the last run started, if any.

pub const fn run_finished(&self) -> Option<UnixNanos>

Returns when the last run finished, if any.

pub const fn backtest_start(&self) -> Option<UnixNanos>

Returns the last backtest range start, if any.

pub const fn backtest_end(&self) -> Option<UnixNanos>

Returns the last backtest range end, if any.

pub fn list_venues(&self) -> Vec<Venue>

Returns the list of registered venue identifiers.

pub fn add_venue(&mut self, config: SimulatedVenueConfig) -> Result<()>

Errors

Returns an error if initializing the simulated exchange for the venue fails.

pub fn set_settlement_price( &mut self, venue: Venue, instrument_id: InstrumentId, price: Price, ) -> Result<()>

Sets the settlement price for the specified venue instrument.

Errors

Returns an error if the venue has not been added to the engine.

pub fn change_fill_model(&mut self, venue: Venue, fill_model: FillModelAny)

Changes the fill model for the specified venue.

pub fn add_instrument(&mut self, instrument: &InstrumentAny) -> Result<()>

Adds an instrument to the backtest engine for the specified venue.

Errors

Returns an error if:

• The instrument’s associated venue has not been added via add_venue.
• Attempting to add a CurrencyPair instrument for a single-currency CASH account.

pub fn add_data( &mut self, data: Vec<Data>, _client_id: Option<ClientId>, validate: bool, sort: bool, ) -> Result<()>

Adds market data to the engine for replay during the backtest run.

Errors

Returns an error if:

• data is empty.
• validate is true and the instrument for the first element has not been added to the cache via add_instrument.
• validate is true and the first element is a [Data::Bar] whose aggregation_source is not [AggregationSource::External].

pub fn add_strategy<T>(&mut self, strategy: T) -> Result<()>

where T: Strategy + Component + Debug + 'static,

Adds a strategy to the backtest engine.

Errors

Returns an error if the strategy is already registered or the trader is in an invalid state for strategy registration.

pub fn add_strategies<T>(&mut self, strategies: Vec<T>) -> Result<()>

where T: Strategy + Component + Debug + 'static,

Adds the given strategies to the backtest engine. Stops at the first error.

Errors

Returns an error if any strategy fails to register; preceding strategies remain registered.

pub fn add_actor<T>(&mut self, actor: T) -> Result<()>

where T: DataActor + Component + Debug + 'static,

Adds an actor to the backtest engine.

Errors

Returns an error if the actor is already registered or the trader is in an invalid state for actor registration.

pub fn add_actors<T>(&mut self, actors: Vec<T>) -> Result<()>

where T: DataActor + Component + Debug + 'static,

Adds the given actors to the backtest engine. Stops at the first error.

Errors

Returns an error if any actor fails to register; preceding actors remain registered.

pub fn add_exec_algorithm<T>(&mut self, exec_algorithm: T) -> Result<()>

where T: ExecutionAlgorithm + Component + Debug + 'static,

Adds an execution algorithm to the backtest engine.

Errors

Returns an error if the algorithm is already registered or the trader is running.

pub fn add_exec_algorithms<T>(&mut self, exec_algorithms: Vec<T>) -> Result<()>

where T: ExecutionAlgorithm + Component + Debug + 'static,

Adds the given execution algorithms to the backtest engine. Stops at the first error.

Errors

Returns an error if any execution algorithm fails to register; preceding algorithms remain registered.

pub fn run( &mut self, start: Option<UnixNanos>, end: Option<UnixNanos>, run_config_id: Option<String>, streaming: bool, ) -> Result<()>

Run a backtest.

Processes all data chronologically. When streaming is false (default), finalizes the run via end. When streaming is true, the run pauses without finalizing so additional data batches can be loaded. Timer advancement stops at data exhaustion to avoid producing synthetic events (e.g. zero-volume bars) past the current batch.

Streaming workflow:

1. Add initial data and strategies
2. Loop: call run(streaming=true), clear_data(), add_data(next_batch)
3. After all batches: call end() to finalize

Errors

Returns an error if the backtest encounters an unrecoverable state.

pub fn end(&mut self)

Manually end the backtest.

pub fn reset(&mut self)

Reset the backtest engine.

All stateful fields are reset to their initial value. Data and instruments persist across resets to enable repeated runs with different strategies.

pub fn sort_data(&mut self)

Sort the engine’s internal data stream by timestamp.

Useful when data has been added with sort=false for batch performance, then sorted once before running.

pub fn clear_data(&mut self)

Clear the engine’s internal data stream. Does not clear instruments.

pub fn clear_actors(&mut self) -> Result<()>

Clear all actors from the engine’s internal trader.

Errors

Returns an error if any actor fails to dispose.

pub fn clear_strategies(&mut self) -> Result<()>

Clear all trading strategies from the engine’s internal trader.

Errors

Returns an error if any strategy fails to dispose.

pub fn clear_exec_algorithms(&mut self) -> Result<()>

Clear all execution algorithms from the engine’s internal trader.

Errors

Returns an error if any execution algorithm fails to dispose.

pub fn dispose(&mut self)

Dispose of the backtest engine, releasing all resources.

pub fn get_result(&self) -> BacktestResult

Return the backtest result from the last run.

pub fn add_data_client_if_not_exists(&mut self, client_id: ClientId)

Registers a data client for the given client_id if one does not already exist.

pub fn add_market_data_client_if_not_exists(&mut self, venue: Venue)

Registers a market data client for the given venue if one does not already exist.

Trait Implementations

impl Debug for BacktestEngine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.