Skip to main content

nautilus_backtest/python/
engine.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Python bindings for [`BacktestEngine`].
17
18use std::collections::HashMap;
19
20use ahash::AHashMap;
21use nautilus_common::{
22    actor::data_actor::ImportableActorConfig,
23    enums::ComponentState,
24    python::{
25        actor::{PyDataActor, prepare_python_actor},
26        cache::PyCache,
27        config_error_to_pyvalue_err,
28    },
29};
30use nautilus_core::{
31    UUID4, UnixNanos,
32    python::{to_pyruntime_err, to_pytype_err, to_pyvalue_err},
33};
34use nautilus_execution::{
35    matching_engine::config::OrderPriorityResetPolicy,
36    python::{
37        fee::pyobject_to_fee_model_handle, fill::pyobject_to_fill_model_handle,
38        latency::pyobject_to_latency_model_any,
39    },
40};
41#[cfg(feature = "defi")]
42use nautilus_model::defi::DefiData;
43use nautilus_model::{
44    data::{
45        Bar, CustomData, Data, FundingRateUpdate, IndexPriceUpdate, InstrumentClose,
46        InstrumentStatus, MarkPriceUpdate, OptionGreeks, OrderBookDelta, OrderBookDeltas,
47        OrderBookDepth, QuoteTick, TradeTick,
48    },
49    enums::{AccountType, BookType, OmsType, OtoTriggerMode},
50    identifiers::{AccountId, ActorId, ClientId, ExecAlgorithmId, InstrumentId, TraderId, Venue},
51    python::{
52        account::margin_model::pyobject_to_margin_model_any,
53        instruments::pyobject_to_instrument_any,
54    },
55    types::{Currency, Money},
56};
57use nautilus_portfolio::python::PyPortfolio;
58#[cfg(feature = "examples")]
59use nautilus_trading::examples::strategies::{
60    CompositeMarketMaker, CompositeMarketMakerConfig, DeltaNeutralVol, DeltaNeutralVolConfig,
61    EmaCross, EmaCrossConfig, GridMarketMaker, GridMarketMakerConfig, HurstVpinDirectional,
62    HurstVpinDirectionalConfig, OrderBookImbalance, OrderBookImbalanceConfig,
63};
64use nautilus_trading::{
65    ImportableExecutionAlgorithmConfig, ImportableStrategyConfig,
66    algorithm::{TwapAlgorithm, TwapAlgorithmConfig},
67    python::algorithm::PyExecutionAlgorithm,
68};
69use pyo3::prelude::*;
70use rust_decimal::Decimal;
71
72use super::{modules::pyobject_to_simulation_module_handle, node::create_importable_component};
73use crate::{
74    config::{BacktestEngineConfig, SimulatedVenueConfig},
75    engine::BacktestEngine,
76    result::BacktestResult,
77};
78
79/// PyO3 wrapper around [`BacktestEngine`].
80///
81/// Exposes the backtest engine to Python as `BacktestEngine`.
82/// Uses `unsendable` because the inner engine holds `Rc<RefCell<...>>`.
83#[pyo3::pyclass(
84    module = "nautilus_trader.backtest",
85    name = "BacktestEngine",
86    unsendable
87)]
88#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.backtest")]
89#[derive(Debug)]
90pub struct PyBacktestEngine(BacktestEngine);
91
92// DeFi methods live in their own fully gated `#[pymethods]` block (multiple-pymethods is enabled)
93// so the `gen_stub`/pyo3 expansion never references `DefiData` in non-DeFi builds.
94#[cfg(feature = "defi")]
95#[pyo3_stub_gen::derive::gen_stub_pymethods]
96#[pymethods]
97impl PyBacktestEngine {
98    /// Adds DeFi data to the engine.
99    #[pyo3(name = "add_defi_data", signature = (data, client_id=None, sort=true))]
100    fn py_add_defi_data(
101        &mut self,
102        data: Vec<DefiData>,
103        client_id: Option<ClientId>,
104        sort: bool,
105    ) -> PyResult<()> {
106        self.0
107            .add_defi_data(data, client_id, sort)
108            .map_err(to_pyruntime_err)
109    }
110}
111
112#[pyo3_stub_gen::derive::gen_stub_pymethods]
113#[pymethods]
114impl PyBacktestEngine {
115    #[new]
116    fn py_new(config: BacktestEngineConfig) -> PyResult<Self> {
117        let engine = BacktestEngine::new(config).map_err(to_pyruntime_err)?;
118        Ok(Self(engine))
119    }
120
121    /// Adds a simulated exchange with the given parameters to the engine.
122    ///
123    /// # Liquidation parameters
124    ///
125    /// - `liquidation_enabled` (bool, default `False`): if margin liquidation should be
126    ///   triggered when the account's equity falls to or below the maintenance
127    ///   margin threshold scaled by `liquidation_trigger_ratio`.
128    /// - `liquidation_trigger_ratio` (float, optional, default `1.0`): the ratio of
129    ///   maintenance margin used as the liquidation threshold. A value of `1.0`
130    ///   liquidates when equity <= maintenance margin; higher values trigger earlier.
131    /// - `liquidation_cancel_open_orders` (bool, default `True`): if open resting
132    ///   orders for the venue should be cancelled before synthetic close-out fills
133    ///   are emitted for open positions.
134    #[pyo3(
135        name = "add_venue",
136        signature = (
137            venue,
138            oms_type,
139            account_type,
140            starting_balances,
141            base_currency = None,
142            default_leverage = None,
143            leverages = None,
144            fill_model = None,
145            fee_model = None,
146            margin_model = None,
147            latency_model = None,
148            modules = None,
149            book_type = BookType::L1_MBP,
150            routing = false,
151            reject_stop_orders = true,
152            support_gtd_orders = true,
153            support_contingent_orders = true,
154            use_position_ids = true,
155            use_random_ids = false,
156            use_reduce_only = true,
157            use_message_queue = true,
158            use_market_order_acks = false,
159            bar_execution = true,
160            bar_adaptive_high_low_ordering = false,
161            trade_execution = true,
162            liquidity_consumption = false,
163            queue_position = false,
164            allow_cash_borrowing = false,
165            frozen_account = false,
166            oto_trigger_mode = OtoTriggerMode::Partial,
167            price_protection_points = None,
168            liquidation_enabled = false,
169            liquidation_trigger_ratio = None,
170            liquidation_cancel_open_orders = true,
171            order_priority_reset_policy = OrderPriorityResetPolicy::PriceChange,
172        )
173    )]
174    #[expect(
175        clippy::fn_params_excessive_bools,
176        clippy::too_many_arguments,
177        reason = "method mirrors the existing Python keyword API"
178    )]
179    fn py_add_venue(
180        &mut self,
181        venue: Venue,
182        oms_type: OmsType,
183        account_type: AccountType,
184        starting_balances: Vec<Money>,
185        base_currency: Option<Currency>,
186        default_leverage: Option<Decimal>,
187        leverages: Option<HashMap<InstrumentId, Decimal>>,
188        fill_model: Option<Py<PyAny>>,
189        fee_model: Option<Py<PyAny>>,
190        margin_model: Option<Py<PyAny>>,
191        latency_model: Option<Py<PyAny>>,
192        modules: Option<Vec<Py<PyAny>>>,
193        book_type: BookType,
194        routing: bool,
195        reject_stop_orders: bool,
196        support_gtd_orders: bool,
197        support_contingent_orders: bool,
198        use_position_ids: bool,
199        use_random_ids: bool,
200        use_reduce_only: bool,
201        use_message_queue: bool,
202        use_market_order_acks: bool,
203        bar_execution: bool,
204        bar_adaptive_high_low_ordering: bool,
205        trade_execution: bool,
206        liquidity_consumption: bool,
207        queue_position: bool,
208        allow_cash_borrowing: bool,
209        frozen_account: bool,
210        oto_trigger_mode: OtoTriggerMode,
211        price_protection_points: Option<u32>,
212        liquidation_enabled: bool,
213        liquidation_trigger_ratio: Option<f64>,
214        liquidation_cancel_open_orders: bool,
215        order_priority_reset_policy: OrderPriorityResetPolicy,
216    ) -> PyResult<()> {
217        let leverages: AHashMap<InstrumentId, Decimal> = leverages
218            .map(|m| m.into_iter().collect())
219            .unwrap_or_default();
220        let fill_model = fill_model
221            .map(|obj| Python::attach(|py| pyobject_to_fill_model_handle(obj.bind(py))))
222            .transpose()?
223            .unwrap_or_default();
224
225        let fee_model = fee_model
226            .map(|obj| Python::attach(|py| pyobject_to_fee_model_handle(obj.bind(py))))
227            .transpose()?
228            .ok_or_else(|| {
229                to_pyvalue_err(
230                    "Backtest venue requires an explicit fee_model, including an explicit zero-fee model",
231                )
232            })?;
233
234        let margin_model = margin_model
235            .map(|obj| Python::attach(|py| pyobject_to_margin_model_any(obj.bind(py))))
236            .transpose()?
237            .map(Into::into);
238
239        let latency_model = latency_model
240            .map(|obj| Python::attach(|py| pyobject_to_latency_model_any(obj.bind(py))))
241            .transpose()?
242            .map(Into::into);
243
244        let modules = modules
245            .map(|objs| {
246                objs.into_iter()
247                    .map(|obj| {
248                        Python::attach(|py| pyobject_to_simulation_module_handle(py, obj.bind(py)))
249                    })
250                    .collect::<PyResult<Vec<_>>>()
251            })
252            .transpose()?
253            .unwrap_or_default();
254
255        let sim_config = SimulatedVenueConfig::builder()
256            .venue(venue)
257            .oms_type(oms_type)
258            .account_type(account_type)
259            .book_type(book_type)
260            .starting_balances(starting_balances)
261            .maybe_base_currency(base_currency)
262            .maybe_default_leverage(default_leverage)
263            .leverages(leverages)
264            .fill_model(fill_model)
265            .fee_model(fee_model)
266            .maybe_margin_model(margin_model)
267            .maybe_latency_model(latency_model)
268            .modules(modules)
269            .routing(routing)
270            .reject_stop_orders(reject_stop_orders)
271            .support_gtd_orders(support_gtd_orders)
272            .support_contingent_orders(support_contingent_orders)
273            .use_position_ids(use_position_ids)
274            .use_random_ids(use_random_ids)
275            .use_reduce_only(use_reduce_only)
276            .use_message_queue(use_message_queue)
277            .use_market_order_acks(use_market_order_acks)
278            .bar_execution(bar_execution)
279            .bar_adaptive_high_low_ordering(bar_adaptive_high_low_ordering)
280            .trade_execution(trade_execution)
281            .liquidity_consumption(liquidity_consumption)
282            .allow_cash_borrowing(allow_cash_borrowing)
283            .frozen_account(frozen_account)
284            .queue_position(queue_position)
285            .order_priority_reset_policy(order_priority_reset_policy)
286            .oto_full_trigger(oto_trigger_mode == OtoTriggerMode::Full)
287            .maybe_price_protection_points(price_protection_points)
288            .liquidation_enabled(liquidation_enabled)
289            .liquidation_trigger_ratio(liquidation_trigger_ratio.unwrap_or(1.0))
290            .liquidation_cancel_open_orders(liquidation_cancel_open_orders)
291            .build()
292            .map_err(config_error_to_pyvalue_err)?;
293
294        self.0.add_venue(sim_config).map_err(to_pyruntime_err)?;
295
296        Ok(())
297    }
298
299    /// Changes the fill model for a venue.
300    #[pyo3(name = "change_fill_model")]
301    #[expect(clippy::needless_pass_by_value)]
302    fn py_change_fill_model(
303        &mut self,
304        py: Python,
305        venue: Venue,
306        fill_model: Py<PyAny>,
307    ) -> PyResult<()> {
308        let fill_model = pyobject_to_fill_model_handle(fill_model.bind(py))?;
309        self.0.change_fill_model(venue, fill_model);
310        Ok(())
311    }
312
313    /// Adds data to the engine.
314    #[pyo3(
315        name = "add_data",
316        signature = (data, client_id=None, validate=true, sort=true)
317    )]
318    fn py_add_data(
319        &mut self,
320        py: Python,
321        data: Vec<Py<PyAny>>,
322        client_id: Option<ClientId>,
323        validate: bool,
324        sort: bool,
325    ) -> PyResult<()> {
326        let rust_data: Vec<Data> = data
327            .into_iter()
328            .map(|obj| pyobject_to_data(py, obj.bind(py)))
329            .collect::<PyResult<_>>()?;
330        self.0
331            .add_data(rust_data, client_id, validate, sort)
332            .map_err(to_pyruntime_err)
333    }
334
335    /// Adds an instrument to the engine.
336    #[pyo3(name = "add_instrument")]
337    fn py_add_instrument(&mut self, py: Python, instrument: Py<PyAny>) -> PyResult<()> {
338        let instrument_any = pyobject_to_instrument_any(py, instrument)?;
339        self.0
340            .add_instrument(&instrument_any)
341            .map_err(to_pyruntime_err)
342    }
343
344    /// Adds an actor from a constructed Python instance.
345    ///
346    /// The actor ID and logging flags are sourced from the instance's config.
347    #[pyo3(name = "add_actor")]
348    fn py_add_actor(&mut self, actor: &Bound<'_, PyAny>) -> PyResult<()> {
349        log::debug!("`add_actor` with a constructed instance");
350        Self::add_python_actor(&mut self.0, &actor.clone().unbind())
351    }
352
353    /// Adds an actor from an importable config.
354    #[pyo3(name = "add_actor_from_config")]
355    #[expect(clippy::needless_pass_by_value)]
356    fn py_add_actor_from_config(
357        &mut self,
358        _py: Python,
359        config: ImportableActorConfig,
360    ) -> PyResult<()> {
361        log::debug!("`add_actor_from_config` with: {config:?}");
362        let actor = create_importable_component(
363            &config.actor_path,
364            "actor_path",
365            &config.config_path,
366            &config.config,
367            "actor",
368        )?;
369
370        Self::add_python_actor(&mut self.0, &actor)
371    }
372
373    /// Adds a strategy from a constructed Python instance.
374    ///
375    /// The strategy ID, order ID tag, and logging flags are sourced from the instance's
376    /// config.
377    #[pyo3(name = "add_strategy")]
378    fn py_add_strategy(&mut self, strategy: &Bound<'_, PyAny>) -> PyResult<()> {
379        log::debug!("`add_strategy` with a constructed instance");
380        Self::add_python_strategy(&mut self.0, &strategy.clone().unbind())
381    }
382
383    /// Adds a strategy from an importable config.
384    #[pyo3(name = "add_strategy_from_config")]
385    #[expect(clippy::needless_pass_by_value)]
386    fn py_add_strategy_from_config(
387        &mut self,
388        _py: Python,
389        config: ImportableStrategyConfig,
390    ) -> PyResult<()> {
391        log::debug!("`add_strategy_from_config` with: {config:?}");
392        let strategy = create_importable_component(
393            &config.strategy_path,
394            "strategy_path",
395            &config.config_path,
396            &config.config,
397            "strategy",
398        )?;
399
400        Self::add_python_strategy(&mut self.0, &strategy)
401    }
402
403    /// Adds an execution algorithm from a constructed Python instance.
404    ///
405    /// The execution algorithm ID and logging flags are sourced from the instance's
406    /// config.
407    #[pyo3(name = "add_exec_algorithm")]
408    fn py_add_exec_algorithm(&mut self, exec_algorithm: &Bound<'_, PyAny>) -> PyResult<()> {
409        log::debug!("`add_exec_algorithm` with a constructed instance");
410        Self::add_python_exec_algorithm(&mut self.0, &exec_algorithm.clone().unbind())
411    }
412
413    /// Adds an execution algorithm from an importable config.
414    #[pyo3(name = "add_exec_algorithm_from_config")]
415    #[expect(clippy::needless_pass_by_value)]
416    fn py_add_exec_algorithm_from_config(
417        &mut self,
418        _py: Python,
419        config: ImportableExecutionAlgorithmConfig,
420    ) -> PyResult<()> {
421        Self::ensure_can_add_exec_algorithm(&self.0)?;
422
423        log::debug!("`add_exec_algorithm_from_config` with: {config:?}");
424        let exec_algorithm = create_importable_component(
425            &config.exec_algorithm_path,
426            "exec_algorithm_path",
427            &config.config_path,
428            &config.config,
429            "exec algorithm",
430        )?;
431
432        Self::add_python_exec_algorithm(&mut self.0, &exec_algorithm)
433    }
434
435    /// Adds a built-in example actor from its type name and config.
436    ///
437    /// This method exists only to single-source bundled example actor code across
438    /// Rust and Python tests/examples. It is not a first-class extension path for
439    /// adding native actors.
440    #[cfg(feature = "examples")]
441    #[pyo3(name = "add_builtin_actor")]
442    fn py_add_builtin_actor(&mut self, type_name: &str, config: &Bound<'_, PyAny>) -> PyResult<()> {
443        let register = builtin_actor_register(type_name).ok_or_else(|| {
444            to_pytype_err(format!("Unsupported built-in actor type: {type_name}"))
445        })?;
446        register(&mut self.0, config)
447    }
448
449    /// Adds a built-in example strategy from its type name and config.
450    ///
451    /// This method exists only to single-source bundled example strategy code across
452    /// Rust and Python tests/examples. It is not a first-class extension path for
453    /// adding native strategies.
454    #[cfg(feature = "examples")]
455    #[pyo3(name = "add_builtin_strategy")]
456    fn py_add_builtin_strategy(
457        &mut self,
458        type_name: &str,
459        config: &Bound<'_, PyAny>,
460    ) -> PyResult<()> {
461        let register = builtin_strategy_register(type_name).ok_or_else(|| {
462            to_pytype_err(format!("Unsupported built-in strategy type: {type_name}"))
463        })?;
464        register(&mut self.0, config)
465    }
466
467    /// Adds a compiled-in native Rust execution algorithm from its type name and config.
468    ///
469    /// The type name determines which built-in execution algorithm is constructed.
470    /// All execution happens in Rust; Python is the configuration layer.
471    #[pyo3(name = "add_native_exec_algorithm")]
472    fn py_add_native_exec_algorithm(
473        &mut self,
474        type_name: &str,
475        config: &Bound<'_, PyAny>,
476    ) -> PyResult<()> {
477        let register = native_exec_algorithm_register(type_name).ok_or_else(|| {
478            to_pytype_err(format!(
479                "Unsupported native exec algorithm type: {type_name}"
480            ))
481        })?;
482        register(&mut self.0, config)
483    }
484
485    /// Runs the backtest engine.
486    #[pyo3(
487        name = "run",
488        signature = (start=None, end=None, run_config_id=None, streaming=false)
489    )]
490    fn py_run(
491        &mut self,
492        start: Option<u64>,
493        end: Option<u64>,
494        run_config_id: Option<String>,
495        streaming: bool,
496    ) -> PyResult<()> {
497        self.0
498            .run(
499                start.map(UnixNanos::from),
500                end.map(UnixNanos::from),
501                run_config_id,
502                streaming,
503            )
504            .map_err(to_pyruntime_err)
505    }
506
507    /// Ends the backtest run, finalizing results.
508    #[pyo3(name = "end")]
509    fn py_end(&mut self) -> PyResult<()> {
510        self.0.end().map_err(to_pyruntime_err)
511    }
512
513    /// Resets the engine state for a new run.
514    #[pyo3(name = "reset")]
515    fn py_reset(&mut self) -> PyResult<()> {
516        self.0.reset().map_err(to_pyruntime_err)
517    }
518
519    /// Disposes of the engine, releasing all resources.
520    #[pyo3(name = "dispose")]
521    fn py_dispose(&mut self) {
522        self.0.dispose();
523    }
524
525    /// Returns the backtest result from the last run.
526    #[pyo3(name = "get_result")]
527    fn py_get_result(&self) -> BacktestResult {
528        self.0.get_result()
529    }
530
531    /// Clears all data from the engine.
532    #[pyo3(name = "clear_data")]
533    fn py_clear_data(&mut self) {
534        self.0.clear_data();
535    }
536
537    /// Clears all actors from the engine.
538    #[pyo3(name = "clear_actors")]
539    fn py_clear_actors(&mut self) -> PyResult<()> {
540        self.0.clear_actors().map_err(to_pyruntime_err)
541    }
542
543    /// Clears all strategies from the engine.
544    #[pyo3(name = "clear_strategies")]
545    fn py_clear_strategies(&mut self) -> PyResult<()> {
546        self.0.clear_strategies().map_err(to_pyruntime_err)
547    }
548
549    /// Clears all execution algorithms from the engine.
550    #[pyo3(name = "clear_exec_algorithms")]
551    fn py_clear_exec_algorithms(&mut self) -> PyResult<()> {
552        self.0.clear_exec_algorithms().map_err(to_pyruntime_err)
553    }
554
555    /// Adds multiple actors from importable configs. Stops at the first error.
556    #[pyo3(name = "add_actors_from_configs")]
557    fn py_add_actors_from_configs(
558        &mut self,
559        py: Python,
560        configs: Vec<ImportableActorConfig>,
561    ) -> PyResult<()> {
562        for config in configs {
563            self.py_add_actor_from_config(py, config)?;
564        }
565        Ok(())
566    }
567
568    /// Adds multiple strategies from importable configs. Stops at the first error.
569    #[pyo3(name = "add_strategies_from_configs")]
570    fn py_add_strategies_from_configs(
571        &mut self,
572        py: Python,
573        configs: Vec<ImportableStrategyConfig>,
574    ) -> PyResult<()> {
575        for config in configs {
576            self.py_add_strategy_from_config(py, config)?;
577        }
578        Ok(())
579    }
580
581    /// Adds multiple execution algorithms from importable configs. Stops at the first error.
582    #[pyo3(name = "add_exec_algorithms_from_configs")]
583    fn py_add_exec_algorithms_from_configs(
584        &mut self,
585        py: Python,
586        configs: Vec<ImportableExecutionAlgorithmConfig>,
587    ) -> PyResult<()> {
588        for config in configs {
589            self.py_add_exec_algorithm_from_config(py, config)?;
590        }
591        Ok(())
592    }
593
594    /// Adds multiple actors from constructed Python instances. Stops at the first error.
595    #[pyo3(name = "add_actors")]
596    fn py_add_actors(&mut self, actors: Vec<Py<PyAny>>) -> PyResult<()> {
597        for actor in actors {
598            Self::add_python_actor(&mut self.0, &actor)?;
599        }
600        Ok(())
601    }
602
603    /// Adds multiple strategies from constructed Python instances. Stops at the first error.
604    #[pyo3(name = "add_strategies")]
605    fn py_add_strategies(&mut self, strategies: Vec<Py<PyAny>>) -> PyResult<()> {
606        for strategy in strategies {
607            Self::add_python_strategy(&mut self.0, &strategy)?;
608        }
609        Ok(())
610    }
611
612    /// Adds multiple execution algorithms from constructed Python instances. Stops at the first error.
613    #[pyo3(name = "add_exec_algorithms")]
614    fn py_add_exec_algorithms(&mut self, exec_algorithms: Vec<Py<PyAny>>) -> PyResult<()> {
615        for exec_algorithm in exec_algorithms {
616            Self::add_python_exec_algorithm(&mut self.0, &exec_algorithm)?;
617        }
618        Ok(())
619    }
620
621    /// Sorts the engine's internal data stream by timestamp.
622    #[pyo3(name = "sort_data")]
623    fn py_sort_data(&mut self) {
624        self.0.sort_data();
625    }
626
627    /// Returns the trader ID for this engine.
628    #[getter]
629    #[pyo3(name = "trader_id")]
630    fn py_trader_id(&self) -> TraderId {
631        self.0.trader_id()
632    }
633
634    /// Returns the machine ID for this engine.
635    #[getter]
636    #[pyo3(name = "machine_id")]
637    fn py_machine_id(&self) -> String {
638        self.0.machine_id().to_string()
639    }
640
641    /// Returns the unique instance ID for this engine.
642    #[getter]
643    #[pyo3(name = "instance_id")]
644    fn py_instance_id(&self) -> UUID4 {
645        self.0.instance_id()
646    }
647
648    /// Returns the current iteration count.
649    #[getter]
650    #[pyo3(name = "iteration")]
651    fn py_iteration(&self) -> usize {
652        self.0.iteration()
653    }
654
655    /// Returns the last run config ID, if any.
656    #[getter]
657    #[pyo3(name = "run_config_id")]
658    fn py_run_config_id(&self) -> Option<String> {
659        self.0.run_config_id().map(str::to_string)
660    }
661
662    /// Returns the last run ID, if any.
663    #[getter]
664    #[pyo3(name = "run_id")]
665    fn py_run_id(&self) -> Option<UUID4> {
666        self.0.run_id()
667    }
668
669    /// Returns when the last run started, in nanoseconds since the UNIX epoch.
670    #[getter]
671    #[pyo3(name = "run_started")]
672    fn py_run_started(&self) -> Option<u64> {
673        self.0.run_started().map(|n| n.as_u64())
674    }
675
676    /// Returns when the last run finished, in nanoseconds since the UNIX epoch.
677    #[getter]
678    #[pyo3(name = "run_finished")]
679    fn py_run_finished(&self) -> Option<u64> {
680        self.0.run_finished().map(|n| n.as_u64())
681    }
682
683    /// Returns the last backtest range start, in nanoseconds since the UNIX epoch.
684    #[getter]
685    #[pyo3(name = "backtest_start")]
686    fn py_backtest_start(&self) -> Option<u64> {
687        self.0.backtest_start().map(|n| n.as_u64())
688    }
689
690    /// Returns the last backtest range end, in nanoseconds since the UNIX epoch.
691    #[getter]
692    #[pyo3(name = "backtest_end")]
693    fn py_backtest_end(&self) -> Option<u64> {
694        self.0.backtest_end().map(|n| n.as_u64())
695    }
696
697    /// Returns the list of registered venue identifiers.
698    #[pyo3(name = "list_venues")]
699    fn py_list_venues(&self) -> Vec<Venue> {
700        self.0.list_venues()
701    }
702
703    /// Returns the cache shared with the kernel and registered components.
704    #[getter]
705    #[pyo3(name = "cache")]
706    fn py_cache(&self) -> PyCache {
707        engine_cache(&self.0)
708    }
709
710    /// Returns the portfolio shared with the kernel and registered components.
711    #[getter]
712    #[pyo3(name = "portfolio")]
713    fn py_portfolio(&self) -> PyPortfolio {
714        engine_portfolio(&self.0)
715    }
716
717    /// Generates an orders report as a pandas `DataFrame`.
718    ///
719    /// # Errors
720    ///
721    /// Returns an error if the Python `ReportProvider` import or call fails.
722    #[pyo3(name = "generate_orders_report")]
723    fn py_generate_orders_report<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
724        generate_orders_report(&self.0, py)
725    }
726
727    /// Generates an order fills report as a pandas `DataFrame`.
728    ///
729    /// # Errors
730    ///
731    /// Returns an error if the Python `ReportProvider` import or call fails.
732    #[pyo3(name = "generate_order_fills_report")]
733    fn py_generate_order_fills_report<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
734        generate_order_fills_report(&self.0, py)
735    }
736
737    /// Generates a fills report as a pandas `DataFrame`.
738    ///
739    /// # Errors
740    ///
741    /// Returns an error if the Python `ReportProvider` import or call fails.
742    #[pyo3(name = "generate_fills_report")]
743    fn py_generate_fills_report<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
744        generate_fills_report(&self.0, py)
745    }
746
747    /// Generates a positions report as a pandas `DataFrame`.
748    ///
749    /// # Errors
750    ///
751    /// Returns an error if the Python `ReportProvider` import or call fails.
752    #[pyo3(name = "generate_positions_report")]
753    fn py_generate_positions_report<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
754        generate_positions_report(&self.0, py)
755    }
756
757    /// Generates an account report as a pandas `DataFrame`.
758    ///
759    /// At least one of `venue` or `account_id` must be provided.
760    ///
761    /// # Errors
762    ///
763    /// Returns an error if neither `venue` nor `account_id` is provided, or if the Python
764    /// `ReportProvider` import or call fails.
765    #[pyo3(name = "generate_account_report", signature = (venue=None, account_id=None))]
766    fn py_generate_account_report<'py>(
767        &self,
768        py: Python<'py>,
769        venue: Option<Venue>,
770        account_id: Option<AccountId>,
771    ) -> PyResult<Bound<'py, PyAny>> {
772        generate_account_report(&self.0, py, venue, account_id)
773    }
774
775    fn __repr__(&self) -> String {
776        format!("{:?}", self.0)
777    }
778}
779
780pub(super) fn engine_cache(engine: &BacktestEngine) -> PyCache {
781    PyCache::from_rc(engine.kernel().cache.clone())
782}
783
784pub(super) fn engine_portfolio(engine: &BacktestEngine) -> PyPortfolio {
785    PyPortfolio::from_rc(engine.kernel().portfolio.clone())
786}
787
788pub(super) fn generate_orders_report<'py>(
789    engine: &BacktestEngine,
790    py: Python<'py>,
791) -> PyResult<Bound<'py, PyAny>> {
792    let orders = cache_bound(engine, py)?.call_method0("orders")?;
793    report_provider(py)?.call_method1("generate_orders_report", (orders,))
794}
795
796pub(super) fn generate_order_fills_report<'py>(
797    engine: &BacktestEngine,
798    py: Python<'py>,
799) -> PyResult<Bound<'py, PyAny>> {
800    let orders = cache_bound(engine, py)?.call_method0("orders")?;
801    report_provider(py)?.call_method1("generate_order_fills_report", (orders,))
802}
803
804pub(super) fn generate_fills_report<'py>(
805    engine: &BacktestEngine,
806    py: Python<'py>,
807) -> PyResult<Bound<'py, PyAny>> {
808    let orders = cache_bound(engine, py)?.call_method0("orders")?;
809    report_provider(py)?.call_method1("generate_fills_report", (orders,))
810}
811
812pub(super) fn generate_positions_report<'py>(
813    engine: &BacktestEngine,
814    py: Python<'py>,
815) -> PyResult<Bound<'py, PyAny>> {
816    let cache = cache_bound(engine, py)?;
817    let positions = cache.call_method0("positions")?;
818    let snapshots = cache.call_method0("position_snapshots")?;
819    report_provider(py)?.call_method1("generate_positions_report", (positions, snapshots))
820}
821
822pub(super) fn generate_account_report<'py>(
823    engine: &BacktestEngine,
824    py: Python<'py>,
825    venue: Option<Venue>,
826    account_id: Option<AccountId>,
827) -> PyResult<Bound<'py, PyAny>> {
828    let cache = cache_bound(engine, py)?;
829    let account = match (account_id, venue) {
830        (Some(aid), _) => cache.call_method1("account", (aid,))?,
831        (None, Some(v)) => cache.call_method1("account_for_venue", (v,))?,
832        (None, None) => {
833            return Err(to_pyvalue_err(
834                "At least one of 'venue' or 'account_id' must be provided",
835            ));
836        }
837    };
838
839    if account.is_none() {
840        return py.import("pandas")?.call_method0("DataFrame");
841    }
842    report_provider(py)?.call_method1("generate_account_report", (account,))
843}
844
845fn cache_bound<'py>(engine: &BacktestEngine, py: Python<'py>) -> PyResult<Bound<'py, PyCache>> {
846    Ok(Py::new(py, engine_cache(engine))?.into_bound(py))
847}
848
849fn report_provider(py: Python<'_>) -> PyResult<Bound<'_, PyAny>> {
850    py.import("nautilus_trader.analysis.reporter")?
851        .getattr("ReportProvider")
852}
853
854impl PyBacktestEngine {
855    /// Provides access to the inner [`BacktestEngine`].
856    #[must_use]
857    pub fn inner(&self) -> &BacktestEngine {
858        &self.0
859    }
860
861    /// Provides mutable access to the inner [`BacktestEngine`].
862    pub fn inner_mut(&mut self) -> &mut BacktestEngine {
863        &mut self.0
864    }
865
866    /// Configures and registers a constructed Python strategy instance.
867    ///
868    /// Shared by `add_strategy` (caller-constructed instance) and
869    /// `add_strategy_from_config` (imported and constructed here). The strategy ID,
870    /// order ID tag, and logging flags are sourced from the instance's retained
871    /// `.config`, so both entry points use a single config object.
872    #[allow(
873        unsafe_code,
874        reason = "Required for Python strategy component registration"
875    )]
876    pub(crate) fn add_python_strategy(
877        engine: &mut BacktestEngine,
878        strategy: &Py<PyAny>,
879    ) -> PyResult<()> {
880        let strategy_id = engine
881            .kernel_mut()
882            .trader
883            .borrow_mut()
884            .add_python_strategy_instance(strategy)
885            .map_err(to_pyruntime_err)?;
886
887        let oms_type = Python::attach(|py| -> PyResult<Option<OmsType>> {
888            Ok(strategy
889                .bind(py)
890                .getattr("config")
891                .ok()
892                .filter(|config| !config.is_none())
893                .and_then(|cfg| cfg.getattr("oms_type").ok())
894                .filter(|value| !value.is_none())
895                .and_then(|value| value.extract::<OmsType>().ok()))
896        })?;
897
898        if let Some(oms_type) = oms_type {
899            engine
900                .kernel()
901                .exec_engine
902                .borrow_mut()
903                .register_oms_type(strategy_id, oms_type);
904        }
905
906        Ok(())
907    }
908
909    /// Configures and registers a constructed Python actor instance.
910    ///
911    /// Shared by `add_actor` (caller-constructed instance) and `add_actor_from_config`
912    /// (imported and constructed here). The actor ID and logging flags are sourced from
913    /// the instance's retained `.config`, so both entry points use a single config object.
914    pub(crate) fn add_python_actor(engine: &mut BacktestEngine, actor: &Py<PyAny>) -> PyResult<()> {
915        let actor_id = Python::attach(|py| -> anyhow::Result<ActorId> {
916            let bound = actor.bind(py);
917
918            let config_instance = bound
919                .getattr("config")
920                .ok()
921                .filter(|config| !config.is_none());
922
923            prepare_python_actor(bound, config_instance.as_ref())
924        })
925        .map_err(to_pyruntime_err)?;
926
927        if engine
928            .kernel()
929            .trader
930            .borrow()
931            .actor_ids()
932            .contains(&actor_id)
933        {
934            return Err(to_pyruntime_err(format!(
935                "Actor '{actor_id}' is already registered"
936            )));
937        }
938
939        engine
940            .kernel_mut()
941            .trader
942            .borrow_mut()
943            .add_python_actor_instance(actor, actor_id)
944            .map_err(to_pyruntime_err)?;
945
946        log::info!("Registered Python actor {actor_id}");
947        Ok(())
948    }
949
950    /// Configures and registers a constructed Python execution algorithm instance.
951    ///
952    /// Shared by `add_exec_algorithm` (caller-constructed instance) and
953    /// `add_exec_algorithm_from_config` (imported and constructed here). The execution
954    /// algorithm ID and logging flags are sourced from the instance's retained `.config`.
955    pub(crate) fn add_python_exec_algorithm(
956        engine: &mut BacktestEngine,
957        exec_algorithm: &Py<PyAny>,
958    ) -> PyResult<()> {
959        Self::ensure_can_add_exec_algorithm(engine)?;
960
961        if Self::try_add_py_execution_algorithm(engine, exec_algorithm)? {
962            return Ok(());
963        }
964
965        let actor_id = Python::attach(|py| -> anyhow::Result<ActorId> {
966            let bound = exec_algorithm.bind(py);
967
968            let config_instance = bound
969                .getattr("config")
970                .ok()
971                .filter(|config| !config.is_none());
972
973            let mut py_data_actor_ref = bound
974                .extract::<PyRefMut<PyDataActor>>()
975                .map_err(Into::<PyErr>::into)
976                .map_err(|e| anyhow::anyhow!("Failed to extract PyDataActor: {e}"))?;
977
978            if let Some(config_obj) = config_instance.as_ref() {
979                let id_attr = config_obj
980                    .getattr("exec_algorithm_id")
981                    .ok()
982                    .filter(|v| !v.is_none())
983                    .or_else(|| config_obj.getattr("actor_id").ok().filter(|v| !v.is_none()));
984
985                if let Some(id_value) = id_attr {
986                    let actor_id_val = if let Ok(eaid) = id_value.extract::<ExecAlgorithmId>() {
987                        ActorId::new(eaid.inner())
988                    } else if let Ok(aid) = id_value.extract::<ActorId>() {
989                        aid
990                    } else if let Ok(aid_str) = id_value.extract::<String>() {
991                        ActorId::new_checked(&aid_str)?
992                    } else {
993                        anyhow::bail!("Invalid `exec_algorithm_id`/`actor_id` type");
994                    };
995                    py_data_actor_ref.set_actor_id(actor_id_val);
996                }
997
998                if let Ok(log_events) = config_obj.getattr("log_events")
999                    && let Ok(log_events_val) = log_events.extract::<bool>()
1000                {
1001                    py_data_actor_ref.set_log_events(log_events_val);
1002                }
1003
1004                if let Ok(log_commands) = config_obj.getattr("log_commands")
1005                    && let Ok(log_commands_val) = log_commands.extract::<bool>()
1006                {
1007                    py_data_actor_ref.set_log_commands(log_commands_val);
1008                }
1009            }
1010
1011            py_data_actor_ref.set_python_instance(bound)?;
1012            let actor_id = py_data_actor_ref.actor_id();
1013
1014            Ok(actor_id)
1015        })
1016        .map_err(to_pyruntime_err)?;
1017
1018        let exec_algorithm_id = engine
1019            .kernel_mut()
1020            .trader
1021            .borrow_mut()
1022            .add_python_exec_algorithm_instance(exec_algorithm, actor_id)
1023            .map_err(to_pyruntime_err)?;
1024
1025        log::info!("Registered Python exec algorithm {exec_algorithm_id}");
1026        Ok(())
1027    }
1028
1029    fn try_add_py_execution_algorithm(
1030        engine: &mut BacktestEngine,
1031        exec_algorithm: &Py<PyAny>,
1032    ) -> PyResult<bool> {
1033        let py_exec_algorithm =
1034            Python::attach(|py| -> anyhow::Result<Option<PyExecutionAlgorithm>> {
1035                let bound = exec_algorithm.bind(py);
1036
1037                let config_instance = bound
1038                    .getattr("config")
1039                    .ok()
1040                    .filter(|config| !config.is_none());
1041
1042                let Ok(mut py_exec_algorithm_ref) =
1043                    bound.extract::<PyRefMut<PyExecutionAlgorithm>>()
1044                else {
1045                    return Ok(None);
1046                };
1047
1048                if let Some(config_obj) = config_instance.as_ref() {
1049                    py_exec_algorithm_ref.configure_from_py_config(config_obj)?;
1050                }
1051
1052                py_exec_algorithm_ref.set_python_instance(bound)?;
1053
1054                Ok(Some(py_exec_algorithm_ref.clone()))
1055            })
1056            .map_err(to_pyruntime_err)?;
1057
1058        let Some(py_exec_algorithm) = py_exec_algorithm else {
1059            return Ok(false);
1060        };
1061
1062        let exec_algorithm_id = engine
1063            .kernel_mut()
1064            .trader
1065            .borrow_mut()
1066            .add_py_execution_algorithm_instance(py_exec_algorithm, exec_algorithm)
1067            .map_err(to_pyruntime_err)?;
1068
1069        log::info!("Registered Python exec algorithm {exec_algorithm_id}");
1070        Ok(true)
1071    }
1072
1073    /// Rejects adding an execution algorithm when the trader is running or disposed.
1074    ///
1075    /// Checked before importing and constructing the Python class in the `from_config`
1076    /// path so a rejected addition never runs user constructor code.
1077    pub(crate) fn ensure_can_add_exec_algorithm(engine: &BacktestEngine) -> PyResult<()> {
1078        match engine.kernel().trader.borrow().state() {
1079            ComponentState::PreInitialized | ComponentState::Ready | ComponentState::Stopped => {
1080                Ok(())
1081            }
1082            ComponentState::Running => Err(to_pyruntime_err(
1083                "Cannot add execution algorithms to running trader",
1084            )),
1085            ComponentState::Disposed => {
1086                Err(to_pyruntime_err("Cannot add components to disposed trader"))
1087            }
1088            state => Err(to_pyruntime_err(format!(
1089                "Cannot add execution algorithms in current state: {state}"
1090            ))),
1091        }
1092    }
1093}
1094
1095#[cfg(feature = "examples")]
1096type BuiltinActorRegister = for<'py> fn(&mut BacktestEngine, &Bound<'py, PyAny>) -> PyResult<()>;
1097
1098#[cfg(feature = "examples")]
1099type BuiltinStrategyRegister = for<'py> fn(&mut BacktestEngine, &Bound<'py, PyAny>) -> PyResult<()>;
1100
1101#[cfg(feature = "examples")]
1102fn builtin_actor_register(_type_name: &str) -> Option<BuiltinActorRegister> {
1103    None
1104}
1105
1106#[cfg(feature = "examples")]
1107fn builtin_strategy_register(type_name: &str) -> Option<BuiltinStrategyRegister> {
1108    match type_name {
1109        "CompositeMarketMaker" => Some(register_composite_market_maker),
1110        "DeltaNeutralVol" => Some(register_delta_neutral_vol),
1111        "EmaCross" => Some(register_ema_cross),
1112        "GridMarketMaker" => Some(register_grid_market_maker),
1113        "HurstVpinDirectional" => Some(register_hurst_vpin_directional),
1114        "OrderBookImbalance" => Some(register_orderbook_imbalance),
1115        _ => None,
1116    }
1117}
1118
1119type NativeExecutionAlgorithmRegister =
1120    for<'py> fn(&mut BacktestEngine, &Bound<'py, PyAny>) -> PyResult<()>;
1121
1122fn native_exec_algorithm_register(type_name: &str) -> Option<NativeExecutionAlgorithmRegister> {
1123    match type_name {
1124        "TwapAlgorithm" => Some(register_twap_algorithm),
1125        _ => None,
1126    }
1127}
1128
1129fn register_twap_algorithm(engine: &mut BacktestEngine, config: &Bound<'_, PyAny>) -> PyResult<()> {
1130    let config = config.extract::<TwapAlgorithmConfig>()?;
1131    if config.exec_algorithm_id.is_none() {
1132        return Err(to_pyvalue_err(
1133            "TwapAlgorithm config requires `exec_algorithm_id`",
1134        ));
1135    }
1136    engine
1137        .add_exec_algorithm(TwapAlgorithm::new(config))
1138        .map_err(to_pyruntime_err)
1139}
1140
1141#[cfg(feature = "examples")]
1142fn register_composite_market_maker(
1143    engine: &mut BacktestEngine,
1144    config: &Bound<'_, PyAny>,
1145) -> PyResult<()> {
1146    let config = config.extract::<CompositeMarketMakerConfig>()?;
1147    engine
1148        .add_strategy(CompositeMarketMaker::new(config))
1149        .map_err(to_pyruntime_err)
1150}
1151
1152#[cfg(feature = "examples")]
1153fn register_delta_neutral_vol(
1154    engine: &mut BacktestEngine,
1155    config: &Bound<'_, PyAny>,
1156) -> PyResult<()> {
1157    let config = config.extract::<DeltaNeutralVolConfig>()?;
1158    engine
1159        .add_strategy(DeltaNeutralVol::new(config))
1160        .map_err(to_pyruntime_err)
1161}
1162
1163#[cfg(feature = "examples")]
1164fn register_ema_cross(engine: &mut BacktestEngine, config: &Bound<'_, PyAny>) -> PyResult<()> {
1165    let config = config.extract::<EmaCrossConfig>()?;
1166    engine
1167        .add_strategy(EmaCross::from_config(config))
1168        .map_err(to_pyruntime_err)
1169}
1170
1171#[cfg(feature = "examples")]
1172fn register_grid_market_maker(
1173    engine: &mut BacktestEngine,
1174    config: &Bound<'_, PyAny>,
1175) -> PyResult<()> {
1176    let config = config.extract::<GridMarketMakerConfig>()?;
1177    engine
1178        .add_strategy(GridMarketMaker::new(config))
1179        .map_err(to_pyruntime_err)
1180}
1181
1182#[cfg(feature = "examples")]
1183fn register_hurst_vpin_directional(
1184    engine: &mut BacktestEngine,
1185    config: &Bound<'_, PyAny>,
1186) -> PyResult<()> {
1187    let config = config.extract::<HurstVpinDirectionalConfig>()?;
1188    let strategy =
1189        HurstVpinDirectional::new_checked(config).map_err(config_error_to_pyvalue_err)?;
1190    engine.add_strategy(strategy).map_err(to_pyruntime_err)
1191}
1192
1193#[cfg(feature = "examples")]
1194pub(super) fn register_orderbook_imbalance(
1195    engine: &mut BacktestEngine,
1196    config: &Bound<'_, PyAny>,
1197) -> PyResult<()> {
1198    let config = config.extract::<OrderBookImbalanceConfig>()?;
1199    engine
1200        .add_strategy(OrderBookImbalance::from_config(config).map_err(to_pyvalue_err)?)
1201        .map_err(to_pyruntime_err)
1202}
1203
1204#[cfg(all(test, feature = "examples"))]
1205mod tests {
1206    use pyo3::{Python, types::PyDict};
1207    use rstest::rstest;
1208
1209    use crate::{config::BacktestEngineConfig, engine::BacktestEngine};
1210
1211    #[rstest]
1212    #[case("CompositeMarketMaker")]
1213    #[case("DeltaNeutralVol")]
1214    #[case("EmaCross")]
1215    #[case("GridMarketMaker")]
1216    #[case("HurstVpinDirectional")]
1217    #[case("OrderBookImbalance")]
1218    fn test_builtin_strategy_register_accepts_supported_names(#[case] type_name: &str) {
1219        assert!(super::builtin_strategy_register(type_name).is_some());
1220    }
1221
1222    #[rstest]
1223    fn test_builtin_register_rejects_unknown_names() {
1224        assert!(super::builtin_strategy_register("UnknownStrategy").is_none());
1225        assert!(super::builtin_actor_register("UnknownActor").is_none());
1226    }
1227
1228    #[rstest]
1229    fn test_builtin_strategy_register_rejects_mismatched_config() {
1230        Python::initialize();
1231
1232        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
1233        Python::attach(|py| {
1234            let register = super::builtin_strategy_register("EmaCross").unwrap();
1235            let config = PyDict::new(py);
1236            let error = register(&mut engine, config.as_any()).unwrap_err();
1237
1238            assert!(error.is_instance_of::<pyo3::exceptions::PyTypeError>(py));
1239        });
1240    }
1241
1242    #[rstest]
1243    fn test_builtin_actor_register_rejects_retired_imbalance() {
1244        assert!(super::builtin_actor_register("BookImbalanceActor").is_none());
1245    }
1246
1247    #[rstest]
1248    fn test_add_strategy_registers_python_instance() {
1249        use nautilus_model::identifiers::StrategyId;
1250        use nautilus_trading::python::strategy::PyStrategy;
1251        use pyo3::{ffi::c_str, types::PyAnyMethods};
1252
1253        Python::initialize();
1254
1255        let mut engine =
1256            super::PyBacktestEngine(BacktestEngine::new(BacktestEngineConfig::default()).unwrap());
1257
1258        Python::attach(|py| {
1259            let config = py
1260                .eval(
1261                    c_str!("type('_Cfg', (), {'strategy_id': 'S-INSTANCE-001'})()"),
1262                    None,
1263                    None,
1264                )
1265                .unwrap();
1266            let instance = py
1267                .get_type::<PyStrategy>()
1268                .as_any()
1269                .call1((config,))
1270                .unwrap();
1271
1272            engine.py_add_strategy(&instance).unwrap();
1273
1274            assert!(
1275                engine
1276                    .0
1277                    .kernel()
1278                    .trader
1279                    .borrow()
1280                    .strategy_ids()
1281                    .contains(&StrategyId::from("S-INSTANCE-001"))
1282            );
1283        });
1284    }
1285
1286    #[rstest]
1287    fn test_add_actor_registers_python_instance() {
1288        use nautilus_common::python::actor::PyDataActor;
1289        use nautilus_model::identifiers::ActorId;
1290        use pyo3::{ffi::c_str, types::PyAnyMethods};
1291
1292        Python::initialize();
1293
1294        let mut engine =
1295            super::PyBacktestEngine(BacktestEngine::new(BacktestEngineConfig::default()).unwrap());
1296
1297        Python::attach(|py| {
1298            let config = py
1299                .eval(
1300                    c_str!("type('_Cfg', (), {'actor_id': 'A-INSTANCE-001'})()"),
1301                    None,
1302                    None,
1303                )
1304                .unwrap();
1305            let instance = py
1306                .get_type::<PyDataActor>()
1307                .as_any()
1308                .call1((config,))
1309                .unwrap();
1310
1311            engine.py_add_actor(&instance).unwrap();
1312
1313            assert!(
1314                engine
1315                    .0
1316                    .kernel()
1317                    .trader
1318                    .borrow()
1319                    .actor_ids()
1320                    .contains(&ActorId::from("A-INSTANCE-001"))
1321            );
1322        });
1323    }
1324
1325    #[rstest]
1326    fn test_add_exec_algorithm_registers_python_instance() {
1327        use nautilus_common::python::actor::PyDataActor;
1328        use nautilus_model::identifiers::ExecAlgorithmId;
1329        use pyo3::{ffi::c_str, types::PyAnyMethods};
1330
1331        Python::initialize();
1332
1333        let mut engine =
1334            super::PyBacktestEngine(BacktestEngine::new(BacktestEngineConfig::default()).unwrap());
1335
1336        Python::attach(|py| {
1337            let config = py
1338                .eval(
1339                    c_str!("type('_Cfg', (), {'exec_algorithm_id': 'EXEC-INSTANCE-001'})()"),
1340                    None,
1341                    None,
1342                )
1343                .unwrap();
1344            let instance = py
1345                .get_type::<PyDataActor>()
1346                .as_any()
1347                .call1((config,))
1348                .unwrap();
1349
1350            engine.py_add_exec_algorithm(&instance).unwrap();
1351
1352            assert!(
1353                engine
1354                    .0
1355                    .kernel()
1356                    .trader
1357                    .borrow()
1358                    .exec_algorithm_ids()
1359                    .contains(&ExecAlgorithmId::from("EXEC-INSTANCE-001"))
1360            );
1361        });
1362    }
1363
1364    #[rstest]
1365    fn test_add_exec_algorithm_retains_py_execution_algorithm_wrapper() {
1366        use nautilus_common::python::wrappers::get_python_wrapper;
1367        use nautilus_model::identifiers::{ComponentId, ExecAlgorithmId};
1368        use nautilus_trading::python::algorithm::PyExecutionAlgorithm;
1369        use pyo3::{ffi::c_str, types::PyAnyMethods};
1370
1371        Python::initialize();
1372
1373        let mut engine =
1374            super::PyBacktestEngine(BacktestEngine::new(BacktestEngineConfig::default()).unwrap());
1375
1376        Python::attach(|py| {
1377            let config = py
1378                .eval(
1379                    c_str!("type('_Cfg', (), {'exec_algorithm_id': 'EXEC-WRAPPED-001'})()"),
1380                    None,
1381                    None,
1382                )
1383                .unwrap();
1384            let instance = py
1385                .get_type::<PyExecutionAlgorithm>()
1386                .as_any()
1387                .call1((config,))
1388                .unwrap();
1389
1390            engine.py_add_exec_algorithm(&instance).unwrap();
1391
1392            assert!(
1393                engine
1394                    .0
1395                    .kernel()
1396                    .trader
1397                    .borrow()
1398                    .exec_algorithm_ids()
1399                    .contains(&ExecAlgorithmId::from("EXEC-WRAPPED-001"))
1400            );
1401            assert!(
1402                get_python_wrapper(ComponentId::from("EXEC-WRAPPED-001"))
1403                    .expect("registering must retain the algorithm's Python wrapper")
1404                    .bind(py)
1405                    .is(&instance)
1406            );
1407        });
1408    }
1409
1410    #[rstest]
1411    fn test_add_exec_algorithm_colliding_with_actor_leaves_the_actor_registered() {
1412        use nautilus_common::python::{actor::PyDataActor, wrappers::get_python_wrapper};
1413        use nautilus_model::identifiers::{ActorId, ComponentId};
1414        use nautilus_trading::python::algorithm::PyExecutionAlgorithm;
1415        use pyo3::{ffi::c_str, types::PyAnyMethods};
1416
1417        Python::initialize();
1418
1419        let mut engine =
1420            super::PyBacktestEngine(BacktestEngine::new(BacktestEngineConfig::default()).unwrap());
1421
1422        Python::attach(|py| {
1423            let actor_config = py
1424                .eval(
1425                    c_str!("type('_Cfg', (), {'actor_id': 'COLLIDING-ALGO'})()"),
1426                    None,
1427                    None,
1428                )
1429                .unwrap();
1430            let actor = py
1431                .get_type::<PyDataActor>()
1432                .as_any()
1433                .call1((actor_config,))
1434                .unwrap();
1435
1436            engine.py_add_actor(&actor).unwrap();
1437
1438            let algorithm_config = py
1439                .eval(
1440                    c_str!("type('_Cfg', (), {'exec_algorithm_id': 'COLLIDING-ALGO'})()"),
1441                    None,
1442                    None,
1443                )
1444                .unwrap();
1445            let algorithm = py
1446                .get_type::<PyExecutionAlgorithm>()
1447                .as_any()
1448                .call1((algorithm_config,))
1449                .unwrap();
1450
1451            let error = engine
1452                .py_add_exec_algorithm(&algorithm)
1453                .expect_err("an algorithm colliding with a live actor must not register");
1454            assert!(error.to_string().contains("already registered"));
1455
1456            assert_eq!(
1457                engine.0.kernel().trader.borrow().actor_ids(),
1458                vec![ActorId::from("COLLIDING-ALGO")]
1459            );
1460            assert!(
1461                engine
1462                    .0
1463                    .kernel()
1464                    .trader
1465                    .borrow()
1466                    .exec_algorithm_ids()
1467                    .is_empty()
1468            );
1469            assert!(
1470                get_python_wrapper(ComponentId::from("COLLIDING-ALGO"))
1471                    .expect("the actor must still hold its wrapper")
1472                    .bind(py)
1473                    .is(&actor)
1474            );
1475        });
1476    }
1477
1478    #[rstest]
1479    fn test_add_strategies_registers_multiple_python_instances() {
1480        use nautilus_model::identifiers::StrategyId;
1481        use nautilus_trading::python::strategy::PyStrategy;
1482        use pyo3::{ffi::c_str, types::PyAnyMethods};
1483
1484        Python::initialize();
1485
1486        let mut engine =
1487            super::PyBacktestEngine(BacktestEngine::new(BacktestEngineConfig::default()).unwrap());
1488
1489        Python::attach(|py| {
1490            let strategy_type = py.get_type::<PyStrategy>();
1491            let first_config = py
1492                .eval(
1493                    c_str!("type('_Cfg', (), {'strategy_id': 'S-MULTI-001'})()"),
1494                    None,
1495                    None,
1496                )
1497                .unwrap();
1498            let second_config = py
1499                .eval(
1500                    c_str!("type('_Cfg', (), {'strategy_id': 'S-MULTI-002'})()"),
1501                    None,
1502                    None,
1503                )
1504                .unwrap();
1505            let instances = vec![
1506                strategy_type
1507                    .as_any()
1508                    .call1((first_config,))
1509                    .unwrap()
1510                    .unbind(),
1511                strategy_type
1512                    .as_any()
1513                    .call1((second_config,))
1514                    .unwrap()
1515                    .unbind(),
1516            ];
1517
1518            engine.py_add_strategies(instances).unwrap();
1519
1520            let trader = engine.0.kernel().trader.borrow();
1521            let strategy_ids = trader.strategy_ids();
1522            assert!(strategy_ids.contains(&StrategyId::from("S-MULTI-001")));
1523            assert!(strategy_ids.contains(&StrategyId::from("S-MULTI-002")));
1524        });
1525    }
1526
1527    #[rstest]
1528    fn test_add_exec_algorithms_registers_multiple_python_instances() {
1529        use nautilus_common::python::actor::PyDataActor;
1530        use nautilus_model::identifiers::ExecAlgorithmId;
1531        use pyo3::{ffi::c_str, types::PyAnyMethods};
1532
1533        Python::initialize();
1534
1535        let mut engine =
1536            super::PyBacktestEngine(BacktestEngine::new(BacktestEngineConfig::default()).unwrap());
1537
1538        Python::attach(|py| {
1539            let algo_type = py.get_type::<PyDataActor>();
1540            let first_config = py
1541                .eval(
1542                    c_str!("type('_Cfg', (), {'exec_algorithm_id': 'EXEC-MULTI-001'})()"),
1543                    None,
1544                    None,
1545                )
1546                .unwrap();
1547            let second_config = py
1548                .eval(
1549                    c_str!("type('_Cfg', (), {'exec_algorithm_id': 'EXEC-MULTI-002'})()"),
1550                    None,
1551                    None,
1552                )
1553                .unwrap();
1554            let instances = vec![
1555                algo_type.as_any().call1((first_config,)).unwrap().unbind(),
1556                algo_type.as_any().call1((second_config,)).unwrap().unbind(),
1557            ];
1558
1559            engine.py_add_exec_algorithms(instances).unwrap();
1560
1561            let trader = engine.0.kernel().trader.borrow();
1562            let exec_algorithm_ids = trader.exec_algorithm_ids();
1563            assert!(exec_algorithm_ids.contains(&ExecAlgorithmId::from("EXEC-MULTI-001")));
1564            assert!(exec_algorithm_ids.contains(&ExecAlgorithmId::from("EXEC-MULTI-002")));
1565        });
1566    }
1567}
1568
1569fn pyobject_to_data(_py: Python, obj: &Bound<'_, PyAny>) -> PyResult<Data> {
1570    if let Ok(delta) = obj.extract::<OrderBookDelta>() {
1571        return Ok(Data::BookDelta(delta));
1572    }
1573
1574    if let Ok(deltas) = obj.extract::<OrderBookDeltas>() {
1575        return Ok(Data::BookDeltas(Box::new(deltas)));
1576    }
1577
1578    if let Ok(quote) = obj.extract::<QuoteTick>() {
1579        return Ok(Data::Quote(quote));
1580    }
1581
1582    if let Ok(trade) = obj.extract::<TradeTick>() {
1583        return Ok(Data::Trade(trade));
1584    }
1585
1586    if let Ok(bar) = obj.extract::<Bar>() {
1587        return Ok(Data::Bar(bar));
1588    }
1589
1590    if let Ok(depth) = obj.extract::<OrderBookDepth>() {
1591        return Ok(Data::BookDepth(Box::new(depth)));
1592    }
1593
1594    if let Ok(mark) = obj.extract::<MarkPriceUpdate>() {
1595        return Ok(Data::MarkPrice(mark));
1596    }
1597
1598    if let Ok(index) = obj.extract::<IndexPriceUpdate>() {
1599        return Ok(Data::IndexPrice(index));
1600    }
1601
1602    if let Ok(funding_rate) = obj.extract::<FundingRateUpdate>() {
1603        return Ok(Data::FundingRate(funding_rate));
1604    }
1605
1606    if let Ok(greeks) = obj.extract::<OptionGreeks>() {
1607        return Ok(Data::OptionGreeks(greeks));
1608    }
1609
1610    if let Ok(status) = obj.extract::<InstrumentStatus>() {
1611        return Ok(Data::InstrumentStatus(status));
1612    }
1613
1614    if let Ok(close) = obj.extract::<InstrumentClose>() {
1615        return Ok(Data::InstrumentClose(close));
1616    }
1617
1618    if let Ok(custom) = obj.extract::<CustomData>() {
1619        return Ok(Data::Custom(custom));
1620    }
1621
1622    #[cfg(feature = "defi")]
1623    if let Ok(defi) = obj.extract::<DefiData>() {
1624        return Ok(Data::Defi(Box::new(defi)));
1625    }
1626
1627    let type_name = obj.get_type().name()?;
1628    Err(to_pytype_err(format!("Cannot convert {type_name} to Data")))
1629}
1630
1631#[cfg(test)]
1632mod model_tests {
1633    use nautilus_execution::{
1634        matching_engine::config::OrderPriorityResetPolicy,
1635        models::fee::{FeeModelAny, MakerTakerFeeModel},
1636        python::{fee::PyFeeModel, fill::PyFillModel},
1637    };
1638    use nautilus_model::{
1639        accounts::AccountAny,
1640        data::{
1641            Bar, BarType, Data,
1642            stubs::{quote_audusd, stub_custom_data},
1643        },
1644        enums::{AccountType, BookType, OmsType, OtoTriggerMode},
1645        identifiers::Venue,
1646        instruments::{
1647            InstrumentAny,
1648            stubs::{audusd_sim, crypto_perpetual_ethusdt},
1649        },
1650        types::{Currency, Money, Price, Quantity},
1651    };
1652    use pyo3::{
1653        IntoPyObjectExt, Python,
1654        exceptions::PyRuntimeError,
1655        ffi::c_str,
1656        types::{PyAnyMethods, PyDict, PyDictMethods},
1657    };
1658    use rstest::rstest;
1659
1660    use crate::{
1661        config::{BacktestEngineConfig, SimulatedVenueConfig},
1662        engine::BacktestEngine,
1663    };
1664
1665    #[rstest]
1666    #[case::tick("TICK")]
1667    #[case::volume("VOLUME")]
1668    #[case::value("VALUE")]
1669    fn test_run_non_time_bar_raises_runtime_error(#[case] aggregation: &str) {
1670        Python::initialize();
1671
1672        let mut engine =
1673            super::PyBacktestEngine(BacktestEngine::new(BacktestEngineConfig::default()).unwrap());
1674        let config = SimulatedVenueConfig::builder()
1675            .venue(Venue::from("BINANCE"))
1676            .oms_type(OmsType::Netting)
1677            .account_type(AccountType::Margin)
1678            .book_type(BookType::L1_MBP)
1679            .starting_balances(vec![Money::from("1_000_000 USDT")])
1680            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
1681            .build()
1682            .unwrap();
1683        engine.0.add_venue(config).unwrap();
1684        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt());
1685        engine.0.add_instrument(&instrument).unwrap();
1686        let bar_type =
1687            BarType::from(format!("ETHUSDT-PERP.BINANCE-200-{aggregation}-LAST-EXTERNAL").as_str());
1688
1689        let bar = Bar::new(
1690            bar_type,
1691            Price::from("1500.00"),
1692            Price::from("1505.00"),
1693            Price::from("1490.00"),
1694            Price::from("1502.00"),
1695            Quantity::from("100.000"),
1696            1_000_000_000.into(),
1697            1_000_000_000.into(),
1698        );
1699        engine
1700            .0
1701            .add_data(vec![Data::Bar(bar)], None, true, true)
1702            .unwrap();
1703
1704        let error = engine.py_run(None, None, None, false).unwrap_err();
1705        engine.0.dispose();
1706
1707        Python::attach(|py| {
1708            assert!(error.is_instance_of::<PyRuntimeError>(py));
1709        });
1710
1711        assert_eq!(
1712            error.to_string(),
1713            format!(
1714                "RuntimeError: Bar execution requires time-aggregated bars, received {bar_type}"
1715            )
1716        );
1717    }
1718
1719    #[rstest]
1720    fn test_pyobject_to_data_accepts_custom_data() {
1721        Python::initialize();
1722
1723        Python::attach(|py| {
1724            let custom = stub_custom_data(2, 42, None, None);
1725            let obj = custom.into_py_any(py).unwrap();
1726            let converted = super::pyobject_to_data(py, obj.bind(py)).unwrap();
1727
1728            let Data::Custom(converted) = converted else {
1729                panic!("Expected Data::Custom");
1730            };
1731            assert_eq!(converted.data_type.type_name(), "StubCustomData");
1732            assert_eq!(converted.data.ts_init().as_u64(), 2);
1733        });
1734    }
1735
1736    #[rstest]
1737    fn test_pyobject_to_data_rejects_duck_typed_object() {
1738        Python::initialize();
1739
1740        Python::attach(|py| {
1741            // Mirrors the attribute shape the removed Cython `from_pyobject` path accepted
1742            let obj = py
1743                .eval(
1744                    c_str!(
1745                        "type('FakeQuote', (), {\
1746                            'instrument_id': type('I', (), {'value': 'AUD/USD.SIM'})(), \
1747                            'bid_price': type('P', (), {'raw': 1, 'precision': 5})(), \
1748                            'ask_price': type('P', (), {'raw': 1, 'precision': 5})(), \
1749                            'bid_size': type('Q', (), {'raw': 1, 'precision': 0})(), \
1750                            'ask_size': type('Q', (), {'raw': 1, 'precision': 0})(), \
1751                            'ts_event': 0, \
1752                            'ts_init': 0\
1753                        })()"
1754                    ),
1755                    None,
1756                    None,
1757                )
1758                .unwrap();
1759
1760            let err = super::pyobject_to_data(py, &obj).unwrap_err();
1761
1762            assert_eq!(
1763                err.to_string(),
1764                "TypeError: Cannot convert FakeQuote to Data"
1765            );
1766        });
1767    }
1768
1769    #[rstest]
1770    fn test_add_venue_accepts_python_defined_fee_fill_and_margin_models() {
1771        Python::initialize();
1772
1773        let mut engine =
1774            super::PyBacktestEngine(BacktestEngine::new(BacktestEngineConfig::default()).unwrap());
1775        Python::attach(|py| {
1776            let locals = PyDict::new(py);
1777            locals
1778                .set_item("FeeModel", py.get_type::<PyFeeModel>())
1779                .unwrap();
1780            locals
1781                .set_item("FillModel", py.get_type::<PyFillModel>())
1782                .unwrap();
1783
1784            let fill_model = py
1785                .eval(
1786                    c_str!(
1787                        "type('CustomFillModel', (FillModel,), {\
1788                            'is_limit_filled': lambda self: True, \
1789                            'is_slipped': lambda self: False\
1790                        })()"
1791                    ),
1792                    None,
1793                    Some(&locals),
1794                )
1795                .unwrap();
1796            let fee_model = py
1797                .eval(
1798                    c_str!(
1799                        "type('CustomFeeModel', (FeeModel,), {\
1800                            'get_commission': \
1801                                lambda self, order, fill_quantity, fill_px, instrument: self.commission\
1802                        })()"
1803                    ),
1804                    None,
1805                    Some(&locals),
1806                )
1807                .unwrap();
1808            fee_model
1809                .setattr("commission", Money::from("0 USD").into_py_any(py).unwrap())
1810                .unwrap();
1811
1812            locals
1813                .set_item("initial", Money::from("123.45 USD"))
1814                .unwrap();
1815            locals
1816                .set_item("maintenance", Money::from("67.89 USD"))
1817                .unwrap();
1818            let margin_model = py.eval(c_str!("type('Margin', (), {'calculate_initial_margin': lambda self, *args: initial, 'calculate_maintenance_margin': lambda self, *args: maintenance})()"), Some(&locals), None).unwrap();
1819
1820            engine
1821                .py_add_venue(
1822                    Venue::from("SIM"),
1823                    OmsType::Netting,
1824                    AccountType::Margin,
1825                    vec![Money::from("1_000_000 USD")],
1826                    None::<Currency>,
1827                    None,
1828                    None,
1829                    Some(fill_model.unbind()),
1830                    Some(fee_model.unbind()),
1831                    Some(margin_model.unbind()),
1832                    None,
1833                    None,
1834                    BookType::L1_MBP,
1835                    false,
1836                    true,
1837                    true,
1838                    true,
1839                    true,
1840                    false,
1841                    true,
1842                    true,
1843                    false,
1844                    true,
1845                    false,
1846                    true,
1847                    false,
1848                    false,
1849                    false,
1850                    false,
1851                    OtoTriggerMode::Partial,
1852                    None,
1853                    false,
1854                    None,
1855                    true,
1856                    OrderPriorityResetPolicy::PriceChange,
1857                )
1858                .unwrap();
1859
1860            let instrument = InstrumentAny::CurrencyPair(audusd_sim());
1861            engine.0.add_instrument(&instrument).unwrap();
1862            engine
1863                .0
1864                .add_data(vec![Data::Quote(quote_audusd())], None, true, true)
1865                .unwrap();
1866            engine.py_run(None, None, None, false).unwrap();
1867            let account = engine
1868                .0
1869                .kernel()
1870                .cache
1871                .borrow()
1872                .account_for_venue(&Venue::from("SIM"))
1873                .unwrap()
1874                .clone();
1875
1876            let AccountAny::Margin(account) = account else {
1877                panic!("expected margin account")
1878            };
1879
1880            let quantity = Quantity::from(10000);
1881            let price = Price::from("0.81234");
1882            assert_eq!(
1883                account
1884                    .calculate_initial_margin(&instrument, quantity, price, None)
1885                    .unwrap(),
1886                Money::from("123.45 USD")
1887            );
1888            assert_eq!(
1889                account
1890                    .calculate_maintenance_margin(&instrument, quantity, price, None)
1891                    .unwrap(),
1892                Money::from("67.89 USD")
1893            );
1894            assert_eq!(engine.0.list_venues(), vec![Venue::from("SIM")]);
1895        });
1896    }
1897}
1898
1899#[cfg(test)]
1900mod lifecycle_tests {
1901    use indexmap::IndexMap;
1902    use nautilus_model::identifiers::ActorId;
1903    use nautilus_testkit::{cache::TestCacheDatabaseControl, components::StateActor};
1904    use pyo3::Python;
1905    use rstest::rstest;
1906
1907    use super::PyBacktestEngine;
1908    use crate::{config::BacktestEngineConfig, engine::BacktestEngine};
1909
1910    #[rstest]
1911    fn test_end_continues_after_state_persistence_error() {
1912        Python::initialize();
1913
1914        let actor_id = ActorId::from("PY-END-FAIL-SAVE-ACTOR");
1915        let (database, control) = TestCacheDatabaseControl::create();
1916        control.set_fail_update_actor(true);
1917        let config = BacktestEngineConfig {
1918            save_state: true,
1919            run_analysis: false,
1920            ..Default::default()
1921        };
1922        let mut engine = PyBacktestEngine(BacktestEngine::new(config).unwrap());
1923        engine
1924            .0
1925            .kernel_mut()
1926            .cache
1927            .borrow_mut()
1928            .set_database(Box::new(database));
1929        engine
1930            .0
1931            .add_actor(StateActor::new(
1932                actor_id,
1933                control.clone(),
1934                IndexMap::from([("state".to_string(), b"value".to_vec())]),
1935            ))
1936            .unwrap();
1937        engine.0.kernel_mut().start();
1938        engine.0.kernel_mut().start_trader().unwrap();
1939        engine.0.kernel_mut().stop_trader();
1940
1941        engine.py_end().unwrap();
1942        engine.0.dispose();
1943
1944        assert_eq!(
1945            control.events(),
1946            vec![
1947                "actor.on_start",
1948                "actor.on_stop",
1949                "actor.on_save",
1950                "actor.update:PY-END-FAIL-SAVE-ACTOR",
1951                "database.close",
1952            ]
1953        );
1954    }
1955}