Metadata-Version: 2.4
Name: compileiq
Version: 1.0.0
Summary: NVIDIA compiler control optimization engine.
License-File: LICENSE
License-File: NOTICE
Author: NVIDIA Corporation
Maintainer: CompileIQ Team
Maintainer-email: compileiq@nvidia.com
Requires-Python: >=3.11,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: aiohttp (>=3.13.3,<4.0.0)
Requires-Dist: dill (>=0.4.0,<0.5.0)
Requires-Dist: json5 (>=0.14.0,<0.15.0)
Requires-Dist: loguru (>=0.7.2,<0.8.0)
Requires-Dist: msgpack (>=1.1.1,<2.0.0)
Requires-Dist: numpy (>=2.1.3,<3.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: pydantic (>=2.9.2,<3.0.0)
Requires-Dist: ray[default] (>=2.53.0,<3.0.0)
Requires-Dist: requests (>=2.32.5,<3.0.0)
Requires-Dist: tqdm (>=4.67.0,<5.0.0)
Requires-Dist: urllib3 (>=2.6.2,<3.0.0)
Project-URL: Documentation, https://github.com/NVIDIA/CompileIQ/blob/main/README.md
Project-URL: Repository, https://github.com/NVIDIA/CompileIQ
Description-Content-Type: text/markdown

# CompileIQ - NVIDIA Compiler HPO

CompileIQ is a hyperparameter optimizer for tuning NVIDIA compiler controls and application parameters.

## Quick install

You can either install through PyPI:

```bash
pip install compileiq
```

Or, build from the [repo](https://github.com/NVIDIA/CompileIQ) yourself:

```bash
pip install -e .
```

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

```python
from compileiq.search_spaces.compilers import PtxasSearchSpace

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

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

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

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

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

```bash
python -m poetry install --with examples
```

## Documentation development

Install the docs dependencies once:

```bash
make install-docs
```

To preview uncommitted documentation edits from your live worktree:

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

