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 (
MethodError, IRError, 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 (17 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 → IRError |
Use max.(a, b) (broadcast dot) |
| 3 |
IRError / MethodError mentioning IRStructurizer |
Compiler bug — file upstream with minimal reproducer |
| 4 |
ct.launch arg order silently wrong |
Args are positional — match kernel signature exactly |
| 5 |
ct.load with order — index positions wrong |
order remaps BOTH shape AND index (Critical Rule 16) |
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, ct.@compiler_options |
MMA / tensor core operations |
| 03 |
softmax |
Persistent scheduling, for loops, gather/scatter, padding_mode, multi-pass |
Large-tensor reduction patterns |
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 |
17 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)
- CUDA 13.1+ driver
- Blackwell GPU (compute capability 10+)
- Dependencies managed via
julia/Project.toml: CUDA.jl, cuTile.jl, NNlib.jl, Test
1---2name: nvidia-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.05---67# cuTile Python → cuTile.jl (Julia) Conversion89Convert `@ct.kernel` Python kernels to Julia `function ... end` cuTile.jl kernels.1011## Workflow Selection1213- **Standard conversion** → Full workflow: [`translations/workflow.md`](translations/workflow.md)14- **Errors** (`MethodError`, `IRError`, numerical mismatch) → [`references/debugging.md`](references/debugging.md)15- **Quick reference** → [`references/api-mapping.md`](references/api-mapping.md) + [`references/critical-rules.md`](references/critical-rules.md)16- **Test patterns** → [`references/testing.md`](references/testing.md)1718## Architecture1920Julia kernels are **standalone** — no Python bridge, no pytest integration. The Julia sub-project21lives in `julia/` at the repo root with its own `Project.toml` for dependency management.2223```24julia/ # Self-contained Julia sub-project25├── Project.toml # Dependencies: CUDA.jl, cuTile.jl, NNlib.jl, Test26├── kernels/ # cuTile.jl kernel implementations27│ ├── add.jl # ← Ground-truth: 1D element-wise with alpha scaling (tensor+tensor, tensor+scalar)28│ ├── matmul.jl # ← Ground-truth: 2D tiled MMA, standard Julia layout (M,K)×(K,N)→(M,N)29│ └── softmax.jl # ← Ground-truth: 3 strategies (TMA, online, chunked) using ct.load/ct.store30└── test/ # Julia-native tests (using Test stdlib)31 ├── runtests.jl # Test runner entry point32 ├── test_add.jl33 ├── test_matmul.jl34 └── test_softmax.jl35```3637**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.3839## Instructions40411. **Analyze** the Python kernel: identify patterns, shapes, dtypes, operations422. **Write Julia kernel** — `julia/kernels/<op>.jl` with cuTile.jl kernel + bridge function(s)433. **Convert** kernel signature (see `translations/workflow.md` Phase 2)444. **Convert** kernel body (apply `references/api-mapping.md` + `references/critical-rules.md`)455. **Write Julia test** — `julia/test/test_<op>.jl` using `Test` stdlib + `NNlib.jl` for reference466. **Register test** — add `include(...)` in `julia/test/runtests.jl`477. **Validate** — run the bundled validator: `python <skill-dir>/scripts/validate_cutile_jl.py <file.jl>`488. **Test** — run `julia --project=julia/ julia/test/runtests.jl`4950Full conversion checklist with post-conversion verification → [`translations/workflow.md`](translations/workflow.md)5152## ⚠️ Top Pitfalls5354The most dangerous translation errors. Full rules (17 total) in [`references/critical-rules.md`](references/critical-rules.md).5556| # | Pitfall | One-line fix |57|---|---------|-------------|58| 1 | `ct.full()` doesn't exist in Julia | Use `fill(val, shape)`, `zeros(T, dims...)`, or `ones(T, dims...)` |59| 2 | `max(a, b)` on tiles → `IRError` | Use `max.(a, b)` (broadcast dot) |60| 3 | `IRError` / `MethodError` mentioning `IRStructurizer` | Compiler bug — file upstream with minimal reproducer |61| 4 | `ct.launch` arg order silently wrong | Args are positional — match kernel signature exactly |62| 5 | `ct.load` with `order` — index positions wrong | `order` remaps BOTH shape AND index (Critical Rule 16) |6364## Worked Examples6566Side-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).6768| # | Example | Key Patterns | When to Reference |69|---|---------|-------------|-------------------|70| 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 |71| 02 | [`matmul`](examples/02_matmul/) | `muladd`, TF32 conversion, K-loop with `for`, 2D swizzle, standard Julia layout, `ct.@compiler_options` | MMA / tensor core operations |72| 03 | [`softmax`](examples/03_softmax/) | Persistent scheduling, `for` loops, `gather`/`scatter`, `padding_mode`, multi-pass | Large-tensor reduction patterns |7374These 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.7576## Reference Documents7778| Category | Document | Content |79|----------|----------|---------|80| **Workflows** | [`translations/workflow.md`](translations/workflow.md) | Full conversion workflow with todo list, validation loop, checklist |81| **Rules** | [`references/critical-rules.md`](references/critical-rules.md) | 17 Critical Rules for cuTile Python → Julia conversion |82| **API** | [`references/api-mapping.md`](references/api-mapping.md) | Python↔Julia bidirectional API mapping + kernel patterns |83| **Testing** | [`references/testing.md`](references/testing.md) | Julia-native test patterns, tolerances, failure diagnosis |84| **Debugging** | [`references/debugging.md`](references/debugging.md) | Julia-specific error diagnosis + IR debug commands |85| **Scripts** | [`scripts/validate_cutile_jl.py`](scripts/validate_cutile_jl.py) | Static validation for Julia anti-patterns (run it) |86| **Ground Truth** | `julia/kernels/*.jl` + `julia/test/*.jl` | Actual working implementations in the codebase |8788## Environment Setup8990**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.9192Then, from the repo root:9394```bash95# Install Julia dependencies declared in julia/Project.toml96julia --project=julia/ -e 'using Pkg; Pkg.instantiate()'9798# Run tests99julia --project=julia/ julia/test/runtests.jl100```101102Requirements:103- Julia (minimum version declared in `julia/Project.toml` under `[compat] julia`)104- CUDA 13.1+ driver105- Blackwell GPU (compute capability 10+)106- Dependencies managed via `julia/Project.toml`: CUDA.jl, cuTile.jl, NNlib.jl, Test
autohandai