Tutorial

The tutorial teaches Tungsten and Paint, and how to think about the machine they program. It has two parts:

• The main sequence: twelve lessons, in order. Together they cover the ideas every program uses:
  • how a PE computes;
  • how PEs exchange data;
  • when a transfer waits;
  • how a PE reacts to messages;
  • how rows and grids of PEs work together.
• Extension topics: optional, and in no order. Each covers a feature or pattern that some programs need. Each topic starts with the lessons and topics it needs.

Every lesson and topic is a complete program. It builds, runs in the simulator and checks its own result.

The chapters, in order

Read the four main groups in this order. The extension groups have no order: read a topic once you have read everything on its Needs line.

Group	What it teaches
Tutorial I – Single-PE Programming	Lessons 1-3: the build-and-test loop, ordinary Tungsten code, and how a PE runs a loop and what it costs
Tutorial II – Communication Between PEs	Lessons 4-7: sockets, colors and routes; concurrent activities and FIFOs; blocking and deadlock; tasks started by messages
Tutorial III – Spatial Programming	Lessons 8-10: one kernel on a row, a wavefront, broadcast and reduce, and switches
Tutorial IV – Whole-Grid Applications	Lessons 11-12: a grid of blocks with halo exchange, and a complete iterative solver
Collective Communication	The fabric adder, self-restoring switch protocols, a barrier and a broadcast from switch positions, and collectives over messages
Routing	Message passing, variable-length exchanges, eight-neighbour stencils, filters and fan-out, and a loop through every PE
Numerics	Precision and exact references, bit-level and wide integers, and hardware random numbers
Single-PE Programming Techniques	Vector-step loops, memory placement and budget, and locks, until conditions and timers
Algorithms	Matrix multiplication, sorting networks, physics on a grid of points, and command streams
Layouts and Debugging	Larger layouts in Paint, and debugging and profiling a multi-PE run
Write your own example	A guide, with no program of its own: setting up, building and testing a program of your own

The main sequence

#	Lesson	You will be able to
1	Hello, wafer!	build, run and check a one-PE program, and read what the build produced
2	Values, control flow and functions	write ordinary code with types, if, while and functions in a module, and load input data
3	How a PE runs a loop	measure a loop in cycles and write loops that run as vector instructions
4	Sockets, wavelets, colors and routes	send data between PEs, route it, and multicast it
5	One core, many activities	run transfers concurrently with parallel, and buffer them in a FIFO
6	Blocking, buffering and deadlock	say when a send or receive waits, recognize a deadlock, and remove it
7	Tasks	write handlers that run when a message arrives
8	Space and time: a wavefront	run one kernel on a row with per-PE data, and map a recurrence onto PEs and steps
9	Broadcast and reduce along a row	compute on a passing stream, and return a result to every PE
10	Switches	let several PEs take turns on one color
11	A grid of blocks	split a 2-D field across PEs, exchange halos, and budget colors, queues and memory
12	A complete iterative solver	combine halo exchange, a grid-wide sum and a convergence test in one program

Extension topics

A topic's Needs list names the lessons and topics it builds on directly. Each lesson in the main sequence assumes the lessons before it, so "lesson 9" includes lessons 1-8.

Topic	Needs
Reductions in the router: the fabric adder	lesson 9
Switch protocols	lesson 10
A barrier and a broadcast from switch positions	lessons 10 and 11; Switch protocols
Collectives over messages	Message passing; lesson 9
Message passing: routing by address	lessons 4, 6 and 10
Variable-length exchanges and teardown	lessons 6 and 11
Eight neighbours: spiral routing on a budget	lessons 8 and 11
Data in and out: filters, fan-out and funnels	lessons 7 and 10; Switch protocols
A route through every PE	lessons 10 and 11; Switch protocols
Precision: how the PE rounds	lessons 2 and 3
Bits and wide integers	lesson 2
Hardware random numbers	lessons 2 and 3
Vector-step loops, predication and memory iterators	lesson 3
Memory: placing data and the memory budget	lessons 2 and 3
Locks, until conditions, rings and timer tasks	lessons 5 and 7
Matrix multiplication across PEs	lessons 9 and 10
Sorting networks along a row	lessons 2 and 6
Physics on a grid of points	lesson 11
Command streams: Tetris on a column	lessons 7 and 9
Large layouts: geovars, terminals and transports	lessons 8, 9 and 11
Debugging and profiling a multi-PE run	lessons 3 and 6

Which lesson for which dataflow

Dataflow question	Pattern	Where
One producer, one consumer?	Point-to-point send and receive	Lesson 4
A sequence of transforming stages?	Pipeline	Lesson 4
Two streams combined on one PE?	parallel transfers and a FIFO	Lesson 5
Two PEs that both send and receive?	A deadlock-free exchange	Lesson 6
Indexed records, then a flush?	Dispatch	Lesson 7
A recurrence along a row?	Wavefront	Lesson 8
One value for every PE of a row, or a sum over them?	Broadcast and reduce	Lesson 9
Several producers sharing one color in turn?	Serial drain with switches	Lesson 10
Nearest-neighbour exchange on a grid?	Halo exchange	Lesson 11
A sum over a whole grid, every step?	Grid allreduce	Lesson 12
Every PE waiting for all the others?	Barrier from switch positions	Barrier and broadcast
Destinations known only at run time?	Message passing	Message passing
A reduction done in the routers?	Fabric adder	The fabric adder
Two matrices streamed across a grid?	Systolic matrix multiply	Matrix multiplication

Prerequisites

• The experimental SDK, set up as Run the tutorials shows. With <sdk> the SDK's directory, set up means:
  • <sdk>/bin on $PATH, for carbide, paint, miget/miset, portrait and pipeline;
  • FLUTEMK=<sdk>/share/build/flute.mk and TESTMK=<sdk>/share/build/test.mk in the environment;
  • SIMFABRIC=simfabric-sdk, so that the build runs the Cerebras SDK simulator.
• make, and python3 with numpy.
• Familiarity with basic C-like syntax.

Paint compiles each lesson with Carbide.

Quick start

Work in a copy of the SDK's tutorial, <sdk>/share/tutorial.

cp -r <sdk>/share/tutorial tutorial
cd tutorial/main-1-one-pe/01-hello-wafer

# Run the test in simulation mode:
make TEST=tutorial MODE=sim

# If the test passes, make prints a line ending in
# PASS tutorial [ N=4 ARCH=sdr ]. If it fails, the line says FAIL, and
# test-tutorial/make-log has the details.

• make TEST=tutorial MODE=sim in tutorial/ runs the first row of every lesson and topic.
• tungsten-tutorials runs them all, or the ones -f selects, and prints a scorecard: -f main for the main sequence, or -f main-1 for lessons 1-3.

After you edit a lesson's files, run make clean before make. Otherwise make does not rebuild an existing test-<label>/ directory, and it reports the old result.

Write a kernel with a coding agent

The lessons and the language references are plain Markdown and source files, and every lesson checks its own result in the simulator. An agent can learn the languages from them and test the kernels it writes. Ask the agent to:

1. read the Tungsten and Paint references, the main sequence, and the lesson or topic closest to your kernel. The table above maps dataflows to lessons.
2. copy that lesson, or start from scratch as Write your own example describes. Then write the kernel (.w), its layout (bench.paint) and a Python reference for its output (ref.py).
3. build and simulate it in the lesson's directory, as in the quick start, and repeat until the result matches the reference.

Also see

• Tungsten syntax and Paint syntax: quick references to the two languages
• Test infrastructure: a lesson's Makefile, test.rc, bench.paint and ref.py
• Debugging kernels: Portrait, miget and pipeline traces
• Architecture notes: the PE, the router, colors, queues and tasks
• Tungsten Language Reference: the complete language specification
• Paint Language Reference and Paint Examples
• Portrait Debug Tool: debug visualization
• miset/miget Tools: symbol-based data access