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

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

Portfolio Analytics

Exit Analysis

Stress Testing / Scenario Queue

CLI Workflow

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

• Architecture - layer boundaries, engine roles, artifact flow.
• Execution Contract - shared execution-kernel semantics, gap rules, and intrabar conflict policy.
• Module Map - quick reference for canonical packages and contributor entry points.
• Agent Context - compact project context for LLMs and automation agents.
• Usage Guide - CLI examples, common workflows, and dashboard launch commands.
• Contributing Guide - setup, workflow, tests, strategy additions, PR expectations.
• Analytics README
• Config README
• Execution README
• Optimization README
• Portfolio Layer README
• Runtime README
• Single-Asset README
• Terminal UI README
• Strategies README
• Tests README

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.