Skip to content

Conversation

@faysou
Copy link
Collaborator

@faysou faysou commented Jan 21, 2026

Pull Request

NautilusTrader prioritizes correctness and reliability, please follow existing patterns for validation and testing.

  • I have reviewed the CONTRIBUTING.md and followed the established practices

Summary

Summary

  • Refined the handling of timers within the BacktestEngine to ensure correct chronological processing when data is exhausted.
  • Replaced the previous "jump to end" timer processing logic with a more granular _process_next_timer approach. This allows the engine to correctly handle on-the-fly data loading triggered by timer callbacks (e.g., subscriptions during a backtest).
  • Fixed an initialization issue in the main backtest loop where _last_ns was set to 0 instead of the backtest start time.
  • Introduced a new suite of unit tests specifically for backtest engine timers, covering various scenarios including interleaved data/timers and chained alerts.

Key changes

Backtest engine refinements

  • Modified nautilus_trader/backtest/engine.pyx to implement _process_next_timer, which finds the absolute next timer time across all component clocks and advances to it.
  • Updated the main backtest loop to call _process_next_timer when the data stream is empty, ensuring that timers within the backtest range are processed sequentially.
  • Corrected the initial state of _last_ns to prevent premature time jumps or incorrect event processing at the start of a backtest.

Testing and examples

  • Added tests/unit_tests/backtest/test_engine_timers.py with 7 new test cases to validate timer execution with and without data, chained alerts, and interleaved processing.
  • Updated examples/backtest/notebooks/databento_test_order_book_deltas.py to use set_time_alert for more robust testing of order book delta subscriptions.

Test plan

  • Ran the new unit tests using uv run --no-sync pytest tests/unit_tests/backtest/test_engine_timers.py.
  • Verified that all 7 tests passed, confirming the correct handling of:
    • Timer execution with no data.
    • On-the-fly data loading from timer callbacks.
    • Multiple timers at the same timestamp.
    • Chained timers and alerts.
    • Interleaved data and timer events.

Related Issues/PRs

Type of change

  • Bug fix (non-breaking)
  • New feature (non-breaking)
  • Improvement (non-breaking)
  • Breaking change (impacts existing behavior)
  • Documentation update
  • Maintenance / chore

Breaking change details (if applicable)

Documentation

  • Documentation changes follow the style guide (docs/developer_guide/docs.md)

Release notes

  • I added a concise entry to RELEASES.md that follows the existing conventions (when applicable)

Testing

Ensure new or changed logic is covered by tests.

  • Affected code paths are already covered by the test suite
  • I added/updated tests to cover new or changed logic

@faysou faysou force-pushed the refine-timers-in-backtestengine branch from aac06b2 to ecfeb24 Compare January 21, 2026 10:28
@faysou faysou changed the title refine-timers-in-backtestengine Refine handling of timers in backtest engine Jan 21, 2026
@faysou faysou force-pushed the refine-timers-in-backtestengine branch from ecfeb24 to 053e92b Compare January 21, 2026 14:18
@faysou faysou force-pushed the refine-timers-in-backtestengine branch from 053e92b to cf83411 Compare January 21, 2026 19:13
@faysou faysou force-pushed the refine-timers-in-backtestengine branch from cf83411 to 65ae969 Compare January 21, 2026 19:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants