Index of every page on this site: llms.txt
All skills
nvidia avatar

/tilegym-converting-cutile-to-julia

@81b3b24
by NVIDIA Corporationnvidia/tilegym847 stars
92
Run it yourself

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.

  • 17 files
  • 136 KB
  • CC-BY-4
  • Updated last month
  • GitHub
Use this Skill: https://skilld.dev/gh/nvidia/tilegym/tilegym-converting-cutile-to-julia

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈113 tokens for metadata: the name and description. ≈1.9k when used: this file. ≈20k more on demand in 8 files.

Description uses 5.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈451 characters, or 5.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

cuTile Python → cuTile.jl (Julia) Conversion

Convert @ct.kernel Python kernels to Julia function ... end cuTile.jl kernels.

Workflow Selection

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

⚠️ 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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 81b3b24. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated last month
Other metadata
metadata
{
  "author": "TileGym Team <TileGym@nvidia.com>",
  "tags": [
    "cutile",
    "julia",
    "conversion",
    "gpu",
    "kernel"
  ]
}

README badge

README badge for nvidia/tilegym/tilegym-converting-cutile-to-julia