kernelfoundry

KernelFoundry - Python package for GPU kernel generation and evaluation.

Module Attributes

PACKAGE_ROOT	The installed (or checked-out) kernelfoundry package directory.
CONFIG_DIR	Hydra config tree.

class kernelfoundry.TestBase

Base class from which kernel task tests must derive.

Example

The following shows how to define a test by deriving from TestBase:

# This is a partial example; see templates for a complete task.
from pathlib import Path
import torch
import pytest
from kernelfoundry import TestBase

# ... pytest fixtures for device/kernel/data are omitted for brevity.

class TestRelu(TestBase):
    def build(self, gpu_arch) -> list[str]:
        return self.compile_torch_extension(
            extension_name="relu_kernel",
            src="relu_kernel.sycl",
            output_dir=Path(__file__).parent,
            gpu_arch=gpu_arch,
        )

    def test_correctness(self, data, kernel, device):
        x, y = data
        assert torch.allclose(kernel(x), y, rtol=1e-4, atol=1e-4)

    @pytest.mark.performance
    def test_benchmark(self, data, kernel, device, measure_runtime_torch):
        # measure_runtime_torch fixture is provided by kernelfoundry/conftest.py
        x, _ = data
        measure_runtime_torch(kernel, device, args=(x,))

build(gpu_arch, **buildtime_params) → list[str]

Builds the kernel and returns a list of build artifacts required for running the tests.

Returns:

List of paths to the build artifacts. The artifacts must not

be outside of the task folder structure.

Return type:

list[str]

build_reference(gpu_arch, **buildtime_params) → list[str]

Builds the reference code and returns a list of build artifacts required for running the tests.

Returns:

list of paths to the build artifacts. The artifacts must not

be outside of the task folder structure.

Return type:

list[str]

static compile_torch_extension(extension_name: str, src: str | Path, output_dir: str | Path, gpu_arch: str, timeout: int = 120, backend: str = 'torch') → list[str]

Compiles the source file to a PyTorch extension.

Parameters:

• extension_name (str) – Name of the PyTorch extension to build.

• src (str) – Path to the source file.

• output_dir (str) – Directory to store the compiled outputs.

• gpu_arch (str) – GPU architecture string.

• timeout (int) – Timeout for each compilation step in seconds.

• backend (str) – The backend to use for compilation. This is either ‘torch’ (default) or ‘icpx’.

Returns:

List of paths to the compiled extensions.

Return type:

list[str]

static get_machine_gpu_arch() → str

Returns the GPU architecture string of the local machine.

Returns:

GPU architecture string.

Return type:

str

static validate()

Hook for task-specific validation of the task definition.

Override in a subclass to assert anything that must hold before a job starts – for example that required data files are present, or that a build script is executable. The default implementation does nothing.

kernelfoundry.PACKAGE_ROOT = PosixPath('/home/runner/work/kernelfoundry/kernelfoundry/kernelfoundry')

The installed (or checked-out) kernelfoundry package directory.

kernelfoundry.CONFIG_DIR = PosixPath('/home/runner/work/kernelfoundry/kernelfoundry/kernelfoundry/configs')

Hydra config tree. Ships as package data, so this exists in a wheel too.

Modules

algorithm	Algorithm code of kernelfoundry (runs evolutionary algorithm).
compiler	Kernel compilation helpers for building PyTorch extensions.
conftest	This is the conftest file for configuring pytest for kernelfoundry tasks.
custom_test	Compatibility shim for the old kernelfoundry.custom_test API.
eval_pipeline	Evaluation pipeline module for kernelfoundry.
gui	NiceGUI frontend to visualize results and logs.
mcp_server	MCP server for running the KernelFoundry evaluation pipeline as a tool in an agentic workflow.
test_base	Base class for custom task tests from which all tests must derive.
testing	Testing utilities for kernel output validation.
utils	Utility helpers for kernelfoundry.