Trellis

GPU acceleration that stays honest: probe the machine → budget memory → validate the launch → run — with coded errors, a doctor, and no silent “CPU as GPU peak.”

Research codename was Lattice. Product / import / CLI: trellis (ADR D01). PyPI distribution: heddura (pip install heddura → import trellis).

What Trellis is / is not

Architecture (one screen)

Intent (map/stencil/…)
   → Structure (components/packs)
   → Schedule (tile/fuse/…)
   → Resource (MemoryBudget, streams, parallel_map plans)
   → Conductor: stock → cache → generate → escape
   → ISA / door (CUDA · CPU · HIP scaffold · WebGPU floors)
CSM/doctor probes sparse capabilities (no invented warp/TMEM)

Why Trellis

• Safety modes (strict / balanced / expert) bound MemoryBudget headroom
• validate() rejects illegal / zero-occupancy launches before you ship a kernel
• Conductor prefers stock libraries (cuBLAS) when available — and only then may label gpu_peak=true
• One native CUDA door backs Python, C, C++, and Rust (no dual-stack drift)
• Doctor / CSM read real device props (warp_size from the GPU — never hardcoded)

Gold-standard checklist: docs/GOLD_STANDARD.md · Authority: ROADMAP.md §A · Queue: §C.

Status

Φ0 complete · Φ1 advancing · Φ2 draft (legal-only Peak). Product 0.1.0rc15. Not bare v0.1.0 — public CUDA 2-SKU wheels / multi-GPU CI (§8.6) still open.

Door × outcome (honest matrix)

Full taxonomy: WORLD_GPU_COMPATIBILITY.md.

Quickstart — Python

From PyPI (import stays trellis):

python -m pip install heddura

From a clone (editable / extras):

python -m pip install -e ".[dev,interop]"
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
$env:TRELLIS_LIB_DIR = "$PWD\build"
$env:CUDA_PATH = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4"  # optional
trellis doctor --json
python scripts/support_bundle.py -o support_bundle.json

import trellis

ctx = trellis.Context(device=0, safety="strict")  # or device="cpu"
x = ctx.alloc((64, 64), dtype="float32")
x.fill_ramp()
y = trellis.stencil(ctx, x, schedule={"tile": (16, 16)})
z = trellis.parallel_map(ctx, x, fn="relu", strategy="auto")
print(trellis.sources()["best"])

Peak honesty: generate kernels set gpu_peak=false. Stock cuBLAS (gemm_like) may set gpu_peak=true.

Tutorials

python examples/01_first_op.py
python examples/02_components.py
python examples/03_schedule_roofline.py
python examples/04_dlpack_interop.py
python scripts/repro_beachhead.py
python docs/e2e/run_phi1_smoke.py

Contributing / support

• CONTRIBUTING.md · CODE_OF_CONDUCT.md · SUPPORT.md
• SECURITY.md · GOVERNANCE.md · CITATION.cff

Hard rules

• Never invent warp_size — probe CSM / CUDA attrs
• Never label CPU as GPU peak
• Never skip validate() before launch
• Do not replace cuBLAS / FlashAttention / NCCL with DIY “stock”
• No ZLUDA-class CUDA translation

License

Apache-2.0 — see LICENSE and NOTICE.