compileiq 1.0.2

NVIDIA compiler control optimization engine.

CompileIQ - NVIDIA Compiler HPO

Push GPU kernels further with NVIDIA compiler tuning.

CompileIQ is a hyperparameter optimizer for NVIDIA compiler controls and application parameters. It helps kernel developers tune those controls against workload-specific benchmarks, adding another optimization path for CUDA C++, Triton, and Helion kernels after source-level tuning has plateaued.

Documentation | PyPI | Latest Release | Search Space Catalog Releases | Booster Pack Catalog Releases

What CompileIQ Does

CompileIQ tunes NVIDIA compilers to your workload using the compiler's Advanced Controls interface. At a high level CompileIQ:

• Searches optimal PTXAS and NVCC Advanced Controls for your target kernel.
• Iteratively measures candidates against metrics defined by you (runtime, compile time, power, etc).
• Produces an Advanced Control File (ACF) that can be distributed with the kernel.
• Supports CUDA C++, Triton, and Helion tuning workflows.

Basic Workflow

1. Define the kernel benchmark and objective.
2. Run CompileIQ over the relevant compiler controls.
3. Apply the generated ACF in future builds or JIT compilation.

Tune the compiler to the workload.

See the documentation and examples for more.

Quick install

You can either install through PyPI:

pip install compileiq

Or, build from the the source in this repository yourself:

pip install -e .

Supported platforms

CompileIQ supports Python 3.11, 3.12, and 3.13. Published wheels include the bundled CompileIQ core for Linux x86_64, Linux aarch64, and Windows amd64.

Linux wheels target glibc 2.34 or newer and are tagged manylinux_2_34. See the installation guide for Linux runtime library requirements and Windows runtime notes.

Search Spaces

CompileIQ can retrieve curated compiler search spaces from GitHub release assets and cache them locally. Use PtxasSearchSpace or NvccSearchSpace to select a compiler, compiler version, and optional variant:

from compileiq.search_spaces.compilers import PtxasSearchSpace

search_space = PtxasSearchSpace(version="13.3", variant="att")

For reproducible runs, pin a search-space release tag:

search_space = PtxasSearchSpace(version="13.3", tag="search-spaces-2026.05.05")

Set CIQ_SEARCH_SPACES_DIR to use a local mirror containing manifest.json plus the referenced .bin files. Set CIQ_SEARCH_SPACES_REPO to test or use a different release repository.

Browse the published Search Space Catalog Releases to inspect available catalog assets and release notes.

Environment Configuration Options

Environment Variable	Default Value	Type	Description
CIQ_SOCKET_TIMEOUT	20	int	Controls how long CompileIQ waits for a core response. If you experience timeouts because your search space is too big, consider increasing this value.
CIQ_KEEP_CACHE	False	bool	If set to True, .cache files will not be deleted.
CIQ_PROCESS_MODE	"forkserver"	str	Start method for process-based workers. Set to "fork" for tighter process separation when threads are involved. IsoMultiProcessWorker defaults to "fork" independently.
CIQ_SEARCH_SPACES_DIR	unset	path	Reads compiler search-space manifest.json and .bin files from a local mirror instead of GitHub.
CIQ_SEARCH_SPACES_REPO	NVIDIA/CompileIQ	str	GitHub repository used for search-space release lookups, useful for staging or a future dedicated asset repo.

Examples

The examples/ folder has simple examples for you to get started on using CompileIQ.

For the full user guide, see the CompileIQ documentation.

If you are planning on running examples, you may need additional dependencies:

python -m poetry install --with examples

Documentation development

Install the docs dependencies once:

make install-docs

To preview uncommitted documentation edits from your live worktree:

make docs-preview

Then open http://localhost:8000/main/.

If port 8000 is already in use, stop the existing local docs server first.

Use make docs or make docs-serve when you need to test the multiversion documentation shape used by GitHub Pages. Those commands build from Git refs, so they are not the right choice for checking dirty worktree edits before commit.