# Kernelin

> Kernelin is a K2 compiler plugin for Kotlin 2.4.21. It translates plain Kotlin functions marked @Kernel into WGSL compute shaders that run on any GPU through WebGPU. The same functions still run on the CPU (KernelinCpu) for unit tests. Version 0.4.0 is on Maven Central (group io.github.rajumark, Gradle plugin id io.github.rajumark.kernelin).

Key rules for writing a kernel: top-level function, returns Unit, parameters only FloatArray / IntArray / Int / Float / Boolean, start with `val i = globalId()`, write results into an array at index i, Float literals with `f`, no Double / Long / String / lambdas (except repeat) / recursion / classes / nullable types, math only from kotlin.math (Float versions). Run it with `KernelinCpu.dispatch(size) { kernel(...) }` on the CPU, or on the GPU from Kotlin/Wasm (and natively on Android 8.0+ and in desktop JVM apps on macOS, Linux x64 and Windows x64 through jWebGPU/wgpu, JDK 21+, no browser; since 0.4.0) with `gpu.dispatch(size) { kernel(...) }` (typed, checked by the compiler; the arrays the kernel writes hold the results; since 0.4.0); on devices that may have no GPU use `Compute.create().dispatch(size) { kernel(...) }`, which runs on the GPU when there is one and on the CPU otherwise (also after a lost device; since 0.4.0) or `WebGpu.create().load(kernelSource(::kernel)).run(size, scalars, buffers)` (add `readBack = emptySet()` and pass `GpuData.of(result.buffer(name))` to the next run to keep data on the GPU; `load` and `run` throw `GpuException` on WebGPU errors or a lost device; `close()` frees GPU memory). Supported projects: Kotlin JVM, Android (Kotlin Android plugin or AGP 9 built-in Kotlin), and Kotlin Multiplatform with JVM, Android, JS, Wasm and Native (iOS, macOS, tvOS, watchOS, Linux, Windows) targets (since 0.3.0). Gradle setting: `kernelin { enabled = false }`. 2D/3D thread ids (since 0.4.0): `globalIdX()`, `globalIdY()`, `globalIdZ()` with `KernelinCpu.dispatch(width, height) { k(...) }`, `gpu.dispatch(width, height) { k(...) }`, `Compute.dispatch(width, height) { k(...) }` or `run(width, height, scalars, buffers)` (3D: add `depth`); `globalId()` is then `x + y * width + z * width * height`, the index in a flat row-major array; in a 1D launch x == globalId() and y = z = 0. Random numbers (since 0.4.0): `randomFloat(seed, globalId(), stream)` in [0, 1), `randomInt`, `randomIntBelow(bound, seed, index, stream)`, `randomNormal`; stateless, same bits on CPU and GPU (`randomNormal` within about 1e-5).

## Docs

- [Full documentation (Markdown)](https://rajumark.github.io/kernelin/docs.md): install, writing kernels, supported Kotlin subset, CPU and GPU runners, API reference, compiler internals, generated WGSL layout, manifest format, troubleshooting
- [For AI agents](https://rajumark.github.io/kernelin/docs.html#for-ai-agents): strict rules, kernel / test / GPU templates, AGENTS.md snippet, self-check
- [Documentation (HTML)](https://rajumark.github.io/kernelin/docs.html)

## Code

- [Repository](https://github.com/rajumark/kernelin): source of the runtime, compiler plugin, WebGPU host and Gradle plugin
- [Sample kernels](https://github.com/rajumark/kernelin/blob/main/samples/src/commonMain/kotlin/io/github/rajumark/kernelin/samples/Kernels.kt): vectorAdd, saxpy, mandelbrot, waves, blur
- [Examples](https://github.com/rajumark/kernelin/tree/main/examples): hello-jvm and hello-multiplatform projects

## Optional

- [Changelog](https://github.com/rajumark/kernelin/blob/main/CHANGELOG.md): released versions plus an "Unreleased" section for main
- [CONTRIBUTING.md](https://github.com/rajumark/kernelin/blob/main/CONTRIBUTING.md): rules for changing the compiler
- [VERSIONING.md](https://github.com/rajumark/kernelin/blob/main/VERSIONING.md): compatibility policy and what counts as public API
- [Live demo](https://rajumark.github.io/kernelin/demo/): a Mandelbrot computed on your GPU by Kernelin-generated code
- [Benchmarks (JSON)](https://github.com/rajumark/kernelin/blob/main/benchmarks/2026-10-15-apple-m5.json): Apple M5
- [JVM GPU host benchmarks (JSON)](https://github.com/rajumark/kernelin/blob/main/benchmarks/2026-10-20-apple-m5-jvm.json): Apple M5, native WebGPU from a plain JVM app
- [Android benchmarks (JSON)](https://github.com/rajumark/kernelin/blob/main/benchmarks/2026-10-16-moto-g57-power.json): moto g57 power, Adreno GPU in Chrome
- [Android native benchmarks (JSON)](https://github.com/rajumark/kernelin/blob/main/benchmarks/2026-10-20-moto-g57-power-native.json): moto g57 power, Adreno 710 through AndroidX WebGPU in an app
- [Android native benchmarks, fewer copies (JSON)](https://github.com/rajumark/kernelin/blob/main/benchmarks/2026-10-20-moto-g57-power-native-fewer-copies.json): the same phone after the Android host stopped copying the data more than once; end-to-end faster than Chrome for all 5 kernels