improve-cutile-kernel-perf

name	improve-cutile-kernel-perf
description	Iteratively optimize cuTile kernel performance through systematic profiling, bottleneck analysis, IR comparison, and targeted tuning. Covers tile sizes, occupancy, autotune configs, TMA, latency hints, persistent scheduling, num_ctas, flush_to_zero, and IR-level debugging. Use when asked to "optimize cutile kernel", "improve kernel perf", "tune cutile performance", "make kernel faster", or iteratively benchmark and refine a cuTile GPU kernel in the TileGym project.
version	2026.04.11-alpha
environment	{"IDE":["Claude Code","Cursor (Agent mode)"],"model":["Opus 4.6"]}
requires	["GPU node Blackwell, Hopper and Ampere for benchmarking"]
license	CC-BY-4.0 AND Apache-2.0
metadata	{"author":"TileGym Team <[e-mail]>","tags":["cutile","performance","optimization","kernel","profiling"]}

Iterative cuTile Kernel Performance Optimization

Systematically profile, diagnose bottlenecks, and iteratively tune a cuTile kernel's performance in the TileGym repository.

Instructions

Follow the three phases in order: Setup the environment and baseline, run the Experimentation loop with a tracked log, then iterate The experiment loop until perf goals are met or further gains plateau.

Setup

Work with user to prepare optimization environment:

1. Create a fresh git branch: Propose a branch name, e.g., cutile-perf-<kernel_name>-<date> from current branch. Checkout git checkout -b <branch name>

2. Locate the target kernel:

   • cuTile kernels live under src/tilegym/suites/<suite>/cutile/ or src/tilegym/ops/cutile/
   • Read the kernel file and identify: the @ct.kernel decorated function(s), the launch wrapper (ct.launch() or ct_experimental.autotune_launch()), the @register_impl registration, and current autotune configs (if any)

3. Classify the kernel:

   • Arithmetic Intensity < 10 -> Memory-bound
   • Arithmetic Intensity 10-50 -> Balanced
   • Arithmetic Intensity > 50 -> Compute-bound

   Note: classification is only used to pick the optimization priority order in the experiment loop. The core metric is always latency (ms).

4. Check GPU environment:

   • Ensure a GPU node (Blackwell or Ampere GPU) is available
   • All subsequent benchmark commands should run on the GPU node

5. Study related references:

   • references/optimization-playbook.md: Step-by-step recipes for each optimization (A through J) with before/after code examples
   • references/perf-knobs-catalog.md: Complete catalog of all tunable parameters (TMA, persistent scheduling, occupancy, tile sizes, latency hints, etc.)
   • references/cutile-api-reference.md: cuTile API reference and 18 critical rules
   • references/performance-model.md: Roofline/performance model, bottleneck diagnosis, autotuning
   • references/ir-dump-guide.md: IR dump, analysis, and error diagnosis
   • references/cutile-patterns-reference.md: Common cuTile patterns and conversion quick-reference