library_name: kernels
license: apache-2.0

metakernel

The measuring instrument for the kernel-design loop, packaged as a kernel and loadable through kernels: trustworthy timing, adversarial correctness comparison, and measured facts about the device. The reference standard is the suite of measurement invariants any correctly functioning device must satisfy, certified on multiple architectures.

An agent iterating on CUDA candidates is good at writing code and bad at trusting its own measurements. It needs three things it cannot reliably improvise: timing that rejects thermal throttling, comparison that distinguishes real bugs from legitimate reduction-order noise, and device numbers that were measured rather than copied from a spec sheet. metakernel ships those as loadable ops that run anywhere get_kernel runs, including headless CI where Nsight and CUPTI are unavailable, which is exactly where agent loops live.

The dossier drawing its own roofline, every line measured live by probe kernels: the 790 GB/s DRAM diagonal, compute roofs from fp64's 1.2 TF to int8's 715 TOP/s, the dependent-load latency ladder from 30 shared-memory cycles to 666 at DRAM, and a real fp16 GEMM plotting itself at its measured 116 TF with throttled samples rejected from the median.

Usage

from kernels import get_kernel
mk = get_kernel("phanerozoic/metakernel", version=1, trust_remote_code=True)

dossier = mk.probe_device()                          # measured device facts
report  = mk.bench(lambda: cand.op(x), iters=200,    # throttle-rejected medians
                   bytes=B, flops=F, dossier=dossier)
verdict = mk.compare(ref_op, cand_op, gen=make_inputs)   # pass/fail with ULP evidence
table   = mk.sweep(factory, {"BLOCK": [64, 128, 256]})   # config search

Every op returns plain dicts and tensors with fixed schemas, never prose, so an agent parses results instead of scraping stdout. version selects the release branch; trust_remote_code is required by kernels for publishers without the trusted-publisher mark.

API

Method

Each dossier entry is produced by a dedicated probe kernel: streaming triads and read/write/gather kernels for bandwidth, Sattolo-cycle pointer chases for latency, register-resident FMA chains and register-fragment mma_sync loops for compute, an atomic hammer swept over distinct-address counts, empty-launch trains, and a cooperative-groups kernel for grid-barrier cost. Every number carries the SM clock it was measured under; bench probes the clock and rejects samples from sagged windows, reporting the count. The comparison ops treat the reference as a distribution: an order shuffle over contractual-noise dimensions bounds the legitimate numerical band, applied pointwise so a uniformly wrong candidate cannot hide behind one order-sensitive element.

Measured

Release-pinned dossier for RTX 6000 Ada (sm89, 142 SMs, 96 MB L2, ECC on):

A second pinned dossier covers GeForce RTX 3070 Ti Laptop (sm86). MMA flops derive from accumulator read-back with every fragment element observed; mma_tile_check reproduces the reference GEMM exactly through the same fragment path.

Certification

The test suite asserts invariants that must hold on any correctly functioning device: L2 exceeds DRAM bandwidth and random gather costs more than streaming; latencies order smem < L1 < L2 < DRAM; tensor-core rates beat the FMA pipe and hold the silicon's structural ratios; a large cuBLAS GEMM lands within [0.30, 1.05] of the dossier fp16 rate; compare passes reordered reductions and fails corrupted candidates through both routes; fuzz_shapes catches a contiguity-cheating op and reports the 2^31 case as run or skipped, never silently; the chase probe repeats within 20%.

Requirements and limits

• No hardware counters: everything is inferred from timing, clocks, and the occupancy API, so entries carry a confidence field and timing-differential inference can misattribute.
• Single device, single tenant: contention surfaces as rejected samples, not errors. launch_overhead includes torch dispatch.
• MMA numbers are dense-tile register rates with no memory traffic, an upper bound. In-process fuzz_shapes cannot survive a context-killing candidate; isolate=True can, at a torch startup per child.
• Published variants are Linux x86_64; on Windows load_local.py JIT-builds the same source.

References

Williams, Waterman, Patterson, "Roofline: An Insightful Visual Performance Model" (2009); Sattolo's algorithm for single-cycle pointer chases; the occupancy API and cudaEvent timing model.

License

Apache-2.0.