smear

name	smear
description	pyqcu.smear 目录的完整生成 skill：stout smearing（Morningstar-Peardon SU(3) 投影）与 Wuppertal 高斯模糊，含数值稳定性处理与 MPI 支持。

CLAUDE.md — pyqcu.smear

Gauge field smearing — spatial smoothing of gauge links to reduce UV noise.

Files

File	Purpose
_stout.py	Stout smearing algorithm (copied/adapted from EasyDistillation's elemental generator)

Exported API

stout_smear(U, nstep=1, rho=0.12, support_parallel=False) → torch.Tensor

Apply nstep iterations of stout smearing with parameter rho.

Algorithm (per step):

1. Compute Q_μ = staple sum for each direction μ: sum over ν≠μ of two 3-link staples (U_ν U_μ U^†_ν forward + U^†_ν U_μ U_ν backward)
2. Project to su(3) algebra: Q ← ρ · Q · U^†, then anti-hermitize: Q ← i/2 · (Q^† − Q) − (1/3) Tr(Q) · I
3. Compute SU(3) projection coefficients f₀, f₁, f₂ via the Morningstar-Peardon method:
   • c₀ = Re(Tr(Q³))/3, c₁ = Re(Tr(Q²))/2
   • θ = arccos(c₀ / (2(c₁/3)^(3/2)))
   • u = √(c₁/3) · cos(θ/3), w = √c₁ · sin(θ/3)
   • f₀, f₁, f₂ expressed in terms of e^{iu}, e^{2iu}, cos(w), sinc(w)
4. Parity handling (when c₀ < 0): f₀ → f₀^, f₁ → −f₁^, f₂ → f₂^* (standard path); NPU path uses real/imag decomposition
5. Update U: U_new = (f₀·I + f₁·Q + f₂·Q²) · U

Numerical stability:

• c₁ clamped to min 1e-15 (prevents c₀_max = 0)
• ratio clamped to [−1+1e-15, 1−1e-15] for arccos domain
• sinc(w) uses Taylor expansion for |w| ≤ 0.05, sin(w)/w otherwise
• Denominator 9u² − w² has 1e-15 epsilon to prevent division by zero

MPI support: When support_parallel=True, MPI boundary data (U_head, U_tail, U_head_tail) is recomputed each step since U changes with each smearing step.

Key Anti-Pattern (Fixed)

The nstep>1 loop previously did not update U between steps — the loop variable was properly rebound but the MPI boundary data was computed outside the loop. Fixed by moving MPI exchange inside the step loop.

Wuppertal Gaussian Smearing (_wuppertal.py, 2026-08-24)

与 stout 同目录的高斯模糊。bug33/34 修复要点（logs/fix-report-2026-08-24.md）：

• wards 含 t 维时系数表须同步扩展为 8 邻居（只改 x/y/z 会漏 t 方向），否则常数场每步 按 (1+2σ) 发散；U=I 不动点判据（单位规范场模糊后仍为单位场，<1e-4）是廉价黄金自检。
• MPI halo 交换每步须重做，且两次 Sendrecv 的 recvtag 必须区分方向——第二次错复用 rank_plus 在 grid 维度=2 时周期退化死锁；边界切片缺方向轴仅在 7v6 等不对称网格显性崩溃。
• 黄金回归判据：np=2/4 常数源 rel≈5e-08（test16 三重不变量守护）。

Data Layout

Gauge field: [3, 3, 4, Lx, Ly, Lz, Lt] = [color, color, direction, x, y, z, t]

Returned tensor has the same shape.

NPU Support

Has per-module force_use_npu flag. On NPU, the parity sign convention for f₀/f₁/f₂ uses explicit real/imag decomposition:

• f₀: imag = −imag (conj)
• f₁: real = −real, imag unchanged (conj + leading minus cancel)
• f₂: real = −real, imag unchanged (same as f₁)