compileiq-search-space

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,
)

# Default — auto-fetch latest PTXAS 13.3 default variant from GitHub releases
ss = PtxasSearchSpace()

# Pinned for reproducibility
ss = PtxasSearchSpace(version="13.3", variant="default", tag="search-spaces-2026.05")

# **Attention** workloads (FlashAttention / GQA / MHA / MLA / FlashInfer Batch Decode)
ss = PtxasSearchSpace(version="13.3", variant="att")

# NVCC variant for full-pipeline tuning
ss = NvccSearchSpace(version="13.3")

# Single .bin you already have on disk — skips manifest + network
ss = LocalSearchSpaceBin("/path/to/ptxas13.3_search_space.bin")

# Pass to Search
from compileiq.ciq import Search
tuner = Search(objective_function=..., search_space=ss, search_config=...)

Variants available today

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

To enumerate variants in the latest release at any time:

gh release view --json assets --jq '.assets[].name' -R NVIDIA/CompileIQ <tag>

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:

# On a connected host
mkdir -p /shared/ciq-search-spaces
gh release download search-spaces-latest -R NVIDIA/CompileIQ -D /shared/ciq-search-spaces

# Move the directory to the air-gapped host (rsync, scp, sneaker-net, …)

# On the air-gapped host
export CIQ_SEARCH_SPACES_DIR=/shared/ciq-search-spaces
python -c "from compileiq.search_spaces.compilers import PtxasSearchSpace; print(PtxasSearchSpace().retrieve())"

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:

import compileiq.search_spaces.base as ss

search_space = {
    "block_size":  ss.choice([64, 128, 256, 512]),
    "unroll":      ss.range(start=1, end=8, step=1),
    "use_shmem":   ss.literal(True, knockout_prob=0.5),
    "lr":          ss.log_sampling(start=1e-5, end=1e-1, total=20),
}

Mixed user + compiler search space (list shape):

search_space = [
    {"config_idx": ss.range(0, len(CONFIGS) - 1)},   # user-defined
    PtxasSearchSpace(version="13.3"),                # compiler-side
]

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

# Default variant resolves
python -c "
from compileiq.search_spaces.compilers import PtxasSearchSpace
p = PtxasSearchSpace().retrieve()
assert p.exists() and p.stat().st_size > 0, p
print(f'default OK: {p}')
"

# Attention variant resolves
python -c "
from compileiq.search_spaces.compilers import PtxasSearchSpace
p = PtxasSearchSpace(version='13.3', variant='att').retrieve()
assert p.exists() and p.stat().st_size > 0, p
print(f'att OK: {p}')
"

# Misconfigured air-gap mirror produces a clear error
CIQ_SEARCH_SPACES_DIR=/nonexistent python -c "
from compileiq.search_spaces.compilers import PtxasSearchSpace
try:
    PtxasSearchSpace().retrieve()
    print('UNEXPECTED: should have failed')
except Exception as e:
    print(f'expected failure: {type(e).__name__}')
"

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.

Next

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