atrs 1.1.0

Alpha Trading Rust System - Ultra-fast backtest engine for A-shares

ATRS - Alpha Trading Rust System

专为 A 股高频多因子策略设计的超高速回测引擎

⚡ 比主流框架快 50-150 倍 | 🇨🇳 完整支持 A 股规则 | 🎯 极简 API

🏆 核心优势

⚡ 极致性能：秒级完成大规模回测

• 53万行数据仅需 0.4 秒（Backtrader 需要 30-60 秒）
• Rust 底层 + Polars 高效数据处理
• 零拷贝数据传输，原生数组操作
• 比 VectorBT 快 5-10 倍，比 Backtrader 快 100+ 倍

🇨🇳 A 股专业化：唯一完整支持 A 股规则的开源框架

• ✅ 自融资约束：买入金额 ≤ 卖出金额（不能加杠杆）
• ✅ 涨跌停限制：涨停不能买，跌停不能卖
• ✅ T+1 交易：内置 A 股交易机制
• ✅ 停牌处理：自动跳过停牌日，延迟换仓
• ✅ 多时间点换仓：支持日内多次调仓（09:31, 14:00 等）

🎯 创新功能：多周期持仓 + 灵活换仓模式

• 固定换仓 (mode="fixed")：定期换仓，适合短期信号
• 滚动换仓 (mode="rolling")：滑动平均信号，平滑波动，降低换手率
• 多周期持仓 (holding_period)：支持 1天、5天、10天等固定持仓周期
• 灵活组合：两个参数可同时使用，满足不同策略需求

💻 极简 API：一行代码完成复杂回测

# ATRS：一行代码
result = backtest(df, mode="rolling", holding_period=5)

# Backtrader：需要几十行配置
cerebro = bt.Cerebro()
cerebro.addstrategy(MyStrategy)
cerebro.adddata(data)
cerebro.broker.setcash(100000)
...

✨ 特性

• 🚀 极致性能：Rust 实现，比 Python 快 50-150 倍
• 📊 Polars 集成：零拷贝数据传输，支持大规模数据
• 🔌 插件化架构：可扩展的数据源、执行引擎、输出器和分析器
• 🇨🇳 A 股规则：内置自融资约束、涨跌停限制、满仓运行
• ⏱️ 高频支持：支持日内多个时间点换仓
• 💰 费用模型：支持自定义买卖费率
• 📅 多周期持仓：支持固定持仓周期（1天、5天、10天等）
• 🔄 灵活换仓：支持固定换仓和滚动换仓两种模式

📦 安装

pip install atrs

或从源码编译：

git clone https://github.com/yourusername/atrs.git
cd atrs
maturin develop --release

🚀 快速开始

基础回测（1日持仓）

import polars as pl
from atrs import backtest

# 准备数据
data = pl.read_csv("factor_data.csv")

# 运行回测
result = backtest(data, limit=True)

# 查看结果
pos_df = result['pos']  # 持仓详情
ret_df = result['ret']  # 每日收益

# 计算累计收益
total_return = (1 + ret_df['long']).product() - 1
print(f"累计收益: {total_return:.2%}")

多周期持仓回测

from atrs import backtest

# 5日持仓周期，含交易费用
result = backtest(
    data,
    limit=True,
    buy_fee=0.0003,        # 买入费率 0.03%
    sell_fee=0.0013,       # 卖出费率 0.13%（含印花税）
    holding_period=5       # 每5个交易日换仓
)

# 查看扣除费用后的收益
ret_df = result['ret']
total_return = (1 + ret_df['long']).product() - 1
print(f"累计收益（5日持仓）: {total_return:.2%}")

# 对比不同持仓周期
for period in [1, 5, 10]:
    result = backtest(data, holding_period=period, buy_fee=0.0003, sell_fee=0.0013)
    ret = (1 + result['ret']['long']).product() - 1
    print(f"{period}日持仓: {ret:.2%}")

滚动换仓回测（滑动平均信号）

from atrs import backtest

# 使用最近5天信号的加权平均作为target_weight
result = backtest(
    data,
    limit=True,
    buy_fee=5e-4,
    sell_fee=10e-4,
    holding_period=5,
    mode="rolling"  # 启用滚动换仓模式
)

# 对比不同换仓模式
for mode in ["fixed", "rolling"]:
    result = backtest(data, holding_period=5, mode=mode)
    ret = (1 + result['ret']['long']).product() - 1
    print(f"{mode}模式: {ret:.2%}")

滚动换仓优势：

• 📉 平滑信号波动：减少噪音干扰
• 💸 降低换手率：节省交易成本
• 🎯 适合持续性信号：发挥因子稳定性

📋 数据格式

输入数据必须包含以下列：

列名	类型	说明
date	str	日期 (YYYY-MM-DD)
time	str	时间 (HH:MM:SS)
asset	str/int	资产代码
price	float	当前价格
prev_close	float	昨日收盘价
open	float	开盘价
close	float	收盘价
target_weight	float	目标权重
limit	float	涨跌停标记（可选，>0 表示受限）

🔧 API 参考

backtest(weight_df, limit=True, buy_fee=0.0, sell_fee=0.0, holding_period=1, mode="fixed")

超高速回测引擎（支持多周期持仓、灵活换仓模式和费用）。

参数：

• weight_df: Polars DataFrame，输入数据
• limit: bool，是否启用涨跌停限制（默认 True）
• buy_fee: float，买入费率（默认 0.0）
• sell_fee: float，卖出费率（默认 0.0）
• holding_period: int，持仓周期（交易日数），默认 1（每日换仓）
• mode: str，换仓模式，"fixed"（固定换仓）或 "rolling"（滚动换仓），默认 "fixed"

返回：

{
    'pos': DataFrame,  # 持仓详情
    'ret': DataFrame   # 每日收益
}

示例：

# 1日持仓（每日换仓）
result = backtest(data, holding_period=1)

# 5日持仓（每5个交易日换仓）
result = backtest(data, holding_period=5, buy_fee=0.0003, sell_fee=0.0013)

# 10日持仓
result = backtest(data, holding_period=10)

# 滚动换仓（5日持仓 + 滚动模式）
result = backtest(data, holding_period=5, mode="rolling")

# 组合使用：5日持仓 + 滚动换仓 + 费用
result = backtest(data, holding_period=5, mode="rolling", buy_fee=0.0003, sell_fee=0.0013)

bt(weight_df, period="1d", buy_fee=5e-4, sell_fee=10e-4)

完整回测引擎（支持持仓周期和费用，性能略低于backtest()）。

💡 推荐：优先使用 backtest() 函数，它已经支持所有功能且性能更优。

参数：

• weight_df: Polars DataFrame，输入数据
• period: str，持仓周期，如 "1d", "5d", "10d"
• buy_fee: float，买入费率（默认 0.05%）
• sell_fee: float，卖出费率（默认 0.1%，含印花税）

返回： 同 backtest()

📊 输出说明

持仓详情 (pos)

列名	说明
date	日期
time	时间
asset	资产代码
price	价格
forward_ret	向前收益率
target_weight	目标权重
limit	涨跌停标记
avail_sell	可卖出权重
beg_weight	期初权重
chg_weight	目标权重变化
change_weight	实际权重变化（经约束调整）
real_weight	实际持仓权重
end_weight	期末权重（含收益）

每日收益 (ret)

列名	说明
date	日期
long	当日收益率（已扣除费用）

🎯 A 股规则支持

1. 自融资约束

• 买入金额 ≤ 卖出金额（不能加杠杆）
• 首日建仓不受限制
• 后续交易日严格执行约束

2. 涨跌停限制

• 涨停时不能买入
• 跌停时不能卖出
• 通过 limit 列控制

3. 满仓运行

• 每次调仓后自动归一化权重
• 确保总仓位始终为 100%

4. 首日逐步建仓

• 首日目标权重分摊到各个时间点
• 确保首日结束时达到满仓

5. 多周期持仓

• 支持固定持仓周期（1天、5天、10天等）
• 到期日统一换仓，期间保持持仓不变
• 停牌或涨跌停时跳过换仓，继续持有
• 基于交易日索引判断换仓日，即使一天有多个时间点也能正确工作

6. 滚动换仓

• 通过 mode="rolling" 启用滚动换仓模式
• 使用最近n天信号的加权平均作为target_weight（n由holding_period决定）
• 平滑信号波动，降低换手率
• 按 (asset, time) 分组计算过去n天的同一时间点信号之和
• 性能开销仅约10%，完全可接受

🔌 插件化架构

ATRS 采用插件化设计，支持扩展自定义功能。

详见 CONTRIBUTING.md 了解如何贡献代码。

📈 性能对比

⚡ 超高速引擎 vs 主流框架

框架	语言	53万行数据回测时间	相对速度
ATRS (超高速引擎)	Rust + Polars	0.4s ⚡⚡⚡	1x (基准)
VectorBT	Python+Numba	2-5s	5-12x 慢
Qlib	Python+C++	5-10s	12-25x 慢
Zipline	Python	20-40s	50-100x 慢
Backtrader	Python	30-60s	75-150x 慢
Rqalpha	Python	15-30s	38-75x 慢

测试环境：MacBook Pro M3, Apple Silicon

超高速引擎优化技术

我们引入了全新的超高速回测引擎，通过以下优化技术实现显著性能提升：

• ✅ 零 DataFrame 循环操作
• ✅ 索引代替 String (减少 90% 内存)
• ✅ 紧凑数据结构 (cache-friendly)
• ✅ 预分配内存 (零动态 alloc)
• ✅ 多周期持仓支持（固定持仓模式）
• ✅ 滚动换仓支持（mode="rolling"，Polars over窗口函数）

数据规模	原始引擎	超高速引擎	提升倍数
半年数据 (533K行)	1.56s	0.35s	4.5x ⚡⚡⚡
5年数据预估	~9.4s	~2.1s	4.5x ⚡⚡⚡

结果一致性: 两种引擎收益完全一致 (误差 < 1e-16) ✅

多周期持仓性能:

• 1日持仓: 0.389s (基准)
• 5日持仓: 0.356s (提速 1.09x)
• 10日持仓: 0.352s (提速 1.11x)

滚动换仓性能:

• 无滚动: 0.371s (基准)
• 3天滚动: 0.432s (+16.3%)
• 5天滚动: 0.404s (+8.8%)
• 10天滚动: 0.397s (+6.9%)
• 平均开销: 10.7% (完全可接受) ✅

详见 PERFORMANCE_OPTIMIZATION.md

📝 示例

查看 tests/test_engine_with_real_data.py 获取完整示例。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License