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 Ubuntu benchmark snapshot from 2026-06-27, measured on Ubuntu 24.04.4 LTS x86_64 across 117 strategy benchmark cases with Python as the reference:

Ubuntu evidence CSVs:

• Benchmark aggregate: artifacts/bt2cpp/full_validation_20260627/benchmarks/benchmark_all_strategies_summary.csv
• Benchmark speedup: artifacts/bt2cpp/full_validation_20260627/benchmarks/benchmark_speedup.csv
• Strategy Python/C++ validation: artifacts/bt2cpp/full_validation_20260627/strategies_py_cpp/all_results.csv
• Strategy pybind11/Python validation: artifacts/pybind11_strategy_local/full_validation_20260627/summary.json

Previous macOS snapshot from 2026-06-19, kept as historical platform-specific data:

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.