docs(hipdnn): RFC 0019 Universal Heuristic Descriptor (UHD) - #10255
Open
jdcampbe wants to merge 10 commits into
Open
docs(hipdnn): RFC 0019 Universal Heuristic Descriptor (UHD)#10255jdcampbe wants to merge 10 commits into
jdcampbe wants to merge 10 commits into
Conversation
Introduce the UHD as the kernel-selection follow-up to RFC 0017: a data-driven, per-engine (UED-owned) heuristic that ranks the matched UKDs of a pack. Covers the UHD schema and adapter seam (static_order, table, tree_data, onnx, custom_library), the features_signature and its KMD-backed contract checks, dependency stance (in-tree tree-walker as the default, LightGBM/ONNX as opt-in), the model-generation pipeline, and the engine-selection / estimated-TFLOPS interplay. Grounded in the rocKE LGBM prototype and MIOpen's shipped LightGBM text-model walker. Co-Authored-By: Claude <noreply@anthropic.com>
Remove references to the personal `users/jascampb/fmha-gen-sweep` branch and the one-off "prototype" framing. Present the heuristic-generation pipeline as reusable tooling any package author can run to produce a heuristic for their own pack. Retitle §3.1 and update all cross-references. Co-Authored-By: Claude <noreply@anthropic.com>
Replace the external rocKE pipeline reference with a two-stage, provider-agnostic workflow: ship a pack with a trivial static_order UHD, then run a standalone generation tool that times the shipped kernels via hipDNN autotune (RFC 0013) across a shape corpus, trains a model, and emits an updated tree_data UHD in place. The tool runs over hipDNN's public API only -- no provider internals, no new hipDNN code -- so any package author can use it. Update the two contracts, Stage P packaging, phased delivery, and open questions accordingly; add RFC 0013 as related. Co-Authored-By: Claude <noreply@anthropic.com>
…back Sharpen Section 11 around the goal: an absolute, calibrated figure of merit so engines run per-package heuristics independently yet stay cross-comparable. State the safety valve explicitly -- if calibrated cross-engine comparison proves unreliable, engine selection degrades to classic rank-ordering at the RFC-0007 policy level -- as one named fallback, leaving other cross-engine schemes open for the future. Reframe the calibration OPENs (Section 4, Section 11, Risks, Open Questions) from "mandate calibrated" to "build the absolute path and the rank-ordering backstop together." Co-Authored-By: Claude <noreply@anthropic.com>
… policies Rework the engine-selection interplay (Section 11) to match the refined design: applicability (the matcher pass) bubbles up and rules out engines before ranking; the tooling produces TWO heuristics per engine -- a cheap engine-level expected-performance estimate (A) and the fine-grained config UHD (B); and TWO RFC-0007 policies consume them -- a quick policy (rank by A, drill into the winner's B) and a thorough policy (run every B, compare across engines), with non-descriptor engines (MIOpen) participating at the A level only. Update Section 2 (bubble-up), Section 13 (tool emits both models), the overview, and open questions accordingly. Co-Authored-By: Claude <noreply@anthropic.com>
Reorganize RFC 0018 (Universal Heuristic Descriptor) to improve structure while preserving all technical detail from the original. Key changes: - Reorder sections: ownership model (§4) now precedes schema (§5) - Add dedicated Applicability Flow section (§11) - Add Versioning and Compatibility section (§9) - Consolidate scattered ownership text into §4.1 with ASCII diagram - Group Open Questions by category (Schema/Structural/Operational) - Format Risks as scannable table (all 8 risks preserved) Restored detail that was inadvertently condensed: - §4.3: "Earlier drafts... that gap is now closed" KMD rationale - §4.3: Contract bullets (UKD as point, KDP as collection, subset check) - §5: Full regressor vs. ranker OPEN discussion inline - §8: Two-tier resolution framing (data → escape-hatch → native) - §14.3-14.5: Full Stage P outputs with arch-awareness parentheticals No technical content removed — 2-reader parity verified. Co-Authored-By: Claude <noreply@anthropic.com>
…eview RFC 0018 is claimed by the concurrent UMD/graph-matcher follow-up, so the UHD RFC becomes 0019 and cites the UMD RFC as a sibling. Align with the RFC 0017 review-feedback branch and the UMD RFC: - Knobs reframed: there is one variant-field space (the KMD), and a knob is simply a KMD field the engine exposes -- a name, nothing more. Legal values come from the catalog and a knob's default is whatever the UHD ranks first. This supersedes the earlier runtime-vs-compilation split. - Expression language is JsonLogic, pinned by the UMD RFC; its operator set already includes log2 / min / max / div / sub, so this RFC's request for expression-op extensions is resolved and dropped. - Answer the UMD RFC's open question on feature source: the matcher's bindings ARE the canonical feature source for kernel selection. - Caching corrected: the model cache is per process, not per handle, and results ride the descriptor cache key (engine id, graph id, device id) plus the inventory generation counter. - Heuristic load is triggered by ranking, not winning: answering a knob query ranks a losing engine's catalog. - Note RFC 0017 no longer forecloses cross-engine UHD score comparison, and place the two policies within its existing policy-configuration mechanism alongside explicit selection and auto-tuning. Co-Authored-By: Claude <noreply@anthropic.com>
- $q.* namespace: document that problem fields are op-specific (SDPA, conv, MoE expose different fields); engine is op-scoped - $device.* namespace: document expected fields from rocminfo/rocKE (arch, cu_count, lds_size, etc.) - A vs B heuristics: add suggestion that two-policy design implies A must be distinct — derived A collapses quick/thorough policies Co-Authored-By: Claude <noreply@anthropic.com>
Merge origin/users/jascampb/rfc-uhd-heuristics-descriptor into users/cderb/rfc-uhd, preserving our structural improvements while incorporating upstream content updates: Upstream changes incorporated: - Renumber RFC 0018 → 0019 (0018 is now UMD) - JsonLogic expression language (pinned by sibling UMD RFC) - Knobs reframing as view onto KMD fields - Caching corrections (per-process, triggered by ranking) - Updated section references and glossary entries Our changes preserved: - Section reorganization (commit 2afcd82) - Implementation notes in §7.1 ($q.* is op-specific, $device.* fields) - A vs B suggestion in §12.1 (two-policy design requires distinct A) - Categorized Open Questions (Schema/Structural/Operational) - Consolidated ownership text and grouped open questions Post-merge fixes: - Updated stale section anchors (§6.1 → §4.2, §12.2 short form) - Added impact-site links to all 10 Open Questions Co-Authored-By: Claude <noreply@anthropic.com>
…efinements Two refinements from the merged RFC 0017 review updates: - KMD<->UHD coupling is conditional, not unconditional. An additive KMD change (new field, or new legal values) needs no retrain until it is exposed to selection; only a breaking change (removed/reinterpreted field) must land its retrain in the same change. Update Section 4.3, Section 9.1, the overview, the risks table, and the glossary. - The KMD is a superset of the UHD's features: UHD features are a subset of KMD fields, since the KMD also carries dispatch-only fields a UDD formula consumes. State the subset relationship explicitly. Also fix stale "Section 6.1" cross-reference labels left by the section restructure (now Section 4.2) and drop a duplicated in-scope paragraph. Co-Authored-By: Claude <noreply@anthropic.com>
github-actions
Bot
added
documentation
ci:docs-only
❌ PR Check — Action Required
📖 Need help? See the Policy FAQ for details on every check and how to fix failures. |
|
🚫 Please fix the failed policies before requesting reviews. The following policy checks failed:
The |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds RFC 0019: Universal Heuristic Descriptor (UHD) — the "UHD + kernel selection" follow-up named in RFC 0017 §12.2. It designs the data-driven, per-engine kernel-selection model for the descriptor-based provider, plus the tooling that generates one.
Docs-only: one new file,
projects/hipdnn/docs/rfcs/0019_UniversalHeuristicDescriptor.md.What it covers
adapter) overstatic_order/table/tree_data(default) /onnx/custom_library; the model ships as data with the engine, read by an in-tree interpreter (noliblightgbmruntime dependency).features_signaturein JsonLogic (the language pinned by the sibling UMD RFC), sourced from the matcher's bound symbols; a three-part fail-closed contract check.static_orderpack, then generates and drops in atree_dataUHD — usable by any package author, no provider code changes.Relationship to concurrent RFCs
(engine id, graph id, device id), load-on-ranking, conditional KMD↔UHD coupling.Test plan