Metadata-Version: 2.2
Name: back-trader-cpp
Version: 0.39.2
Summary: High-performance backtrader-compatible trading platform powered by back_trader_cpp.
Keywords: backtrader,quantitative-trading,backtesting,pybind11
Author-Email: cloudQuant <yunjinqi@cloudquant.com>
License: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Office/Business :: Financial :: Investment
Project-URL: Homepage, https://github.com/cloudQuant/back_trader
Requires-Python: <3.15,>=3.8
Requires-Dist: backports.zoneinfo>=0.2.1; python_version < "3.9"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: numpy; extra == "dev"
Requires-Dist: pandas; extra == "dev"
Requires-Dist: pyecharts>=2; extra == "dev"
Provides-Extra: data
Requires-Dist: numpy; extra == "data"
Requires-Dist: pandas; extra == "data"
Provides-Extra: plot
Requires-Dist: pyecharts>=2; extra == "plot"
Description-Content-Type: text/markdown

# 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):

| Python env | System | Python | Benchmark parity | Installed `tests_python` | pybind11 total | pybind11 run | C++ total | C++ run |
| --- | --- | ---: | --- | --- | ---: | ---: | ---: | ---: |
| `py38` | Win11 | 3.8.20 | 117/117 success, max delta 0.0001 | PASS | 33.33x | 56.43x | 46.93x | 140.80x |
| `py39` | Win11 | 3.9.25 | 117/117 success, max delta 0.0001 | PASS | 28.52x | 47.46x | 35.82x | 106.80x |
| `py310` | Win11 | 3.10.18 | 117/117 success, max delta 0.0001 | PASS | 35.75x | 58.30x | 50.56x | 148.51x |
| `bt311` | Win11 | 3.11.14 | 117/117 success, max delta 0.0001 | PASS | 28.84x | 46.82x | 39.53x | 117.41x |
| `py312` | Win11 | 3.12.12 | 117/117 success, max delta 0.0001 | PASS | 28.03x | 41.63x | 35.72x | 107.08x |
| `py313` | Win11 | 3.13.5 | 117/117 success, max delta 0.0001 | PASS | 25.50x | 39.38x | 36.06x | 106.65x |
| `py314` | Win11 | 3.14.6 | 117/117 success, max delta 0.0001 | PASS | 29.30x | 48.14x | 43.87x | 131.18x |

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):

| Python env | System | Python | Benchmark parity | Installed `tests_python` | pybind11 total | pybind11 run | C++ total | C++ run |
| --- | --- | ---: | --- | --- | ---: | ---: | ---: | ---: |
| `py38` | Ubuntu 24.04 | 3.8.20 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 42.30x | 56.70x | 66.37x | 101.11x |
| `py39` | Ubuntu 24.04 | 3.9.23 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 41.30x | 56.30x | 86.88x | 135.67x |
| `py310` | Ubuntu 24.04 | 3.10.20 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 43.89x | 59.26x | 93.02x | 143.00x |
| `py311` | Ubuntu 24.04 | 3.11.15 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 36.97x | 50.35x | 77.65x | 117.33x |
| `py312` | Ubuntu 24.04 | 3.12.13 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 28.79x | 39.96x | 57.81x | 88.46x |
| `py313` | Ubuntu 24.04 | 3.13.14 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 26.94x | 40.16x | 58.70x | 86.82x |
| `py314` | Ubuntu 24.04 | 3.14.6 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 27.73x | 40.18x | 59.53x | 90.31x |

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):

| Python env | System | Python | Benchmark parity | Installed `tests_python` | pybind11 total | pybind11 run | C++ total | C++ run |
| --- | --- | ---: | --- | --- | ---: | ---: | ---: | ---: |
| `py38` | macOS 26.5.1 | 3.8.20 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 40.97x | 54.65x | 84.17x | 140.72x |
| `py39` | macOS 26.5.1 | 3.9.23 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 39.68x | 53.43x | 82.33x | 140.24x |
| `py310` | macOS 26.5.1 | 3.10.18 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 41.06x | 54.36x | 87.41x | 142.49x |
| `py311` | macOS 26.5.1 | 3.11.13 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 36.68x | 48.43x | 81.88x | 136.24x |
| `py312` | macOS 26.5.1 | 3.12.11 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 28.93x | 38.13x | 66.20x | 107.15x |
| `py313` | macOS 26.5.1 | 3.13.5 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 25.52x | 36.96x | 65.46x | 100.28x |
| `py314` | macOS 26.5.1 | 3.14.6 | 117/117 success, max delta 0.0001 | PASS, 1925 passed, 1 skipped | 26.48x | 37.34x | 61.41x | 102.37x |

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

| Path | Purpose |
| --- | --- |
| `back_trader_cpp/include/` | Public C++ headers and API declarations |
| `back_trader_cpp/src/` | C++ core implementation |
| `tests_cpp/unit/` | C++ unit tests for core components |
| `tests_cpp/functional/` | C++ functional strategy parity tests |
| `tests_python/` | Python reference tests, data assets, and helper fixtures |
| `benchmarks/strategies/` | C++/Python strategy benchmark cases |
| `benchmarks/tools/` | Aggregate benchmark runner and reporting utilities |
| `benchmarks/tests/` | Benchmark tooling and CSV schema tests |
| `benchmarks/perf/` | Performance baselines, profiling notes, and retained artifacts |
| `tools/` | Quality gates and compatibility-check tooling |
| `docs/` | Project documentation, quality gates, and iteration records |
| `_bmad-output/` | BMad planning and implementation artifacts |

See [docs/index.md](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:

```bash
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:

```bash
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:

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

### 3. Run the C++ test suite

```bash
./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:

```bash
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

```bash
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:

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

### 5. Run quality gates

For benchmark/tooling changes:

```bash
python3 tools/quality_gate.py
```

For C++ correctness plus public API compatibility:

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

For Python package/facade quality:

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

See [docs/quality-gates.md](docs/quality-gates.md) for gate policy.

## Benchmarking

Run the aggregate strategy benchmark runner:

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

Useful focused modes:

```bash
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](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](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](docs/development-guide.md) and `.github/pull_request_template.md`.

## Documentation

Start here:

- [Documentation index](docs/index.md)
- [Project overview](docs/project-overview.md)
- [Architecture overview](docs/architecture-overview.md)
- [Development guide](docs/development-guide.md)
- [Benchmarking guide](docs/benchmarking.md)
- [Quality gates](docs/quality-gates.md)
- [Pandas data feeds comparison](docs/others/PANDAS_DATA_FEEDS_COMPARISON.md)

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.

