pyqcu-report

Files (3)

• AGENTS.md
• SKILL.md
• beamer_pdf_to_pptx.py · scripts/

SKILL.md (first lines)

# pyqcu-report — PyQCU 科研汇报生成

把仓库中的技术报告、源码、tag 数据和历史报告整理成一套内容一致、证据可追溯的
横版汇报 PDF、PPTX 和竖版讲稿。

## 核心原则

1. **横版与竖版职责分离**
   - 横版 PDF 负责公式、算法、流程图和数据图，文字只做解释。
   - 竖版讲稿负责完整叙事、公式含义、时间控制、风险和问答，不重复横版所有细节。
2. **统一视觉但不过度装饰**
   横版结构元素统一使用黑/灰/白，移除标题线、圆角框、色块、彩色 bullet 和装饰边框；
   饱和颜色只允许出现在真实数据图中。标题、页脚、算法和公式依靠字体层级与留白分组。
3. **证据优先**
   - 老版本文档只作为视觉或历史参考，事实与默认值优先读取当前源码和当前 tag 数据。
   - 性能数字优先读取当前 tag 对应的 CSV、JSON、combined 记录和生成脚本。
   - `git tag test27` 的精确口径与旧 tag 的实验结果不可混合。
   - 508 报告数据只用于“先前成果/大规模历史测试”页：测试环境为 4 张
     Pre-Wukong DCU、64--1024 MPI ranks。TEST8 c64 在 1024 ranks 记录
     Wilson `3.119x`、Clover `7.193x`；TEST9 c128 为
     `2.211x`、`4.258x`，两组不得混用；
     它不证明当前 Strict-MG 已完成千卡扩展，也不与 test27 速度比混算。
4. **公式和算法是主体**
   复杂算法使用编号公式和单列表格式伪代码；不要把伪代码压成普通段落。
   每个正式公式使用章节化编号（如 `(3.2)`），图和表分别使用 `图 章节.序号`、
   `表 章节.序号`，算法使用 `Algorithm 章节.序号`。
   主体页面应优先填满公式、伪代码、数据流或数据图，不把版面让给背景性段落。
5. **图必须来自真实证据**
   优先使用报告中的原始图表；自制图只能从同一 CSV/JSON 重绘，并注明来源。
   数据图必须给出基线、方向定义、样本数和限制，例如 `R=QUDA/PyQCU`。
6. **字体可投影**
   正文和公式不能靠缩小字体塞入页面。空间不足时删重复说明、合并公式行或增加页数。
   横版推荐正文不低于约 10--11 pt，图内标签保持可辨；竖版讲稿使用一倍半行距。
7. **版式验收是硬闸门**
   XeLaTeX 两遍编译后必须 `Overfull=0`、`Float too large=0`，并渲染全部页面检查
   遮挡、裁切、空白和页脚侵入。
8. **PPTX 与 PDF 同源**
   横版 PDF 作为视觉权威；若交付 PPTX，应从同一版 Beamer PDF 逐页渲染后封装，
   避免 PDF 和 PPTX 出现不同内容或样式。
9. **Strict 与 Legacy 分栏**
   - `test27` 性能链对应 Strict full-coarse MATPC + fused right-FGMRES。
   - 33 点 coarse stencil 属于 Legacy compact-Schur，不能与 Strict 的
     \(X/Y/\widehat Y\) 写成同一个粗算子。
   - Legacy CUDA 的 `local_orthogonalize` 使用 batched reduced QR；
     Strict/reference 的 aggregate CGS 是另一套实现。
   - 不应把 CUDA Graph、cooperative coarsest solve 或完全异步 MPI
     外推到所有 Strict 配置。

## 性能图规范

性能汇报必须多视角作图，不能只放一张总耗时表。正式批次至少包含：总求解时间、相对
QUDA 的加速比、1/2/4 MPI 并行效率、总迭代数、独立真残差，以及 setup/cache 与稳态
solve 的分段成本。Legacy/Strict、c64/c128、格点大小和 rank 数改变时使用分面或独立图，
不把不同口径拼成同一系列。

作图遵守以下规则：

- CSV/JSON 原始记录是唯一数据源；图中数字必须能回溯到源文件和生成命令；
- 同时输出 SVG（报告主用）与 PNG（快速检查），记录生成脚本和数据摘要；
- 一个坐标轴只使用一种单位；标题/轴标题写清指标与方向，如 `R=QUDA/PyQCU`；
- 每个加速比必须同时给出分子/分母的绝对时间、单位和统计量；禁止只展示 `x` 倍；
- 显示样本数、误差条或离散度定义；正式曲线不得用单样本冒充实测；
- 保留 `1.0x` 加速比线和残差阈值线；需要跨数量级时显式使用对数轴；
- 同一后端/算法保持稳定配色；按主指标排序，图内文字满足投影可读性；
- 较大格点与多 MPI 图单独展示，smoke 数据只能在明确标注的 smoke 图中出现；
- 图注必须写明硬件、gauge/RHS、cache identity、精度、variant、rank/grid 和限制。

## 性能简报参数清单

性能页和文字简报必须同时给出可复现实验配方，不能只写“默认配置”或“相同参数”。
每条正式结果至少列出：

- 格子 `X×Y×Z×T`、MPI ranks、4D process grid、进程/rank/设备映射；
- 后端、Legacy/Strict、精度，以及 `mass`、`kappa`、`csw`；
- 调用主功能函数、原生 solver/cycle 入口；Legacy/Strict levels、block/`mg_grid`、
  dof/nvec、restart、coarse max-iter/tolerance、atol、max_iter；
- warmup、正式重复数、实际迭代/cycle/correction 次数、残差口径和独立真残差；
- cache path/identity/hit、gauge/RHS SHA256、设备型号/UUID、PyQCU/QUDA 库 SHA256；
- 计时边界，例如 total solve、steady solve、setup、cache verification/load 或
  residual reconstruction。

会改变算法、收敛或耗时的参数若缺失，该结果只能标为不可比较；可选诊断缺失时写 `None`，
不能用配置值或另一后端结果补齐。图表页脚、表格列或附录必须能追溯到完整参数记录。

## 推荐字体

在 XeLaTeX 中统一配置：

```tex
\setmainfont{TeX Gyre Termes}
\setsansfont{TeX Gyre Heros}
\setmonofont{TeX Gyre Cursor}
\setCJKmainfont{FandolSong-Regular.otf}[
  BoldFont=FandolSong-Bold.otf,
  ItalicFont=FandolKai-Regular.otf
]
\setCJKsansfont{FandolHei-Regular.otf}[BoldFont=FandolHei-Bold.otf]
\setCJKmonofont{FandolSong-Regular.otf}
```

用途：正文 `FandolSong`，标题/页眉 `FandolHei`，强调 `FandolKai`，
英文和数字 `TeX Gyre Termes`，代码 `TeX Gyre Cursor`。

## 工作流程

### Step 1：锁定来源和口径

1. 先读当前源码，再读最近的相关报告；不从记忆重建机制或数值：
   - 当前性能：`docs/report_multigrid_quda_pyqcu_YYYYMMDD.tex`
   - 算法构造：`docs/report_pyqcu_mg_operator_construction_*.tex`
   - CUDA/MPI 实现：`docs/report_pyqcu_multigrid_cuda_*.tex`
   - 历史大规模成果：`docs/张鑫 508应用测试报告-PyQCU/`
   - 会话上下文：`logs/v2026*.txt`
2. 明确数据基线 tag。比较前核对 config/input、phase、真残差、显存和硬件 provenance。
3. 建立 `claim -> evidence -> visual` 清单；每个图表至少记录源文件、生成命令和限制。
4. 分离三类事实：
   - 当前正式性能；
   - 实现机制或历史实验；
   - 尚未验证的扩展方向。

From ZhangXin8069/PyQCU, MIT.

More from ZhangXin8069/PyQCU