# TAKT 案例展示：ADX、ATR 和 PSAR 指标（Python `ta` 的移植版）

同一个基准测试的四个级别：原始构建、0 级（构建调优）、1 级（经证明正确的自动优化）和 2 级（工程师人工优化）。四个程序的输出逐位一致。本包提供各级别的可执行程序、原始版本的源代码、数据生成器、预期输出和测量数据。

## 基准测试计算的内容

在同一段 100 万根 K 线的历史数据上进行参数扫描：窗口 7、10、14、20、28 下的 ATR、ADX、+DI、−DI，以及四种配置的 Parabolic SAR。每个序列输出其全部值的校验和。该移植版与 `ta` 0.11.0 逐位一致，包括 numpy 的求和顺序（`tools/ta_reference_check.py`）。

## 测量（TAKT 测试台）

AMD Threadripper PRO 5975WX（Zen 3），在专用核心上的隔离虚拟机中采集用户态时钟周期（vPMU），9 轮交替测量，取中位数。所测文件正是本包中的这些文件。

| 级别 | 构建方式 | 时钟周期（百万） | 加速 | 时间（ms） | 相对 0 级：周期 · 时间 |
|---|---|---:|---:|---:|---:|
| 基线 | `cargo build --release` | 1,376.9 | 1.00× | 503 | — |
| 0 级 | LTO、codegen-units 1、target-cpu x86-64-v3 | 1,248.6 | 1.10× | 463 | 1.00× · 1.00× |
| 1 级 | 编译参数方案 + 经证明正确的自动变换 | 791.4 | 1.74× | 342 | 1.58× · 1.35× |
| 2 级 | 编译参数方案 + 工程师人工优化 | 143.3 | 9.61× | 81 | 8.72× · 5.73× |

作为对比，在同一核心上：Python `ta` 处理 100 万根 K 线约需 208 s；同一算法的 Numba 实现（同样逐位一致）计算耗时 0.335 s，另加 `pandas.read_csv` 的 0.201 s；2 级计算耗时 0.018 s，CSV 解析 0.020 s。详见 `measurements.json`。

## 运行

```sh
python3 tools/gen_ohlc.py 1000000 data/ohlc.csv        # 与测量时相同的数据（会创建 data/）
TAKT_INPUTS=data bin/ta-bench-level2 > out.txt
cmp out.txt expected_stdout.txt                        # 逐字节一致
for l in base level0 level1 level2; do TAKT_INPUTS=data bin/ta-bench-$l | sha256sum; done
```

Linux x86-64（glibc）。0–2 级针对 x86-64-v3 构建（AVX2、FMA、BMI2：Intel Haswell 及更新的处理器，AMD Zen 及更新的处理器）；计算中不使用 FMA。

## 等价性

在上述输入以及另外 60 组不同形态、规模和 CSV 格式的生成数据上，四个程序的输出均一致，其中包括会让程序以 panic 退出的输入。原始版本与 Python `ta` 逐位一致：`tools/ta_reference_check.py data/ohlc.csv bin/ta-dump-base out/`（需要 `pandas`、`numpy`、`ta`）。

## 包内容

- `bin/`：各级别的程序，以及用于与 Python `ta` 交叉核对的 `ta-dump-base`；
- `source/`：原始版本（`ta` 移植版）的源代码，基线和 0 级均由此构建；
- `tools/`：数据生成器、与 `ta` 的交叉核对脚本、用于对比的 Numba 版本；
- `expected_stdout.txt`、`measurements.json`、`SHA256SUMS`、`LICENSE`；
- `README.md`：本文的英文版本；`README.<language>.md`：其他语言版本。

1 级和 2 级的源代码不公开：我们交付的是构建产物。