pyqcu-kupl

Files (2)

• AGENTS.md
• SKILL.md

SKILL.md (first lines)

# pyqcu-kupl — 独立 MPI+OpenMP CPU 后端

## 执行前置

先读取工作目录 `AGENTS.md`、`cpp/kupl/qcu/AGENTS.md` 与本次触及目录的
`AGENTS.md`。该后端独立实现，不 include 或 link `cpp/cuda/qcu`。

## 文件

| 路径 | 用途 |
|---|---|
| `cpp/kupl/qcu/include/kupl/` | 扁平 ABI、`LatticeSet`、几何、CPU 运行时与算子声明 |
| `cpp/kupl/qcu/src/apply_*.cpp` | 与 CUDA QCU 对应的单入口族 C ABI 薄封装 |
| `cpp/kupl/qcu/src/backend.cpp` | `LatticeSet<Real>` 门面、参数校验与 scratch 所有权 |
| `cpp/kupl/qcu/src/lattice_*.cpp` | geometry、halo、Wilson/Clover、solver、Laplacian、Gauss、MG 分域实现 |
| `cpp/kupl/qcu/qcu.map` | 仅导出 40 个 CUDA 兼容 `*Qcu` 符号 |
| `cpp/kupl/qcu/tests/test_kupl.cpp` | c64/c128、1/2/4-rank、canonical layout 与真残差 |
| `cpp/kupl/qcu/tests/test_new_abi.py` | 独立 NumPy/ctypes 差分，覆盖新增 Wilson/Laplacian 入口 |
| `cpp/kupl/qcu/tests/test_multigrid.py` | 1/2-rank Gaussian、restrict/prolong、窄/宽 coarse halo 差分 |
| `pyqcu/testing/kupl/test_dslash_block_mpi.py` | block dslash/Schur/adjoint 的 2-rank 直接全局参考门 |
| `pyqcu/testing/kupl/test_strict.py` | strict coarse/fine MATPC、R-P、持久 V-cycle、FGMRES，1/2/4-rank 与 c64/c128 |
| `pyqcu/testing/kupl/test_legacy_mg.py` | 1/2/4-rank 递归 Clover-MG、deflate 开关、warm/cold 路径与 verify |
| `pyqcu/testing/kupl/kunpeng_runtime.py` | 实际 affinity/sysfs NUMA 探测与 HMPI/OpenMPI、CPU/内存绑定规划 |
| `pyqcu/testing/kupl/test_kunpeng_runtime.py` | 合成双 NUMA、片上内存 offset、线程容量与 CLI JSON 契约 |
| `pyqcu/testing/kupl/kupl_env.py` | MPI-free 环境报告：CPU/NUMA/cgroup、HBM 候选、KUPL 库/变量冲突、真实 MG/BiStabCG 生产命令 |
| `pyqcu/testing/kupl/test_kupl_env.py` | HBM offset/歧义/无 sysfs fail-safe、报告命名/原子写和 CLI 不导入 MPI 的契约 |
| `pyqcu/testing/kupl/test_kunpeng_mpi_binding.py` | 双 rank 实际 cpuset 非空/不重叠门；硬件不足返回 skip 77 |
| `pyqcu/testing/kupl/test_kunpeng_profile_contract.py` | 非鲲鹏主机拒绝鲲鹏 profile，rank 间 profile 不一致快速失败 |
| `pyqcu/testing/kupl/benchmark_runtime.py` | 分离 init、首次 Clover 与 RSS 的库级初始化 A/B |
| `cpp/kupl/qcu/tests/test_failure_modes.py` | 非收敛与 fail-closed 入口的显式失败门 |
| `cpp/kupl/qcu/tests/benchmark_kupl.cpp` | Wilson/Clover Dslash 吞吐与 rank affinity 证据 |
| `pyqcu/testing/kupl/check_abi.py` | KUPL/CUDA C 声明与动态库 40 项导出符号一致性门 |
| `pyqcu/kupl/qcu.py` | `ctypes.CDLL(..., RTLD_LOCAL)` Python 绑定；40 个 ABI 名称均有 Python 包装 |
| `pyqcu/kupl/linear_operator.py` | `KuplLinearOperator` — compact Wilson/Clover Schur apply 与 native whole-solve adapter |
| `pyqcu/kupl/krylov.py` | `KuplBiCGStabDriver` / `KuplCGDriver` — 每次请求只调用一次 C++ solve |
| `pyqcu/kupl/multigrid/` | 统一 KUPL multigrid 入口：`LegacyMultigrid` / `StrictMultigrid`，生命周期为 `setup/solve/close` |
| `pyqcu/testing/kupl/test_kupl_python.py` | PyQCU 参考、Clover、dslash、solver 跨语言门 |
| `pyqcu/testing/simple/kupl_bistabcg.py` | 独立 NumPy 布局转换、KUPL ctypes 求解与真残差 |
| `pyqcu/testing/simple/kupl_multigrid.py` | full-site Galerkin、MG verify、独立真残差 |
| `pyqcu/testing/simple/compare_kupl_*.py` | 同 gauge/RHS 的 KUPL↔QUDA 解对照 |
| `pyqcu/testing/simple/benchmark_kupl.py` | 多次运行 C++ 算子 benchmark 并汇总中位数/MAD |

## ABI 与布局

跨 CUDA/KUPL/Torch 的公共 PyQCU 接口规范以
[`pyqcu-api/SKILL.md`](../pyqcu-api/SKILL.md#三后端统一接口强制规范) 为唯一权威源。
`KuplLinearOperator`、`KuplBiCGStabDriver`、KUPL `Multigrid` 和 `ctypes` ABI 属于后端
适配层；高层调用统一走 `Solver`/`Krylov`、`Multigrid`、`MultigridCache`。新增 KUPL
功能时保持公共参数名、控制对象和返回类型一致；不支持的能力在构造或能力检查阶段失败关闭。

同一 QCU 版本内 identity、gauge、MPI coarse geometry、dtype 和 setup provenance 一致的
Legacy/Strict cache 直接复用，包括 CUDA/Torch 生成的 canonical odd-Schur Legacy cache。
复用前执行统一 manifest 校验，命中后跳过 null-space/Galerkin setup；只有 miss、损坏或
identity 不一致时才重建。

- `params=int32[58]`、`argv=real[8]`、`set_ptrs=int64[100]`。
- `argv[7]=csw`，`kappa=1/(2*mass+8)`，Clover onsite 项
  `T=-0.125*kappa*csw*sum(sigma*F)`。
- `applyCloverQcu`/`applyCloversQcu` 返回 `A=I+T`；后者另返回 `A^-1`。
  `csw=0` 必须精确得到 identity。
- Gauge `[2,3,3,4,X,Y,Z,T/2]`、fermion `[2,4,3,X,Y,Z,T/2]`、
  Clover `[4,3,4,3,X,Y,Z,T/2]` 均为 C-order canonical 布局。
- 外部 fermion 索引必须为 `(parity*12+component)*half_sites+site`；
  外部 Clover 索引必须为 `(row*12+column)*half_sites+site`。
- MPI halo 临时缓冲可 site-major，但进入计算前必须 gather 为局部 `C[12]`，
  结果必须 scatter 回 canonical 外部布局。
- Strict public wrapper 与 raw ctypes ABI 已对齐；回归应交叉比较两条路径，
  当前同输入 L32 解相对差约 `8.3e-8`。若只验证 raw ABI，不得外推为所有公共路径可用。
- 公共 Legacy cache 使用 canonical odd-Schur、parity-compressed-time 布局，KUPL 通过
  `SET_PTRS_LEGACY_LAYOUT=1` 可直接消费 CUDA/Torch 生成的兼容 cache。KUPL 也保留
  历史 full-time cache 路径；两种布局 coarse shape 不同，必须按 manifest 校验
  identity、dtype、coarse geometry 与 layout，禁止按路径或文件大小猜测。

## 并行与绑定

- MPI 负责四维 rank 分解与 face/corner halo；rank 内只使用 OpenMP。
- `KUPL_OMP_THREADS` 显式指定正数时精确采用，不再向 2 的幂取整；未指定时
  将 OpenMP 最大值裁剪到进程初始 CPU affinity 大小。
- `KUPL_NUMA_BIND=1` 按 sysfs cpulist 分配完整 NUMA-local CPU 子集，并尝试
  `KUPL_MEMORY_POLICY=preferred|bind`；此时 MPI 必须使用 `--bind-to none` 且
  不得设置 `OMP_PROC_BIND`/`OMP_PLACES`/`GOMP_CPU_AFFINITY`/`KMP_AFFINITY`，
  否则运行时会在库绑定前压缩可见 cpuset。库会绑定实际 OpenMP team 的每个线程。
- `KUPL_MEMORY_NODE=local+N` 用于独立编号的片上内存 node；
  `KUPL_REQUIRE_MEMORY_BIND=1` 把 `set_mempolicy` 失败改为 fatal，
  `KUPL_TOPOLOGY_REPORT=1` 输出每 rank 的最终 cpuset/node/thread 证据。
- 生产前用 `python -B pyqcu/testing/kupl/kupl_env.py --ranks ... --threads-per-rank ...`
  生成 `logs/kupl_env-vYYYY-MM-DD-HH-MM-SS.txt`。只有 sysfs 中无 CPU 且有内存的
  NUMA 节点对每个 CPU 节点按 `distance` 唯一映射、且 offset 完全一致时才建议
  `local+N`；无候选或不唯一时只建议 `local`。`bind + require=1` 是严格 HBM
  配置，`preferred` 会回退 DDR；最终用 `numastat -p` 或 `/proc/<pid>/numa_maps`
  验证实际页分布。
- 从仓库根 `source ./env.sh` 会导出当前树优先的 `PYTHONPATH`、`PYQCU_ROOT`、
  `PYQCU_KUPL_BUILD_DIR`/`PYQCU_KUPL_LIB` 和保守 KUPL 默认值；显式调用者值优先。
  `cpp/kupl/qcu/libqcu.so` 是构建生成的稳定软链接，指向当前 build 目录中的实际
  `libqcu.so`；Python ctypes 与生产启动器都通过该路径，不直接写死 build 目录。
  批处理命令应在作业内 source，随后使用 `--kupl-lib default`，不要在外层单引号中
  直接展开 `$PYQCU_KUPL_LIB`。
- `PYQCU_KUPL_PROFILE=kunpeng|kunpeng-2numa` 会校验 Linux ARM64 与
  Kunpeng/HiSilicon CPU 标识；profile/topology/oversubscribe 开关在 rank 间必须
  一致，不一致必须在任何提前返回之前由集合归约统一失败。
- HMPI 首选调度器 `--map-by numa --bind-to numa`。HMPI 在 `--bind-to none`
  下可能让部分拓扑集合算法回退，因此库内绑定只作无调度器回退。
- 默认不设置 `OMP_PROC_BIND=close/spread`；只在稳定独占 cpuset 上做同题 A/B。
  短 OpenMP 并行区的历史回退证据禁止把该设置写成通用默认。
- `KUPL_FUSED_BICG_DOTS=0` 可回退 BiCGStab `(t,t)`/`(t,s)` 成对归约；
  `KUPL_HUGEPAGE=1` 只对大型内部 scratch 发 `MADV_HUGEPAGE` advice。
- Clover cache 默认要求 gauge 内容在 set 生命周期内不可变。原地改写同一地址时
  必须 `KUPL_DISABLE_CLOVER_CACHE=1`，强制刷新 gauge halo 和目标 parity inverse。
- 调度器已提供 NUMA-local cpuset 时保持 `KUPL_NUMA_BIND=0`，只设置
  `KUPL_OMP_THREADS`/`OMP_NUM_THREADS`。
- 同节点多 rank 应在 Python/NumPy 输入分配前完成 MPI 或调度器绑定；库内
  `KUPL_NUMA_BIND=1` 发生在 `applyInitQcu`，不能迁移调用方已前触到错误 NUMA
  节点的页。仓库 LIME benchmark/MG driver 会先执行一次私有 prebind lifecycle；
  自定义调用方仍须自行保证顺序。OpenMPI 可用
  `--bind-to numa --map-by ppr:1:numa`。
- 全局点积/范数使用 `MPI_Allreduce`，所有 rank 必须走对称集合操作。
- 大 local-volume dslash 默认启用跨 site SIMD 内点/周期面内核；local
  `half_sites < 65536` 自动回退 scalar。`KUPL_DISABLE_BLOCK_DSLASH=1`
  可做 A/B，`KUPL_BLOCK_DSLASH_MIN_HALF_SITES` 仅用于矩形/阈值回归。

From ZhangXin8069/PyQCU, MIT.

More from ZhangXin8069/PyQCU