pyqcu-cpp-qcu-include

Files (2)

• AGENTS.md
• SKILL.md

SKILL.md (first lines)

# cpp/cuda/qcu/include

C++ header files for the CUDA backend. 24 templated headers containing CUDA kernel implementations (kernels are inline in headers).

CUDA/GPGPU production topology is one Python process = one MPI rank = one
device. The headers remain rank-local; cross-device coordination belongs to
MPI. `MultiGpuMultigrid` is a test-only exception. See
[`pyqcu-cuda/SKILL.md`](../pyqcu-cuda/SKILL.md#cuda-production-topology).

## Key Headers

| Header | Purpose |
|--------|---------|
| `define.h` | Parameter index constants, block size — must mirror `pyqcu/cuda/define.py` |
| `include.h` | 系统/第三方头聚合（`cuda*`/`cublas_v2`/`curand*`/`mpi.h`/`chrono`/…），被 `qcu.h:6` 首先包含 |
| `lattice_complex.h` | Complex number arithmetic on GPU |
| `lattice_set.h` | Lattice geometry, grid layout, site indexing, private singleton communicator lifecycle for serial patches |
| `lattice_cuda.h` | CUDA stream management, device utilities |
| `lattice_mpi.h` | MPI halo exchange (blocking `MPI_Sendrecv`) |
| `qcu.h` | Top-level include aggregator |
| `dslash.h` | Dslash dispatch (Wilson vs Clover) |
| `wilson_dslash.h` | Wilson dslash kernel |
| `clover_dslash.h` | Clover dslash dispatch |
| `lattice_wilson_dslash.h` | Wilson dslash implementation |
| `lattice_clover_dslash.h` | Clover dslash implementation |
| `bistabcg.h` / `cg.h` | BiCGStab and CG algorithm kernels |
| `lattice_wilson_bistabcg.h` / `lattice_wilson_cg.h` | Wilson solver wrappers |
| `lattice_clover_bistabcg.h` | Clover BiStabCG solver |
| `lattice_sap.h` | SAP（Schwarz 交替过程）`sap_mask_kernel`/`sap_update_kernel` — 5-stream MG 的平滑器；已被 `qcu.h:20` 与 `lattice_clover_multigrid.h:40` 实际包含 |
| `lattice_clover_multigrid.h` | Clover multigrid V-cycle（5745 行，5-stream architecture） |
| `lattice_multigrid.h` / `multigrid.h` | Multigrid restrict/prolong/coarse-dslash |
| `laplacian.h` / `lattice_laplacian.h` | Laplacian operator |
| `gauss_gauge.h` | Gaussian gauge field generation |

Headers correspond to `.cu` source files in `../src/` that `#include` them and instantiate the templates.

Serial overlap patches under a multi-rank world must use the owning
`LatticeSet::comm`, not `MPI_COMM_WORLD`. Clover and coarse halo paths therefore
use `set_ptr->comm`; newly added halo code must do the same. The singleton
communicator is created only for local grid product one and freed in `end()`.

## 参数与 Strict 槽位

- `define.h` 必须与 `pyqcu/cuda/define.py` 镜像：`_PARAMS_SIZE_=58` 是整个
  `params` 数组长度，`_MG_PARAMS_SIZE_=8` 是每个 coarse-level 描述块的长度。
- `params[54..57]` 依次为 `_MG_USE_GCR_`、`_MG_USE_DEFLATE_`、`_MG_MU_PRE_`、
  `_MG_USE_INIT_GUESS_`；其中 57 是 `fermion_out` 奇半 x0 的 0/1 开关。
- Strict 的 `set_ptrs[60..79]` 按 transition 每四槽存放 `V/raw-Y/Yhat/(X,X^-1)`，
  `set_ptrs[80]` 存放持久 hierarchy；这些槽位不替代
  `params[_SET_INDEX_]` 指向的 `LatticeSet` 槽位。

## Legacy Clover MultiGrid 性能机制（2026-08-25，dev84）

- CUDA Graph 段回放（8 迭代/段）——WSL2 ~300µs/内核执行税的对症解（成本单位是内核个数）
- 零拷贝映射内存标量传递 + 守卫标量内核（mg_give_1beta_rp / mg_give_1alpha /
  mg_give_1omega / mg_give_rx）、单块点积归约
- 粗解热启动 + r0_ref 锚定、SYNC DIET（削减冗余同步）、PROF 剖析计数开关
- `define.h` 同步项：`_MG_USE_DEFLATE_` / `_MG_MU_PRE_` /
  `_MG_USE_INIT_GUESS_` / `_PARAMS_SIZE_=58`

实测收益（V100，`pyqcu/testing/qcu/multigrid/benchmarks/large_volume/report.md`）：粗解向量开销 3246→4ms（~800×）、
V-cycle 156→60ms（2.6×）。

Strict 专用 CUDA kernel 位于 `../src/apply_multigrid_strict.cu`，不是一个额外
头文件；本目录的 `qcu.h` 提供其依赖的公共 CUDA 类型和工具。

From ZhangXin8069/PyQCU, MIT.

More from ZhangXin8069/PyQCU