compileiq-search-space

CompileIQ ships compiler search spaces as release-backed binary blobs that the providers in compileiq.search_spaces.compilers fetch on demand. This skill covers the three provider classes, the variants they expose today, how to use them offline, and how to define a custom search space for non-compiler tuning.

When

Choosing a search space for a new project.
Pinning a specific release for a paper or production deployment.
Working on an air-gapped or corporate-firewalled host.
Stress-testing a one-off .bin you have on hand.

The three provider classes

Reference: compileiq/search_spaces/compilers.py:66-102.

from compileiq.search_spaces.compilers import (
    PtxasSearchSpace,
    NvccSearchSpace,
    LocalSearchSpaceBin,
)

Variants available today

From release/search-spaces/manifest-source.yaml:

Compiler	Version	Variant	File	When to use
`ptxas`	`13.3`	`default`	`ptxas13.3_search_space.bin`	Generic PTXAS tuning; the right starting point for most kernels.
`ptxas`	`13.3`	`att`	`ptxas13.3_att_search_space.bin`	Attention workloads. `att` is short for attention, not "attribute". This variant is curated for FlashAttention, GQA, MHA, MLA, FlashInfer Batch Decode, and similar attention kernels. Prefer this whenever the kernel is attention-shaped.
`nvcc`	`13.3`	`default`	`nvcc13.3_search_space.bin`	Full-compiler (front-end + back-end) tuning when you want NVCC-level knobs, not just PTXAS.

To enumerate variants in the latest release at any time:

Air-gapped / offline mirror

Pre-download the manifest plus all .bin files on a connected host, then point CompileIQ at the local mirror via CIQ_SEARCH_SPACES_DIR:

Other env-var knobs:

CIQ_SEARCH_SPACES_REPO (default NVIDIA/CompileIQ): override the GitHub repo the resolver queries — useful for staging or forks.
CIQ_SS_TAG_PREFIX (default search-spaces-): tag prefix used when resolving tag="latest". Rarely needs changing.

Cache location

Resolved binaries are cached at ~/.cache/compileiq/<tag>/<sha256_prefix>_<filename>. The resolver verifies cached files by sha256; a corrupted entry is re-downloaded on the next call. Safe to wipe — wiping just costs one re-download.

Custom search spaces (non-compiler tuning)

For hyperparameter tuning, autotuner knobs, or any user-defined space, pass a dict (or list-of-dicts) directly instead of a provider. Primitives live in compileiq/search_spaces/base.py:

Primitive	Purpose
`choice([...])`	Sample uniformly from a discrete list.
`range(start, end, step)`	Range-like sampling (also supports float steps).
`literal(value, knockout_prob=...)`	Constant value; `knockout_prob` lets the GA disable this parameter.
`log_sampling(start, end, total)`	Logarithmic distribution between `start` and `end` with `total` discrete buckets.

Mixed user + compiler search space (list shape):

When the search space is a list, the objective receives a list of the same length — see compileiq-author-objective for the unpacking pattern.

Self-test

Gotchas

att is attention, not "attribute". Earlier docs and a test fixture mislabeled the variant as "attribute-based register allocation" — corrected in this same branch. When recommending the variant to a user, say "attention" explicitly.
Providers vs Booster Packs are different things. Providers return one binary search space the optimization core consumes during a search; Booster Packs are pre-built .acf candidates to apply outside a search. Don't feed a .acf from a Booster Pack to PtxasSearchSpace(...).
LocalSearchSpaceBin doesn't validate .bin contents. It only validates that the file exists. A malformed file will fail downstream when the core tries to parse it; the resulting error message points at the resolver, not the provider.

Writing the objective function that consumes the search space: compileiq-author-objective.
Running the search: compileiq-run-search.