optimize-handoff

Handoff d'optimisation (kernel-optimize)

Quand l'objectif est de pousser un noyau vers la limite matérielle (pas seulement un contrôle de perf), ce fichier est l'interface entre Primus-Turbo et la boucle d'optimisation autonome dans ../../kernel-optimize/SKILL.md. Il fournit les informations prérequises dont cette boucle a besoin. Lire d'abord le hub ../SKILL.md.

Processus

1. Vérifier l'environnement — pip show primus_turbo ; réinstaller en mode éditable si ce n'est pas le cas (hub SKILL.md → Build).
2. Lire "Informations prérequises" de kernel-optimize/SKILL.md pour savoir ce dont la boucle a besoin.
3. Collecter les prérequis pour l'opération cible (tableaux ci-dessous + la carte du code / les commandes dans le hub SKILL.md).
4. Handoff vers kernel-optimize/SKILL.md ; il exécute DEFINE_TARGET → PREPARE_ENVIRONMENT → BASELINE → (ANALYZE → OPTIMIZE → VALIDATE)* → REPORT.
5. Acceptation — de retour dans le projet : exécuter la suite complète pytest tests/pytorch/ -v, examiner le rapport, confirmer un diff/commit propre.

Avant le démarrage de la boucle, lire ../../../rules/iteration_rules.mdc : une hypothèse par tour, porte de correction avant la perf, lignée d'acceptation/rollback, et tout gain accepté doit être transféré à une étape d'entraînement réelle (pas de caches d'activation/grad_out indexés par id(...), pas de raccourcis GroupGemm seulement avec distribution uniforme).

Informations prérequises (par opération)

Exigence	Où l'obtenir
Chemin du fichier source du noyau	hub SKILL.md → Code Map
Commande de test ciblée	hub SKILL.md → Test & Bench ; ex. pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and TRITON"
Commande de benchmark ciblée	../verify-performance/SKILL.md ; ex. PRIMUS_TURBO_GEMM_BACKEND=TRITON python benchmark/ops/training/bench_gemm_turbo.py --dtype fp8 --granularity blockwise
Format de sortie / métriques du benchmark	../verify-performance/SKILL.md (Forward/Backward TFLOPS, porte Check)
Harnais de validation rapide	"Validation rapide" ci-dessous
Règles de score	"Score d'optimisation" ci-dessous
execution_mode + reconstruction	"Environnement d'optimisation" ci-dessous

Environnement d'optimisation

Backend / langage	execution_mode recommandé	Reconstruction après modification
Triton (Python)	repo-mode	aucune (installation éditable)
HIP / CK (C++), modifications petites/param	repo-mode	GPU_ARCHS=<arch> pip install --no-build-isolation -e . -v
HIP / CK (C++), nouveau noyau / essais-erreurs lourds	workspace-mode	selon la pile minimale dans kernel-optimize/SKILL.md

Score d'optimisation

La colonne Check est une porte dure — toute forme avec FAIL/ERROR rejette le candidat.

Type de campagne	primary_metric (agrégation = moyenne géométrique sur les formes PASS)
Borne calcul, forward seulement	Forward TFLOPS
Borne calcul, forward + backward (entraînement)	Combined Step TFLOPS (forward/backward conservés comme diagnostics)
Borne mémoire (elementwise, quant)	Forward GB/s / Backward GB/s

La dérivation de l'étape combinée (préférée pour les ops de type GEMM fwd+bwd) se trouve dans ../verify-performance/SKILL.md. Confirmer primary_metric avec l'utilisateur à DEFINE_TARGET.

Validation rapide

Deux outils, rôles séparés — ne pas comparer les nombres absolus entre eux (ils utilisent des moteurs de chronométrage différents) :

• quick_test_bench.py (ce dossier, copié dans le répertoire de campagne) est la source faisant autorité pour la porte de régression par forme de tour en tour. BASELINE (tour-1) et chaque tour VALIDATE exécutent CE script et comparent sa sortie --summary-csv. Il utilise une boucle time.perf_counter maison.
• le bench_<op>_turbo.py complet (voir ../verify-performance/SKILL.md, torch.utils.benchmark.Timer) est utilisé seulement pour (i) choisir les representative_shapes de l'ensemble complet des formes et (ii) effectuer l'acceptation finale après la campagne.

Les deux niveaux de validation s'exécutent via quick_test_bench.py, ne différant que par SHAPES :

• validation complète (BASELINE + acceptation finale) → SHAPES = toutes les target_shapes.
• validation rapide (chaque tour VALIDATE) → SHAPES = le sous-ensemble de 3-5 representative_shapes.

representative_shapes : seules les formes avec Check=PASS de l'exécution BASELINE, couvrant les petites échelles (surcharge de lancement) + grandes échelles (calcul/mémoire), en privilégiant les formes à variance élevée. Les enregistrer dans manifest.yaml: representative_shapes.

Harnais : le modèle quick_test_bench.py est la référence canonique. Pendant PREPARE_ENVIRONMENT, le copier dans <campaign_dir>/quick_test_bench.py avec SHAPES vide et <target_backend> défini ; remplir SHAPES avec toutes les target_shapes pour BASELINE, puis le réduire à representative_shapes pour les tours VALIDATE. Adapter l'opération/configuration pour votre cible ; conserver le rédacteur --summary-csv et le schéma de colonnes (voir la note de portée du schéma ci-dessous pour les ops non-GEMM).

Contrat de cohérence de mesure : BASELINE (tour-1) et chaque VALIDATE lisent le même CSV faisant autorité via --summary-csv, analysé de manière identique d'un tour à l'autre par le même lecteur CSV — l'assistant MCP optionnel mcp__turbo__parse_bench_csv s'il est configuré, sinon un csv.DictReader direct indexé sur les colonnes ci-dessous. Le lecteur spécifique n'a pas d'importance ; ce qui compte, c'est de figer le schéma. Le schéma DOIT correspondre exactement à ces colonnes (toute dérive désactive silencieusement la porte de régression par forme) :

label,B,M,N,K,Check,Forward TFLOPS,Forward TFLOPS_stddev,Backward TFLOPS,Backward TFLOPS_stddev,Forward Time (ms),Backward Time (ms),out_snr,da_snr,db_snr

Check utilise PASS / FAIL ; *_stddev sont les écarts-types absolus dans l'unité de la métrique. Enregistrer l'invocation dans manifest.yaml comme quick_command: "python <campaign_dir>/quick_test_bench.py" ; BASELINE et chaque VALIDATE ajoutent --summary-csv <round_dir>/artifacts/benchmark.csv.

Portée du schéma : les colonnes ci-dessus sont spécifiques à la classe GEMM (dimensions M,N,K, Forward/Backward TFLOPS, out_snr/da_snr/db_snr). Pour une opération non-GEMM, conserver label, Check et la convention *_stddev, mais remplacer les colonnes propres à GEMM par celles dont votre primary_metric a besoin — par exemple, une opération bornée mémoire (selon "Score d'optimisation") utilise Forward GB/s / Backward GB/s au lieu de TFLOPS, et une opération à sortie unique remplace out_snr/da_snr/db_snr par sa propre métrique de correction. Quel que soit le schéma choisi, le figer à BASELINE, le garder byte-identique à tous les tours, et mettre à jour le lecteur CSV que vous utilisez (la correspondance mcp__turbo__parse_bench_csv si elle est configurée, sinon votre csv.DictReader direct) pour correspondre — la porte de régression par forme s'appuie sur les noms exacts des colonnes.