tilegym-improve-cutile-kernel-perf

cuTile カーネルの反復的なパフォーマンス最適化

TileGym リポジトリで、cuTile カーネルのパフォーマンスを体系的にプロファイリングし、ボトルネックを診断して、反復的に調整します。

手順

次の3つのフェーズを順番に進めます。環境とベースラインをセットアップし、記録したログを使って実験ループを実行した後、パフォーマンス目標を達成するか、改善が頭打ちになるまで実験ループを繰り返します。

セットアップ

最適化環境を準備するため、ユーザーと作業します。

1. 新しい git ブランチを作成します。ブランチ名（例：cutile-perf-<kernel_name>-<date>）を現在のブランチから作成するよう提案します。git checkout -b <branch name> でチェックアウトします。

2. 対象のカーネルを特定します。

   • cuTile カーネルは src/tilegym/suites/<suite>/cutile/ または src/tilegym/ops/cutile/ の下にあります。
   • カーネルファイルを読み、次の項目を特定します。@ct.kernel デコレーターが付いた関数、起動ラッパー（ct.launch() または ct_experimental.autotune_launch()）、@register_impl 登録、および現在の自動チューニング設定（ある場合）。

3. カーネルを分類します。

   • Arithmetic Intensity < 10 → メモリバウンド
   • Arithmetic Intensity 10-50 → バランス型
   • Arithmetic Intensity > 50 → コンピュートバウンド

   注：分類は、実験ループで最適化の優先順位を決めるためだけに使用します。コア指標は常に latency (ms) です。

4. GPU 環境を確認します。

   • GPU ノード（Blackwell または Ampere GPU）が利用可能であることを確認します。
   • 以降のベンチマークコマンドはすべて GPU ノードで実行します。

5. 関連するリファレンスを確認します。

   • references/optimization-playbook.md：最適化ごとの手順（A から J）と、変更前後のコード例
   • references/perf-knobs-catalog.md：調整可能なパラメーターの完全な一覧（TMA、永続スケジューリング、占有率、タイルサイズ、レイテンシヒントなど）
   • references/cutile-api-reference.md：cuTile API リファレンスと重要な18のルール
   • references/performance-model.md：Roofline／パフォーマンスモデル、ボトルネック診断、自動チューニング
   • references/ir-dump-guide.md：IR ダンプ、分析、エラー診断
   • references/cutile-patterns-reference.md：一般的な cuTile パターンと変換のクイックリファレンス

6. 進捗を記録するために @sandbox/perf_results.md を作成します。最初の実行でベースラインを記録します。

7. 確認を得て開始します。確認後、実験を開始します。

実験

各実験の反復では、対象カーネルに最適化を1つ適用し、正しさを検証して、ベンチマークを再実行し、結果を記録します。各反復は10分以内に完了するようにします。

目標

• コア指標を改善します。latency (ms) を短縮します。
• コア制約を守ります。正しさを損なってはなりません。すべての最適化で数値的な正しさを維持する必要があります。latency (ms) がベースラインと比べて2%を超えて悪化してはなりません。

変更できる項目

• src/tilegym/suites/<suite>/cutile/ または src/tilegym/ops/cutile/ の対象カーネルファイル：カーネル本体、タイルサイズ、占有率、num_ctas、TMA の使用、レイテンシヒント、flush_to_zero、自動チューニング設定、永続スケジューリング、その他の cuTile 固有パラメーター
• カーネルの起動ラッパー：グリッド計算、自動チューニング設定空間
• @sandbox/：新しいファイルの追加や、自分が作成したファイルの変更は自由ですが、git に追加しないでください。

変更できない項目

• カーネルの機能的な意味（入力、出力、許容誤差内での数値的な動作）
• テスト基盤とベンチマークハーネス
• 上記に記載されていないもの

実験出力の内容

正しさのテスト：

python -m pytest tests/suites/.../test_<kernel_name>.py -k "test_ and cutile and not test_perf" -v

パフォーマンスベンチマーク：

各反復で次の操作を行います。

1. pytest ベンチマークを実行します：python -m pytest ... --print-record → latency (ms) を抽出します。
2. latency を perf_results.md に記録します。

ベンチマークコマンドライン：

python -m pytest tests/suites/.../test_<kernel_name>.py -k "test_perf and cutile" --print-record -v

latency のサンプル：

Cutile: {'forward': {'mean': 3.7903138461538455, 'std': 0.0016941310873207053, 'rel_std': 0.044696327430505396, 'median': 3.789880999999999, 'min': 3.7883389999999992, 'max': 3.7941230000000004, 'nrep': 13, 'peak_mem_mb': 913}} ms

実験の進捗を記録する

各イテレーションの結果を @sandbox/perf_results.md に記録します。ファイルには、次の 5 列からなる Markdown テーブルのみを記載してください。

• iteration：イテレーション番号。0（ベースライン）から開始します
• optimization：適用した内容（例：「baseline」、「TMA replace gather」、「persistent scheduling」）
• latency_ms：カーネルのレイテンシー（ミリ秒）、小数点以下 6 桁
• correctness：PASS または FAIL
• status：このイテレーションが keep、revert、crash のいずれだったか

記入例：

| iteration | optimization       | latency_ms | correctness | status |
|----------:|:-------------------|-----------:|:------------|-------:|
| 0         | baseline           |   0.820000 | PASS        | keep   |
| 1         | TMA replace gather |   0.390000 | PASS        | keep   |

ファイルが空の場合は、テーブルのヘッダーを作成してください。イテレーションごとに 1 行追加します。

ベースライン

最初のイテレーション（イテレーション 0）ではコードを変更せず、正確性テストとパフォーマンスベンチマークを実行するだけです。結果はベースラインとして最初の行に記載します。

実験ループ

基本的な手順は、プレイブックからイテレーションごとに最適化を 1 つ適用し、正確性を検証し、ベンチマークを実行して、採用するか元に戻すかを判断することです。一度に試す最適化は 1 つだけにし、実験記録を整理してください。

ループ：

1. Git のステータスを確認します。現在の Git ブランチ／コミットを確認します

2. references/optimization-playbook.md から最適化を 1 つ選択して適用します。

3. 正確性を検証します。失敗した場合は、直ちに元に戻します。よくある原因：flush_to_zero／rounding_mode=APPROX による結果の変化、タイルサイズの OOB、allow_tma=False のセマンティクス、永続ループの境界条件の誤り

4. 再度ベンチマークを実行し、現在のベースラインと比較します

5. Git にコミットします

6. 結果を @sandbox/perf_results.md に記録します

7. 判断基準：

   結果	対応
   改善（latency (ms)）が 5% 以上	新しいベースラインとして採用し、続行します
   改善が 2～5%	採用します。次のイテレーションでは優先度を下げます
   改善が 2% 未満	採用しますが、ユーザーが続行を希望しない限り停止します
   いずれかの構成で性能が低下	直ちに元に戻し、次の最適化を試します
   2 回連続のイテレーションで改善がない	停止します
   根本原因が scheduling または unknown	ユーザーにエスカレーションします

8. 採用する場合はベースラインの数値を更新してループを続けます

9. 元に戻す場合は、開始時点まで Git をリセットし、優先順位に従って次の最適化を試します 終了条件：すべての試行が完了した場合、25 回を超えるイテレーションが行われた場合、またはユーザーが中断した場合

自律的に進めてください：セットアップ段階では、ユーザーに確認を求めてください。実験ループに入ったら、ユーザーのフィードバックを求めるために立ち止まらないでください。判断には最善の判断を用い、最適化プレイブックとパフォーマンス調整項目カタログを速やかに参照し、行き詰まった場合はさらに深く考えてください。