[andriy-ca]

JIRA ID : AICK-2523

This PR now also carries #13432 (kernel selection and the runbook), which was reviewed and approved there and merged into this branch. It has two commits: the training-data step, then #13432's.

Why

A full sweep builds every kernel of a configuration space and times it on every problem it can run, which can take days for a large space over many problems. A model trained on earlier measurements can rank each problem's candidates so that only its top K are built and timed, and a sweep of the same problems measures how good the picks are. This PR adds the two heuristics-side steps of that workflow, turning the tile_engine GEMM driver's results into training data and picking the kernels to measure, plus a runbook for the whole workflow (HEURISTIC_BENCHMARKING.md). The driver-side options it uses are in #13430.

Training data: the heuristic trains on canonical parquet rows (data_pipeline.CANONICAL_COLUMNS), and no in-tree tool converted the driver's CSV into them. convert_csv_to_parquet.py's generic path matches only gemm_universal_ names, so for the driver's gemm_<dtype>_... kernels it kept dtype and pipeline and lost tile, warps, warp tile, padding, epilogue and vector widths; it wrote non-canonical columns (M, tflops) and kept rows that failed --verify as labels.

What changes

Training data from the driver's CSV:

• data_pipeline.parse_gemm_driver_csv(path, arch): canonical rows from a gemm_full_benchmark.py CSV. Kernel fields, dtype and layout come from parse_kernel_name (vector widths included, 0 = native). Rows with verified=False are dropped and counted; an empty verified (no --verify) is kept. A name that does not decode raises. Floats are read round-trip. bandwidth_gb_s counts A and B in the input dtype and C in the driver's output dtype (fp16 for fp8/bf8).
• data_pipeline.py accepts a .csv input.
• convert_csv_to_parquet.py detects a driver CSV, delegates to it and adds the arch's HW_PROFILES constants. Batched GEMM results keep their own path, checked first; every other CSV keeps the generic path.

Kernel selection and the runbook (from #13432):

• dispatcher/heuristics/select_kernels.py: ranks the candidates from gemm_full_benchmark.py --list-pairs with Predictor.rank_kernels and writes the top K per problem as a --pairs file for the driver, plus a CSV of the picks (problem, rank, kernel, predicted TFLOP/s).
  • The candidates are the driver's own pairs, after its vector-width and tile rules, so every pick can launch.
  • Ties in the predicted value break on the kernel name.
  • The driver's field names map to the feature engine's (wave_* -> warp_*, vector_size_* -> vec_*).
  • It refuses a model trained for another dtype or arch, and non-universal variants.
• dispatcher/heuristics/HEURISTIC_BENCHMARKING.md, a runbook: when the workflow applies, prerequisites and inputs, the reference sweep, training data and model, candidates and selection, measuring the picks, scoring them against the sweep, cost, and troubleshooting. It is linked from the heuristics README and the tile_engine GEMM README, and whitelisted in dispatcher/heuristics/.gitignore like the other tracked docs.
• README: the conversion step under Quick Start.

Testing

• tests/test_driver_csv.py (10 tests): canonical columns, fields from names, the verify filter, exact floats, bandwidth for bf16 and fp8, hardware constants, the generic path for other CSVs, the data_pipeline.py CLI, and that GemmUniversalVecFeatureEngine.extract_batch reads the result.
• tests/test_select_kernels.py (13 tests):
  • field mapping, top-K and tie-breaking, and the model/run checks;
  • an end-to-end run on the in-tree gemm_universal_fp16_gfx950 model;
  • the runbook's scoring snippet, executed on constructed data;
  • every option the runbook's commands use exists in that script's argparse. The driver part skips until feat(tile_engine): measurement options for the GEMM sweep driver #13430 is in the tree.
• Heuristics suite on develop with this PR: 576 passed, 2 skipped.
• Real driver CSVs converted and trained with train.py --operation gemm_universal_vec: the model's spec records the vector-width engine, encoding version 1, 78 features and the arch's LDS capacity.
• With feat(tile_engine): measurement options for the GEMM sweep driver #13430 merged in, the runbook's steps run as written. Training data, train.py, --list-pairs and select_kernels.py ran for real; the sweep and the picks run used stand-ins for the compiler and GPU. Only the picks' kernels were built, the measured pairs equalled the picks, and the scoring snippet ran on the outputs.

Merge order

#13430 -> this PR

The runbook documents #13430's driver options, so #13430 merges first.

🤖 Generated with Claude Code

[therock-pr-bot]

✅ All Checks Passed — Ready for Review

Check	Status	Details
📝 PR Description	✅ Pass	—
⛔ Forbidden Files	✅ Pass	—
🧪 Unit Test	✅ Pass	—
🔎 pre-commit	✅ Pass	—
🚫 Draft PR	🔜 To Be Enabled	—
🚩 Feature Flag	🔜 To Be Enabled	—
📊 Code Coverage	🔜 To Be Enabled	—
🤖 therock-pr-bot	✅ Pass	—

🎉 All checks passed! This PR is ready for review.

📖 Need help? See the Policy FAQ for details on every check and how to fix failures.

🙋 Wish to Override Policy?

[therock-pr-bot]

🎉 All checks passed! This PR is ready for review.

[andriy-ca]

@illsilin thanks for approving #13432. It was stacked on this PR, so merging it landed its commit on this branch rather than on develop: this PR now carries both the training-data step and the kernel selection + runbook from #13432. I rebased it onto current develop (one conflict with the batched GEMM path in convert_csv_to_parquet.py, resolved by keeping both paths) and updated the description to cover both parts.

The runbook documents the driver options in #13430, so #13430 should merge before this PR.

[assistant-librarian]

TheRock Submodule Bump Activity

Newest first

• 2026-10-30 — Included in TheRock via ROCm/TheRock#9626.