Skip to content

README.md

Latest commit

 

History

History
230 lines (168 loc) · 7.88 KB

README.md

File metadata and controls

230 lines (168 loc) · 7.88 KB

Note

Project status

The main branch contains the latest stable v1 release of Backtesting Engine.

Active development is now focused on Backtesting Engine v2 in the v2-alpha branch.
v2 is a major upgrade built around NautilusTrader, with a cleaner architecture, faster execution, and better support for realistic futures/FX/CFD backtesting.

Use main if you want the last stable v1 version.
Use v2-alpha if you want to follow the current v2 alpha work.

Current v2 alpha tag:

git checkout v2.0.0-alpha.1

Backtesting Platform

CI Python

Futures-focused research platform for:

  • single-strategy backtests
  • walk-forward optimization
  • multi-strategy portfolio backtests
  • terminal-style analytics review via FastAPI

The codebase is optimized for research workflows where no-lookahead execution, artifact reproducibility, and post-run analytics matter more than framework breadth.

Screenshots

Terminal UI Overview

image

Portfolio Analytics

image

Exit Analysis

image

Stress Testing / Scenario Queue

image image

CLI Workflow

image

What This Project Does

  • Runs single-asset event-driven backtests on cached OHLCV futures data.
  • Runs walk-forward validation through Optuna-based parameter search.
  • Runs portfolio backtests with shared capital, rebalancing, allocation, and slot-level execution.
  • Persists canonical artifacts for later inspection in the terminal UI.
  • Supports scenario reruns and portfolio-level analytics from saved artifacts.

Core Guarantees

  • No-lookahead contract: signal at close[t], execution at open[t+1].
  • Shared-capital accounting in the portfolio engine.
  • Artifact-first workflow: runs write reusable bundles to disk for later analysis.
  • Clear layer boundaries: CLI -> services -> engines/runtime.

Quick Start

git clone https://github.com/DanRedelien/backtesting-engine.git
cd backtesting-engine
pip install -r requirements.txt
pytest tests/

Python 3.11+ is recommended.

pyproject.toml already configures pytest pythonpath, so no manual PYTHONPATH export is needed.

Common Commands

# Download cached market data
python run.py --download ES NQ YM RTY CL GC SI

# Single backtest
python run.py --backtest --strategy sma_pullback --symbol ES --tf 1h

# Walk-forward optimization
python run.py --wfo --strategy ict_ob --symbol ES --tf 1h

# Portfolio backtest
python run.py --portfolio-backtest
python run.py --portfolio-backtest --portfolio-config src/backtest_engine/portfolio_layer/portfolio_config_example.yaml

# Lightweight batch backtests with one combined Matplotlib popup
# Batch summary MDD% is drawdown depth (non-negative). Plot filtering uses settings.batch_plot_max_drawdown_pct (default 80).
python run.py batch --strategies sma_pullback ict_ob --symbol ES NQ --tf 1h 30m

# Lightweight WFO batch sweep with verdict heatmap and candidate exports
python run.py wfo-batch --strategies sma_pullback ict_ob --symbol ES --tf 1h

# Launch terminal UI for the latest artifacts
python run.py --dashboard

# Run a backtest and open the UI after completion
python run.py --portfolio-backtest --dashboard

Redis Requirement

The Stress Testing tab in the terminal UI uses Redis/RQ. The rest of the platform does not require Redis.

Install Redis only if you want scenario queueing from the dashboard.

Windows:

winget install Redis.Redis

macOS:

brew install redis

Ubuntu/Debian:

sudo apt install redis-server

Project Layout

.
|-- README.md
|-- CONTRIBUTING.md
|-- docs/
|   |-- ARCHITECTURE.md
|   |-- EXECUTION_CONTRACT.md
|   |-- MODULE_MAP.md
|   `-- agents.md
|-- cli/
|   |-- single.py
|   |-- wfo.py
|   |-- portfolio.py
|   |-- batch.py
|   `-- wfo_batch.py
|-- run.py
|-- tests/
|   |-- README.md
|   |-- unit/
|   `-- regression/
`-- src/
    |-- data/
    |-- strategies/
    `-- backtest_engine/
        |-- analytics/
        |-- config/
        |-- execution/
        |-- optimization/
        |-- portfolio_layer/
        |-- runtime/
        |-- services/
        |-- single_asset/
        `-- serialization.py

Architecture At A Glance

  • run.py parses CLI args and dispatches to cli/.
  • cli/ is intentionally thin and delegates orchestration to src/backtest_engine/services/.
  • src/backtest_engine/single_asset/engine.py is the canonical single-asset execution engine.
  • src/backtest_engine/execution/ is the shared execution kernel package.
  • src/backtest_engine/config/ is the canonical home for runtime settings models.
  • src/backtest_engine/portfolio_layer/engine/engine.py is the portfolio event loop with shared capital and multi-slot execution.
  • src/backtest_engine/runtime/terminal_ui/ is the active FastAPI analytics UI.
  • src/backtest_engine/analytics/ contains artifact builders, reports, metrics, and shared analytics transforms.
  • src/backtest_engine/services/scenario_job_service.py remains the public scenario-queue entry point, with adjacent helper modules for metadata storage and worker execution.
  • src/data/ib_fetcher.py remains the public IB data entry point, with adjacent helper modules for contract resolution, cache/checkpoint storage, and historical backfill orchestration.

Results And Artifacts

  • Single runs write to results/.
  • Portfolio runs write to results/portfolio/.
  • Scenario reruns write to results/scenarios/<scenario_id>/....
  • The terminal UI reads saved artifacts rather than requiring a rerun.

Documentation Map

Strategy Registry

Strategies are exposed through src/strategies/registry.py.

Current canonical IDs:

  • ict_ob
  • sma_pullback
  • three_bar_mr (three-bar mean reversion)

The alias ict_order_block maps to ict_ob and is also accepted by the CLI.