---
name: compileiq-search-space
description: >
  Use when picking the search_space= argument for Search(). Covers the three
  provider classes (PtxasSearchSpace, NvccSearchSpace, LocalSearchSpaceBin),
  how to pin a version/variant/tag, the attention-focused 'att' variant for
  attention kernels (FlashAttention, GQA, MHA, MLA, FlashInfer Batch Decode),
  air-gapped mirroring via CIQ_SEARCH_SPACES_DIR, and custom user-defined
  search spaces built from compileiq.search_spaces.base primitives. Triggers
  on "search space", "PtxasSearchSpace", "NvccSearchSpace", "air-gapped
  compileiq", "offline compileiq", "CIQ_SEARCH_SPACES_DIR", "attention
  variant", "ptxas att".
when_to_use: |
  - About to instantiate Search() and need to pick a search_space.
  - Network-restricted host that can't reach github.com/releases.
  - Have a one-off .bin and want to use it directly.
  - Want to pin a specific search-space release for reproducibility.
license: Apache-2.0
metadata:
  version: "1.0.0"
  author: NVIDIA CompileIQ
  domain: compiler-optimization
allowed-tools: Bash Read
paths: ["**/*.py", "**/*.yaml", "**/*.yml"]
---

# 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`.

```python
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`:

| 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:

```bash
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`:

```bash
# 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`:

```python
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),
}
```

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

```python
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

```bash
# 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`.