pypto-pitfalls

PyPTO 常见陷阱

1. 运算符规则（最高频错误）

+ *：标量任意位置。- /：tensor 必须在左。函数调用：第一参数必须 Tensor。

1.0 + x            # OK（__radd__）
1.0 - x            # CRASH（__rsub__ 未实现）
1.0 / x            # CRASH（__rtruediv__ 未实现）
pypto.add(1.0, x)  # CRASH（函数调用标量在前）

# 1 - x 正确写法
x * (-1.0) + 1.0   # 推荐

# 标量之间用 Python 运算
neg_delta = -delta  # OK（delta 是闭包 float）

2. clamp / min(x, d) 实现

pypto.clamp 不可用。min(x, d) 用双重取反：-max(-x, -d)。pypto.minimum(x, 0.0) 可用。

# min(abs_diff, delta) — delta 是闭包 float
neg_abs = pypto.mul(abs_diff, -1.0)
clipped = pypto.mul(pypto.maximum(neg_abs, -delta), -1.0)  # = min(abs_diff, delta)

Huber Loss 完整模式（必须用 clamp，不能简化）：

diff = predictions - targets
abs_diff = pypto.abs(diff)
neg_abs = pypto.mul(abs_diff, -1.0)
clipped = pypto.mul(pypto.maximum(neg_abs, -delta), -1.0)  # min(|d|, delta)
half_sq = clipped * clipped * 0.5
loss = half_sq + abs_diff - clipped  # 完整 Huber 公式
total = pypto.sum(loss, dim=0, keepdim=True)
output[:] = total / flat_size

3. 工厂函数

标量参数（eps、slope、margin 等）必须作为工厂函数参数通过闭包传入 kernel。

3D+2D matmul 时，forward 展平后传展平维度 nm=N*M 给工厂，不要分别传 N、M。

4. matmul K > 65535

用逐元素乘法 + pypto.sum(a * b_broadcast, dim=1) 替代。forward 中 B.reshape(1, -1) 使其可广播。

5. 距离度量必须 sqrt

sum(diff*diff) 是平方距离，不是 L2 距离。TripletMarginLoss 等必须 pypto.sqrt(sum_sq + eps)。

6. tile rank = tensor rank

set_vec_tile_shapes 参数个数必须等于被操作 tensor 的 rank。2D tensor 用 2D tile。

6.1 盲抄 tile 常量（尤其 16384）

示例里的 16384/8192 是经验候选，不是固定答案。必须按当前 shape 和归约维重算。

• 常见误用：输入 (128, 4096) 却写 set_vec_tile_shapes(1, 16384)。
• 更合理候选：set_vec_tile_shapes(4, 4096)（归约轴不浪费，且 batch 并行更高）。

要点：

• 优先避免明显 tile[i] > shape[i] 的“预算浪费”。
• 示例代码只能借结构，不能照抄 shape/tile 数字。

6.2 把“少分段”误读成“归约轴越大越快”

“连续搬运达阈值后再调归约轴”是二级目标，但不是“归约轴 tile 越大越快”。

• 常见误用：直接写 tile_hidden = hidden，追求归约轴一次覆盖。
• 典型后果：UB/OoOSchedule 报错（即使语义正确也无法编译）。

正确做法：

• 先满足 prod(tile_shape) <= 16384 与 auto_tiles <= 2048。
• 若出现 UB/OoOSchedule 报错，优先降档：16384 -> 8192 -> 4096。
• 若 auto_tiles > 2048，优先改为 loop 分块，不要硬塞更激进 tile。
• 先让连续搬运达到约 1KB（经验阈值），再在达标候选里做归约轴甜点比较（常试 16/32/64）。