py-alpha-lib-private 0.2.5

Alpha Library: A high-performance rolling window calculation library implemented in Rust with Python bindings. Used for financial data analysis and factor research.

alpha-lib

高性能量化金融算子库。Rust 实现 + Python 绑定 (PyO3)。

提供因子量化交易中常用的滚动窗口高效计算。

性能

基于 Alpha 101 基准，4000 只股票 × 261 个交易日（每个因子 1,044,000 个数据点）：

实现	因子数	数据加载	计算	总耗时	加速比
pandas	75	31.2s	2,643s	2,675s (44min)	1×
polars_ta	81	0.3s	58s	58s	46×
alpha-lib	101	0.3s	3.6s	3.9s	729×

逐因子耗时与正确性差异详见各 example 子目录。

安装

pip install py-alpha-lib-private

使用

上下文设置

通过 alpha.set_ctx() 控制计算行为：

• groups — 数据数组中的标的数量。每个 group 独立并行处理。cc_rank 等截面算子需要设置。

• start — 计算起始下标（默认 0）。

• end — 计算结束下标（默认 len(data)）。在迭代回测等只需算一段数据的场景下使用。

• flags — 位标志：

  • FLAG_SKIP_NAN (1)：滚动窗口中跳过 NaN。
  • FLAG_STRICTLY_CYCLE (2)：窗口未填满前返回 NaN（与 pandas rolling() 默认行为一致）。
  • 用 | 组合：flags=FLAG_SKIP_NAN | FLAG_STRICTLY_CYCLE

  import alpha
  import numpy as np
  
  data = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], dtype=np.float64)
  
  # 3 周期均线（预热阶段返回部分窗口结果）
  result = alpha.ts_ma(data, 3)
  # [1.  1.5 2.  3.  4.  5.  6.  7.  8.  9.]
  
  # 严格模式：窗口填满前返回 NaN
  alpha.set_ctx(flags=alpha.FLAG_STRICTLY_CYCLE)
  result = alpha.ts_ma(data, 3)
  # [nan nan 2.  3.  4.  5.  6.  7.  8.  9.]
  
  # 跳过 NaN
  alpha.set_ctx(flags=alpha.FLAG_SKIP_NAN)
  data_nan = np.array([1, 2, np.nan, 4, 5, 6, 7, 8, 9, 10], dtype=np.float64)
  result = alpha.ts_ma(data_nan, 3)
  # [1.    1.5     nan 2.333 3.667 5.    6.    7.    8.    9.   ]
  

命名规范

• 时序算子（rolling-window）以 ts_ 开头：ts_ma、ts_sum、ts_delta、ts_rank 等
• 截面算子（cross-sectional，跨 group）以 cc_ 开头：cc_rank、cc_zscore、cc_neutralize 等
• 元素级算子（max/min/abs/log/sign 等）无前缀

示例 1：直接调用

import alpha
from alpha.context import ExecContext
import polars as pl

# ExecContext 会从 securityid/tradetime 自动推断 groups，
# 并自动调用 alpha.set_ctx(groups=...)
data = pl.read_csv("data.csv").sort(["securityid", "tradetime"])
ctx = ExecContext(data)

# 直接对 numpy 数组调用算子
close = data["close"].to_numpy()
ma20 = alpha.ts_ma(close, 20)
rank = alpha.cc_rank(close)        # 截面 rank（groups 已自动配置）
corr = alpha.ts_corr2(close, data["vol"].to_numpy().astype(float), 10)

数据布局：扁平化的一维数组 [stock1_day1, stock1_day2, ..., stockN_dayM]，先按 securityid 再按 tradetime 排序。groups 参数告诉算子库每只股票的数据从哪里开始。

示例 2：因子表达式转译

把因子表达式（GTJA / WQ101 风格的 DSL）转成 Python 代码再运行：

python -m alpha.lang examples/wq101/alpha101.txt

# 使用生成的 Python 代码
from alpha.context import ExecContext
from factors import alpha_001
import polars as pl

data = pl.read_csv("data.csv").sort(["securityid", "tradetime"])
ctx = ExecContext(data)  # 自动推断 groups
result = alpha_001(ctx)

因子表达式 → Python 代码

使用 lang 模块把因子表达式转成 Python 代码：

python -m alpha.lang examples/wq101/alpha101.txt

会读取 examples/wq101/alpha101.txt 中的因子表达式，生成对应的、调用 alpha-lib 的 Python 代码。

转译完成后可能仍需手动调整：

• 修正 float 与 bool 之间的类型转换
• 按需添加上下文设置

基准测试与完整示例

GTJA Alpha 191

国泰君安 Alpha 191 因子集，190 / 191 已实现，见 examples/gtja191/：

指标	值
可计算	190 / 191
计算耗时	~4.5s（4000 只股票 × 261 天）
单因子平均	24ms

python -m examples.gtja191.al 143      # 跑指定因子
python -m examples.gtja191.al          # 跑全部因子

WorldQuant Alpha 101

完整实现 101 Formulaic Alphas，见 examples/wq101/：

• al/ — alpha-lib 实现（Rust 后端）
• pl/ — polars_ta 参考实现（用作正确性 / 性能对比）

examples/wq101/main.py --with-al 1 2 3 4         # 跑指定因子
examples/wq101/main.py --with-al -s 1 -e 102     # 跑全部因子
examples/wq101/main.py --with-pl --with-al -s 1 -e 15  # 与 polars_ta 对比

基准脚本即 examples/wq101/main.py，加上 --with-pl --with-al 可同时跑两个 backend。

已支持的算子

完整函数签名与说明：python/alpha/algo.md

入门示例

examples/quickstart/ 下放了几个最小可运行示例：

• usage.py —— 演示 set_ctx、各种 flag 与常见时序/截面算子
• rank.py —— 截面 rank 与 pandas 对比
• verify_sumif.py —— ts_sumif 行为验证

python examples/quickstart/usage.py

开发

环境要求：

• Rust（最新 stable）
• Python 3.11+
• maturin

# 编译并以开发模式安装
maturin develop --release
cargo build --release
# 运行 Rust 单元测试
cargo test

Vibe Coding

借助 LLM 添加新算子时，可把 算子清单 作为上下文提供。也可参考 skill 文档 add_algo.md 走引导式实现。

本项目由 Gemini（通过 Antigravity）与 Claude（来自 tic-top）共创。