# BMM_Theory — batch_mat_mul_v3 理论最优实现分析软件

> 目标芯片: Ascend950PR (DAV_3510) | 算子: batch_mat_mul_v3 | 实现: Python 3
>
> 理论依据: 《BMM算子优化分析 v0.98》《MergeBatch_vs_IterBatch分析 v1.1》《BMM尾轮处理策略对比分析 v1.5》

## 这是什么

对任意 BMM (BatchMatMul) case, 回答两个问题:

1. **理论最优实现方案是什么** —— 该走哪个分支 (转Matmul/特殊分支/MergeBatch/IterBatch/StreamK/ASW_Basic), 核间怎么切, 核内 tile 怎么取, Cache/流水怎么配;
2. **这个实现方案在 NPU 上跑得怎么样** —— 各级硬件 (MTE2 搬入 / Cube 计算 / Fixpipe 搬出 / StreamK 归约) 时延多少, 谁是瓶颈, 怎么优化.

与 ops-nn 源码的关系: 源码是"当前实现", 本软件是"理论最优"——用于评估源码方案离理论上限有多远、瓶颈在哪里.

## 快速上手

```bash
# 无需安装, 在项目根目录直接运行 (Python >= 3.8, 仅标准库)

# 模式 1: 方案推荐 —— 输入 case, 输出理论最优方案 + 时延评估
python -m bmm_theory recommend examples/cases_demo.csv -o result.csv --plans plans.csv -v

# 模式 2: 方案评估 —— 输入 case + 自己的实现方案, 评估硬件表现与瓶颈
python -m bmm_theory evaluate examples/cases_demo.csv examples/plans.csv -o eval.csv -v

# 跑单元测试
python -m unittest discover -s tests -v
```

### case 输入 csv 格式

| 列名 | 含义 | 缺省 |
|---|---|---|
| case_id | 标识 | case_行号 |
| batch_a, batch_b | A/B 的 batch 维 | 1 |
| m, n, k | 矩阵维度 | 1 |
| dtype_a, dtype_b, dtype_c | 数据类型 (bf16/fp16/fp8/fp32) | bf16 |
| trans_a, trans_b | 是否转置 | 0 |
| has_bias | 是否有 bias | 0 |
| deterministic_level | 确定性等级 (>=2 禁用 StreamK) | 0 |

`examples/cases_demo.csv` 里有一份覆盖各分支的示例.

### 输出

- `result.csv`: 每行一个 case —— case 参数 + `plan_*` 方案字段 + 时延评估 (`t_mte2/t_mmad/t_fixpipe/t_total` 等, 单位秒) + `bottleneck` 瓶颈级 + `bound_type` Bound 类型 + `advice` 仲裁过程与优化建议;
- `plans.csv` (可选): 纯方案表, 标准结构体 `ImplPlan` 的全部字段, 可直接作为模式 2 的输入.

### 时延模型要点 (读结果前必看)

- **搬入 MTE2 分两段**: `t_mte2_gm` (GM→L1 直读, 按 GM 带宽 1.6TB/s; 无论是否随路驻留 L2 都不再累加 L2→L1) 与 `t_mte2_l2` (数据驻留 L2 后重复读命中, 按 L2 带宽 5.2TB/s);
- **Cube 计算** `t_mmad`: 单核算力 ≈15.2 TFLOPS, MergeBatch 的冗余计算计入;
- **Fixpipe 搬出** `t_fixpipe`: 数据量按 **C 矩阵 dtype** 计 (fp16/fp8 时随路转换、写出量减半); StreamK 中间部分和为防精度丢失按 4B (L0C dtype) 计;
- **总时延** `t_total = max(各级) + t_drain` (双缓冲稳态取最大 + 末级排空暴露);
- **瓶颈交换**: 搬移瓶颈可牺牲算力换搬移效率 (MergeBatch), 计算瓶颈可牺牲搬移换计算效率 (ASW_Basic 切 M/N).

## 目录结构

```
BMM_Theory/
├── README.md                  # 本文档 (用法)
├── bmm_theory/                # 软件包
│   ├── __main__.py            # CLI 入口 (recommend / evaluate)
│   ├── models.py              # 数据模型: BmmCase / ImplPlan(标准结构体) / HardwareTiming
│   ├── hardware/ascend950pr.py# 950PR 硬件参数表 (换芯片只换这份)
│   ├── timing.py              # 时延评估引擎 (MTE2/Cube/Fixpipe/Reduce 模型)
│   ├── constraints.py         # 单一约束源 (生成与校验共用, L0C/L0A/L0B/L1/dValue/核数)
│   ├── router.py              # 分支决策路由 + 重叠区仲裁 + 生成后自检
│   ├── evaluator.py           # 方案评估器 (约束校验 + 瓶颈分析)
│   ├── io_csv.py              # csv 输入输出
│   └── branches/              # 六分支理论脚本 (全部已实现)
│       ├── merge_batch.py     # MergeBatch
│       ├── iter_batch.py      # IterBatch (a/b/c/d 四形态)
│       ├── to_matmul.py       # 转Matmul
│       ├── special.py         # 特殊分支 (K=0/1, AIV 通路)
│       ├── stream_k.py        # StreamK (切K + 归约)
│       └── asw_basic.py       # ASW_Basic (含降核/swizzle/L2分组/尾轮决策)
├── docs/                      # 文档 (架构 + 理论梳理 + 软件测评)
│   ├── 01_软件架构.md
│   ├── 02_分支理论/
│   │   ├── 00_总纲_分支决策树.md
│   │   ├── 01_MergeBatch分支.md
│   │   ├── 02_IterBatch分支.md
│   │   ├── 03_转Matmul分支.md
│   │   ├── 04_特殊分支.md
│   │   ├── 05_StreamK分支.md
│   │   ├── 06_ASW_Basic分支.md      # 尾轮策略已内化为其必要环节
│   │   └── 07_尾轮处理策略.md        # 尾轮完整推导 (参考)
│   └── 03_测评报告/             # 外部测评报告 (v1.0/v2.0 及后续复评)
├── examples/                  # 示例输入输出
└── tests/                     # 单元测试 (固化文档边界 case + issue 回归)
```

**Python 版本**：实测通过 3.12（本机）与 3.14（测评环境）；代码用 `from __future__ import annotations` 兜底注解，逻辑仅用标准库。建议 3.10+。

## 当前进度与路线图

| 分支 | 进入条件 | 方案生成 | 时延评估 | 状态 |
|---|---|---|---|---|
| MergeBatch | ✅ | ✅ | ✅ | 完成 |
| IterBatch (a/b/c/d 四形态) | ✅ | ✅ | ✅ | 完成 |
| 转Matmul | ✅ | ✅ (折叠+粗估) | ✅ (粗估) | 完成, 折叠后 Matmul 精切待 MM 体系打通 |
| 特殊分支 (K=0/1) | ✅ | ✅ | ✅ | 完成 |
| StreamK | ✅ | ✅ | ✅ (含归约) | 完成 |
| ASW_Basic (含降核/swizzle/L2分组/尾轮决策) | ✅ | ✅ | ✅ | 完成, 尾轮已内化 (默认方案B, 周长型A1b) |

## 设计原则

1. **以理论分析文档为准**——源码实现仅作对照, 不作为依据;
2. **参数表与逻辑分离**——换芯片只换 `hardware/` 下的参数表, 分支逻辑不动;
3. **结构体标准化**——`ImplPlan` 是推荐输出与评估输入的统一格式, 字段与理论文档符号一一对应;
4. **可验证**——文档中的典型边界 case 全部固化进 `tests/`, 改动不破结论.