Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-kernel

Column interpreter for per-element code (Houdini's Wrangle in Luce Base): a typed column IR and builder, a chunked parallel interpreter that never traps, host columns in and out, and the lib of vector, noise and random functions.

A library written in luce-base. Latest release 0.1.3.

Install#

luc add dymokomi/luce-kernel

Documentation#

Luce Kernel

The column interpreter behind luced-3d's Code node: per-element code (Houdini's Wrangle) written in Luce Base, run over millions of elements at once. It knows nothing about meshes: a host hands it named, typed columns and gets named, typed columns back.

def dependency "luce-kernel" {
    str owner = "dymokomi"
    str version = "^0.1.0"
}

Three public modules:

  • luce_kernel.engine: the column IR, its Builder, verify, and run. A program is a flat list of instructions over typed registers (f32 f64 i32 i64 u32 u64 mask; a vector is 2 to 4 consecutive registers). run executes every instruction over a chunk of lanes (4096 by default) as one tight loop, chunks in parallel. A would-be Base trap (bounds, overflow, division by zero, failed conversion, assert, trap, a runaway loop) stops the run with a Fault: the source line and column and the lowest failing lane, the same at any thread count. The engine itself never traps.
  • luce_kernel.lib: the functions a snippet calls without importing them, in Base spelling: dot cross length length2 distance distance2 normalized, `lerp clamp fit fit01 smooth degrees radians, rand rand3 rand64, Perlin noise/snoise` in 1 to 4 dimensions (noise1 noise2 noise noise4), each with f64 forms (64 suffix). VEX's math and transforms in VEX's row-vector convention: Mat3/Mat4 (identity, rotation, transposed, inverted, determinant, multiply, transform, rotate/prerotate/scale/ prescale/translate/pretranslate), Quat with `quaternion qmultiply qrotate qinvert qconvert slerp eulertoquaternion quaterniontoeuler, maketransform cracktransform lookat dihedral polardecompwith thexform_*orders,abs sign frac rint trunc min max avg sum product pow exp log log10 cbrt sinpi cospi tanpi, solvequadratic solvecubic, the point distances, and efit fit10 fit11 invlerp lspline cspline kspline spline; noise and sampling: pnoise flownoise noised xnoised curlnoise curlnoise2d onoise wnoise mxcellnoise anoise nrandom randomsobol randompoisson samplecircle_uniform sampledirectionuniform samplesphereuniform samplehemisphere sampledirection_cone sample_normal`. The engine runs the first group as column operations; the rest lower from their Base bodies like a snippet's own helpers (structs, methods and all). A snippet imports only the lib names it uses and does not declare itself.
  • luce_kernel.lower: from the user's snippet text to a program. wrap puts the body in the Run Over entry function (point(p: Point*, k: const Kernel*), given by the host), write_root lays out the modules the checker resolves imports against, and compile checks the module with luce-base's own checker (embed.Library) and lowers the typed tree. A Host says what its API members are (column fields, accessors by literal name, the element number, uniforms and parameters, builtins) and which of its stub modules are helper libraries, inlined like lib (Host.library). Element-dependent conditions become exec masks, uniform ones jumps; helpers in the header are inlined, and may take the element (fade(p)) and read and write it through its members. Every diagnostic and fault maps back to the user's line and column. For an editor, complete lists what may come at the caret (members after a dot, else locals, the header's helpers, lib functions, types and keywords, each with its signature and ## doc) and hover gives the word's signature and doc; both read the lib's and the host's stub texts, so the docs live once, and still help on half-typed code.
from luce_kernel import lower
from luce_kernel.lower import Host, RunOver

var host = Host()
try host.field("Point", "P", "P", 3)          # p.P is the P column, 3 components
try host.element("Point", "ptnum")
try host.parameter("Kernel", "f32")            # k.f32("amount", 0.2): a spare parameter
try host.column("P", .f32, 3)                  # what the input holds
try lower.write_root(root)                     # then the host's own stubs under root
let points = RunOver(entry = "point", parameters = "p: Point*, k: const Kernel*",
                     imports = "from luce_geocore.code import Point, Kernel")
var compiled = try lower.compile(root, points, header, "p.P[1] += math32.sin(p.P[0] * 4.0) * 0.1", &host)
defer compiled.destroy()
for d in compiled.diagnostics(): show(d.part, d.line, d.column, d.message)
var items = try lower.complete(root, points, header, "p.", .body, 1, 3, stub_texts)
defer items.destroy()                          # items.items(): label, kind, detail, doc

The IR can also be built by hand:

from luce_kernel import engine
from luce_kernel.engine import Builder, Column, Request

# p.P[1] += math32.sin(p.P[0] * 4.0) * 0.1, by hand
var b = Builder()
let x = b.input("P", 0, .f32)
let y = b.input("P", 1, .f32)
let wave = b.unary(.sin, b.binary(.mul, x, b.constant_f32(4.0)))
let moved = b.binary(.add, y, b.binary(.mul, wave, b.constant_f32(0.1)))
b.store(b.output("P", 1, .f32), moved)
var program = try b.finish()
defer program.destroy()
let request = Request(count = count, inputs = [Column.input_f32("P", positions, 3)],
                      outputs = [Column.output_f32("P", moved_positions, 3)], uniforms = no_uniforms)
if let fault = try engine.run(&program, &request):
    print(fault.describe(buffer, "point"))

The design is luced-3d's docs/research/CODE-NODE.md. The per-kind lane loops are written by tools/lanes.py (run it after changing its tables), and the texts write_root writes by tools/sources.py (run it after changing src/lib). Run luc test for the unit, conformance, fault and fuzz suites; python3 tests/bench/run.py for timings.

Licensed under MIT or Apache-2.0, at your option.

Dependencies#

PackageVersion
dymokomi/luce-basenewest
dymokomi/luce-stdnewest

Versions#

0.1.3

Browse source · pack · commit d997aff468ea

SHA-256 8c738f30fe80d48feab432d10577a35e4da3f608bcf831311c1ba8d25d459f08

luce-kernel 0.1.3: batch release

0.1.2

Browse source · pack · commit 1621b3d0b788

SHA-256 c70da3ae0cc2f4243f475787f60a42458ae349907dd3d538b6bb903036c66e5f

luce-kernel 0.1.2: batch release

0.1.1

Browse source · pack · commit 598b6fbb9d4d

SHA-256 1e8dc9f7d035997ae901348192e1660111e11308415db04c828b49fc233ed744

luce-kernel 0.1.1: batch release

0.1.0

Browse source · pack · commit 6d0cb601b142

SHA-256 925526be24f9aef42f82bc1bb136254b0de8019e2eccd495b7f0384b665f5e3e

luce-kernel 0.1.0: first release