Kernel

This library is in flux. APIs may change without notice. Generated from source on 6/15/2026.

High-performance computation primitives inspired by shader languages.

kernel.kz

Koru Standard Library: Computation Kernels ============================================ High-performance computation primitives inspired by shader languages. Describe RELATIONSHIPS between data elements, not iteration patterns. The compiler decides optimal data layout and iteration strategy. USAGE: ~import std/kernel // 1. Declare the shape (structure with explicit types) ~std/kernel:shape(Body) { x: f64, y: f64, z: f64, vx: f64, vy: f64, vz: f64, mass: f64 } // 2. Initialize kernel data (creates instance of shape) // Uses Koru syntax (x: value) which transforms to Zig (.x = value) ~std/kernel:init(Body) { x: 0, y: 0, z: 0, vx: 1.0, vy: 0, vz: 0, mass: 1.0 } | kernel bodies |> ... // 3. Perform kernel operations std/kernel:pairwise { bodies.vel -= d * mag * bodies.other.mass bodies.other.vel += d * mag * bodies.mass } DESIGN: - kernel.shape is [norun] - just a declaration, sits in AST as metadata - kernel.init is [transform] - looks up shape, emits struct + instance - kernel.pairwise is [transform] - emits iteration code KERNEL OPERATIONS: - kernel.pairwise: All unique pairs (i,j where i < j) - kernel.self: Per-element operations (future) - kernel.reduce: Reduction to single value (future) - kernel.cross: Cross-product of two kernels (future) MAGIC BINDINGS: Inside kernel.pairwise: - `bodies` refers to the current element (self, bodies[i]) - `bodies.other` refers to the paired element (bodies[j])

// ============================================================================
// KERNEL.SHAPE - Declare kernel data structure (just metadata, no execution)
// ============================================================================
// 
// Declares the STRUCTURE of kernel data with explicit types.
// This is NOT a transform - it just sits in the AST for kernel.init to look up.
// 
// Example:
//   ~std/kernel:shape(Body) { x: f64, y: f64, z: f64, mass: f64 }
~[norun]pub event shape {
    expr: Expression,
    source: Source
}

// ============================================================================
// Internal no-op event for refactored flows
// (This is here for reference; the transform injects a local one into the user program)
~[norun]pub event nop {}

// ============================================================================
// 
// Creates kernel data from a shape. Looks up the shape by name, emits
// the struct definition and initialization code, replaces the flow.
// 
// Example:
//   ~std/kernel:init(Body) { x: 0, y: 0, mass: 1.0 }
//   | kernel bodies |> ...
// 
// Koru syntax "x: 0" transforms to Zig syntax ".x = 0"
// 
// This transform:
//   1. Looks up kernel.shape(Body) in AST
//   2. Emits a module-scope type declaration for Body
//   3. Generates a local init event+proc that allocates kernel data and returns a view
//   4. Rewrites the flow to call that init event
~[comptime|transform|claims_descendants]pub event init {
    expr: Expression,
    source: Source,
    invocation: *const Invocation,
    item: *const Item,
    program: *const Program,
    allocator: std.mem.Allocator
}
| transformed SiteResult

// ============================================================================
// KERNEL.PAIRWISE - Pairwise iteration over kernel data (TRANSFORM)
// ============================================================================
// 
// Iterates over all unique pairs (i, j) where i < j.
// The kernel variable becomes "self" and .other refers to the paired element.
// 
// Example:
//   std/kernel:pairwise {
//       bodies.vel -= d * mag * bodies.other.mass
//       bodies.other.vel += d * mag * bodies.mass
//   }
// 
// Generated code:
//   const __kernel_pair = struct {
//       inline fn call(noalias b1: *@TypeOf(bodies.ptr[0]), noalias b2: *@TypeOf(bodies.ptr[0])) void {
//           b1.vel -= d * mag * b2.mass;
//           b2.vel += d * mag * b1.mass;
//       }
//   };
//   for (0..bodies.len) |i| {
//       for (i+1..bodies.len) |j| {
//           __kernel_pair.call(&bodies.ptr[i], &bodies.ptr[j]);
//       }
//   }
~[comptime|transform]pub event pairwise {
    expr: ?Expression,
    source: Source,
    invocation: *const Invocation,
    item: *const Item,
    program: *const Program,
    allocator: std.mem.Allocator
}
| transformed SiteResult

// ============================================================================
// KERNEL.SELF - Per-element operation over kernel data (TRANSFORM)
// ============================================================================
// 
// Iterates over every element individually.
// k.X refers to the current element (no k.other).
// 
// Example:
//   std/kernel:self { k.vel += k.force * dt }
// 
// Generated code:
//   const ptr = k.ptr;
//   for (0..N) |i| {
//       ptr[i].vel += ptr[i].force * dt;
//   }
~[comptime|transform]pub event self {
    expr: Expression,
    source: Source,
    invocation: *const Invocation,
    item: *const Item,
    program: *const Program,
    allocator: std.mem.Allocator
}
| transformed SiteResult

// Kernel:step - wraps kernel ops in an outer iteration loop
// Kernel:step - wraps kernel ops in an outer iteration loop.
// The proc removes step from the AST after init's fusion consumes it.
~[comptime|transform]pub event step {
    expr: ?Expression,
    invocation: *const Invocation,
    item: *const Item,
    program: *const Program,
    allocator: std.mem.Allocator,
}
| transformed SiteResult