pyqcu-benchmark

Files (3)

• AGENTS.md
• SKILL.md
• qcu-multigrid-20261023.md · references/

SKILL.md (first lines)

# pyqcu/testing/benchmark

Performance benchmarks comparing PyTorch, TileLang, and C++ CUDA backend implementations.

GPU/DCU/GPGPU benchmarks keep one Python process = one MPI rank = one device.
`MultiGpuMultigrid` benchmarks are explicit test-only evidence; do not treat
their launch shape as the production default. See
[`pyqcu-cuda/SKILL.md`](../pyqcu-cuda/SKILL.md#cuda-production-topology).

Legacy-MultiGrid is the QCU default solver and the primary development/debug/
optimization benchmark target. Strict-MultiGrid rows are explicit comparison,
algorithm-reference, or special-fallback evidence unless a task says otherwise.

Legacy hierarchies deeper than two levels emit `MultigridDepthWarning`; Strict
hierarchies deeper than three do the same. The same warning also considers the
global and rank-local lattice after the process grid and parity compression,
the coarsening block, the coarsest volume and whether another stable transition
is possible. Do not treat a warning-only run as a valid multi-level result.
Record native and independently reconstructed true residuals together, and
mark distributed Legacy depth greater than two as unsupported unless a
dedicated regression proves both correctness and benefit.

MPI benchmarks accept only a positive power of two ranks (`1/2/4/8/...`).
Reject every other count before launching MPI or allocating the solver. The
complete 2026-10-23 rank, quick-matrix, true-residual and evidence guidance is in
[`references/qcu-multigrid-20261023.md`](references/qcu-multigrid-20261023.md);
read it before running the QCU MultiGrid matrix.

Do not treat MG cache files as interchangeable by filename or size. CUDA/Torch
Legacy consume the blocked odd-Schur layout with parity-compressed time
(`lonv=[E,e,X,x,Y,y,Z,z,T/2,t]`), while KUPL's native full-time builder emits a
different coarse shape. Validate `lonv/hnn/hdg/sit` shapes against the selected
backend before setup; fail closed on a mismatch. For a prebuilt odd-Schur cache,
the Torch fine operator may use `parity_only=True`, but never enable that mode
while the same operator is still needed to construct a Galerkin hierarchy.

The MPI cache entry is
`python -m pyqcu.testing.simple.mpi.build_full_mg_cache`, not the serial parent
script. It must run every rank through distributed null-vector construction,
assign each rank a disjoint coarse slab, stage only a periodic overlap halo for
local stencil evaluation, write all four tensors through HDF5 MPI-IO owned slabs,
validate every rank slab against the published HDF5, and publish the manifest
atomically. Never root-gather multi-GiB `lonv`; L48 experience also rules out
root assembly of `hnn/hdg/sit`. The
correct `lonv` patch axes are `(2,4,6,8)`, not the last four tensor axes. Record
MPI ranks/grid, per-rank patch extent, slab reconstruction status, and all
global tensor SHA256 values. A 2/4-rank cache is functionally equivalent to the
1-rank reference only when tensor-level relative differences are reported; MPI
reduction order means bitwise SHA equality must not be required across rank
counts.

Identity-safe reuse, QUDA fallback, formal matrix scope, figure/speedup rules,
required recipe fields, and the real-time document ledger are defined in
[`references/qcu-benchmark-contract.md`](references/qcu-benchmark-contract.md).
Read it before launching a formal or multi-backend benchmark. Every speedup must
show absolute numerator and denominator times with units and sample statistics.

正式三方基准的输入、同窗比较、历史证据和不可外推条件见
[`pyqcu-docs/references/extracted-guidance.md`](../pyqcu-docs/references/extracted-guidance.md#5-性能与证据解释)。

Legacy/Strict CUDA MG 的运行时峰值必须用同时覆盖 C++ 原生分配的独立设备级采样器，
不能只报 PyTorch allocator。现有同输入 c64 两级、`nvec=12` 记录中 Legacy solve
峰值为 0.596/1.533/4.113 GiB，Strict 为 0.789/2.326/6.715 GiB
（`8x8x8x16`、`12x12x12x24`、`16x16x16x32`）；`24x24x24x64` Strict 缺失。Legacy 同时是
`n_vcycles=0`，所以只能作为当前实际入口的容量证据。详见
[`docs/legacy_vs_strict_mg_memory_20261023.md`](../../docs/legacy_vs_strict_mg_memory_20261023.md)。
这些 JSON 没有 `device_name`，只能确认总显存 `34,359,345,152` bytes；不能用相同
总量代替物理设备身份。Legacy asset-build 另有 `432,013,312`、`1,591,738,368`、
`4,722,786,304` bytes 的三点峰值，它们是独立 setup 阶段，不能与 Strict 全程峰值
拼成同一阶段比较。

## Files

| File | Purpose |
|------|---------|
| `conftest.py` | Benchmark entry point |
| `env.py` | Benchmark environment configuration |

## 2026-10-23 六版本真实输入基准

正式编排入口为 `pyqcu/testing/benchmark/qcu_six_way.py`，隔离 worker 为
`qcu_six_way_worker.py`。默认输入是真实 LIME 的 `8×8×8×16` 前缀，运行
Torch/CUDA/KUPL × Legacy/Strict、QUDA aligned MG，并额外执行 CUDA Legacy
fine-only 消融。结果与解释见
[`docs/qcu_six_way_benchmark_20261023.md`](../../docs/qcu_six_way_benchmark_20261023.md)。

所有后端的正确性门固定为 `8×8×8×16`，包括 Torch/CUDA/KUPL × Legacy/Strict
六项 QCU-MG；`16×16×16×16` 及更大格点只能用于性能、容量或历史数据验证。
合格批次还必须包含
同输入的 QUDA aligned MG 以及 Torch/CUDA/KUPL/QUDA BiCGStab 边界对照。正式矩阵只用
trace-off，并在进程启动前设置 `QUDA_ENABLE_TUNING=0`；trace-on 只能单独用于诊断。
详细执行与证据口径见
[`references/qcu-multigrid-20261023.md`](references/qcu-multigrid-20261023.md)。

不得由 `levels`、`restart` 或 cycle 配置推断 coarse 已执行。每个 Legacy side 必须读取
`n_vcycles`、`coarse_iters`/`coarse_iterations` 和实际 cycle/correction 计数；多 rank
CUDA 未显式设置 `params[_MG_USE_DEFLATE_]` 时结果为 fine-only，不能标成 coarse MG。

QUDA GCR-MG on the A100 native-LAPACK build was made usable with `nvec=12`,
2 levels, `mg_block=2^4`, and `--no-mma`. MMA failed differently by path: `nvec=24`
exhausted A100 memory, while `nvec=12` requested unsupported coarse color `N=24`.
The working no-MMA L32 comparison uses internal null-vector setup and should be reported
as a GCR-MG entry-point comparison, not as an identical Legacy cycle. L32 medians are
QUDA `0.482426/0.314393/0.287465 s` versus CUDA Legacy
`0.214456/0.219506/0.218343 s` for 1/2/4 ranks; all three pass independent full residuals.

本轮确认的三个硬边界：

- CUDA Legacy 在同一 `LatticeSet` 上连续 cold solve 会污染后续 RHS/状态；正式样本必须
  在计时前重建运行时，重建时间单独记录，不能把后端自报残差当作末次解的正确性证据。
- KUPL Strict 的 public 与 raw ABI 已完成对齐；可用的正式入口应使用
  `--kupl-strict-abi both` 交叉校验两条路径。仍不得只验证 raw ABI 就宣称其他公共
  wrapper 可用，ABI 差异必须 fail closed。
- sm70 QUDA 构建为 `QUDA_QIO=OFF`。缺少共享 QIO null-vector 时，QUDA 只能在同 gauge 上
  自生成 null space；该结果可作同配置算法对照，不能写成 byte-identical null-basis replay。

Capacity-bound residual validation must run after native teardown. End the
`LatticeSet`, close the MG hierarchy, delete cache/asset owners and any bound
method closure that references the hierarchy, run GC/allocator cleanup, then
construct a fresh Clover/operator for the independent full residual. Computing

From ZhangXin8069/PyQCU, MIT.

More from ZhangXin8069/PyQCU