tilegym-converting-cutile-to-julia

--- name: tilegym-converting-cutile-to-julia description: Converts cuTile Python GPU kernels (@ct.kernel) to cuTile.jl Julia equivalents. Handles kernel syntax translation, 0-indexed to 1-indexed conversion, broadcasting differences, memory layout (row-major to column-major), type system mapping, and launch API differences. Use when converting, porting, or translating cuTile Python kernels to Julia cuTile.jl, or debugging/optimizing existing Julia cuTile translations. license: CC-BY-4.0 AND Apache-2.0 metadata: author: "TileGym Team <TileGym@nvidia.com>" tags: - cutile - julia - conversion - gpu - kernel --- # cuTile Python → cuTile.jl (Julia) Conversion Convert `@ct.kernel` Python kernels to Julia `function ... end` cuTile.jl kernels. ## Workflow Selection - **Standard conversion** → Full workflow: [`translations/workflow.md`](translations/workflow.md) - **Errors** (`CodegenErrors`, `MethodError`, `UndefVarError`, numerical mismatch) → [`references/debugging.md`](references/debugging.md) - **Quick reference** → [`references/api-mapping.md`](references/api-mapping.md) + [`references/critical-rules.md`](references/critical-rules.md) - **Test patterns** → [`references/testing.md`](references/testing.md) ## Architecture Julia kernels are **standalone** — no Python bridge, no pytest integration. The Julia sub-project lives in `julia/` at the repo root with its own `Project.toml` for dependency management. ``` 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 ``` **Ground-truth reference**: Always consult `julia/kernels/*.jl` and `julia/test/*.jl` for patterns that compile and pass tests. These are the canonical examples of working cuTile.jl code. ## Instructions 1. **Analyze** the Python kernel: identify patterns, shapes, dtypes, operations 2. **Write Julia kernel** — `julia/kernels/<op>.jl` with cuTile.jl kernel + bridge function(s) 3. **Convert** kernel signature (see `translations/workflow.md` Phase 2) 4. **Convert** kernel body (apply `references/api-mapping.md` + `references/critical-rules.md`) 5. **Write Julia test** — `julia/test/test_<op>.jl` using `Test` stdlib + `NNlib.jl` for reference 6. **Register test** — add `include(...)` in `julia/test/runtests.jl` 7. **Validate** — run the bundled validator: `python <skill-dir>/scripts/validate_cutile_jl.py <file.jl>` 8. **Test** — run `julia --project=julia/ julia/test/runtests.jl` Full conversion checklist with post-conversion verification → [`translations/workflow.md`](translations/workflow.md) ## ⚠️ Top Pitfalls The most dangerous translation errors. Full rules (18 total) in [`references/critical-rules.md`](references/critical-rules.md). | # | Pitfall | One-line fix | |---|---------|-------------| | 1 | `ct.full()` doesn't exist in Julia | Use `fill(val, shape)`, `zeros(T, dims...)`, or `ones(T, dims...)` | | 2 | `max(a, b)` on tiles → `CodegenErrors` (unsupported `isless`) | Use `max.(a, b)` (broadcast dot) | | 3 | `IRError` / `MethodError` mentioning `IRStructurizer` | Compiler bug — file upstream with minimal reproducer | | 4 | Launch arg order silently wrong | `@cuda backend=cuTile blocks=grid kernel(args...)` — args are positional, match kernel signature exactly | | 5 | `ct.max(t, axis=0)` → `max(...)` | Python `ct.max` is a *reduction* → `maximum(t; dims=1)`; Julia `max` is element-wise | | 6 | `ct.load` with `order` — index positions wrong | `order` remaps BOTH shape AND index (Critical Rule 16) | | 7 | Kept Python's `(M, N)` shape → strided loads, 3–8× slower | Reverse dims: Python row-major `(M, N)` = Julia `(N, M)`; reduce over `dims=1` (Critical Rule 7) | ## Worked Examples Side-by-side Python → Julia conversions matching the released Julia kernels in `julia/kernels/`. Each directory contains `cutile_python.py` (before) and `cutile_julia.jl` (after). | # | Example | Key Patterns | When to Reference | |---|---------|-------------|-------------------| | 01 | [`add`](examples/01_add/) | 1D `ct.load`/`ct.store`, alpha scaling, scalar broadcast, `fill`/`zeros`, keyword load/store | Starting point; basic TMA + element-wise patterns | | 02 | [`matmul`](examples/02_matmul/) | `muladd`, TF32 conversion, K-loop with `for`, 2D swizzle, standard Julia layout, tile sizes and `num_ctas` chosen per problem size at launch | MMA / tensor core operations | | 03 | [`softmax`](examples/03_softmax/) | Row-major `(M, N)` → column-major `(N, M)` layout, persistent scheduling, `for` loops, `gather`/`scatter`, `padding_mode`, multi-pass | Large-tensor reduction patterns; any per-row Python kernel | These match the released kernels in `julia/kernels/` (`add.jl`, `matmul.jl`, `softmax.jl`). The examples are simplified teaching versions — always consult `julia/kernels/*.jl` for the canonical, tested implementations. ## Reference Documents | Category | Document | Content | |----------|----------|---------| | **Workflows** | [`translations/workflow.md`](translations/workflow.md) | Full conversion workflow with todo list, validation loop, checklist | | **Rules** | [`references/critical-rules.md`](references/critical-rules.md) | 18 Critical Rules for cuTile Python → Julia conversion | | **API** | [`references/api-mapping.md`](references/api-mapping.md) | Python↔Julia bidirectional API mapping + kernel patterns | | **Testing** | [`references/testing.md`](references/testing.md) | Julia-native test patterns, tolerances, failure diagnosis | | **Debugging** | [`references/debugging.md`](references/debugging.md) | Julia-specific error diagnosis + IR debug commands | | **Scripts** | [`scripts/validate_cutile_jl.py`](scripts/validate_cutile_jl.py) | Static validation for Julia anti-patterns (run it) | | **Ground Truth** | `julia/kernels/*.jl` + `julia/test/*.jl` | Actual working implementations in the codebase | ## Environment Setup **Prerequisite — Julia**: this skill requires the Julia version declared in `julia/Project.toml` under `[compat] julia`. If `julia --version` is missing or older than that, install from the official Julia site at <https://julialang.org/install/> following the verified installer instructions for your OS. Resume below once `julia --version` is compatible. Then, from the repo root: ```bash # 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 ``` Requirements: - Julia (minimum version declared in `julia/Project.toml` under `[compat] julia`) - NVIDIA driver supporting CUDA 13 (r580+); CUDA.jl downloads the toolkit and `tileiras` artifacts itself - GPU with compute capability 8.0+ (TileGym CI targets Blackwell) - Dependencies managed via `julia/Project.toml` (versions pinned in `julia/Manifest.toml`): cuTile.jl 1.x, CUDA.jl 6.3+, NNlib.jl, Test CUDA versions follow cuTile.jl and CUDA.jl upstream: use the CUDA.jl version cuTile.jl's compat allows and the toolchain artifacts CUDA.jl selects by default. Do not pin a CUDA toolkit version (e.g., via `LocalPreferences.toml`) in this repo. Kernels are launched with `@cuda backend=cuTile blocks=grid kernel(args...)`, which needs both `using cuTile: cuTile` (for the `backend=cuTile` name) and `import cuTile as ct` (for the API) — see `julia/kernels/*.jl`.

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本