technical-patterns-lab/scripts/README_performance_tests.md

# 性能优化测试脚本说明

本目录包含了用于性能分析和优化验证的测试脚本。

## 测试脚本清单

### 1. `test_performance.py` - 性能基线测试

**用途**: 分析原版代码的性能瓶颈，生成profile报告。

**运行方式**:
```bash
python scripts/test_performance.py
```

**输出**:
- 终端显示性能统计
- `outputs/performance/profile_*.prof` - cProfile分析结果

**测试配置**:
- 小规模: 10只股票 × 300天
- 中等规模: 50只股票 × 500天
- 全量: 108只股票 × 500天

**关键信息**:
- 识别性能瓶颈函数
- 累计耗时和调用次数
- Top 20热点函数

---

### 2. `test_optimization_comparison.py` - 优化对比测试

**用途**: 对比原版和Numba优化版各个函数的性能。

**运行方式**:
```bash
python scripts/test_optimization_comparison.py
```

**输出**:
- 每个优化函数的性能对比
- 加速比和性能提升百分比
- 结果一致性验证

**测试函数**:
1. `pivots_fractal` - 枢轴点检测
2. `pivots_fractal_hybrid` - 混合枢轴点检测
3. `fit_boundary_anchor` - 锚点拟合
4. `calc_fitting_adherence` - 拟合贴合度
5. `calc_boundary_utilization` - 边界利用率
6. `calc_breakout_strength` - 突破强度

**预期结果**:
- 总加速比 > 300x
- 所有输出一致（误差 < 1e-6）

---

### 3. `test_full_pipeline.py` - 完整流水线测试

**用途**: 测试完整的批量检测流程，验证端到端性能提升。

**运行方式**:
```bash
python scripts/test_full_pipeline.py
```

**输出**:
- 原版流水线性能统计
- 优化版流水线性能统计
- 结果一致性验证
- 端到端加速比

**测试内容**:
- 加载全量数据（108只股票 × 500天）
- 运行完整批量检测
- 对比两个版本的输出DataFrame
- 验证所有数值列的一致性

**预期结果**:
- 原版耗时: ~30秒
- 优化版耗时: ~0.1秒
- 加速比: ~300x
- 输出完全一致

---

## 快速测试流程

### 基础验证（快速）

```bash
# 1. 安装numba
pip install numba

# 2. 运行优化对比测试（~10秒）
python scripts/test_optimization_comparison.py

# 3. 查看结果
# 应显示: 总加速比 332x, 所有输出一致
```

### 完整验证（耗时）

```bash
# 1. 运行性能基线测试（~1分钟）
python scripts/test_performance.py

# 2. 运行完整流水线测试（~1分钟）
python scripts/test_full_pipeline.py

# 3. 查看profile结果（可选）
pip install snakeviz
snakeviz outputs/performance/profile_全量测试.prof
```

---

## 测试结果解读

### 性能基线测试

重点关注：
- **pivots_fractal**: 最大瓶颈（~22秒，72%）
- **nanmax/nanmin**: 大量调用开销（~16秒，52%）
- **fit_boundary_anchor**: 次要瓶颈（~6秒，20%）

### 优化对比测试

重点关注：
- **加速比**: 应 > 100x（枢轴点检测）
- **结果一致性**: 所有输出应显示"[OK] 一致"
- **总性能提升**: 应 > 99%

### 完整流水线测试

重点关注：
- **端到端加速比**: 应 > 200x
- **输出一致性**: 所有数值列误差 < 1e-6
- **实际耗时**: 优化版应 < 1秒

---

## 常见问题

### Q: 测试失败，提示 "No module named 'numba'"

**A**: 需要先安装numba：

```bash
pip install numba
```

### Q: 优化对比测试显示 "无法启用优化"

**A**: 检查以下几点：

1. numba是否安装成功
2. `src/converging_triangle_optimized.py` 是否存在
3. Python版本是否 >= 3.7

### Q: 完整流水线测试运行很慢（> 5分钟）

**A**: 可能的原因：

1. **首次运行**: Numba需要JIT编译，第一次会慢
2. **优化未生效**: 检查是否显示"已启用Numba加速"
3. **数据量大**: 全量测试需要处理28,000+个点

解决方法：
- 等待第一次编译完成
- 确认优化版正确导入
- 考虑先用小规模数据测试

### Q: 结果不一致，显示 "[ERR] 不一致"

**A**: 检查以下几点：

1. **误差大小**: 如果 < 1e-6，属于正常浮点误差
2. **Numba版本**: 建议使用 0.56+
3. **NumPy版本**: 确保版本兼容

如果误差很大（> 1e-3），请：
- 检查优化代码是否正确实现
- 运行单元测试逐个函数排查
- 查看profile确认调用路径

---

## Profile结果查看

### 使用snakeviz可视化

```bash
# 安装snakeviz
pip install snakeviz

# 查看profile结果
snakeviz outputs/performance/profile_全量测试.prof

# 浏览器会自动打开，显示交互式火焰图
```

### 使用cProfile内置工具

```bash
# 查看Top 20热点函数
python -m pstats outputs/performance/profile_全量测试.prof

# 进入交互模式后输入：
# sort cumulative
# stats 20
```

---

## 测试数据说明

### 数据规模

- **小规模**: 10只股票 × 300天 = 610个检测点
- **中等规模**: 50只股票 × 500天 = 13,050个检测点
- **全量**: 108只股票 × 500天 = 28,188个检测点

### 数据来源

- 位置: `data/*.pkl`
- 格式: Pickle序列化的字典
- 内容: OHLCV数据 + 股票代码/名称

### 数据处理

- 自动过滤NaN值
- 仅使用有效交易日
- 窗口大小: 240天

---

## 性能优化原理

### Numba JIT编译

Numba将Python代码编译为机器码，消除解释器开销：

```python
# 原版：解释执行，慢
for i in range(n):
    # Python解释器逐行执行
    ...

# Numba优化：编译为机器码，快
@numba.jit(nopython=True)
for i in range(n):
    # 编译为机器码，直接执行
    ...
```

### 优化技巧

1. **预分配数组**: 避免动态扩容
2. **提前终止**: 发现不满足条件立即跳出
3. **缓存编译结果**: `cache=True` 避免重复编译
4. **nopython模式**: 完全编译为机器码

### 为什么加速这么多？

- **枢轴点检测**: 大量嵌套循环 → Numba擅长优化循环
- **NumPy函数开销**: 180万次调用 → JIT编译消除开销
- **纯Python计算**: 二分搜索、统计计算 → 编译为机器码

---

## 相关文档

- `docs/性能优化方案.md` - 详细优化文档
- `docs/性能优化执行总结.md` - 快速总结
- `src/converging_triangle_optimized.py` - 优化实现代码

---

**最后更新**: 2026-01-27