# power-quant-backtest

**Repository Path**: power-quant/power-quant-backtest

## Basic Information

- **Project Name**: power-quant-backtest
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-15
- **Last Updated**: 2026-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Power-Quant-Backtest

> Rust 驱动的量化回测引擎，提供 Python 绑定。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

## 特性

- **Rust 核心引擎**：BacktestEngine + FIFO 仓位匹配 + 多品种支持
- **Python 绑定**：PyO3 0.27.2 + abi3-py312 单 wheel 覆盖 Python 3.12/3.13+
- **零运行时依赖**：Python 库本身不依赖 pandas/numpy 等第三方包
- **多周期合成**：BarGenerator 支持 1min → 5min/60min/日线 合成
- **日线回测**：原生支持日线数据（`cancel_on_day_rollover=False`），T 日信号 → T+1 日开盘价成交
- **指标计算**：ArrayManager 提供 OHLCV 数组 + 常用技术指标
- **完整报告**：BacktestReport 含资金曲线、交易明细、夏化/索提诺/最大回撤

## 安装

### 从 Gitee Release 安装（推荐）

> **注意**：Gitee Release 的下载链接会被 CDN 重定向，`pip install <URL>` / `uv pip install <URL>` 直装都会遭遇 `403 Forbidden`（CDN 拦截 pip/uv 的请求特征，与 User-Agent 无关；curl/wget 不受影响）。请先下载 wheel 文件再本地安装。

**uv（推荐，装包最快）**：

```bash
curl -O https://gitee.com/power-quant/power-quant-backtest/releases/download/v0.2.0/power_quant_backtest-0.2.0-cp312-abi3-win_amd64.whl
uv pip install power_quant_backtest-0.2.0-cp312-abi3-win_amd64.whl
```

**pip（Linux / macOS / Git Bash）**：

```bash
curl -O https://gitee.com/power-quant/power-quant-backtest/releases/download/v0.2.0/power_quant_backtest-0.2.0-cp312-abi3-win_amd64.whl
pip install power_quant_backtest-0.2.0-cp312-abi3-win_amd64.whl
```

**PowerShell / CMD（Windows）**：

```powershell
Invoke-WebRequest -Uri "https://gitee.com/power-quant/power-quant-backtest/releases/download/v0.2.0/power_quant_backtest-0.2.0-cp312-abi3-win_amd64.whl" -OutFile "power_quant_backtest-0.2.0-cp312-abi3-win_amd64.whl"
pip install power_quant_backtest-0.2.0-cp312-abi3-win_amd64.whl
```

或直接到 [Releases 页面](https://gitee.com/power-quant/power-quant-backtest/releases) 手动下载 `.whl` 文件后 `pip install <文件路径>`。

### 从源码构建

需要 Rust 工具链（stable）+ maturin：

```bash
pip install maturin
maturin build --release --strip
pip install target/wheels/*.whl
```

## 快速开始

引擎统一通过 **TOML 配置文件**创建（`BacktestEngine.from_config_file`），替代旧的 `BacktestEngine(capital)` 构造函数。

```python
from power_quant_backtest import BacktestEngine

# 1. 写一个 backtest.toml（格式见下方表格）
# 2. 从配置文件创建引擎并自动注册品种
engine = BacktestEngine.from_config_file("backtest.toml")
engine.add_bars([...])  # 你的 K 线数据
report = engine.run_with_python_strategy(my_strategy)
report.print_summary()
```

最小 TOML 配置（分钟线回测）：

```toml
[engine]
initial_capital = 100000
cancel_on_day_rollover = true   # 日内回测 true，日线回测必须 false

[instruments.RB88]
multiplier = 10.0               # 必填：合约乘数
tick_size = 1.0                 # 必填：最小变动价位
commission_rate = 0.00001
slippage = 1.0
margin_ratio = 0.1
asset_class = "futures"         # "futures"（默认）/ "equity"（A 股）
```

> 撮合时序固定为 T+1（T 日 on_bar 信号 → T+1 开盘成交），无未来函数，不可配置。

| 配置项 | 必填 | 默认 | 说明 |
|--------|------|------|------|
| `[engine].initial_capital` | 否 | `1000000` | 初始资金 |
| `[engine].cancel_on_day_rollover` | 否 | `true` | ⚠ 日线回测**必须** `false`，否则零成交 |
| `[instruments.SYM].multiplier` | **是** | — | 合约乘数 |
| `[instruments.SYM].tick_size` | **是** | — | 最小变动价位 |
| `[instruments.SYM].commission_rate` | 否 | `0` | 手续费率 |
| `[instruments.SYM].slippage` | 否 | `0` | 滑点 |
| `[instruments.SYM].margin_ratio` | 否 | `0.10` | 保证金比例 |
| `[instruments.SYM].asset_class` | 否 | `"futures"` | `"futures"` / `"equity"` |

> ⚠ **A 股品种**（印花税/整手/涨跌停）TOML 暂不支持，需用 `engine.add_equity(...)` 追加。

完整示例见 [`examples/`](examples/)。

## 市场与品种配置

引擎按 `asset_class` 为每个品种加载对应的**市场规则**（撮合 / 费用 / 资金流 / 权益公式）。同一套引擎核心代码可服务不同资产类别：

| `asset_class` | 规则 | 状态 |
|---------------|------|------|
| `"futures"` | 期货：保证金、双向持仓、合约乘数口径盈亏与权益、0.95 杠杆上限 | ✅ 已支持 |
| `"equity"` | A 股：T+1、100 股整手、涨跌停、印花税/过户费、全额资金制、禁做空 | ✅ 已支持 |

### 期货配置

**Python**（`add_instrument`，`asset_class` 默认 `"futures"`，老调用零改动兼容）：

```python
engine.add_instrument(
    "RB88", multiplier=10.0, commission_rate=0.00001,
    slippage=1.0, tick_size=1.0, margin_ratio=0.1, asset_class="futures",
)
```

**Rust**（Builder API）：

```rust
use power_quant_backtest::{InstrumentConfig, AssetClass};

let cfg = InstrumentConfig::builder("RB88", AssetClass::Futures)
    .contract_multiplier(10.0)
    .commission_rate(0.00001)
    .slippage(1.0)
    .margin_ratio(0.1)
    .build();
engine.add_instrument(cfg)?;  // 返回 Result
```

### A 股配置

**Python**（`add_equity` 便捷方法，带 A 股常用默认费率）：

```python
# A 股日线：cancel_on_day_rollover=false（日线必须）
engine = BacktestEngine.from_config_file("ashare.toml")
# 沪市，全默认费率（佣金万3/最低5元、印花税千0.5、过户费万0.1、100股/手、10%涨跌停）
engine.add_equity("600000", is_sh=True)
# 深市，自定义佣金
engine.add_equity("000001", commission_rate=0.00025, is_sh=False)
```

> A 股日线数据须带 `prev_close`（昨收）字段，用于涨跌停计算；缺失则涨跌停校验退化（不限制）。

**Rust**（Builder API，需逐项配置 A 股字段）：

```rust
let cfg = InstrumentConfig::builder("600000", AssetClass::Equity)
    .contract_multiplier(1.0)
    .commission_rate(0.0003)
    .stamp_duty_rate(0.0005)   // 印花税（卖出单边）
    .transfer_fee_rate(0.00001) // 过户费（沪市双向）
    .min_commission(5.0)       // 最低佣金
    .lot_size(100.0)           // 100 股整手
    .price_limit_ratio(0.10)   // 10% 涨跌停
    .sh_market(true)           // 沪市
    .build();
engine.add_instrument(cfg)?;
```

### A 股规则行为说明

- **T+1**：当日买入次日才能卖出。买入进 `frozen_today`，日终（交易日切换）转入 `available`。策略平仓校验用 `long_available` 而非持仓总量。
- **涨跌停**：委托价须在 `[跌停价, 涨停价]`（`prev_close × (1±ratio)`，四舍五入到分）。一字涨停买不进、一字跌停卖不出。
- **100 股整手**：买入须为 `lot_size`（100）整数倍；卖出允许零股（不足一手可卖）。
- **印花税**：仅卖出单边征收（`成交额 × stamp_duty_rate`）；佣金双向最低 `min_commission` 元；沪市额外收过户费。
- **全额资金制**：买入扣全额现金（无保证金冻结），卖出回笼全额；权益 = 现金 + 持仓市值。
- **禁做空**：`sell_short` 直接拒单。

> 旧的位置参数构造法 `InstrumentConfig::new(symbol, mult, ...)` 仍保留（内部默认 `Futures`），已标记 `#[deprecated]`，建议迁移到 Builder。

## 示例

### Python 示例（面向策略开发者）

| 文件 | 内容 |
|------|------|
| [`examples/01_quickstart.py`](examples/01_quickstart.py) | 最小可运行回测 |
| [`examples/02_dual_ma.py`](examples/02_dual_ma.py) | 双均线 + 多周期合成 |
| [`examples/03_range_break.py`](examples/03_range_break.py) | 日内突破 + 止损止盈 |
| [`examples/04_trend_adaptive.py`](examples/04_trend_adaptive.py) | SuperTrend + 自适应仓位 |
| [`examples/05_daily_breakout.py`](examples/05_daily_breakout.py) | **日线回测** + parquet 数据加载 |
| [`examples/06_futures_config_builder.py`](examples/06_futures_config_builder.py) | **市场配置** + asset_class 新 API |
| [`examples/07_ashare_strategy.py`](examples/07_ashare_strategy.py) | **A 股回测** + T+1/涨跌停/印花税 |

### 日线回测

日线数据每根 bar 对应一个交易日，与日内（分钟线）回测的关键差异：**必须关闭"日终撤单"**，否则引擎会在每根日 K 开头撤销上一根 bar 的订单，导致零成交。

```toml
# 日线回测：cancel_on_day_rollover = false 是关键
[engine]
initial_capital = 100000
cancel_on_day_rollover = false
```

```python
from power_quant_backtest import BacktestEngine
engine = BacktestEngine.from_config_file("daily.toml")
```

订单在 T 日 `on_bar` 下单后，会在 T+1 日以开盘价撮合（限价单按 OHLC 判断是否触及，市价单直接按开盘价成交），无未来函数。

读取 rq-parquet-downloader 格式的日线 parquet，使用示例工具 [`examples/_parquet_io.py`](examples/_parquet_io.py)（依赖可选的 `pyarrow`）：

```bash
pip install pyarrow  # 可选依赖，仅 parquet 加载需要
python examples/05_daily_breakout.py
```

### Rust 示例（面向引擎开发者）

| 文件 | 内容 |
|------|------|
| [`examples-rs/dual_ma.rs`](examples-rs/dual_ma.rs) | Rust Strategy 完整实现模式 |
| [`examples-rs/range_break.rs`](examples-rs/range_break.rs) | 内置策略驱动示例 |
| [`examples-rs/trend_adaptive.rs`](examples-rs/trend_adaptive.rs) | 4 状态进阶信号 |

运行 Rust 示例：

```bash
cargo run --example dual_ma
cargo run --example range_break
cargo run --example trend_adaptive
```

## 文档

- [市场规则与配置 API](docs/api-market.md)：Market trait、InstrumentConfig 字段全表、期货/A 股配置方法
- [更新日志](CHANGELOG.md)

## 协议

[MIT](LICENSE)

## 致谢

本项目从 [`power-quant-1`](https://gitee.com/power-quant/power-quant-1)（私有）提取而来。