external-cannbot-ops-pypto-precision-debug

PyPTO Operator Precision Troubleshooting Skill

This skill focuses onthe user code levelfor precision troubleshooting, providing syntax and logic checks and workaround methods.

Core Positioning

⭐ Scope of Responsibilities

This skill is responsible for：

User code syntax and logic checks
Providing workaround methods and tools
Trying various possible solutions

This skill is not responsible for：

Underlying framework code analysis
Deep root cause localization
Framework bug confirmation

Conclusion determination：

If the workaround is effective → provide a solution
If the workaround is ineffective → report that it may be an underlying framework-level issue

Common Workarounds Quick Reference Table

⚠️ When encountering precision issues, try the following workarounds one by one in priority order. Priority 1 is the default recommended solution.

Priority	Issue Symptom	Workaround Method	Code Example	Reason Explanation
1 ★Recommended	Use the old frontend syntax	Switch to `pypto.frontend.jit`	`@pypto.frontend.jit`	The new frontend is the recommended PyPTO syntax, and the old frontend is no longer maintained, which can avoid multiple known issues
2	view + reshape precision abnormality	Avoid `inplace=True`	`pypto.reshape(tensor, shape, inplace=False)`	inplace=True will incorrectly modify the memory address after view, causing data to point to an incorrect region
3	Precision abnormality after loop unrolling	`unroll_list=[1]`	`pypto.loop(range(n), unroll_list=[1])`	Disable loop unrolling to work around the register copy bug in the RegisterCopy pass
4	Nested loop precision abnormality	`submit_before_loop=True`	`pypto.loop(range(m), submit_before_loop=True)`	Ensure sub-loops are correctly submitted to avoid memory overwrite during parallel execution
5	Specific shape precision abnormality	Adjust shape	Avoid a tail axis of 1, avoid non-divisibility	Specific shapes may trigger boundary cases in Pass inference, causing valid_shape errors
6	Compiler optimization abnormality	`+0.0` technique	`result = compute(...) + 0.0`	Prevent the compiler from over-optimizing and preserve the integrity of computation operations

⭐ Important Note: Use the New Frontend Syntax

It is strongly recommended to use pypto.frontend.jit instead of pypto.jit！

The new frontend (pypto.frontend.jit) is the recommended syntax for PyPTO, and the old frontend (pypto.jit) is no longer maintained. Using the new frontend can avoid many known issues.

Recommended Syntax：

# ✅ 推荐：新前端写法
@pypto.frontend.jit
def my_kernel(
    input_tensor: pypto.Tensor(shape, pypto.DT_FP32),
    output_tensor: pypto.Tensor(shape, pypto.DT_FP32),
):
    ...

# ❌ 不推荐：旧前端写法（已废弃）
@pypto.jit
def my_kernel(input_tensor, output_tensor):
    ...

Troubleshooting Decision Tree

精度问题
    │
    ├─ 步骤 0：前端写法检查
    │   └─ 使用 pypto.jit？ ──是──▶ 切换到 pypto.frontend.jit 重试
    │
    ├─ 步骤 1：用户代码语法检查
    │   ├─ 数据类型正确？
    │   ├─ shape 定义正确？
    │   └─ valid_shape 配置正确？
    │
    ├─ 步骤 2：快速规避方法尝试
    │   ├─ 避免 view + reshape inplace=True
    │   ├─ unroll_list=[1]
    │   ├─ submit_before_loop=True
    │   └─ +0.0 技巧
    │
    ├─ 步骤 3：二分定位（如需要）
    │
    └─ 步骤 4：结论判断
        ├─ 规避方法有效 ──▶ 提供解决方案
        └─ 规避方法无效 ──▶ 报告可能是框架问题

Complete Workflow

Step 0: Check the frontend syntax

⚠️ Highest priority: First check whether the user is using the old frontend syntax!

Check content: Check whether the decorator in the user code is pypto.jit or pypto.frontend.jit

Basis reference：

docs/tutorials/development/compile.md: Official documentation uses @pypto.frontend.jit as the standard syntax
docs/tutorials/introduction/quick_start.md: The quick start example uses @pypto.frontend.jit

If the user uses pypto.jit：

Immediately recommend that the user switch to the new frontend
Show the user a modification example：

# 修改前
@pypto.jit
def my_kernel(input_tensor, output_tensor):
    ...

# 修改后
@pypto.frontend.jit
def my_kernel(
    input_tensor: pypto.Tensor(shape, pypto.DT_FP32),
    output_tensor: pypto.Tensor(shape, pypto.DT_FP32),
):
    ...

Rerun the test to verify accuracy

If the issue is resolved: End troubleshooting and recommend that the user use the new frontend syntax

If the issue is not resolved: Continue to the next step

Phase summary：

## 步骤 0 总结：前端写法检查

### 检查结果
- 使用的前端：[pypto.jit / pypto.frontend.jit]
- 是否切换：[是/否]

### 结论
- [问题已解决 / 需要继续排查]

Step 1: User code syntax check

⚠️ Important: First check whether the user code logic is correct, then try workarounds.

1.1 Data type check

Check item：

Whether the input and output data types are consistent
Whether intermediate calculations require higher precision
Whether implicit type conversion exists

Reference basis: General programming best practices.Note: This check item is a general check method for numerical computation.

Common issues：

Issue	Symptom	Solution
FP16 precision loss	Large numerical calculation error	Use FP32 or adjust the calculation order
Type mismatch	Abnormal calculation results	Ensure types are consistent

1.2 Shape definition check

Check item：

Whether shape is correctly defined
Whether dynamic axes are correctly marked

Reference basis: General programming best practices.Note: This check item is a general check method for tensor programming.

Common issues：

Issue	Symptom	Solution
Shape does not match the actual data	Out-of-bounds or data truncation	Check the shape definition
Incorrect dynamic axis marking	Compilation or runtime error	Check the dynamic axis definition

1.3 valid_shape configuration check

Check item：

Whether the valid_shape parameter is correct during view/reshape
Whether the valid_shape expression is correct in dynamic shape scenarios

Reference basis：

pypto.view API documentation：valid_shape is a parameter of the view method, used to specify the valid data size of the view
pypto.reshape API documentation：valid_shape is a parameter of the reshape method, used to specify the valid data Shape of the output Tensor

Example：

# ✅ 正确：view 时直接传入 valid_shape 参数
tensor_view = pypto.view(tensor, shape=[4, 4], offsets=[0, 0], valid_shape=[2, 4])

# ✅ 正确：reshape 时直接传入 valid_shape 参数
tensor_reshaped = pypto.reshape(tensor, new_shape, valid_shape=valid_shape_expr)

Common issues：

Issue	Symptom	Solution
valid_shape is not set correctly	Boundary data processing error	Correctly pass the valid_shape parameter during view/reshape
valid_shape does not match the actual data	Data truncation or out-of-bounds	Ensure valid_shape is consistent with the actual valid data size

Phase summary：

## 步骤 1 总结：用户代码语法检查

### 检查结果
- 数据类型检查：[正常/异常 - 描述问题]
- Shape 定义检查：[正常/异常 - 描述问题]
- valid_shape 配置检查：[正常/异常 - 描述问题]

### 发现的问题
1. [问题描述1]
2. [问题描述2]
...

### 修复建议
1. [修复建议1]
2. [修复建议2]
...

### 结论
- [问题已解决 / 需要继续排查]

Step 2: Try quick workarounds

⚠️ Important: Try the following workarounds one by one in order of priority, and record the effect of each method.

2.1 Avoid view + reshape inplace=True

Applicable scenario：pypto.view followed by pypto.reshape(inplace=True) causes severe accuracy deviation

Problem symptom: Severe accuracy deviation (96%+ elements exceed tolerance)

Operation：

# ❌ 避免写法
tensor_view = pypto.view(tensor, new_shape, ...)
result = pypto.reshape(tensor_view, final_shape, inplace=True)  # 精度严重偏差

# ✅ 推荐写法
tensor_view = pypto.view(tensor, new_shape, ...)
result = pypto.reshape(tensor_view, final_shape, inplace=False)  # 精度正确