spire-opencl

spire-opencl is a Scala 3 library for GPU numeric computing with Typelevel Spire and OpenCL. It turns ordinary Spire typeclass code into an OpenCL kernel by running that code once with symbolic values.

These pages are checked by ./mill docs.mdoc: scala mdoc fences compile, and non-hardware examples also run. Generate the HTML site with ./mill docs.site; mdoc runs first, then Laika renders the checked markdown.

Setup

SBT:

libraryDependencies += "io.github.mercurievv" %% "spire-opencl" % "0.1.7"

Mill:

def mvnDeps = Seq(
  mvn"io.github.mercurievv::spire-opencl:0.1.7"
)

You also need an OpenCL 1.2 runtime and driver. Check what the library sees:

./mill spireOpencl.runMain io.github.mercurievv.spireopencl.opencl.DeviceProbe

The generated kernels use Float. The IR stores constants as Double, but CodeGen emits single precision OpenCL because common devices, including Apple Silicon, do not expose cl_khr_fp64.

Write one numeric program

Write the computation once, polymorphic in the value type:

import spire.algebra.{Field, Trig}
import spire.implicits.*
import spire.math.sin

// Plain Spire code: no OpenCL imports and no library-specific DSL. Args groups the arguments, Answer
// names the result — both ordinary case classes, nothing OpenCL-specific about either.
case class Args[V](b: V, c: V, d: V)
case class Answer[V](value: V)

def program[V: {Field, Trig}](args: Args[V]): Answer[V] =
  Answer(args.b * args.c - sin(args.d))

// With V = Double it is just a normal CPU calculation.
program(Args[Double](2.5, 4.0, 0.75))
// res0: Answer[Double] = Answer(9.318361239976666)

Build a formula

Run the same function with symbolic arguments — Reify.outTyped[Args, Answer] reads Args's field labels for the params and Answer's for the result name, both off the case classes themselves:

import io.github.mercurievv.spireopencl.symbolic.{Reify, TypedFormula, TypedFormula2, instances}
import instances.given

val formula: TypedFormula2[Args, Answer] = Reify.outTyped[Args, Answer](uniforms = Nil) { (_, args) =>
  program(args) // V = Expr, so operators build an expression tree.
}
formula.formula.params
// res1: List[String] = List("b", "c", "d")
formula.outputNames
// res2: List[String] = List("value")

Reify does not inspect Scala code. It applies your function to Expr values and keeps the expression that comes back. Declared names matter: uniforms are scalar launch arguments, params vary by batch element, and inputs are device-resident arrays.

Inspect the kernel

CodeGen lowers the formula to OpenCL C:

import io.github.mercurievv.spireopencl.opencl.CodeGen

CodeGen(formula.formula).linesIterator.take(6).mkString("\n")
// res3: String = """__kernel void compute(__global float* out, __global const float* params) {
//   int i = get_global_id(0);
//   float fi = (float)i;
//   int e = get_global_id(1);
//   int n = get_global_size(0);
//   float v0 = params[e * 3 + 0] * params[e * 3 + 1];"""

Compile and launch

The launch path needs real OpenCL hardware, so this fence is compile-only in the documentation build. It still type-checks against the real API on every docs run. ClKernel.compileT2 + TypedKernel2.renderT take an Args[Float] and hand back an Answer[Float] — no Map, no out array:

import cats.effect.IO
import cats.effect.unsafe.implicits.global
import io.github.mercurievv.spireopencl.opencl.{ClKernel, renderT}

val result: Answer[Float] =
  ClKernel.compileT2[IO, Args, Answer](formula, size = 1, maxBatchSize = 1).use { kernel =>
    IO { kernel.renderT(Args[Float](b = 2.5f, c = 4.0f, d = 0.75f)) }
  }.unsafeRunSync()

Expected result.value is about 9.318361, matching the Double example up to Float precision.

Arrays

Use Reify.arraysTyped when each work-item reads one element from a device-resident array — one input per field, matched by name, the array analogue of outTyped:

case class Vals[V](a: V, b: V, c: V)

def elementwise[V: Field](vals: Vals[V]): V =
  vals.a * vals.b + vals.c

val arrayFormula: TypedFormula[Vals] = Reify.arraysTyped[Vals](uniforms = Nil, params = Nil) { (_, _, vals) =>
  elementwise(vals)
}
CodeGen(arrayFormula.formula).linesIterator.find(_.contains("__global const float* a")).get
// res5: String = "__kernel void compute(__global float* out, __global const float* a, __global const float* b, __global const float* c) {"

Upload inputs separately from launches — TypedKernel.writeInputsT takes a Vals[Array[Float]], one array per field, instead of one writeInputUnsafe call per array:

import cats.effect.IO
import io.github.mercurievv.spireopencl.opencl.{ClKernel, writeInputsT}

val n = 1024
ClKernel.compileT[IO, Vals](arrayFormula, size = n, maxBatchSize = 1).use { kernel =>
  IO {
    kernel.writeInputsT(Vals[Array[Float]](
      a = Array.fill(n)(1.5f),
      b = Array.fill(n)(2.0f),
      c = Array.fill(n)(0.25f),
    ))

    val out = new Array[Float](n)
    kernel.kernel.renderBatchUnsafe(Map.empty, Seq(Map.empty), out)
    out(0) // 3.25f
  }
}

Inputs stay on the device until written again. This is the right shape for repeated kernels over data that changes less often than the launch parameters.

Value kinds

kind varies use
Expr.Const never literals and folded constants
Expr.Uniform(name) per launch scalars shared by the whole launch
Expr.Param(name) per batch element small per-case values packed for one launch
Expr.Input(name) per work-item large arrays resident on the device
Expr.Index per work-item the OpenCL global id as a float

Supported numeric surface: Field, Trig, NRoot, numeric literals through ConvertableTo, and OrderS comparisons as 0/1 masks. There are no booleans, integers, loops, or data-dependent branches in the generated kernel.

More examples: