Skip to content

Tutorials

Six walkthroughs, each ending in something that runs.

Prerequisites: The Language — at least Types, Functions and Scopes and Placement.

How this chapter differs from the rest

The Language and Operations are organised by capability — one page per feature, so you can look a thing up. This chapter is organised by task: each page builds one artefact from nothing, and every step along the way is a program you can run.

That means the pages repeat each other's features on purpose. If you want the full surface of pl.at, read Scopes and Placement. If you want to write a matmul, read Tiled matmul — it will use pl.at without explaining all of it.

Two tracks

Writing operators (00–03) — how to express the computation.

Page You end up with Reading time
Your first operator A running element-wise kernel, checked against torch ~20 min
Reduction and softmax A numerically stable softmax ~30 min
Tiled matmul A K-blocked matmul ~40 min
Mixed kernels Cube and vector working concurrently in one scope ~40 min

Shaping the schedule (04–05) — how to control what the runtime does with it.

Page You end up with Reading time
Shaping the task graph A multi-task program whose dependency graph you control ~30 min
Tuning the schedule A measurement loop you can re-run on your own kernel ~40 min

Reading order

00-elementwise ──► 01-reduction-softmax ──► 02-matmul ──► 03-mixed-kernel
      │                                                          │
      └──────────────────────────► 04-task-graph ──► 05-scheduling-tuning

The operator track is cumulative — each page assumes the tile vocabulary of the one before. The scheduling track only needs 00: it is about the shape of the graph between kernels, not about what any one kernel computes.

Which unit runs your operator

A core group pairs one cube unit (AIC) with vector units (AIV). Which one executes an operator is not a choice you make per call — it follows from the operator:

Operator family Unit Covered in
matmul, matmul_acc, gemv Cube (AIC) Tiled matmul
Element-wise, reduction, broadcast, cast Vector (AIV) 00, 01
tpush_to_aiv, tpop_from_aic, aiv_shard, aic_gather Both, by construction Mixed kernels

A kernel built only from one family occupies one unit and leaves the other idle. That observation is the whole point of Mixed kernels; everything before it writes single-unit kernels. See Operations for the full list.

Running the examples

Every page names a file under examples/. RunConfig.platform defaults to "a2a3sim", so none of them needs a device:

python examples/beginner/02_elementwise.py
python examples/advanced/03_mixed_kernel.py --mode staged

Most of the companions hard-code that default. 03_mixed_kernel.py is the exception: it takes --mode to pick between the split forms, and --platform to retarget.

See Also