cutlass-skill

CUTLASS と CuTe の開発

ローカルの CUTLASS チェックアウトを、実装の主要な参照先として使用してください。CuTeDSL のパスやインターフェースは頻繁に変更されるため、記憶している API よりも、現在のソースやサンプルを優先してください。

チェックアウトの場所を特定する

この SKILL.md が含まれるディレクトリを特定し、その中の repos/cutlass/ を使用してください。インストーラーは、このパスを agent-gpu-skills/third_party/cutlass/、または CUTLASS_REPO を通じて指定されたチェックアウトにリンクします。

以下のコマンドでは、CUTLASS_REPO を特定した絶対パスに置き換えてください。

CUTLASS_REPO=/absolute/path/to/cutlass-skill/repos/cutlass

チェックアウトが見つからない場合は、agent-gpu-skills リポジトリで以下を実行し、Skill を再インストールしてください。

bash update-repos.sh cutlass
bash install.sh --skill cutlass-skill

参照するソースを選ぶ

タスク	最初に確認する場所
CuTeDSL API と実装	python/CuTeDSL/cutlass/
CuTeDSL の全サンプルとチュートリアル	examples/python/CuTeDSL/
CUTLASS C++ のサンプル	examples/
CUTLASS C++ のカーネルとビルダー	include/cutlass/
CuTe C++ のレイアウト、コピー、MMA	include/cute/
Python のレイアウトとスウィズルのユーティリティ	python/pycute/
Python のマニフェストとジェネレーターのユーティリティ	python/cutlass_library/

検証済みのチェックアウト内で、操作やアーキテクチャに対応する具体的なファイルを特定する際は、quick-reference.md を確認してください。

調査の進め方

1. プログラミング対象を特定します。CuTeDSL Python、CuTe C++、または CUTLASS C++ のいずれかです。
2. 対象のアーキテクチャと操作に最も近いサンプルを探します。
3. サンプルをたどり、インスタンス化される実装とヘッダーを確認します。
4. データ型、レイアウト、アラインメント、アーキテクチャのターゲット、スケジュール、エピローグをまとめて確認します。
5. 対象のリポジトリに適用する前に、代表的な最小のサンプルをビルドまたは実行します。

大きなソースファイルを読み込む前に、ファイルを検索してください。

find "$CUTLASS_REPO/examples/python/CuTeDSL" -type f | sort
find "$CUTLASS_REPO/examples" -mindepth 1 -maxdepth 1 -type d | sort

CuTeDSL の定義と使用箇所をまとめて検索します。

rg -n 'TiledMMA|tiled_mma' \
  "$CUTLASS_REPO/python/CuTeDSL/cutlass/cute" \
  "$CUTLASS_REPO/examples/python/CuTeDSL"

rg -n 'Pipeline|pipeline' \
  "$CUTLASS_REPO/python/CuTeDSL/cutlass/pipeline" \
  "$CUTLASS_REPO/examples/python/CuTeDSL/cute"

CUTLASS C++ のビルダーとカーネルをたどります。

rg -n 'CollectiveBuilder' \
  "$CUTLASS_REPO/examples/49_hopper_gemm_with_collective_builder"

rg -n 'CollectiveMainloop' \
  "$CUTLASS_REPO/include/cutlass/gemm/collective"

rg -n 'GemmUniversal' \
  "$CUTLASS_REPO/include/cutlass/gemm"

CuTe のレイアウトとアーキテクチャプリミティブをたどります。

rg -n 'make_layout|composition|complement' \
  "$CUTLASS_REPO/include/cute/layout.hpp"

rg -n 'TiledCopy|make_tiled_copy' "$CUTLASS_REPO/include/cute"
rg -n 'SM90_TMA|SM100_TMA' "$CUTLASS_REPO/include/cute/arch"

C++ のサンプルでは、その CMakeLists.txt を確認し、選択したターゲットのみをビルドしてください。以下のアーキテクチャとターゲットは、ワークロードに合わせて置き換えてください。

cmake -S "$CUTLASS_REPO" -B /tmp/cutlass-build -DCUTLASS_NVCC_ARCHS=100a
cmake --build /tmp/cutlass-build \
  --target 71_blackwell_gemm_with_collective_builder

CuTeDSL のサンプルを実行する前に、互換性のある CUDA や Python のバージョンを推測せず、現在の python/CuTeDSL/pyproject.toml と requirements ファイルを確認してください。

実装の進め方

CUTLASS カーネルの問題を診断する際は、次の 3 つの層を分けて考えてください。

problem shape and tensor layout
  → selected collective and schedule
  → generated CUDA/PTX behavior on the target architecture

サンプルディレクトリの名前から、選択されるスケジュールを推測しないでください。インスタンス化された型とビルダーパラメーターをたどって確認してください。アーキテクチャや命令の詳細が正しさを左右する場合は、cuda-skill を追加し、CUDA または PTX のリファレンスと照合してください。

正しさを検証する場合：

• 元の問題の形状、ストライド、レイアウト、データ型、スケーリング形式、エピローグを維持します。
• 独立した参照実装と比較します。
• パフォーマンスのチューニング前に、境界形状とアラインメントのケースをテストします。
• テンプレートのコンパイル成功は必要条件ですが、それだけでは十分ではありません。

パフォーマンスを検証する場合：

• 安定したベースラインと測定方法を確立します。
• スケジュール、タイル、ステージ数、エピローグの選択肢を、一度に 1 つだけ変更します。
• コンパイラーのリソース使用量と、正確なアーキテクチャターゲットを記録します。
• 測定対象のディスパッチ経路が意図したカーネルを使用していることを確認してから、プロファイルを実行します。

ソースの更新

agent-gpu-skills リポジトリで、以下を実行してください。

bash update-repos.sh cutlass
python3 scripts/validate_repo.py --require-sources

このチェックアウトは CUTLASS の main を追跡し、third_party/UPSTREAMS.toml には、この Skill が最後に承認したコミットが記録されています。この記録を更新する前に、ソースマップの差異を確認してください。