Metadata-Version: 2.4
Name: py-alpha-lib-private
Version: 0.2.5
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: numpy>=2
License-File: LICENSE
Summary: Alpha Library: A high-performance rolling window calculation library implemented in Rust with Python bindings. Used for financial data analysis and factor research.
Keywords: financial data analysis,factor research,technical indicator calculation
Author: ElseJJ
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: repository, https://github.com/tic-top/py-alpha-lib

# alpha-lib

高性能量化金融算子库。Rust 实现 + Python 绑定 ([PyO3](https://pyo3.rs/))。

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

## 性能

基于 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 子目录。

## 安装

```bash
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`

  ```python
  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：直接调用

```python
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 代码再运行：

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

```python
# 使用生成的 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 代码：

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

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

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

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

## 基准测试与完整示例

### GTJA Alpha 191

国泰君安 Alpha 191 因子集，190 / 191 已实现，见 [`examples/gtja191/`](examples/gtja191/)：

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

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

### WorldQuant Alpha 101

完整实现 [101 Formulaic Alphas](https://arxiv.org/pdf/1601.00991.pdf)，见 [`examples/wq101/`](examples/wq101/)：

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

```bash
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](python/alpha/algo.md)

### 入门示例

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

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

```bash
python examples/quickstart/usage.py
```

## 开发

环境要求：

- Rust（最新 stable）
- Python 3.11+
- [maturin](https://github.com/PyO3/maturin)

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

### Vibe Coding

借助 LLM 添加新算子时，可把 [算子清单](python/alpha/algo.md) 作为上下文提供。也可参考 skill 文档 [add_algo.md](.agent/skills/add_algo/SKILL.md) 走引导式实现。

本项目由 `Gemini`（通过 [Antigravity](https://antigravity.google/)）与 `Claude`（来自 [tic-top](https://github.com/tic-top/py-alpha-lib)）共创。

