compileiq-booster-pack

Try curated .acf candidates before running a full CompileIQ search. A Booster Pack is a zip of ACFs that NVIDIA validated against a specific workload family. They are not guaranteed speedups; treat every candidate as workload-specific and validate it on your own benchmark.

Authoritative narrative: docs/booster_packs.md, docs/flashinfer_booster.md.

When

If this is true	Use this path
Workload is close to a Booster Pack's intended workload, compiler, GPU, and validation context.	Try the Booster Pack first.
Workload differs materially or no pack candidate helps.	Run a full CompileIQ search (`compileiq-run-search`).
Baseline, correctness check, compiler path, or benchmark setup are not in place.	Wait. Fix those before applying any ACF.

Available packs (today)

Pack	Workloads it was validated against	Notes
`booster-pack-helion.zip`	Helion FP8 Quantization, Causal Depthwise Convolution, Gated DeltaNet Forward	Has shown benefit on FlashInfer `BatchDecodeWithPagedKVCacheWrapper`; related attention workloads worth testing.
`booster-pack-debug.zip`	Diagnostic ACFs (`O0`, `O3`, others that disable or alter selected optimizations)	Not for speed; for debugging. Use the O0/O3 canary below before trusting any other pack.

The public release shape is documented in docs/booster_packs.md. Read each candidate's compiler_stages from its pack manifest and use every listed stage. There is no runtime download API today. Don't invent one.

Steps

0. Pre-flight: the O0/O3 ACF-injection canary (mandatory first step)

The most common silent failure when applying ACFs is a framework cache (Triton, Helion, FlashInfer's flashinfer_cubin/flashinfer_jit_cache, NVCC build cache) serving a stale binary that ignored the ACF. The Debug pack has two ACFs with predictable, opposite-direction signatures:

ptxas_opt0.acf: forces unoptimized PTXAS compilation. Applied → expect a measurable regression (often 2-10x slower) vs. baseline.
ptxas_opt3.acf: forces the default PTXAS optimization level. Applied → expect to match baseline (the no-ACF default is already -O3).

# Baseline
T_BASE_MS=$(./run-benchmark.sh)
 
# O0 must regress
PTXAS_OPTIONS=

If this fails, stop. Fix the cache-bust before trying any real pack candidate:

Triton: export TRITON_ALWAYS_COMPILE=1, unique TRITON_CACHE_DIR per eval.
Helion: export HELION_SKIP_CACHE=1.
FlashInfer: confirm flashinfer_cubin and flashinfer_jit_cache packages are absent (docs/flashinfer_booster.md:56-64).
Raw nvcc: clean the build dir between candidates.

1. Download

Browse https://github.com/NVIDIA/CompileIQ/releases, find the latest tag matching booster-packs-*, and download the relevant pack zip plus the top-level booster-pack-catalog.json.

Always read the per-pack manifest before applying: it lists the intended workload, compiler version, GPU target, validation context, and known caveats. For a reproducible rerun, set BOOSTER_TAG to the exact tag printed above.

2. Apply one ACF at a time

Target	Injection
Raw PTXAS	`ptxas -v -arch=sm_100 --apply-controls candidate.acf kernel.ptx`
NVCC (CUDA source)	`nvcc -Xptxas --apply-controls=candidate.acf -arch=sm_100 kernel.cu -o exe`
Triton	`PTXAS_OPTIONS="--apply-controls=candidate.acf" TRITON_ALWAYS_COMPILE=1 python bench.py`
Helion	Helion's official ACF API + `HELION_SKIP_CACHE=1` (see `helionlang.com/examples/acfs/softmax_acf.html`).
FlashInfer	`FLASHINFER_EXTRA_CUDAFLAGS="--ptxas-options=--apply-controls=$ACF_FILE" python bench.py` (see `docs/flashinfer_booster.md:107`).

Apply exactly one ACF per run. If it fails to compile, hangs, crashes, returns wrong answers, or regresses, reject that candidate and move to the next.

3. Validate every candidate

Compare against a known-good reference (correctness, not just speed).
Test multiple input shapes when shape matters.
Use compile and runtime timeouts to bound runaway candidates.
Run multiple performance trials if the benchmark is noisy.
Record the reproducibility checklist below (one row per candidate).

4. Reproducibility log

For every candidate you accept or reject, append a row to booster-pack-log.csv with:

ACF filename (and sha256)
Manifest / release version
Benchmark command
GPU model + driver version
CTK version
nvcc and ptxas paths + versions
Framework version or commit
Input shape
Baseline result (mean ± std)
Candidate result (mean ± std)
Correctness status
Decision: KEPT or REJECTED:<reason>

This is the same checklist docs/flashinfer_booster.md:135-148 recommends. The scripts/apply_one_acf.sh helper does most of this automatically.

Self-test

Dry-runs a "baseline vs baseline" comparison (no ACF applied to either side) and confirms the helper correctly reports "NOT a real improvement". Catches misconfigured script invocations before they pollute the reproducibility log.

Gotchas

Pack name is not a hard boundary. Helion Pack helps some FlashInfer cases (docs/booster_packs.md:34); test before assuming.
Booster Packs are not search-space inputs. Don't try to feed an ACF through PtxasSearchSpace(...); packs are already-generated .acf candidate bundles, not inputs to PtxasSearchSpace or NvccSearchSpace.
Force recompilation. If you can't prove a recompile happened between candidates, don't trust the measurement. See the cache-bust hints under the pre-flight canary.

If no pack candidate helps your workload, go to compileiq-run-search for a full CompileIQ search over PtxasSearchSpace().
For attention workloads specifically, also see compileiq-search-space (variant="att").*