tilegym-converting-cutile-to-julia

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/                          # Self-contained Julia sub-project
├── Project.toml                # Dependencies: CUDA.jl, cuTile.jl, NNlib.jl, Test
├── kernels/                    # cuTile.jl kernel implementations
│   ├── add.jl                  # ← Ground-truth: 1D element-wise with alpha scaling (tensor+tensor, tensor+scalar)
│   ├── matmul.jl               # ← Ground-truth: 2D tiled MMA, standard Julia layout (M,K)×(K,N)→(M,N)
│   └── softmax.jl              # ← Ground-truth: 3 strategies (TMA, online, chunked) using ct.load/ct.store
└── test/                       # Julia-native tests (using Test stdlib)
    ├── runtests.jl             # Test runner entry point
    ├── test_add.jl
    ├── test_matmul.jl
    └── test_softmax.jl

事实依据：始终参考 julia/kernels/*.jl 和 julia/test/*.jl，了解能够编译并通过测试的模式。这些是可正常运行的 cuTile.jl 代码的权威示例。

说明

1. 分析 Python 内核：识别模式、形状、数据类型和操作
2. 编写 Julia 内核——在 julia/kernels/<op>.jl 中编写 cuTile.jl 内核和桥接函数
3. 转换内核签名（参见 translations/workflow.md 的第 2 阶段）
4. 转换内核主体（应用 references/api-mapping.md + references/critical-rules.md）
5. 编写 Julia 测试——使用 Test 标准库 + NNlib.jl 作为参考，编写 julia/test/test_<op>.jl
6. 注册测试——在 julia/test/runtests.jl 中添加 include(...)
7. 验证——运行捆绑的验证器：python <skill-dir>/scripts/validate_cutile_jl.py <file.jl>
8. 测试——运行 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	ct.load 使用 order 时索引位置错误	order 会同时重映射形状和索引（关键规则 16）

完整示例

与已发布的 julia/kernels/ 中 Julia 内核对应的 Python → Julia 并排转换示例。每个目录都包含 cutile_python.py（转换前）和 cutile_julia.jl（转换后）。

#	示例	关键模式	参考时机
01	add	1D ct.load/ct.store、alpha 缩放、标量广播、fill/zeros、关键字形式的 load/store	入门；TMA 和逐元素模式基础
02	matmul	muladd、TF32 转换、使用 for 的 K 循环、2D swizzle、标准 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 满足版本要求后，继续以下步骤。

然后，在仓库根目录执行：

# Install Julia dependencies declared in julia/Project.toml
julia --project=julia/ -e 'using Pkg; Pkg.instantiate()'

# Run tests
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