[issue4] AllReduce/Reduce-Scatter bitwise 复现性诊断工具

src/code/issue4/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+reports/
+issue4-reproducibility-report.json

src/code/issue4/README-2026.md

@@ -0,0 +1,75 @@
+# Issue 4：集合通信 Bitwise 可复现性诊断工具
+
+`reproducibility_diagnoser.py` 对完全相同的输入重复执行 AllReduce 或
+Reduce-Scatter，并按 `run / call / rank` 保存逐位摘要。发现差异时，报告会给出：
+
+- 首次出现差异的 collective 调用点和 rank；
+- 首个差异元素、差异元素总数；
+- 最大绝对误差和最大相对误差；
+- 后续差异随 run/call 的演化；
+- PyTorch/CUDA/NCCL 版本、GPU 型号和影响 NCCL 选择的环境变量。
+
+## 单卡冒烟验证
+
+NCCL 只在 Linux 版 PyTorch 中提供，Windows 版不含 NCCL。在 Windows 上开发时请在带
+CUDA 透传的 WSL2 里运行。以下命令在仓库根目录执行：
+
+```bash
+# 无依赖（不需要 GPU）：演示 FP32 归约顺序为何会改变结果位模式
+python src/code/issue4/reproducibility_diagnoser.py \
+  --self-test --output reports/issue4-order-demo.json
+
+# 单卡 NCCL 冒烟测试。它验证采集链路，不足以证明多 rank 可复现性。
+torchrun --standalone --nproc-per-node=1 \
+  src/code/issue4/reproducibility_diagnoser.py \
+  --runs 3 --calls 20 --output reports/issue4-single-gpu.json
+
+# 在 run 1 / call 3 / rank 0 注入一个 ULP，验证定位和误差统计链路。
+torchrun --standalone --nproc-per-node=1 \
+  src/code/issue4/reproducibility_diagnoser.py \
+  --runs 2 --calls 8 --inject-difference 1:3:0 --expect-difference \
+  --output reports/issue4-injection.json
+```
+
+`--inject-difference` 只用于工具自测，不能当作 NCCL 不确定性的证据。
+
+## 多卡验收运行
+
+在 Linux 多卡机器上先运行默认配置，再固定关键选择项。每个命令内部都会对
+相同输入执行多轮对照，避免把输入随机性误判成通信差异。
+
+```bash
+# 默认选择逻辑
+torchrun --standalone --nproc-per-node=8 \
+  src/code/issue4/reproducibility_diagnoser.py \
+  --operation all-reduce --shape 1048576 --runs 5 --calls 100 \
+  --output reports/all-reduce-default.json
+
+# 固定 Ring + Simple，关闭 NVLS，减少运行间算法/拓扑路径变化
+torchrun --standalone --nproc-per-node=8 \
+  src/code/issue4/reproducibility_diagnoser.py \
+  --operation all-reduce --shape 1048576 --runs 5 --calls 100 \
+  --env NCCL_ALGO=Ring --env NCCL_PROTO=Simple --env NCCL_NVLS_ENABLE=0 \
+  --output reports/all-reduce-ring-simple.json
+
+# Reduce-Scatter
+torchrun --standalone --nproc-per-node=8 \
+  src/code/issue4/reproducibility_diagnoser.py \
+  --operation reduce-scatter --shape 131072 --runs 5 --calls 100 \
+  --env NCCL_ALGO=Ring --env NCCL_PROTO=Simple \
+  --output reports/reduce-scatter-ring-simple.json
+```
+
+建议逐项改变 `NCCL_ALGO`（Ring/Tree/PAT）、`NCCL_PROTO`
+（Simple/LL/LL128）和 `NCCL_NVLS_ENABLE`，每个配置保存独立 JSON。跨机器复现时还应
+固定 GPU/rank 映射、NCCL/CUDA/驱动版本和拓扑文件。`torch.use_deterministic_algorithms`
+只能约束 PyTorch 可控的本地算子，不能替代对 NCCL 算法、协议与拓扑的固定。
+
+## 报告判读
+
+- `status=bitwise-reproducible`：本次指定配置和运行窗口内未发现位级差异；这不是对所有
+  消息大小、拓扑和并发负载的普遍保证。
+- `status=difference-detected`：查看 `first_difference` 定位首次调用，再用
+  `difference_evolution` 判断误差是否持续或放大。
+- `world_size=1`：只代表工具自检通过，不能形成 NCCL 多 rank 可复现性结论。
+