Book contents +

XVII · Python C-ABI (welvet on PyPI) / CHAPTER 27

Python C-ABI: list backends and pick one

Samuel Watson · Welvet feature bookOriginal source ↗

welvet (PyPI)accel soft-SKIP


Why it exists

Accelerators are opt-in at runtime. Scripts should probe what this host can run instead of hard-coding CUDA or Metal.

What it is

Print list_backends(), then create a grid on the first available accelerator (or CPU), place Dense, and forward once.

Backend ids

cpu_tiled · simd · webgpu · native_cpu · cuda · metal · rocm · vulkan · qnn · mlx. Routed GPU backends enable Go EnableRouting inside the CABI. For qnn / mlx, call prepare_grid after place_* (SyncTo* before forward): see §117.

Missing sibling libs or no GPU print as available: false; create_grid with an unavailable name raises. Prefer probe → pick → place. Go twins: §89 CUDA · §82 Metal · §110 MLX.

Python example

examples/115-python-backends/main.py

Run:cd welvet/examples/115-python-backends && python3 main.py
"""115. Python C-ABI: list backends and pick one."""
from __future__ import annotations

import welvet as w

# Prefer a real accelerator when the sibling lib + device are present.
PREFER = ("cuda", "metal", "vulkan", "rocm", "native_cpu", "simd", "cpu_tiled")


def try_forward(backend: str) -> bool:
    g = w.create_grid(backend=backend)
    try:
        w.place_dense(
            g,
            {"in": 16, "out": 16, "act": "relu", "dtype": w.DType.FLOAT32},
        )
        out = w.forward(g, [0.05] * 16)
        print("chosen", backend)
        print("forward_len", len(out), "head", [round(v, 4) for v in out[:4]])
        return True
    except RuntimeError as exc:
        print(f"SKIP {backend}: {exc}")
        return False
    finally:
        w.free_grid(g)


def main() -> None:
    w.assert_engine_version()
    backends = w.list_backends()
    print("backends")
    for b in backends:
        mark = "ok" if b.get("available") else "--"
        print(f"  {mark} {b['id']}")

    by_id = {b["id"]: b for b in backends}
    for name in PREFER:
        if not by_id.get(name, {}).get("available"):
            continue
        if try_forward(name):
            return

    print("FAIL: no usable backend")
    raise SystemExit(1)


if __name__ == "__main__":
    main()

Output

exit 0 · last run via python3 main.py

backends
  ok cpu_tiled
  ok simd
  ok webgpu
  ok native_cpu
  ok cuda
  -- metal
  ok rocm
  ok vulkan
  -- qnn
  -- mlx
chosen cuda
forward_len 16 head [0.0, 0.0, 0.0, 0.0]

Validate (harness)

cd welvet/examples/115-python-backends && PYTHONPATH=../../../w2a/python/src python3 main.py