User Manual¶

How to write, compile, run, and debug PyPTO programs.

Reading paths¶

Pick the path that matches what you are trying to do. All four assume Installation is done.

I want to write my first kernel¶

Quickstart → Programming Model → Language Guide

Start by getting something to compile, then learn what it was doing, then fill in the rest of the surface. Keep the operator catalog open alongside — you will be looking up operators constantly at first.

I have a kernel and the numbers are wrong¶

Torch Codegen Debug Guide → Programming Model § execution model

Lower the IR to a PyTorch script and compare tensor by tensor. If the result changes between runs rather than being consistently wrong, the problem is ordering, not arithmetic — read the execution-model section, because statement order does not constrain execution order.

I have a kernel and it is slow¶

Programming Model § memory hierarchy → Diagnostics → Runtime DFX

Check report/perf_hints.log from your compile output before measuring anything — the compiler may already have told you. Performance is the dedicated chapter.

I want to run across multiple devices¶

Distributed Programming

Get a single-device kernel running first — distributed programs compose the same pl.* kernels behind pld.* collectives and a HOST orchestrator. Once it runs correctly, the distributed chapter covers ring vs. mesh trade-offs and cross-rank overlap.

Contents¶

Page	What it covers
Installation	Prerequisites, install from source, build options, verification, a tour of `examples/`
Quickstart	Tensor-level kernels with `@pl.jit` — no manual data movement — plus loops, splitting work across functions, compiling and reading the IR
Programming Model	Tensor / Tile / Block levels, control vs. execution plane, the pass pipeline, memory hierarchy, execution model
Language Guide	The full language, one topic per page: types, functions, control flow, memory, scopes and tasks, directives
Operations	Choosing between the `pl.`, `pl.tensor.`, and `pl.tile.*` namespaces, plus the operator catalog
Compiling a Program	`ir.compile()` and `JITFunction.compile()`, and inspecting the result
Running on Device	Resident device tensors, explicit dispatch, and the `RunConfig` fields that affect dispatch
Torch Codegen Debug Guide	Generating a PyTorch reference implementation from the IR to isolate accuracy problems
Distributed Programming	Symmetric-memory model, collectives, primitives, execution, and debugging for cross-rank programs

What PyPTO gives you¶

Capability	Where it is documented
Kernel authoring with `@pl.jit` (and the `@pl.function` / `@pl.program` form it specializes into)	Quickstart, Functions and Programs
Explicit on-chip memory placement (Vec / Mat / L0A / L0B / L0C)	Programming Model
Control flow: loops, carried values, conditionals, while	Control Flow
Multi-function programs and cross-function calls	Quickstart
The full `@pl.jit` family (`.incore`, `.inline`, `.opaque`, `.host`)	Quickstart, Functions and Programs
Hand-written C++ kernel integration	External Kernels
Device-resident tensors, explicit dispatch	Running on Device
Distributed (multi-card) programs and collectives	Distributed Programming
Accuracy debugging against a PyTorch reference	Torch Codegen Debug Guide
Compile-time diagnostics and performance hints	Diagnostics
Runtime DFX: swimlane, PMU, dependency graph, scope stats	Runtime DFX
On-chip memory map visualization	Memory Map

What is not here yet¶

This manual is being expanded into a full chaptered structure — tutorials, performance optimization, and accuracy debugging each get their own chapter. Until those land, the corresponding material lives in the developer documentation:

Topic	Current location
Mixed kernels (AIC + AIV in one function)	LowerAutoVectorSplit, ExpandMixedKernel, TPUSH/TPOP
Performance hints and diagnostics	Diagnostics, Compile Profiling
Runtime DFX flags, ring sizing, memory map	Runtime DFX, Per-Task Ring Sizing, Memory Map
External C++ kernels	Integrating Hand-Written C++ Kernels