Running The Examples¶
The examples target Bertha EVT0. Each downloadable Python file under
tutorials/code contains its kernel, host setup and verification. Download one
file or copy the complete source from its page; no companion Python file is
needed. The rendered code comes from these same files. Importing a sample
defines its kernels without allocating device tensors or launching them.
Execution starts under if __name__ == "__main__".
Activate the SDK environment¶
Start with an SDK Python environment containing legato, hart, torch_ha,
PyTorch 2.10.0 and the native compiler/toolchain. Device execution also needs
either Bertha EVT0 hardware with its driver or a runtime built with the EVT0
Torch FSim backend. Activating a virtual environment does not build those
components; see the installation instructions
if the SDK is not prepared yet.
Set the first three paths to your SDK checkout, this documentation checkout, and prepared SDK virtual environment. Run this block in Bash, then use the commands below in the same terminal:
1 2 3 4 5 6 7 8 9 10 11 12 | |
Frontend-only examples need Legato and CPU PyTorch, without a driver or device. The compile diagnostics example also uses no device: it runs real compiler checks with CPU inputs and catches the expected errors. It needs the native compiler with component-specific diagnostics.
Running the example on hardware¶
To run the example on the hardware, install the SDK for your LPU and use the environment variables stated above.
You can run the example through
1 2 3 4 5 6 7 8 9 | |
To run a downloaded example, save the complete Python source as its filename.
After activating the SDK environment, run that file directly. For example,
replace the directory below with the location of simple_matmul.py:
1 2 3 | |
For hardware, use unset HA_BACKEND instead of export HA_BACKEND=sim.
No repository-local Python helper is required alongside the downloaded file.
What the examples verify¶
The source of each numerical example shows these steps directly, with comments:
- Register the LPU Torch backend, configure FSim when selected, and select device zero.
- Prepare CPU inputs, allocate the required physical device layouts, and copy contiguous data.
- Compile and launch inside
legato.sessionwith binary output. - Synchronize the stream so asynchronous device errors fail the example.
- Copy the result to the CPU, check finite values, and compare every output element with a CPU reference.
Padded examples also show the physical backing tensor and its logical view.
Compile-only and frontend-only cases explicitly use launch=False and skip
device initialization and synchronization.
| Script | Verification performed |
|---|---|
simple_matmul.py |
Binary + FSim values, every output element |
static_multi_core.py |
Binary + FSim values, all 32 cores |
tensor_memory.py |
Dynamic allocation: binary compile only; partial copy: FSim values and preserved rows |
attention.py |
Binary + FSim values, runtime prefix shorter than capacity |
math_and_masking.py |
Binary + FSim values, supplied post-mask maximum |
broadcasting.py |
Binary + FSim values, add/conv/dwconv/pool/LayerNorm/RMSNorm |
channel_multi_core.py |
Two rank-local ELF binaries and four per-core tensor-channel bindings; no launch |
weight_quant_matmul.py |
Converter byte counts + binary compilation; no FSim numeric claim |
static_evaluation.py, tensor_fill_frontend.py |
Frontend MLIR only, no launch |
compile_diagnostics.py |
Three real compile failures: source labels, headline/reason codes, alignment and transfer facts; no launch |
A successful frontend compile, a generated binary, and correct device values are separate checks. The FP8 quantization simulator limitation and standalone fill/reduction limits remain documented on their example/API pages. Hardware parity has not been measured for this documentation update. Architecture manuals describe silicon capabilities; they are not compiler support tables.
Checking documentation examples¶
Use the commands below to check the downloadable Python examples and execute the tutorial notebooks in your SDK environment.
With the SDK development dependencies installed, run each test file separately:
1 2 3 4 5 6 7 | |
Or run both test files together:
1 2 | |
The numerical checks compare every output element with a CPU reference after stream synchronization. Compile-only checks require a nonempty binary without launching, and frontend-only checks inspect the generated MLIR. Notebook checks execute every code cell in a real Jupyter kernel using the active SDK Python interpreter.
For a quick syntax/API audit without starting FSim or Jupyter:
1 2 | |
For interactive use, select the SDK Python environment in Jupyter and run all cells
from Documentation/tutorial. The same assertions run when using the notebooks
interactively; notebook outputs are not committed.
Build the documentation site with its documentation dependencies installed:
1 2 | |