back_trader

back_trader is a C++20 quantitative trading backtesting engine focused on Python Backtrader compatibility, high-performance strategy execution, and reproducible benchmark evidence.

The project provides a modular C++ core, a broad C++ regression suite, Python parity tests, and benchmark tooling for comparing C++ strategy execution with Python reference behavior.

Performance snapshot

Latest Win11 benchmark snapshot from 2026-07-04, measured on Microsoft Windows 11 Pro 10.0.26200 build 26200 x86_64 (Lenovo 21H2A04WCD, 13th Gen Intel Core i5-1340P, 12 cores / 16 logical processors, 31.7 GiB RAM) with Anaconda Python environments, backtrader==1.2.0 from F:/source_code/backtrader as the Python reference, installed back-trader-cpp==0.39.2 wheels for pybind11, and 117 strategy benchmark cases (--repeats 5 --workers 1, warmed C++ builds):

The speedups above are medians across all 117 strategies. The Win11 run used the configured C++ launch fallback for five strategies that had been blocked by local CreateProcess security policy during validation (macd_gradient_strategy, mean_reversion_sma_strategy, optimization, stochastic_sr_strategy, and timers); those rows remain metric-aligned, but their local Win11 C++ timing is fallback-substituted rather than native executable timing.

Latest Ubuntu benchmark snapshot from 2026-07-04, measured on Ubuntu 24.04.4 LTS x86_64 (Linux 6.17.0-35-generic, glibc 2.39) with Anaconda Python environments, backtrader==1.2.0 from /home/yun/Documents/backtrader as the Python reference, installed back-trader-cpp==0.39.2 manylinux_2_39_x86_64 wheels from the dev branch for pybind11, and 117 strategy benchmark cases (--repeats 5 --workers 1, warmed C++ builds):

The Ubuntu speedups above are medians across all 117 strategy rows. Each strategy row uses the median from five runs per engine to reduce local machine noise.

Latest macOS benchmark snapshot from 2026-07-04, measured on macOS 26.5.1 arm64 (Darwin 25.5.0, Apple M2, 8 physical / 8 logical cores, 16 GiB RAM) with Anaconda Python environments, backtrader==1.2.0 installed from site-packages as the Python reference, installed back-trader-cpp==0.39.2 macOS arm64 wheels from site-packages for pybind11, and 117 strategy benchmark cases (--repeats 5 --workers 1, warmed C++ builds):

The macOS speedups above are medians across all 117 strategy rows. Each strategy row uses the median from five runs per engine to reduce local machine noise. All metric diff reports had no bad rows; the reported max delta of 0.0001 is within the benchmark metric tolerance.

Project goals

• Compatibility first: Preserve Python Backtrader-style trading semantics, data-feed behavior, lifecycle hooks, analyzers, and strategy outcomes.
• Performance with evidence: Optimize the C++ engine only when correctness parity is maintained and before/after benchmark data is available.
• Usable C++ APIs: Keep user-facing strategy code simple; avoid forcing raw-pointer, cache-handle, or benchmark-only APIs into normal strategy development.
• Reproducible quality gates: Use CMake, gtest, pytest, ruff, benchmark schema checks, and API compatibility checks as engineering guardrails.

Current status

• Core version: 1.1.0 from back_trader_cpp/include/version.h
• Primary language: C++20
• Build system: CMake 3.20+
• Test systems: gtest for C++ and pytest for Python/benchmark tooling
• Benchmark focus: C++ vs Python strategy parity and speedup tracking across the strategy benchmark suite
• Project maturity: Active compatibility and performance convergence work

Performance claims should always be read together with the current authority CSVs and quality-gate reports under benchmarks/perf/, benchmarks/results/, _bmad-output/, and docs/.

Repository layout

See docs/index.md for the maintained documentation map.

Quick start

1. Install prerequisites

Required:

• C++20-capable compiler
• CMake 3.20+
• Python 3.11+
• Python development dependencies from requirements-dev.txt

Optional but recommended:

• Quill or spdlog for the logging backend
• ruff for Python tooling checks
• clang-format and clang-tidy for C++ hygiene checks

Install Python development dependencies:

python3 -m pip install -r requirements-dev.txt

2. Configure and build

Default builds expect the configured logging backend to be available. For a portable local build that can fall back when Quill/spdlog is unavailable:

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DBACK_TRADER_LOG_BACKEND=auto \
  -DBACK_TRADER_FALLBACK_LOGGING=ON
cmake --build build --config Release -j 8

If your environment has Quill installed and you want the default backend:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j 8

3. Run the C++ test suite

./run_tests_cpp.sh

The script configures CMake, builds back_trader_cpp_all_tests, validates the dynamically discovered registered script count, and runs gtest shards in parallel.

Common overrides:

CORES=4 ./run_tests_cpp.sh
BUILD_DIR=build-doc-check CORES=4 ./run_tests_cpp.sh
TARGET=back_trader_cpp_all_tests ./run_tests_cpp.sh

4. Run Python tests

python3 -m pytest tests_python -m "priority_p0 or priority_p1"
python3 -m pytest tests_python -ra

When comparing against an external Python Backtrader package, set:

BACK_TRADER_PYTHON_MODULE_PATH=/path/to/backtrader/python/package python3 -m pytest tests_python -ra

5. Run quality gates

For benchmark/tooling changes:

python3 tools/quality_gate.py

For C++ correctness plus public API compatibility:

python3 tools/quality_gate.py --cpp-tests --bt-compat

For Python package/facade quality:

python3 tools/quality_gate.py --skip-default --python-package

See docs/quality-gates.md for gate policy.

Benchmarking

Run the aggregate strategy benchmark runner:

python3 benchmarks/tools/strategy_benchmark_runner.py \
  --repeats 5 \
  --workers 6 \
  --speedup-source-csv benchmarks/perf/baselines/local_speedup.csv

Useful focused modes:

python3 benchmarks/tools/strategy_benchmark_runner.py --max-strategies 2 --repeats 1
python3 benchmarks/tools/strategy_benchmark_runner.py --print-authority --print-authority-source benchmarks/perf/baselines/local_speedup.csv

Benchmark outputs are evidence artifacts. Do not claim performance improvements without a concrete CSV, profile, timer, or metric-diff source.

See docs/benchmarking.md for benchmark workflow and evidence rules.

Architecture at a glance

The core engine follows the familiar Backtrader execution model:

1. Data feeds load and expose OHLCV and extra lines.
2. Line buffers and data series provide indexed line access for strategies and indicators.
3. Indicators consume lines and produce derived lines with streaming and run-once paths where compatible.
4. Strategies implement lifecycle hooks and submit orders through the broker.
5. Brokers, orders, analyzers, and observers model portfolio state, execution, metrics, and runtime notifications.
6. Cerebro orchestrates feeds, strategy stepping, synchronization, analyzers, and the run loop.

See docs/architecture-overview.md for details.

Development workflow

Use small, evidence-backed change sets:

• Keep benchmark tooling, engine hot-path work, and strategy/example rewrites separate unless explicitly justified.
• Preserve Python parity before optimizing.
• Add or update tests with behavior changes.
• Record before/after benchmark evidence for performance work.
• Run the relevant quality gate before review.

See docs/development-guide.md and .github/pull_request_template.md.

Documentation

Start here:

• Documentation index
• Project overview
• Architecture overview
• Development guide
• Benchmarking guide
• Quality gates
• Pandas data feeds comparison

Historical iteration plans under docs/迭代计划/ and BMad artifacts under _bmad-output/ are useful for context and evidence, but the documents above are the preferred onboarding path.

License

Source headers in this repository reference the Apache License, Version 2.0. Before external redistribution, verify that the repository includes the intended top-level license file and release metadata.