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
- Errors (
CodegenErrors, MethodError, UndefVarError, numerical mismatch) → references/debugging.md
- Quick reference →
references/api-mapping.md + references/critical-rules.md
- Test patterns →
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
- Analyze the Python kernel: identify patterns, shapes, dtypes, operations
- Write Julia kernel —
julia/kernels/<op>.jl with cuTile.jl kernel + bridge function(s)
- Convert kernel signature (see
translations/workflow.md Phase 2)
- Convert kernel body (apply
references/api-mapping.md + references/critical-rules.md)
- Write Julia test —
julia/test/test_<op>.jl using Test stdlib + NNlib.jl for reference
- Register test — add
include(...) in julia/test/runtests.jl
- Validate — run the bundled validator:
python <skill-dir>/scripts/validate_cutile_jl.py <file.jl>
- Test — run
julia --project=julia/ julia/test/runtests.jl
Full conversion checklist with post-conversion verification → translations/workflow.md
⚠️ Top Pitfalls
The most dangerous translation errors. Full rules (18 total) in 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 |
1D ct.load/ct.store, alpha scaling, scalar broadcast, fill/zeros, keyword load/store |
Starting point; basic TMA + element-wise patterns |
| 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 |
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 |
Full conversion workflow with todo list, validation loop, checklist |
| Rules |
references/critical-rules.md |
18 Critical Rules for cuTile Python → Julia conversion |
| API |
references/api-mapping.md |
Python↔Julia bidirectional API mapping + kernel patterns |
| Testing |
references/testing.md |
Julia-native test patterns, tolerances, failure diagnosis |
| Debugging |
references/debugging.md |
Julia-specific error diagnosis + IR debug commands |
| Scripts |
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:
# 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---2name: tilegym-converting-cutile-to-julia3description: 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.4license: CC-BY-4.0 AND Apache-2.05metadata:6 source: https://skillmd.com/skills/nvidia/tilegym-converting-cutile-to-julia7 author: "TileGym Team <TileGym@nvidia.com>"8 tags:9 - cutile10 - julia11 - conversion12 - gpu13 - kernel14---1516# cuTile Python → cuTile.jl (Julia) Conversion1718Convert `@ct.kernel` Python kernels to Julia `function ... end` cuTile.jl kernels.1920## Workflow Selection2122- **Standard conversion** → Full workflow: [`translations/workflow.md`](translations/workflow.md)23- **Errors** (`CodegenErrors`, `MethodError`, `UndefVarError`, numerical mismatch) → [`references/debugging.md`](references/debugging.md)24- **Quick reference** → [`references/api-mapping.md`](references/api-mapping.md) + [`references/critical-rules.md`](references/critical-rules.md)25- **Test patterns** → [`references/testing.md`](references/testing.md)2627## Architecture2829Julia kernels are **standalone** — no Python bridge, no pytest integration. The Julia sub-project30lives in `julia/` at the repo root with its own `Project.toml` for dependency management.3132```33julia/ # Self-contained Julia sub-project34├── Project.toml # Dependencies: CUDA.jl, cuTile.jl, NNlib.jl, Test35├── kernels/ # cuTile.jl kernel implementations36│ ├── add.jl # ← Ground-truth: 1D element-wise with alpha scaling (tensor+tensor, tensor+scalar)37│ ├── matmul.jl # ← Ground-truth: 2D tiled MMA, standard Julia layout (M,K)×(K,N)→(M,N)38│ └── softmax.jl # ← Ground-truth: 3 strategies (TMA, online, chunked) using ct.load/ct.store39└── test/ # Julia-native tests (using Test stdlib)40 ├── runtests.jl # Test runner entry point41 ├── test_add.jl42 ├── test_matmul.jl43 └── test_softmax.jl44```4546**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.4748## Instructions49501. **Analyze** the Python kernel: identify patterns, shapes, dtypes, operations512. **Write Julia kernel** — `julia/kernels/<op>.jl` with cuTile.jl kernel + bridge function(s)523. **Convert** kernel signature (see `translations/workflow.md` Phase 2)534. **Convert** kernel body (apply `references/api-mapping.md` + `references/critical-rules.md`)545. **Write Julia test** — `julia/test/test_<op>.jl` using `Test` stdlib + `NNlib.jl` for reference556. **Register test** — add `include(...)` in `julia/test/runtests.jl`567. **Validate** — run the bundled validator: `python <skill-dir>/scripts/validate_cutile_jl.py <file.jl>`578. **Test** — run `julia --project=julia/ julia/test/runtests.jl`5859Full conversion checklist with post-conversion verification → [`translations/workflow.md`](translations/workflow.md)6061## ⚠️ Top Pitfalls6263The most dangerous translation errors. Full rules (18 total) in [`references/critical-rules.md`](references/critical-rules.md).6465| # | Pitfall | One-line fix |66|---|---------|-------------|67| 1 | `ct.full()` doesn't exist in Julia | Use `fill(val, shape)`, `zeros(T, dims...)`, or `ones(T, dims...)` |68| 2 | `max(a, b)` on tiles → `CodegenErrors` (unsupported `isless`) | Use `max.(a, b)` (broadcast dot) |69| 3 | `IRError` / `MethodError` mentioning `IRStructurizer` | Compiler bug — file upstream with minimal reproducer |70| 4 | Launch arg order silently wrong | `@cuda backend=cuTile blocks=grid kernel(args...)` — args are positional, match kernel signature exactly |71| 5 | `ct.max(t, axis=0)` → `max(...)` | Python `ct.max` is a *reduction* → `maximum(t; dims=1)`; Julia `max` is element-wise |72| 6 | `ct.load` with `order` — index positions wrong | `order` remaps BOTH shape AND index (Critical Rule 16) |73| 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) |7475## Worked Examples7677Side-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).7879| # | Example | Key Patterns | When to Reference |80|---|---------|-------------|-------------------|81| 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 |82| 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 |83| 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 |8485These 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.8687## Reference Documents8889| Category | Document | Content |90|----------|----------|---------|91| **Workflows** | [`translations/workflow.md`](translations/workflow.md) | Full conversion workflow with todo list, validation loop, checklist |92| **Rules** | [`references/critical-rules.md`](references/critical-rules.md) | 18 Critical Rules for cuTile Python → Julia conversion |93| **API** | [`references/api-mapping.md`](references/api-mapping.md) | Python↔Julia bidirectional API mapping + kernel patterns |94| **Testing** | [`references/testing.md`](references/testing.md) | Julia-native test patterns, tolerances, failure diagnosis |95| **Debugging** | [`references/debugging.md`](references/debugging.md) | Julia-specific error diagnosis + IR debug commands |96| **Scripts** | [`scripts/validate_cutile_jl.py`](scripts/validate_cutile_jl.py) | Static validation for Julia anti-patterns (run it) |97| **Ground Truth** | `julia/kernels/*.jl` + `julia/test/*.jl` | Actual working implementations in the codebase |9899## Environment Setup100101**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.102103Then, from the repo root:104105```bash106# Install Julia dependencies declared in julia/Project.toml107julia --project=julia/ -e 'using Pkg; Pkg.instantiate()'108109# Run tests110julia --project=julia/ julia/test/runtests.jl111```112113Requirements:114- Julia (minimum version declared in `julia/Project.toml` under `[compat] julia`)115- NVIDIA driver supporting CUDA 13 (r580+); CUDA.jl downloads the toolkit and `tileiras` artifacts itself116- GPU with compute capability 8.0+ (TileGym CI targets Blackwell)117- Dependencies managed via `julia/Project.toml` (versions pinned in `julia/Manifest.toml`): cuTile.jl 1.x, CUDA.jl 6.3+, NNlib.jl, Test118119CUDA versions follow cuTile.jl and CUDA.jl upstream: use the CUDA.jl version cuTile.jl's compat120allows and the toolchain artifacts CUDA.jl selects by default. Do not pin a CUDA toolkit version121(e.g., via `LocalPreferences.toml`) in this repo.122123Kernels are launched with `@cuda backend=cuTile blocks=grid kernel(args...)`, which needs both124`using cuTile: cuTile` (for the `backend=cuTile` name) and `import cuTile as ct` (for the API) —125see `julia/kernels/*.jl`.