Skip to content

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
SDK_ROOT=/path/to/hyperaccel-sdk
DOCS_ROOT=/path/to/ha-sdk-docs
SDK_VENV=/path/to/sdk-venv
source "$SDK_VENV/bin/activate"
cd "$SDK_ROOT/legato"

# Use the SDK's native toolchain and register the Torch backend explicitly in each example.
export HA_TOOLCHAIN=1
export HART_TOOLCHAIN=1
export TORCH_DEVICE_BACKEND_AUTOLOAD=0
# Keep artifacts and simulator logs at a fixed location even after changing directories.
export LEGATO_EXAMPLE_OUTPUT="$PWD/legato_example_output"

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
cd "$SDK_ROOT/legato"
unset HA_BACKEND

python "$DOCS_ROOT/docs/legato-language/tutorials/code/simple_matmul.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/static_multi_core.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/tensor_memory.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/attention.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/math_and_masking.py"
python "$DOCS_ROOT/docs/legato-language/tutorials/code/broadcasting.py"

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
cd /path/to/downloaded-examples
export HA_BACKEND=hw
python simple_matmul.py

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:

  1. Register the LPU Torch backend, configure FSim when selected, and select device zero.
  2. Prepare CPU inputs, allocate the required physical device layouts, and copy contiguous data.
  3. Compile and launch inside legato.session with binary output.
  4. Synchronize the stream so asynchronous device errors fail the example.
  5. 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
cd "$SDK_ROOT/legato"
export HA_BACKEND=sim

# Check the downloadable Python examples.
python -m pytest -c pyproject.toml src/tests/documentation_examples/test_examples.py
# Execute the tutorial notebooks in real Jupyter kernels.
python -m pytest -c pyproject.toml src/tests/documentation_examples/test_tutorials.py

Or run both test files together:

1
2
cd "$SDK_ROOT/legato"
HA_BACKEND=sim python -m pytest -c pyproject.toml src/tests/documentation_examples

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
cd "$SDK_ROOT/legato"
python Documentation/verify_examples.py --api

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
cd "$SDK_ROOT"
python -m mkdocs build --strict --config-file legato/Documentation/mkdocs.yml