RFC: lig — Li GPU package, LKIR, multi-vendor kernels (PH-HW)¶

Status: Draft (WP1 governance)
Track: PH-HW · HW-0 (governance)
Vision: world-studio-vision.md
Kernel catalog: lig-kernel-catalog.md
Bench schema: lig-kernels.toml

Summary¶

Rename and unify GPU work under lig (import lig), replacing the provisional li-gpu package and legacy import gpu surface. User kernels compile through LKIR (Li Kernel IR) under packages/lig/lkir/ and lower to CUDA, HIP/ROCm, Metal, SPIR-V/wgpu, or a custom lab backend — never raw vendor source strings in application code.

WP1 (this RFC): governance, module boundaries, vendor matrix, four proof/bench gates, migration plan.
WP2+: packages/lig/src/lib.li, codegen, and harness drivers.

Package layout¶

Integration steward / WP2 performs the mechanical rename:

git mv packages/li-gpu packages/lig   # when li-gpu exists on the integration branch

Until the mv lands, docs and benches may reference packages/gpu stubs; agents must treat lig as the canonical name.

Module surface¶

Li syntax¶

Use def for all new APIs. Do not document bare proc. extern proc only for FFI to trusted vendor runtimes. Every exported def needs requires / ensures / decreases where applicable.

import lig
import lig.device
import lig.kernel

def matmul_f32(a: tensor[f32], b: tensor[f32]) -> tensor[f32]
  requires a.cols == b.rows
  requires lig.memory.aligned(a) && lig.memory.aligned(b)
  ensures result.rows == a.rows && result.cols == b.cols
=
  lig.kernel.launch(id = "lig.kernel.matmul_f32", args = [a, b])

def pick_backend() -> lig.device.Backend
  requires lig.device.probe_ok()
=
  lig.device.select(prefer = ["metal", "cuda", "hip", "wgpu"])

import lig.present

def viewport_frame(surface: lig.present.Surface) -> ()
  requires surface.valid()
=
  lig.present.begin(surface)
  lig.present.submit()
  lig.present.end(surface)

# li.toml (engine / studio project)
[engine.lig]
backend = "auto"   # auto | cuda | hip | metal | wgpu | custom_lab
lkir_path = "kernels/my_tile.lkir"
custom_lab_manifest = ""   # required when backend = custom_lab

LKIR (Li Kernel IR)¶

LKIR is the only supported IR for user-defined GPU kernels.

@gpu placement and multi-GPU intent¶

User-facing GPU placement starts in the compiler, not in vendor source strings:

@gpu(devices=2)
def force_tile() -> int
  requires true
  ensures result == 0
  decreases 0
=
  return 0

Today this is a MIR-visible placement tag (mir_gpu_def, mir_gpu_multi_device_def) with integer-literal devices >= 1 validation. Vendor/backend arguments are rejected on @gpu; backend selection stays in lig config/runtime gates. Next PH-HW slices must connect that tag to LKIR catalog launch, device-buffer proofs, and backend selection. lig remains the runtime/benchmark surface for CUDA, HIP/ROCm, Metal, and Vulkan/wgpu comparisons; Li source remains the kernel authority.

Example catalog binding (conceptual):

import lig.kernel

def md_force_short(r: tensor[f32], eps: f32, sigma: f32) -> tensor[f32]
  requires r.len > 0
  requires eps > 0.0 && sigma > 0.0
=
  lig.kernel.launch(id = "lig.kernel.md_force_short", args = [r, eps, sigma])

Vendor matrix¶

Parity rule: ROCm/HIP is a peer of CUDA, not a secondary port. No CUDA-only user kernels.

Four gates (every kernel + backend change)¶

Agents must not weaken these gates in prompts, hooks, or bench thresholds.

Migration from li-gpu / import gpu¶

# Before (deprecated)
# import gpu
# def run() = gpu.cuda.matmul(a, b)

# After
import lig
import lig.kernel

def run(a: tensor[f32], b: tensor[f32]) -> tensor[f32]
  requires a.cols == b.rows
=
  lig.kernel.launch(id = "lig.kernel.matmul_f32", args = [a, b])

PH-HW work packages¶

Proof / trust¶

Dependencies¶

• PH-world-studio-program.md — PH-HW HW-0…4
• portable-targets-rfc.md — CPU triples + [engine.lig]
• ml-async-parallel-rfc.md — streams, Triton-distributed patterns
• algorithms-and-libraries-plan.md — package register

Open questions¶

• Exact LKIR textual syntax (.lkir vs embedded .li attributes) — WP2 spike
• wgpu vs Metal default on Apple Silicon when both available
• External oracle binaries for md_force_short (LAMMPS column) — see lig-kernels.toml