py-alpha-lib-private 0.3.7

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 等截面算子要求 groups >= 2。
• flags — 位标志：
  • FLAG_SKIP_NAN (1)：滚动窗口中跳过 NaN。
  • FLAG_STRICTLY_CYCLE (2)：窗口未填满前返回 NaN（与 pandas rolling() 默认行为一致）。
  • 用 | 组合：flags=FLAG_SKIP_NAN | FLAG_STRICTLY_CYCLE

set_ctx 只更新传入的字段，其它字段保持当前值。要恢复默认 (groups=0, flags=0) 调用 alpha.reset_ctx()。

如需只算某一段，请在调用前自行切片输入数组（如 alpha.ts_ma(data[start:end], 3)）。

NaN 处理合约（所有滑窗算子）

输入条件	默认	FLAG_SKIP_NAN	FLAG_STRICTLY_CYCLE	两者同时
periods == 0	全 NaN（除累计语义算子）	全 NaN	全 NaN	全 NaN
当前位置是 NaN	NaN	NaN	NaN	NaN
窗口含 NaN（当前有效）	NaN	跳过窗口里的 NaN，对剩余有效值算	NaN	有效值数 < periods → NaN
i + 1 < periods（窗口未填满）	partial 输出	partial 输出	NaN	NaN

FLAG_SKIP_NAN 用 fixed-time-slot 语义：窗口固定 periods 个时间槽，里面的 NaN 被跳过。 不是 "expand-window 找最近 N 个有效值"。

少数算子有特殊"最少有效值"门槛：var/stddev/zscore ≥ 2，skewness ≥ 3，kurtosis ≥ 4， 不满足时仍返回 NaN。

非滑窗算子（ts_ema / ts_lwma / ts_dma / ts_sma / ts_sumbars / ts_ref / ts_barslast 等） 有自己的 NaN 语义，详见各算子文档。

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（fixed-time-slot：窗口里跳过 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 3.   4.5  5.   6.   7.   8.   9. ]
# i=2 当前是 NaN ⇒ NaN；i=3 窗口 [2,NaN,4] valid [2,4] mean=3.0；
# i=4 窗口 [NaN,4,5] valid [4,5] mean=4.5；之后窗口无 NaN，恢复正常。

命名规范

• 时序算子（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 等）无前缀

数据布局：扁平化的一维数组 [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）共创。