| name | compileiq-bootstrap |
| description | Use when starting a fresh CompileIQ project, hitting a socket timeout, or before running any other compileiq-* skill. Verifies CUDA 13.3+, ptxas, GPU access, that `from compileiq.ciq import Search` and friends resolve, and that `PtxasSearchSpace().retrieve()` returns a real path. Documents the env vars that control timeouts, caching, and search-space mirroring. Triggers on "set up compileiq", "compileiq doesn't work", "socket timeout", "where do search spaces come from", "air-gapped compileiq".
|
| when_to_use | - First time a user opens a CompileIQ project.
- Search() hangs on its first evaluation (almost always a non-BLAS cause now).
- Before invoking any other compileiq-* skill in this session.
Don't use when: the env is already validated in this session.
|
| license | Apache-2.0 |
| metadata | {"version":"1.0.0","author":"NVIDIA CompileIQ","domain":"compiler-optimization"} |
| allowed-tools | Bash Read |
| paths | ["**/*.py","**/*.cu","**/*.acf","**/*.yaml","**/*.yml"] |
compileiq-bootstrap
Validate that a host can run CompileIQ. No installation of system libraries
(that's distro-specific and out of scope). No state files. Just a checklist
that either passes or prints the precise next fix.
When
- First-time setup on a new host or container.
Search().start() hangs on the first evaluation.- After upgrading CUDA, the
compileiq wheel, or the Python venv.
Steps
1. CUDA toolkit 13.3+
CompileIQ's --apply-controls mechanism requires CUDA 13.3 or later
(see examples/compilers/nvbench_example/optimize_reduction.py:302).
nvcc --version | grep -E "release (1[3-9]|[2-9][0-9])\.[3-9]"
ptxas --version | grep -E "V(1[3-9]|[2-9][0-9])\.[3-9]"
If either command exits non-zero, install or upgrade the CUDA toolkit and put
/usr/local/cuda/bin on PATH and /usr/local/cuda/lib64 on
LD_LIBRARY_PATH.
2. GPU is visible
nvidia-smi --query-gpu=name,compute_cap --format=csv
CompileIQ targets compute capability 9.0 (Hopper / H100) and 10.0 (Blackwell /
B200) most aggressively, but works on any GPU PTXAS supports for the chosen
arch.
3. CompileIQ imports resolve
One shot that covers everything callers will need:
python -c "
from compileiq.ciq import Search
from compileiq.types import INVALID_SCORE, BASELINE_CONFIG, WorkerTypes, ProblemType, SearchConfiguration
from compileiq.search_spaces.compilers import PtxasSearchSpace, NvccSearchSpace, LocalSearchSpaceBin
from compileiq.utils.helpers import save_compiler_config, load_compiler_config
from compileiq.worker import MultiProcessWorker, IsoMultiProcessWorker, RayWorker, AsyncWorker
print('imports OK')
"
If this fails, run pip install compileiq (or pip install -e . from a
source checkout) and re-run.
4. Search-space resolution round-trip
This catches network or air-gapped issues that otherwise surface as
socket-timeout hangs deep inside the first evaluation:
python -c "
from compileiq.search_spaces.compilers import PtxasSearchSpace
p = PtxasSearchSpace().retrieve()
assert p.exists() and p.stat().st_size > 0, p
print(f'resolved: {p}')
"
The first run downloads from GitHub releases and caches under
. Subsequent runs hit the cache.
