| name | pyqcd-propagator |
| description | Use when a PyQCD task must solve Wilson or Clover quark propagators with PyQUDA,
choose a source or multigrid setup, construct sequential sources, or implement a
covariant nonlocal displacement; use pyqcd-physics-correlator for the required
contractions and pyqcd-infra for backend, I/O, and MPI planning.
|
| metadata | {"openclaw":{"emoji":"🌀"}} |
pyqcd-propagator — PyQUDA 传播子生产
目的与边界
本技能把 pyqcd-physics-correlator 给出的传播子清单变成可执行的 PyQUDA 作业：
读规范场、初始化格点和 Dirac 算子、构造源、求逆、做残差/形状检查并落盘。它只负责
数据生产，不重新推导 Wick 缩并、不做谱拟合或图表；后者分别转交
pyqcd-physics-correlator、pyqcd-physics-spectrum 和 pyqcd-analysis。
API 细节见 references/solver.md；顺序源和协变位移见
references/sequential-and-covdev.md；完整的重子三点
外围模板见 reference/baryon_3pt_code.md。
求解前契约
在启动 MPI 前写出并保存：
| 项目 | 必须固定 |
|---|
| 组态 | 路径/格式、格点尺寸、规范作用量参数、组态 ID |
| 费米子 | Wilson/Clover、质量或 κ、csw、各向异性、求解容差/最大迭代 |
| 源 | 点/壁/体积/已存传播子、位置、动量相位、smear 参数和源时刻 |
| 目标 | flavor、sink/source 轴序、投影、所需 t_sep、保存格式 |
| 几何 | raw/smeared 规范场用途、covDev 方向/长度、Wilson 线约定 |
轴序、单位、γ 矩阵和反周期边界先按 pyqcd-conventions 固定；显存、后端和进程数
按 pyqcd-infra 的 dry-run 结果执行。源清单不完整时先停，不用默认参数补齐。
最小工作流
- 初始化：通过
core.getMPIComm/getMPIRank/getMPISize 确认 rank；先
core.init(...)，再创建 LatticeInfo，并设定时间边界 t_boundary=-1。
- 读场：从实际格式读入规范场并
toDevice()；PyQCD 的 HYP/Stout API 返回与输入
独立的 smeared 对象；若进入 PyQUDA 或其他可能原地改写的传播子生产 API，先复制
gauge_raw，分别保留 raw 与 smeared 对象。
- 建算子：按质量、Clover 系数、容差和 multigrid 配置 Wilson/Clover Dirac
算子；把所有求逆放入同一
useGauge 上下文。
- 构造并求逆：逐源时刻和源类型调用 point/wall/volume 或传播子源求逆；顺序源
固定 sink、投影和汇动量后再求逆，所有标签随结果保存。
- 检查与落盘：检查 solver residual、shape、dtype、source/sink 轴序和元数据；
优先使用
saveH5 或 pyqcd-infra 的 HDF5 约定，旧 .npy/.npz 仅作兼容回退。
- 收缩交接：只按上游给出的 einsum 收缩；MPI 归约用
gatherLattice，且在
useGauge/gauge.use() 关闭后执行。非 root rank 不写共享输出。
不能破坏的边界
| 风险 | 强制措施 |
|---|
| PyQUDA 局部布局与 PyQCD 全局布局混用 | 每次调用前标注 parity、tzyx、spin/color 轴，并在 gather 前核对形状 |
| smear 改写 raw 场 | PyQCD HYP/Stout 返回独立对象；传给 PyQUDA 或其他可能原地改写的生产 API 前显式 gauge_work = gauge_raw.copy()；raw 仅作 Wilson 线/covDev |
| 归约 API 猜错 | 不调用不存在的 core.allreduce；使用已核实的 gatherLattice |
| 上下文死锁或场串用 | 求逆与 covDev 的 use() 不嵌套，gather 在上下文外 |
| 结果无从复现 | 保存组态、源、参数、后端、MPI 映射、seed、命令、版本和 residual |
验收与交接
最小验收应包括：自由场/合成场小格点的形状与 γ₅ 厄米性检查、一个实际组态的残差
记录、raw/smeared 用途核对，以及重启读写 round-trip。只有这些证据通过，才把数据交给
pyqcd-analysis 或 TMD 链；缺失 GPU/PyQUDA 时只能做静态检查和 CPU smoke，不能声称
真实求逆完成。
常见问题
| 现象 | 诊断方向 |
|---|
| OOM | 先按 pyqcd-infra 重新规划 rank/批次，再降低规模；不静默删任务 |
| 不收敛 | 检查组态完整性、Clover/质量、边界、初始猜测和 multigrid 配置 |
| 收缩结果形状异常 | 回查 parity、tzyx 与 spin/color [sink, source] 轴序 |
| 非 root 写出竞争 | 只让 rank 0 写，并在写前完成全局归约 |
路由
传播子清单与 Wick 结构 → pyqcd-physics-correlator；谱模型 →
pyqcd-physics-spectrum；统计/拟合 → pyqcd-statistics；后端、HDF5、ASCII、VdV/VVV
和 MPI → pyqcd-infra；纯规范场 → pyqcd-gauge；批量运行 → pyqcd-pipeline。
