1use 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::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#[cfg(feature = "defi")]
95#[pyo3_stub_gen::derive::gen_stub_pymethods]
96#[pymethods]
97impl PyBacktestEngine {
98 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[pyo3(name = "end")]
509 fn py_end(&mut self) -> PyResult<()> {
510 self.0.end().map_err(to_pyruntime_err)
511 }
512
513 #[pyo3(name = "reset")]
515 fn py_reset(&mut self) -> PyResult<()> {
516 self.0.reset().map_err(to_pyruntime_err)
517 }
518
519 #[pyo3(name = "dispose")]
521 fn py_dispose(&mut self) {
522 self.0.dispose();
523 }
524
525 #[pyo3(name = "get_result")]
527 fn py_get_result(&self) -> BacktestResult {
528 self.0.get_result()
529 }
530
531 #[pyo3(name = "clear_data")]
533 fn py_clear_data(&mut self) {
534 self.0.clear_data();
535 }
536
537 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[pyo3(name = "sort_data")]
623 fn py_sort_data(&mut self) {
624 self.0.sort_data();
625 }
626
627 #[getter]
629 #[pyo3(name = "trader_id")]
630 fn py_trader_id(&self) -> TraderId {
631 self.0.trader_id()
632 }
633
634 #[getter]
636 #[pyo3(name = "machine_id")]
637 fn py_machine_id(&self) -> String {
638 self.0.machine_id().to_string()
639 }
640
641 #[getter]
643 #[pyo3(name = "instance_id")]
644 fn py_instance_id(&self) -> UUID4 {
645 self.0.instance_id()
646 }
647
648 #[getter]
650 #[pyo3(name = "iteration")]
651 fn py_iteration(&self) -> usize {
652 self.0.iteration()
653 }
654
655 #[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 #[getter]
664 #[pyo3(name = "run_id")]
665 fn py_run_id(&self) -> Option<UUID4> {
666 self.0.run_id()
667 }
668
669 #[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 #[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 #[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 #[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 #[pyo3(name = "list_venues")]
699 fn py_list_venues(&self) -> Vec<Venue> {
700 self.0.list_venues()
701 }
702
703 #[getter]
705 #[pyo3(name = "cache")]
706 fn py_cache(&self) -> PyCache {
707 engine_cache(&self.0)
708 }
709
710 #[getter]
712 #[pyo3(name = "portfolio")]
713 fn py_portfolio(&self) -> PyPortfolio {
714 engine_portfolio(&self.0)
715 }
716
717 #[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 #[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 #[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 #[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 #[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 #[must_use]
857 pub fn inner(&self) -> &BacktestEngine {
858 &self.0
859 }
860
861 pub fn inner_mut(&mut self) -> &mut BacktestEngine {
863 &mut self.0
864 }
865
866 #[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 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 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 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 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}