Skill de Programmation Python cuTile

Tu es un expert en programmation cuTile, spécialisé dans la rédaction de kernels GPU haute performance utilisant le modèle de programmation basé sur les tuiles de cuTile. Cette skill fournit des conseils complets pour créer, déboguer et optimiser les kernels cuTile.

Aperçu

cuTile est un modèle de programmation parallèle pour les GPU NVIDIA avec un DSL basé sur Python qui exploite automatiquement les capacités matérielles avancées comme les tensor cores. Cette skill t'aide à écrire du code cuTile efficace et correct.

Quand utiliser cette Skill

Invoque cette skill quand tu dois :

Écrire des kernels GPU cuTile à partir de zéro
Convertir des opérations tensorielles en implémentations cuTile
Déboguer ou corriger le code kernel cuTile
Optimiser les kernels cuTile pour les performances
Comprendre l'API cuTile et les patterns de programmation
Valider les implémentations cuTile
Trouver et adapter des exemples à partir des sources de référence disponibles

Spécifie optionnellement lors de l'invocation :

Formes de tenseurs cibles
Types de données (par défaut : float16)
Exigences de performance
Contraintes spéciales

Documentation de Référence

Spécification du Langage cuTile — https://docs.nvidia.com/cuda/cutile-python. Couvre le modèle d'exécution, les modèles de données et de mémoire, le débogage, la compilation, et chaque op publique (load/store, factories, réductions, scans, matmul, sélection, math, bitwise, comparaisons, atomiques, metaprogramming, classes, enums, autotuning).

Directives d'Implémentation (dans le répertoire guidelines/) :

01_implementation_lessons.md - Leçons importantes et règles d'implémentation
02_code_generation_rules.md - Règles et patterns spécifiques de génération de code
03_concepts.md - Concepts fondamentaux : restriction de taille de tuile, opérations mémoire, fusion de kernels, règles par défaut

Exemples

Avant de commencer toute tâche de programmation cuTile, cherche toujours des exemples existants en premier. TileGym est la référence principale ; le répertoire examples/ empaqueté le complète pour les ops que TileGym ne couvre pas encore (convolution, pooling, scan, GEMV, matmul 4D, split-k GEMM, group_norm).

Cette skill supporte deux contextes d'installation :

À l'intérieur d'un checkout TileGym (<repo>/.agents/skills/cutile-python/, ou <repo>/.claude/skills/cutile-python/ via le symlink de rétro-compatibilité) — Les ops TileGym se trouvent à <repo>/src/tilegym/ops/cutile/.
Installée ailleurs (par ex. ~/.agents/skills/cutile-python/, ~/.claude/skills/cutile-python/, ou dans un autre repo) — Clone TileGym une fois dans ${TILEGYM_SKILL_CACHE_DIR:-~/.cache/tilegym}/TileGym et utilise src/tilegym/ops/cutile/.

Voir examples/tilegym_and_examples_guide.md pour l'ordre de recherche complet, la disposition des répertoires, et la procédure de décision cache-vs-repo.

Quand Clarifier Avant l'Implémentation

Pour les tâches complexes ou ambiguës, présente les options d'approche à l'utilisateur avant de coder. Cela évite les efforts gaspillés sur la mauvaise implémentation.

Clarifier pour Ces Types de Tâches

Type de Tâche	Pourquoi Clarifier	Exemples de Questions
Demandes d'optimisation	« Rends ceci plus rapide » a plusieurs chemins	Quel goulot ? Limité par mémoire vs calcul ? Accélération cible ?
Changements d'architecture	Les décisions structurelles affectent tout	Parallélisme des données vs modèle ? Kernel persistant vs standard ?
Opérations ambiguës	Même nom, implémentations différentes	Flash attention vs standard ? Causal vs bidirectionnel ? Conv groupée vs depthwise ?
Tradeoffs performance vs exactitude	L'utilisateur doit choisir	Utiliser TF32 pour la vitesse ? Fonctions math approximatives ? Accumulation en précision réduite ?
Contraintes manquantes	Impossible d'optimiser sans cibles	Formes de tenseurs cibles ? Plage de batch size ? Budget mémoire ?

Agir Directement pour Ces Types de Tâches

Demandes claires et spécifiques : « Écris un kernel ReLU pour la forme (1024, 1024) »
Corrections de bugs avec reproduction : « Ce kernel plante à la ligne 42 »
Questions sur l'API : « Comment utiliser ct.gather ? »
Adaptations d'exemples : « Adapte le softmax TileGym pour mes formes »

Comment Clarifier

Quand une clarification est nécessaire :

Explique brièvement pourquoi plusieurs approches existent
Présente 2-3 options concrètes avec leurs tradeoffs
Recommande une option s'il y a un choix clairement meilleur
Demande à l'utilisateur de choisir avant de continuer

Exemple :

Ta demande « optimise ce matmul » pourrait aller dans plusieurs directions :

1. **Kernel persistant** - Meilleur pour petites matrices, plus rapide, code plus complexe
2. **Tuning de taille de tuile** - Gains modérés, changements de code minimes
3. **TMA prefetching** - Meilleur pour grandes matrices, nécessite GPU Hopper+

Je recommande l'option 2 pour un premier passage. Quelle approche préfères-tu ?

Évaluation de Complexité : Workflow Simple vs Orchestré

Avant de commencer l'implémentation, évalue la complexité de la demande pour choisir le bon workflow.

Utilise le Workflow Simple (Étapes 0-6 ci-dessous) quand :

Tâche d'un seul kernel (par ex., ReLU, softmax, un matmul)
Correction de bug ou optimisation d'un kernel existant
Question sur l'API ou adaptation d'exemple
Demande claire et d'une seule opération

Utilise le Workflow Orchestration Deep Agent quand L'UN DE CES CAS s'applique :

3+ opérations distinctes nécessitant des kernels séparés (par ex., « implémente un bloc transformer avec attention, FFN, et layer norm »)
Fonctions définies par l'utilisateur multiples dans le code d'entrée (par ex., custom_activation(), custom_norm())
Dépendances de données inter-kernels où la sortie d'un kernel alimente un autre
nn.Module PyTorch avec plusieurs couches dans forward()
Demande de décomposition explicite (par ex., « divise ceci en kernels fusionnés »)

Quand l'orchestration est nécessaire, suis le section Deep Agent Orchestration Workflow. Sinon, continue avec les Instructions ci-dessous.

Workflow Orchestration Deep Agent

Pour les tâches complexes nécessitant 3+ kernels, dépendances inter-kernels, ou décomposition de nn.Module multi-couches, utilise le pipeline orchestré multi-agents. L'agent principal agit comme un orchestrateur (pas un codeur) — les sous-agents gèrent la lecture de références et la génération de code.

Pipeline : Op Tracer (optionnel) → Analyzer → Kernel Agents (parallèles) → Composer → Main Agent valide

Pour le workflow complet étape par étape (Étapes O-0 à O-4), les templates de prompts, et la gestion d'erreurs, voir orchestration/workflow.md.

Pour l'architecture d'orchestration, la hiérarchie d'agents, et le format de spécification de kernel, voir orchestration/overview.md.

Instructions

Suis ces étapes lors de l'écriture de kernels cuTile (workflow simple pour les tâches d'un seul kernel).

NOTE : Ignore entièrement cette section si tu utilises le Workflow Orchestration Deep Agent ci-dessus. Le workflow d'orchestration a ses propres étapes (O-0 à O-4). NE COMBINE PAS les deux workflows - cela amène l'agent principal à lire tous les fichiers de référence ET à générer des sous-agents, ce qui gaspille le contexte.

Étape 0 : Rechercher des Exemples et Consulter les Références (OBLIGATOIRE)

Objectif : Trouver des exemples existants et consulter la documentation pertinente

Recherche d'Exemples (Stratégie en Deux Étapes) :

Cherche d'abord TileGym (src/tilegym/ops/cutile/) pour des patterns de kernel cuTile similaires.
Si TileGym n'a pas de correspondance, cherche le répertoire examples/ empaqueté (partie de cette skill).
Lis les fichiers d'exemple pertinents pour comprendre les patterns d'implémentation.

Traduction d'Algorithme Complexe (flash attention, ops fusionnées, etc.) : Quand tu implémente des algorithmes complexes, suis cette approche systématique :

Analyse l'implémentation PyTorch : Comprends les opérations mathématiques, le flux de données, les patterns computationnels clés, les patterns d'accès mémoire, et les optimisations ou contraintes spéciales.
Étudie les exemples cuTile pertinents : Examine les exemples pour des opérations similaires — les exemples existants fournissent souvent exactement les patterns dont tu as besoin. Copie et adapte les patterns qui fonctionnent plutôt que de réinventer la roue.
Implémente la version cuTile : Mappe les opérations PyTorch aux primitives cuTile, applique la fusion de kernels où approprié, assure l'indexation correcte des tuiles et la gestion mémoire, et valide contre la référence PyTorch.

Documentation de Référence :

Language Spec — https://docs.nvidia.com/cuda/cutile-python
Implementation Guidelines (guidelines/ 01–03) — Leçons, règles, et concepts

Étape 1 : Comprendre le Problème

Objectif : Définir clairement ce que le kernel doit calculer

Identifie les tenseurs d'entrée/sortie et leurs formes/dtypes
Comprends les opérations mathématiques requises
Détermine les dépendances de données et le flux de calcul
Analyse les patterns d'accès mémoire pour les opportunités d'optimisation

Travailler avec des implémentations de référence fournies par l'utilisateur :

Préserve le Code de Référence : Garde l'implémentation PyTorch originale intacte. Supprime uniquement le code clairement redondant ou inutile.
Approche Conservative : Ne modifie ni ne réécris l'implémentation de référence sauf si explicitement requis. La référence sert de source de vérité pour la validation d'exactitude.
Cherche une Clarification : Si tu es incertain sur l'exactitude ou l'intention d'une partie du code de référence, demande une clarification à l'utilisateur avant de continuer.
Maintiens la Fonctionnalité : Tout changement au code de référence doit préserver la fonctionnalité et le comportement originaux.

Étape 2 : Concevoir l'Architecture du Kernel

Objectif : Planifier la structure du kernel

Détermine les tailles de bloc/tuile optimales pour la parallélisation (considère les multiples de 32)
Calcule les dimensions de grille basées sur les tailles de tenseur utilisant ct.cdiv(size, block)
Conçois la stratégie d'indexation de bloc utilisant ct.bid()
Gère les cas limites où la taille du tenseur n'est pas divisible par la taille du bloc

Étape 3 : Préparer le Système de Types et les Constantes

Objectif : Assurer les annotations de type appropriées

Identifie toutes les valeurs constantes qui ont besoin d'annotations de type
Ajoute des annotations de type appropriées utilisant ct.Constant[type] pour toutes les constantes
Choisit les dtypes cuTile appropriés (ct.float32, ct.float16, ct.int32, etc.)
Assure que les tailles de bloc et autres paramètres sont correctement typés

Étape 4 : Implémenter le Kernel

Objectif : Écrire la fonction kernel cuTile

Crée une fonction kernel décorée par @ct.kernel avec une signature appropriée
Ajoute les paramètres requis (tenseurs d'entrée, tenseur de sortie, constantes typées)
Implémente l'indexation de bloc avec les appels ct.bid() appropriés
Utilise ct.load() pour l'accès au tenseur d'entrée avec l'indexation appropriée et les formes de tuile
Effectue les opérations sur les tuiles chargées utilisant les opérations de tuile cuTile
Utilise ct.store() pour l'écriture du tenseur de sortie avec l'indexation correcte

Étape 5 : Préparer et Lancer

Objectif : Configurer les entrées de tenseur et lancer le kernel

Assure que tous les tenseurs d'entrée sont sur le dispositif CUDA utilisant .cuda() ou .to("cuda")
Vérifie que les dtypes des tenseurs sont compatibles avec cuTile
Gère les exigences de contiguïté des tenseurs utilisant .contiguous() si nécessaire
Lance le kernel avec les dimensions de grille appropriées

Étape 6 : Valider et Tester

Objectif : Assurer l'exactitude

Vérifie que le kernel se compile sans erreurs
Teste avec diverses tailles de tenseur (alignées et non alignées à la taille de tuile)
Valide les résultats contre l'implémentation de référence si disponible
Vérifie les conditions limites et les cas limites

Boucle de Validation (OBLIGATOIRE)

IMPORTANT : Après avoir généré du code cuTile, tu DOIS l'exécuter pour vérifier l'exactitude. Ne te contente pas d'écrire le fichier - exécute-le et corrige les problèmes.

Workflow de Validation

┌─────────────────────────────────────────────────────────────┐
│  1. Générer le Code                                         │
│     - Écrire le kernel cuTile avec validation intégrée      │
│       dans un fichier                                       │
│                                                             │
│  2. Exécuter le Code                                        │
│     - Lancer : python <filename>.py                         │
│                                                             │
│  3. Vérifier les Résultats                                  │
│     ├─ Erreur de compilation ? → Corriger les problèmes    │
│     │  de syntaxe/type → Réessayer                         │
│     ├─ Erreur d'exécution ? → Corriger la logique kernel   │
│     │  → Réessayer                                         │
│     ├─ Validation ÉCHOUE ? → Corriger les problèmes        │
│     │  numériques → Réessayer                              │
│     └─ Validation RÉUSSIT ? → Fait ✓                       │
└─────────────────────────────────────────────────────────────┘

Étapes d'Exécution

Écris le code généré dans un fichier .py
Lance le fichier utilisant Bash : python <filename>.py
Analyse la sortie :
- Si erreur de compilation : Lis le message d'erreur, corrige le code (vérifie les annotations de type, la syntaxe, l'utilisation de l'API)
- Si erreur d'exécution : Vérifie les formes de tenseur, les dimensions de grille, les patterns d'accès mémoire
- Si validation ÉCHOUE : Vérifie les différences numériques, les tolérances, l'exactitude de l'algorithme
- Si validation RÉUSSIT : Signale le succès à l'utilisateur
Itère jusqu'à RÉUSSIR : Corrige les problèmes et relance jusqu'à la validation réussie (max 3 tentatives)

Bonnes Pratiques de Sortie de Validation

Ne pas afficher de grands tenseurs - Affiche uniquement les contenus de tenseur quand la validation échoue
Afficher les stats résumées - Montre RÉUSSIR/ÉCHOUER, différence max, forme du tenseur

Pattern de validation exemple :

is_close = torch.allclose(cutile_output, reference_output, atol=1e-3, rtol=1e-3)
if is_close:
    print("✓ Validation RÉUSSIE")
else:
    max_diff = (cutile_output - reference_output).abs().max().item()
    print(f"✗ Validation ÉCHOUÉE - diff max : {max_diff}")
    print(f"  Attendu : {reference_output}")
    print(f"  Obtenu :  {cutile_output}")

Problèmes Courants et Corrections

Type d'Erreur	Cause Typique	Correction
`TypeError: missing Constant annotation`	Annotation `ct.Constant[int]` manquante	Ajoute l'annotation de type à toutes les constantes
`ValueError: tile dimension not power of 2`	Taille de tuile non puissance de 2	Utilise `2**((size-1).bit_length())`
`IndexError` / `CUDA error`	Dimensions de grille ou indices incorrects	Vérifie l'utilisation de `ct.cdiv`, les indices de tuile vs éléments
`Validation FAIL: max diff = X`	Désaccord numérique	Vérifie l'algorithme, augmente la tolérance, ou corrige la logique

Valeurs de Tolérance par Défaut

Voir guidelines/03_concepts.md → « Default Rules When User Does Not Specify » pour les valeurs de tolérance, les dtypes par défaut, et les formes de tenseur par défaut.

Checklist de Test

✓ Vérifie que la sortie cuTile correspond à l'implémentation de référence dans la tolérance
✓ Teste avec diverses tailles de tenseur (alignées et non alignées à la taille de tuile)
✓ Teste les conditions limites et les cas limites
✓ Assure que tous les tenseurs sont sur le dispositif CUDA avant le lancement du kernel
✓ Vérifie la cohérence des dtype entre les entrées et sorties

Exigences Critiques

Quatre exigences essentielles pour tous les kernels cuTile :

Chemin forward pur cuTile : Chaque opération de calcul dans forward()/composed_function() doit passer par @ct.kernel + ct.launch. N'appelle pas nn.Conv2d()(x), F.conv2d(x, w), F.linear(x, w), ou toute autre opération de calcul nn.*/F.* en tant qu'opération d'exécution dans le chemin forward.
- Permis dans forward() : torch.empty, torch.zeros, torch.ones (allocation) ; tensor.reshape, tensor.view, tensor.permute, tensor.contiguous (réarrangement) ; torch.cat, torch.stack (concaténation) ; torch.sqrt, .sum(), .mean() (ops scalaires simples entre les lancements de kernel).
- Permis dans __init__() : Utiliser nn.Conv2d, nn.Linear, etc. uniquement pour l'initialisation et le stockage des poids est correct — tant que forward() extrait les poids (par ex., self.conv.weight.data) et les passe à ct.launch au lieu d'appeler self.conv(x).
- Voir Règle 15 et Règle 17 dans guidelines/02_code_generation_rules.md pour les violations courantes et les exemples détaillés.
Indices de tuile, pas indices d'éléments : ct.load(A, index=(bid_m, k), shape=(BLOCK_M, K)) ✅ pas (bid_m * BLOCK_M, k) ❌
Toutes les dimensions de tuile doivent être des puissances de 2 : Utilise 2**((size-1).bit_length()) pour arrondir vers le haut
Toutes les constantes ont besoin d'annotations de type : BLOCK: ct.Constant[int] est requis pour la compilation

Pour des directives détaillées sur les opérations mémoire, le dimensionnement des tuiles, les pièges courants, et les stratégies d'optimisation, voir le répertoire guidelines/ (01–03).

Optimisation des Performances

Principe clé : Pense en blocs de données plutôt qu'en éléments individuels. Choisissez les tailles de tuile qui correspondent aux caractéristiques du matériel et maximisent la réutilisation des données dans les tuiles.

Directives de Gestion des Fichiers

IMPORTANT : Suis ces règles pour la création de fichiers :

Un seul fichier par défaut : Génère un seul fichier .py contenant le kernel, la validation, et le code de test sauf si l'utilisateur demande explicitement plusieurs fichiers
Pas de fichiers de documentation : Ne crée PAS de README.md, fichiers de documentation, ou fichiers d'exemple séparés sauf si explicitement demandé
Intègre tout : Inclus l'implémentation du kernel, la logique de validation, et le code de test dans un seul fichier cohérent
Création minimaliste de fichiers : Ne crée que ce qui est absolument nécessaire - préfère modifier les fichiers existants plutôt que d'en créer de nouveaux
Pas de citations de sources : N'inclus PAS de commentaires ou docstrings mentionnant les fichiers TileGym, les fichiers de référence, ou les sources. Le code doit être autonome sans attribution
Sortie dans le répertoire courant : Tous les fichiers .py générés doivent être écrits dans le répertoire de travail courant d'où l'utilisateur a démarré l'assistant de codage. Lance pwd au début de la tâche. Tous les fichiers .py générés vont directement dans ce répertoire (par ex. ./composed_foo.py), jamais dans un sous-répertoire de la skill.
Le répertoire skill est en lecture seule : <skill_dir> est passé aux sous-agents uniquement pour qu'ils puissent lire les références, les exemples, et les instructions d'orchestration. Aucun agent — principal ou sous-agent — ne doit jamais écrire, créer, ou sauvegarder de fichier sous <skill_dir>. Utilise-le uniquement avec les outils de lecture (Read, Glob, Grep, Bash cat/grep). Ne le passe jamais à Write, Edit, ou à toute commande de création de fichier.

Exemple de structure pour un seul fichier :

import cuda.tile as ct
import torch

# Implémentation du kernel
@ct.kernel
def my_kernel(...):
    ...

# Fonction de validation (si nécessaire)
def validate(...):
    ...

# Code de test/démo en bas
if __name__ == "__main__":
    # Teste le kernel
    ...

Critères de Succès

Ton implémentation est réussie quand :

✅ Chemin forward pur cuTile : Pas d'appels de calcul nn.*/F.* dans forward()/composed_function() — tout le calcul routé par ct.launch (l'utilisation init-only des poids dans __init__ est correcte)
✅ Les exemples existants ont été cherchés avant l'implémentation
✅ Les examples/ empaqueté ont été cherchés si TileGym n'avait pas de correspondance
✅ Un seul fichier .py créé (pas de READMEs, pas d'exemples séparés sauf demandé)
✅ Pas de citations de sources dans le code (pas de mentions des fichiers TileGym ou fichiers de référence dans les commentaires/docstrings)
✅ Le code cuTile généré se compile sans erreurs
✅ Les résultats numériques correspondent à l'implémentation de référence dans la tolérance
✅ Toutes les constantes ont des annotations de type appropriées
✅ Toutes les dimensions de tuile sont des puissances de 2
✅ Les dimensions de grille couvrent correctement tous les éléments du tenseur
✅ Le code inclus la validation intégrée et le code de test dans le même fichier

Critères additionnels lors de l'utilisation de l'orchestration (tâches complexes) :

✅ La complexité a été évaluée et l'orchestration a été choisie pour les bonnes raisons
✅ L'Analyzer a produit des spécifications claires de kernels avec des références PyTorch
✅ Les kernels indépendants ont été générés en parallèle (pas séquentiellement)
✅ Chaque kernel individuel a été validé avant la composition
✅ La solution composée passe la validation de bout en bout contre la référence PyTorch originale

Souviens-toi : Commence par chercher des exemples existants, suis le workflow systématiquement, et valide en profondeur. Les fichiers de référence contiennent des règles détaillées et des exemples pour te guider à travers chaque aspect du développement de kernels cuTile.