tilegym-cutile-python

cuTile Python プログラミングスキル

cuTile プログラミングのエキスパートとして、cuTile のタイルベースのプログラミングモデルを使った高性能 GPU カーネルの作成を専門としています。このスキルでは、cuTile カーネルの作成、デバッグ、最適化に関する包括的なガイダンスを提供します。

概要

cuTile は、テンソルコアなどの高度なハードウェア機能を自動的に活用する、Python ベースの DSL を備えた NVIDIA GPU 向けの並列プログラミングモデルです。このスキルを使うと、効率的で正確な cuTile コードを作成できます。

このスキルを使用する場面

次の作業が必要な場合に、このスキルを呼び出してください。

• cuTile GPU カーネルをゼロから作成する
• テンソル演算を cuTile 実装に変換する
• cuTile カーネルのコードをデバッグまたは修正する
• パフォーマンス向けに cuTile カーネルを最適化する
• cuTile の API やプログラミングパターンを理解する
• cuTile の実装を検証する
• 利用可能なリファレンスソースから例を探して応用する

呼び出し時に、次の情報を任意で指定できます。

• 対象となるテンソルの形状
• データ型（デフォルト：float16）
• パフォーマンス要件
• 特別な制約

リファレンスドキュメント

cuTile 言語仕様 — https://docs.nvidia.com/cuda/cutile-python。実行モデル、データとメモリのモデル、デバッグ、コンパイル、およびすべての公開演算（load/store、ファクトリー、リダクション、スキャン、行列積、選択、数学関数、ビット演算、比較、アトミック演算、メタプログラミング、クラス、列挙型、オートチューニング）を網羅しています。

実装ガイドライン（guidelines/ ディレクトリ内）：

• 01_implementation_lessons.md - 重要な教訓と実装ルール
• 02_code_generation_rules.md - 具体的なコード生成ルールとパターン
• 03_concepts.md - タイルサイズの制限、メモリ操作、カーネル融合、デフォルトルールなどの基本概念

例

cuTile プログラミングの作業を始める前に、必ず既存の例を検索してください。主要なリファレンスは TileGym です。パッケージに含まれる examples/ ディレクトリは、TileGym でまだ扱っていない演算（畳み込み、プーリング、スキャン、GEMV、4D 行列積、split-k GEMM、group_norm）の例を補完します。

このスキルは、次の2つのインストール環境に対応しています。

• TileGym のチェックアウト内（<repo>/skills/tilegym-cutile-python/、または後方互換性のためのシンボリックリンク経由の <repo>/.agents/skills/tilegym-cutile-python/ / <repo>/.claude/skills/tilegym-cutile-python/）— TileGym の演算は <repo>/src/tilegym/ops/cutile/ にあります。
• その他の場所にインストールされている場合（例：~/.agents/skills/tilegym-cutile-python/、~/.claude/skills/tilegym-cutile-python/、または別のリポジトリ内）— TileGym を ${TILEGYM_SKILL_CACHE_DIR:-~/.cache/tilegym}/TileGym に一度クローンし、その src/tilegym/ops/cutile/ を使用します。

検索順序、ディレクトリ構成、キャッシュとリポジトリのどちらを使うかの判断手順については、examples/tilegym_and_examples_guide.md を参照してください。

実装前に確認すること

複雑な作業や曖昧な作業では、コーディングを始める前に実装方針の選択肢をユーザーに提示してください。これにより、誤った実装方針に労力を費やすのを防げます。

次の種類の作業では確認してください

作業の種類	確認が必要な理由	質問の例
最適化の依頼	「高速化して」には多くの選択肢があります	ボトルネックはどこですか？メモリ帯域律速ですか、演算律速ですか？目標とする高速化率はどれくらいですか？
アーキテクチャの変更	構造に関する決定は全体に影響します	データ並列ですか、モデル並列ですか？永続カーネルですか、標準カーネルですか？
曖昧な演算	同じ名前でも実装が異なります	Flash Attention ですか、標準的な方式ですか？因果的ですか、双方向ですか？グループ化畳み込みですか、深度方向畳み込みですか？
パフォーマンスと正確性のトレードオフ	ユーザーが選択する必要があります	高速化のために TF32 を使用しますか？数学関数を近似しますか？累積精度を下げますか？
制約の不足	目標がなければ最適化できません	対象となるテンソルの形状は？バッチサイズの範囲は？メモリ予算は？

これらのタスクではそのまま実行してください

• 明確で具体的な依頼：「形状 (1024, 1024) の ReLU カーネルを書いてください」
• 再現手順のあるバグ修正：「このカーネルは 42 行目でクラッシュします」
• API に関する質問：「ct.gather の使い方を教えてください」
• 例の適応：「TileGym の softmax を自分の形状に合わせてください」

確認方法

確認が必要な場合：

1. 複数のアプローチがある理由を簡潔に説明します
2. トレードオフとともに、具体的な選択肢を 2～3 個提示します
3. 明らかに最適な選択肢がある場合は、それを推奨します
4. 作業を進める前に、ユーザーに選択を依頼します

例：

Your request "optimize this matmul" could go several directions:

1. **Persistent kernel** - Best for small matrices, faster, more complex code
2. **Tile size tuning** - Moderate gains, minimal code changes
3. **TMA prefetching** - Best for large matrices, requires Hopper+ GPU

I recommend option 2 for a first pass. Which approach would you like?

複雑さの評価：シンプルなワークフローとオーケストレーションワークフロー

実装を始める前に、リクエストの複雑さを評価し、適切なワークフローを選択します。

次の場合はシンプルなワークフロー（以下のステップ 0～6）を使用します：

• 単一カーネルのタスク（例：ReLU、softmax、1 つの matmul）
• 既存カーネルのバグ修正または最適化
• API に関する質問または例の適応
• 明確で単一の操作に関するリクエスト

次のいずれかに当てはまる場合は、Deep Agent オーケストレーションワークフローを使用します：

• 個別のカーネルを必要とする 3 つ以上の異なる操作（例：「attention、FFN、layer norm を含む transformer block を実装する」）
• 入力コードにユーザー定義関数が複数ある（例：custom_activation()、custom_norm()）
• カーネル間にデータ依存関係がある（1 つのカーネルの出力が別のカーネルに入力される）
• forward() に複数のレイヤーがある PyTorch nn.Module
• 明示的な分解の依頼（例：「これを融合カーネルに分解する」）

オーケストレーションが必要な場合は、Deep Agent オーケストレーションワークフローのセクションに従います。それ以外の場合は、以下の手順に進みます。

Deep Agent オーケストレーションワークフロー

3 つ以上のカーネル、カーネル間の依存関係、または複数レイヤーの nn.Module の分解を必要とする複雑なタスクでは、オーケストレーションされたマルチエージェントパイプラインを使用します。メインエージェントはオーケストレーターとして動作し（コーダーではありません）、サブエージェントがリファレンスの読み取りとコード生成を担当します。

パイプライン：Op Tracer（任意）→ Analyzer → Kernel Agents（並列）→ Composer → メインエージェントが検証

ステップごとのワークフロー（ステップ O-0～O-4）、プロンプトテンプレート、エラー処理の詳細については、**orchestration/workflow.md**を参照してください。

オーケストレーションのアーキテクチャ、エージェントの階層、カーネル仕様の形式については、**orchestration/overview.md**を参照してください。

---

手順

cuTile カーネルを記述する際は、以下のステップに従います（単一カーネルタスク向けのシンプルなワークフロー）。

注意：上記の Deep Agent オーケストレーションワークフローを使用する場合は、このセクション全体をスキップしてください。 オーケストレーションワークフローには、独自のステップ（O-0～O-4）があります。両方のワークフローを組み合わせないでください。そうすると、メインエージェントがすべてのリファレンスファイルを読み込み、さらにサブエージェントを起動することになり、コンテキストを浪費します。

ステップ 0: サンプルの検索とリファレンスの参照 (必須)

目的: 既存のサンプルを見つけ、関連するドキュメントを確認する

サンプル検索 (2 段階の戦略):

1. まず TileGym (src/tilegym/ops/cutile/) で類似の cuTile カーネルパターンを検索します。
2. TileGym に該当がない場合は、パッケージ化された examples/ ディレクトリ (このスキルの一部) を検索します。
3. 関連するサンプルファイルを読み、実装パターンを理解します。

複雑なアルゴリズムの変換 (flash attention、fused ops など): 複雑なアルゴリズムを実装する場合は、次の体系的なアプローチに従ってください:

1. PyTorch 実装を分析する: 数学的な演算、データフロー、重要な計算パターン、メモリアクセスパターン、および特別な最適化や制約を理解します。
2. 関連する cuTile のサンプルを調査する: 類似の演算のサンプルを確認します。既存のサンプルには、必要なパターンがそのまま示されていることがよくあります。車輪の再発明をするのではなく、動作するパターンをコピーして適応させてください。
3. cuTile 版を実装する: PyTorch の演算を cuTile プリミティブに対応付け、適切な箇所でカーネルフュージョンを適用し、適切なタイルインデックスとメモリ管理を確保し、PyTorch リファレンスに対して検証します。

リファレンスドキュメント:

• 言語仕様 — https://docs.nvidia.com/cuda/cutile-python
• 実装ガイドライン (guidelines/ 01～03) — 教訓、ルール、概念

ステップ 1: 問題を理解する

目的: カーネルが何を計算する必要があるかを明確に定義する

• 入力/出力テンソルとその形状/ dtype を特定する
• 必要な数学的演算を理解する
• データ依存関係と計算フローを判断する
• 最適化の余地を見つけるためにメモリアクセスパターンを分析する

ユーザー提供のリファレンス実装を扱う場合:

1. リファレンスコードを保持する: 元の PyTorch リファレンス実装をそのまま保ちます。明らかに冗長または不要なコードのみを削除してください。
2. 保守的なアプローチ: 明示的に要求されない限り、リファレンス実装を変更または書き換えないでください。リファレンスは、正しさを検証するための基準となります。
3. 確認を求める: リファレンスコードのいずれかの部分の正しさや意図について不確かな場合は、先に進む前にユーザーに確認を求めてください。
4. 機能を維持する: リファレンスコードへの変更は、元の機能と動作を維持しなければなりません。

ステップ 2: カーネルアーキテクチャを設計する

目的: カーネル構造を計画する

• 並列化のための最適なブロック/タイルサイズを決定する (32 の倍数を考慮する)
• ct.cdiv(size, block) を使用してテンソルサイズに基づくグリッド次元を計算する
• ct.bid() を使用してブロックインデックス戦略を設計する
• テンソルサイズがブロックサイズで割り切れないエッジケースを処理する

ステップ 3: 型システムと定数を準備する

目的: 適切な型注釈を確保する

• 型注釈が必要なすべての定数値を特定する
• すべての定数に ct.Constant[type] を使用して適切な型注釈を追加する
• 適切な cuTile dtype (ct.float32、ct.float16、ct.int32 など) を選択する
• ブロックサイズやその他のパラメータが適切に型付けされていることを確認する

ステップ 4: カーネルを実装する

目的: cuTile カーネル関数を記述する

• 適切なシグネチャを持つ @ct.kernel デコレートされたカーネル関数を作成する
• 必要なパラメータ (入力テンソル、出力テンソル、型付き定数) を追加する
• 適切な ct.bid() 呼び出しでブロックインデックスを実装する
• 適切なインデックスとタイル形状を指定して、入力テンソルへのアクセスに ct.load() を使用する
• cuTile のタイル演算を使用して、ロードしたタイルに対する演算を実行する
• 正しいインデックスを指定して、出力テンソルの書き込みに ct.store() を使用する

ステップ 5: 準備と起動

目的: テンソル入力のセットアップとカーネルの起動

• .cuda() または .to("cuda") を使用して、すべての入力テンソルが CUDA デバイス上にあることを確認する
• テンソルの dtype が cuTile と互換性があることを検証するリファレンス
• 必要に応じて .contiguous() を使用してテンソルの連続性要件を処理する
• 適切なグリッド次元でカーネルを起動する

ステップ 6：検証とテスト

目的：正確性を確保します

• カーネルがエラーなくコンパイルされることを確認します
• さまざまなテンソルサイズ（タイルサイズに一致するものと一致しないもの）でテストします
• 利用可能な場合は、参照実装と照らし合わせて結果を検証します
• 境界条件とエッジケースを確認します

検証ループ（必須）

重要：cuTile コードを生成した後は、正確性を確認するために必ず実行してください。ファイルを書くだけでなく、実行して問題を修正してください。

検証ワークフロー

┌─────────────────────────────────────────────────────────────┐
│  1. Generate Code                                           │
│     - Write cuTile kernel with inline validation to file    │
│                                                             │
│  2. Execute Code                                            │
│     - Run: python <filename>.py                             │
│                                                             │
│  3. Check Results                                           │
│     ├─ Compilation error? → Fix syntax/type issues → Retry  │
│     ├─ Runtime error? → Fix kernel logic → Retry            │
│     ├─ Validation FAIL? → Fix numerical issues → Retry      │
│     └─ Validation PASS? → Done ✓                            │
└─────────────────────────────────────────────────────────────┘

実行手順

1. 生成したコードを .py ファイルに書き込みます
2. Bash を使ってファイルを実行します：python <filename>.py
3. 出力を分析します：
   • コンパイルエラーの場合：エラーメッセージを読み、コードを修正します（型注釈、構文、API の使用方法を確認します）
   • 実行時エラーの場合：テンソルの形状、グリッドの次元、メモリアクセスパターンを確認します
   • 検証失敗の場合：数値の差異、許容誤差、アルゴリズムの正確性を確認します
   • 検証成功の場合：ユーザーに成功を報告します
4. 成功するまで反復します：問題を修正して、検証に成功するまで再実行します（最大 3 回）

検証出力のベストプラクティス

• 大きなテンソルを出力しないでください — 検証に失敗した場合のみ、テンソルの内容を出力します
• 概要統計を出力します — PASS/FAIL、最大差分、テンソルの形状を表示します
• 検証パターンの例：

  is_close = torch.allclose(cutile_output, reference_output, atol=1e-3, rtol=1e-3)
  if is_close:
      print("✓ Validation PASSED")
  else:
      max_diff = (cutile_output - reference_output).abs().max().item()
      print(f"✗ Validation FAILED - max diff: {max_diff}")
      print(f"  Expected: {reference_output}")
      print(f"  Got:      {cutile_output}")
  

よくある問題と修正方法

エラーの種類	典型的な原因	修正方法
TypeError: missing Constant annotation	ct.Constant[int] が不足している	すべての定数に型注釈を追加します
ValueError: tile dimension not power of 2	2 のべき乗ではないタイルサイズ	2**((size-1).bit_length()) を使用します
IndexError / CUDA error	グリッドの次元またはインデックスが誤っている	ct.cdiv の使用方法と、タイルインデックスと要素インデックスを確認します
Validation FAIL: max diff = X	数値が一致しない	アルゴリズムを確認するか、許容誤差を大きくするか、ロジックを修正します

デフォルトの許容誤差

許容誤差の値、デフォルトの dtype、デフォルトのテンソル形状については、guidelines/03_concepts.md → 「ユーザーが指定しない場合のデフォルトルール」を参照してください。

テストチェックリスト

• ✓ cuTile の出力が許容誤差の範囲内で参照実装と一致することを確認します
• ✓ さまざまなテンソルサイズ（タイルサイズに一致するものと一致しないもの）でテストします
• ✓ 境界条件とエッジケースをテストします
• ✓ カーネルの起動前に、すべてのテンソルが CUDA デバイス上にあることを確認します
• ✓ 入力と出力の間で dtype に一貫性があることを確認します

重要な要件

すべての cuTile カーネルに必要な 4 つの要件：

1. 純粋な cuTile のフォワードパス：forward()／composed_function() 内のすべての演算は、@ct.kernel + ct.launch を通して実行する必要があります。フォワードパス内で、実行時の演算として nn.Conv2d()(x)、F.conv2d(x, w)、F.linear(x, w)、その他の nn.*／F.* 演算を呼び出さないでください。
   • forward() で許可されるもの：torch.empty、torch.zeros、torch.ones（メモリ確保）；tensor.reshape、tensor.view、tensor.permute、tensor.contiguous（並べ替え）；torch.cat、torch.stack（連結）；カーネル起動間の単純なスカラー演算である torch.sqrt、.sum()、.mean()。
   • __init__() で許可されるもの：nn.Conv2d、nn.Linear などを重みの初期化と保存だけに使用することは問題ありません。ただし、forward() で重みを取り出し（例：self.conv.weight.data）、self.conv(x) を呼び出すのではなく、ct.launch に渡してください。
   • よくある違反と詳しい例については、guidelines/02_code_generation_rules.md のルール 15 とルール 17 を参照してください。
2. 要素インデックスではなくタイルインデックスを使用します：ct.load(A, index=(bid_m, k), shape=(BLOCK_M, K)) ✅ (bid_m * BLOCK_M, k) ではありません ❌
3. すべてのタイル次元は 2 のべき乗にする必要があります：切り上げには 2**((size-1).bit_length()) を使用します
4. すべての定数に型注釈が必要です：コンパイルには BLOCK: ct.Constant[int] が必要です

メモリ操作、タイルサイズの設定、よくある落とし穴、最適化の方針に関する詳しいガイドラインについては、guidelines/ ディレクトリ（01–03）を参照してください。

パフォーマンスの最適化

重要な原則：個々の要素ではなく、データのブロックを基準に考えてください。ハードウェアの特性に合ったタイルサイズを選び、タイル内でのデータ再利用を最大化してください。

ファイル管理のガイドライン

重要：ファイルを作成する際は、次のルールに従ってください。

1. デフォルトでは単一ファイル：ユーザーが複数ファイルを明示的に要求しない限り、カーネル、検証コード、テストコードを含む単一の .py ファイルを生成してください
2. ドキュメントファイルは作成しない：明示的に要求されない限り、README.md、ドキュメントファイル、個別のサンプルファイルを作成しないでください
3. すべてをインラインに記述：カーネルの実装、検証ロジック、テストコードを、まとまりのある1つのファイルに含めてください
4. ファイル作成は最小限に：必要不可欠なファイルだけを作成し、ファイルの新規作成より既存ファイルの編集を優先してください
5. ソースの引用は禁止：TileGym ファイル、参照ファイル、ソースに言及するコメントや docstring を含めないでください。コードは出典を示さず、単独で完結する必要があります
6. 現在の作業ディレクトリに出力：出力するすべての .py ファイルは、ユーザーがコーディングアシスタントを起動した現在の作業ディレクトリに書き込む必要があります。タスクの開始時に pwd を実行してください。生成するすべての .py ファイルはそのディレクトリ直下（例：./composed_foo.py）に配置し、スキルのサブディレクトリには配置しないでください
7. スキルディレクトリは読み取り専用：<skill_dir> は参照資料、サンプル、オーケストレーションの手順を読むためだけにサブエージェントへ渡されます。メインエージェントもサブエージェントも、<skill_dir> 内のファイルを書き込んだり、作成したり、保存したりしてはなりません。読み取りツール（Read、Glob、Grep、Bash の cat／grep）のみを使用してください。Write、Edit、またはファイルを作成するコマンドに渡さないでください。

単一ファイルの構成例：

import cuda.tile as ct
import torch

# Kernel implementation
@ct.kernel
def my_kernel(...):
    ...

# Validation function (if needed)
def validate(...):
    ...

# Test/demo code at bottom
if __name__ == "__main__":
    # Test the kernel
    ...

成功基準

次の条件を満たした場合、実装は成功です。

1. ✅ 純粋な cuTile の順方向パス：forward()／composed_function() 内で nn.*／F.* の計算呼び出しを行わず、すべての計算を ct.launch 経由で実行していること（__init__ 内での重み初期化のみの使用は問題ありません）
2. ✅ 実装前に既存のサンプルを検索していること
3. ✅ TileGym に該当するものがない場合、同梱の examples/ を検索していること
4. ✅ 作成した .py ファイルが1つだけであること（READMEや、要求されていない個別のサンプルは作成しない）
5. ✅ コードにソースの引用がないこと（コメントや docstring で TileGym ファイルや参照ファイルに言及しない）
6. ✅ 生成した cuTile コードがエラーなくコンパイルできること
7. ✅ 数値結果が許容誤差の範囲内で参照実装と一致すること
8. ✅ すべての定数に適切な型注釈が付いていること
9. ✅ すべてのタイルの次元が2の累乗であること
10. ✅ グリッドの次元がすべてのテンソル要素を正しくカバーしていること
11. ✅ 同じファイルにインラインの検証コードとテストコードが含まれていること

オーケストレーションを使用する場合の追加基準（複雑なタスク）：

12. ✅ 複雑さを評価し、適切な理由に基づいてオーケストレーションを選択したこと
13. ✅ アナライザーが PyTorch の参照実装を含む、明確なカーネル仕様を作成したこと
14. ✅ 独立したカーネルを順次ではなく並列に生成したこと
15. ✅ 各カーネルを個別に検証してから合成したこと
16. ✅ 合成したソリューションが元の PyTorch 参照実装に対するエンドツーエンドの検証に合格したこと

---

忘れないでください：まず既存のサンプルを検索し、ワークフローに沿って体系的に進め、十分に検証してください。参照ファイルには、cuTile カーネルの開発に関する詳細なルールとサンプルが記載されています。