
名称	tilegym-converting-cutile-to-julia
描述	将cuTile Python GPU内核（@ct.kernel）转换为cuTile.jl Julia等价实现。处理内核语法转换、0索引到1索引转换、广播差异、内存布局（行主序到列主序）、类型系统映射以及启动API差异。在将cuTile Python内核转换、移植或翻译为Julia cuTile.jl，或调试/优化现有Julia cuTile翻译时使用。
开源协议	CC-BY-4.0 AND Apache-2.0 metadata:
作者	“TileGym Team TileGym@nvidia.com” tags: - cutile - julia - conversion - gpu - kernel

cuTile Python → cuTile.jl（Julia）转换

将@ct.kernel Python内核转换为Julia function ... end cuTile.jl内核。

工作流选择

标准转换 → 完整工作流：translations/workflow.md
错误（MethodError、IRError、数值不匹配）→ references/debugging.md
快速参考 → references/api-mapping.md + references/critical-rules.md
测试模式 → references/testing.md

架构

Julia内核是独立的——没有Python桥接，没有pytest集成。Julia子项目位于仓库根目录的julia/，带有自己的Project.toml用于依赖管理。

julia/                          # 独立的Julia子项目
├── Project.toml                # 依赖：CUDA.jl, cuTile.jl, NNlib.jl, Test
├── kernels/                    # cuTile.jl内核实现
│   ├── add.jl                  # ← 基准真相：带有alpha缩放的1D逐元素（张量+张量，张量+标量）
│   ├── matmul.jl               # ← 基准真相：2D分块MMA，标准Julia布局(M,K)×(K,N)→(M,N)
│   └── softmax.jl              # ← 基准真相：3种策略（TMA、在线、分块），使用ct.load/ct.store
└── test/                       # Julia原生测试（使用Test标准库）
    ├── runtests.jl             # 测试运行器入口
    ├── test_add.jl
    ├── test_matmul.jl
    └── test_softmax.jl

基准真相参考：始终查阅julia/kernels/*.jl和julia/test/*.jl获取可编译并通过测试的模式。这些是有效的cuTile.jl代码的规范示例。

说明

分析Python内核：识别模式、形状、数据类型、操作
编写Julia内核 — julia/kernels/<op>.jl，包含cuTile.jl内核和桥接函数
转换内核签名（参见translations/workflow.md 阶段2）
转换内核主体（应用references/api-mapping.md + references/critical-rules.md）
编写Julia测试 — 使用Test标准库 + NNlib.jl进行参考实现的julia/test/test_<op>.jl
注册测试 — 在julia/test/runtests.jl中添加include(...)
验证 — 运行捆绑的验证器：python <skill-dir>/scripts/validate_cutile_jl.py <file.jl>
测试 — 运行julia --project=julia/ julia/test/runtests.jl

完整的转换清单及转换后验证 → translations/workflow.md

⚠️ 主要陷阱

最危险的翻译错误。完整规则（共17条）在references/critical-rules.md中。

#	陷阱	一行修复
1	在Julia中不存在`ct.full()`	使用`fill(val, shape)`、`zeros(T, dims...)`或`ones(T, dims...)`
2	在tile上使用`max(a, b)` → `IRError`	使用`max.(a, b)`（广播点运算）
3	`IRError` / `MethodError`提到`IRStructurizer`	编译器错误 — 向上游提交最小复现示例
4	`ct.launch`参数顺序静默错误	参数是位置式的 — 与内核签名完全匹配
5	使用`order`的`ct.load` — 索引位置错误	`order`会同时重映射形状和索引（关键规则16）

已完成的示例

并排的Python → Julia转换，与julia/kernels/中发布的Julia内核匹配。每个目录包含cutile_python.py（之前）和cutile_julia.jl（之后）。

#	示例	关键模式	何时参考
01	`add`	1D `ct.load`/`ct.store`、alpha缩放、标量广播、`fill`/`zeros`、关键字加载/存储	起点；基本TMA + 逐元素模式
02	`matmul`	`muladd`、TF32转换、带`for`的K循环、2D交错、标准Julia布局、`ct.@compiler_options`	MMA / 张量核心操作
03	`softmax`	持久调度、`for`循环、`gather`/`scatter`、`padding_mode`、多遍	大张量归约模式

这些与julia/kernels/中发布的内核（add.jl、matmul.jl、softmax.jl）匹配。这些示例是简化的教学版本 — 始终查阅julia/kernels/*.jl获取规范、经过测试的实现。

参考文档

类别	文档	内容
工作流	`translations/workflow.md`	完整的转换工作流，包含待办列表、验证循环、清单
规则	`references/critical-rules.md`	cuTile Python → Julia转换的17条关键规则
API	`references/api-mapping.md`	Python↔Julia双向API映射 + 内核模式
测试	`references/testing.md`	Julia原生测试模式、容差、失败诊断
调试	`references/debugging.md`	Julia特定的错误诊断 + IR调试命令
脚本	`scripts/validate_cutile_jl.py`	Julia反模式的静态验证（运行它）
基准真相	`julia/kernels/.jl` + `julia/test/.jl`	代码库中实际可用的实现

环境设置

先决条件 — Julia：此技能需要julia/Project.toml中[compat] julia声明的Julia版本。如果julia --version缺失或较旧，请按照适用于您的操作系统的已验证安装程序说明，从官方Julia网站https://julialang.org/install/安装。一旦julia --version兼容，请继续以下步骤。

然后，从仓库根目录：

# 安装julia/Project.toml中声明的Julia依赖
julia --project=julia/ -e 'using Pkg; Pkg.instantiate()'

# 运行测试
julia --project=julia/ julia/test/runtests.jl

要求：

Julia（最低版本在julia/Project.toml的[compat] julia中声明）
CUDA 13.1+驱动
Blackwell GPU（计算能力10+）
通过julia/Project.toml管理的依赖：CUDA.jl、cuTile.jl、NNlib.jl、Test