Metadata-Version: 2.2
Name: quantcore
Version: 1.0.0
Summary: High-performance C++20 backtesting engine with Python interface
Keywords: trading,backtesting,algorithmic-trading,quantitative-finance
Author-Email: Stefaan Molenaar <StefaanLMolenaar@gmail.com>
License: MIT License
         
         Copyright (c) 2026 Stefaan Molenaar
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Programming Language :: Python :: 3
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 :: C++
Project-URL: Homepage, https://github.com/SLMolenaar/quantcore
Project-URL: Bug Reports, https://github.com/SLMolenaar/quantcore/issues
Project-URL: Source, https://github.com/SLMolenaar/quantcore
Requires-Python: >=3.8
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7.0; extra == "viz"
Requires-Dist: seaborn>=0.12.0; extra == "viz"
Description-Content-Type: text/markdown

# QuantCore

![PyPI](https://img.shields.io/pypi/v/quantcore)
![Build](https://github.com/SLMolenaar/quantcore/actions/workflows/coverage.yml/badge.svg)
![C++](https://img.shields.io/badge/C%2B%2B-20-blue)
![License](https://img.shields.io/badge/license-MIT-green)

High-performance backtesting engine written in C++20 with a Python research interface.

---

## Overview

QuantCore is an event-driven backtester built around an enhanced version of [my limit order book simulator](https://github.com/SLMolenaar/orderbook-simulator-cpp). Market events are processed chronologically through a priority queue, so there's no look-ahead bias and no assumptions about fill prices. Orders go through a real price-time priority matching engine.

Both bar and tick data are supported. Strategies work unchanged across both.

```
Market Data → EventQueue → Strategy → Signal → OrderBook → Fill → Portfolio
```

---

## Quick Start

```python
pip install quantcore
```

```python
import quantcore as qc

class MyStrategy(qc.Strategy):
    def on_data(self, event):
        if not self.has_position(event.symbol):
            self.generate_signal(event.symbol, qc.SignalType.BUY, 1.0, event.timestamp_ns)

results = qc.run_backtest(
    strategy=MyStrategy(),
    data={'AAPL': qc.load_csv_data('data/aapl.csv', 'AAPL')},
    initial_capital=100_000.0,
)
print(results)
```

Tick data works the same way:

```python
results = qc.run_tick_backtest(
    strategy=MyStrategy(),
    tick_data={'AAPL': qc.load_tick_csv('data/aapl_ticks.csv', 'AAPL')},
    initial_capital=100_000.0,
)
```

`event.close` is the tick price when running on tick data. No strategy changes needed.

For the full API reference, see [docs/usage.md](docs/usage.md).

---

## Performance

Single-threaded. Measured on Windows (Release build, MSVC).

**Order book**

| Pattern | Ops/s |
|---|---|
| Add + cancel (MM quote refresh) | 13.0 M ops/s |
| Add + match (taker sweep) | 4.9 M ops/s |

**Bar mode**

| Scenario | Bars/s | p99 latency |
|---|---|---|
| 1-year (252 bars) | ~270 K/s | 0.93 ms |
| 5-year (1,260 bars) | ~270 K/s | - |
| 1,000-year stress (252,000 bars) | ~290 K/s | - |

**Tick mode**

| Scenario | Ticks/s | Wall time |
|---|---|---|
| 10K ticks, no MM throttle | 315 K/s | 31.7 ms |
| 10K ticks, 1s MM throttle | 1.66 M/s | 6.0 ms |
| 1M ticks aggregated to 1-min bars | 247 M/s | 4.1 ms |

The MM refresh interval is the main lever for tick performance. See [`benchmarks/RESULTS.md`](benchmarks/RESULTS.md) for the full breakdown.

---

## vs. Alternatives

| | QuantCore | Backtrader | Zipline |
|---|---|---|---|
| Core language | C++20 | Python | Python |
| Order book simulation | Yes | No | No |
| Tick data | Yes | No | No |
| Event-driven | Yes | Yes | Yes |
| Look-ahead prevention | Priority queue | Yes | Yes |
| Python strategy API | pybind11 | Native | Native |
| Throughput (bars/s) | ~300K | ~7.7K | unverified |
| Maintenance | Active | Stale | Inactive |

*Throughput: SMA(50/200) crossover, 50K daily bars, Release build, Windows.*
*Reproduce: `python benchmarks/qcVsBacktrader.py --bars 50000 --runs 20`*

The core differentiator is the order book. Backtrader and Zipline fill at close price. QuantCore routes orders through a real matching engine, giving you realistic partial fills, spread simulation, and tick-level execution.

---

## Installation

**Prerequisites:** CMake 3.15+, C++20 compiler (GCC 10+, Clang 12+, MSVC 2022), Python 3.8+

```bash
git clone https://github.com/SLMolenaar/quantcore.git
cd quantcore

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

cd python
pip install pybind11
python build_module.py

python -c "import quantcore; print(quantcore.version())"
```

**Run tests:**

```bash
cmake --build build --target quantcore_tests
./build/quantcore_tests
```

---

## Examples

| Notebook | Strategy | Concepts |
|---|---|---|
| [`mean_reversion.ipynb`](examples/mean_reversion.ipynb) | Z-score mean reversion | Parameter sensitivity, OU process |
| [`sma_crossover.ipynb`](examples/sma_crossover.ipynb) | SMA crossover | Trend following, signal generation |
| [`pairs_trading.ipynb`](examples/pairs_trading.ipynb) | Statistical arbitrage | Cointegration, spread trading |
| [`build_your_own_strategy.ipynb`](examples/build_your_own_strategy.ipynb) | Bollinger Band Breakout | Full walkthrough from scratch |

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Open areas:

- **VWAP / TWAP algos**: child order slicing in `ExecutionEngine`
- **Multi-strategy portfolio**: shared capital with a meta-allocator
- **Parallel sweeps**: `n_jobs` works but Windows process spawn overhead (~500ms per worker) makes it slower than sequential for short backtests. On Linux the break-even is much lower and it works as expected. Use Linux or WSL for parallel parameter sweeps.

The engine doesn't handle survivorship bias or timezone normalization. Feed it clean adjusted data and those aren't problems.

---

## License

MIT: see [LICENSE](LICENSE).