pyqcu-qcu-single-tests

Files (2)

• AGENTS.md
• SKILL.md

SKILL.md (first lines)

# QCU/QUDA 单功能测试

## 适用范围

用于维护 `pyqcu/testing/qcu/single_qcu_*.py` 与 `pyqcu/testing/quda/test_*.py`。每个文件只覆盖一个接口或
一个紧密的接口族，输入使用小格点和固定随机种子，先做纯 PyTorch 参考，再按环境选择 CUDA/QUDA
扩展运行。缺少 CUDA、`libqcu.so`、pyquda 或 QIO 资产时必须明确 skip，不能伪造通过。

当前端到端正确性格点统一为 `8x8x8x16`。QCU/QUDA 单功能入口和 simple MPI wrapper
默认必须使用该格点；`16^4`、`8x8x16x16`、`4^4` 只可保留为显式性能、容量、
合成契约或历史数据测试，并必须在报告中标注。

## QCU 生命周期

控制张量固定为 `params=int32[58]`、`argv=real[8]`（槽 7 为 `csw`）、
`set_ptrs=int64[100]`。每次普通单操作事务严格执行：

```text
applyInitQcu(set_ptrs, params, argv)
operation(..., set_ptrs, params)
applyEndQcu(set_ptrs, params)
params[_SET_INDEX_] += 1
```

`params[_SET_PLAN_]` 使用 -2 Laplacian、-1 Gauss、0 Wilson dslash、1 求解器、2 Clover；QCU
数据为 `[2,3,3,4,X,Y,Z,T/2]`、`[2,4,3,X,Y,Z,T/2]`，纯 PyTorch 参考先经
`tools.poooxyzt2oooxyzt` 还原到 `[... ,X,Y,Z,T]`。

单接口数值语义：Wilson dslash 的输入/输出是相反 parity 的 compact 场，C++ 返回未乘 `kappa`
的 hopping；Clover dslash 随后作用 `(I + T_clover)^{-1}`；Laplacian 是内部 `T=1` 的三维颜色场，
gauge 轴为 `[colour_out, colour_in, direction, X, Y, Z]`，三者分别使用
`single_function_common.py` 中的对应参考函数，禁止用 full-site matvec 直接比较。

## QUDA 排布

PyQUDA/QDP 规范场为 `[4,T,Z,Y,X,3,3]`，费米场为 `[2,T,Z,Y,X/2,4,3]`，棋盘奇偶按
`(x+y+z+t)%2`，与 PyQCU 的 t 压缩布局不同。所有对照脚本必须通过
`pyqcu/testing/quda/common.py` 的显式往返转换，禁止直接 reshape 冒充转换。

## 验收

```bash
python pyqcu/testing/qcu/single_qcu_api.py
python pyqcu/testing/qcu/single_qcu_wilson_dslash.py
pytest pyqcu/testing/quda
git diff --check
```

设置 `QCU_STRICT_NUMERIC=1` 才把跨架构数值偏差升级为失败；默认运行仍记录相对误差，便于诊断
不同 GPU/精度下的归一化差异。新增接口或独立项目完成后，必须依照 `pyqcu/testing/AGENTS.md` 整理
测试入口并更新本技能的接口表。

From ZhangXin8069/PyQCU, MIT.

More from ZhangXin8069/PyQCU