Metadata-Version: 2.2
Name: back-trader-cpp
Version: 0.37.0
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 local benchmark snapshot from 2026-06-19, measured across 117 strategy benchmark cases with Python as the reference:

| Engine | Status | Total-time median speedup | Run-time median speedup | Rows >= 50x total-time |
| --- | --- | ---: | ---: | ---: |
| C++ | 117/117 success, 0 metric mismatches | 128.82x | 235.78x | 98/117 |
| pybind11 | 117/117 success | 43.39x | 57.60x | 49/117 |

Evidence CSVs:

- C++ vs Python: `artifacts/benchmark_strategy_alignment/cpp_python_validation_current/speedup_summary.csv`
- pybind11 vs Python: `artifacts/benchmark_strategy_alignment/iter51_current_validation_pybind_python/speedup_summary.csv`

## 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.
