03. Compile and Run

Once a spec passes validate → compile → run. This is the stage that turns a spec (design) into an artifact (runnable thing).

Pipeline

spec.yaml (validate ✓)
   ↓
eulernpu compile  →  artifact (graph IR + lowering plan)
   ↓
eulernpu run      →  result.npz
   ↓
                     vs golden.npz → correctness / determinism

compile

eulernpu compile \
    --spec    examples/tiny_mlp/spec.yaml \
    --weights examples/tiny_mlp/weights.npz \
    --out     /tmp/tiny_mlp.artifact

Output:

tiny_mlp.artifact/graph.json — lowered op graph
tiny_mlp.artifact/weights/*.npz — backend-tagged weights
tiny_mlp.artifact/plan.json — execution plan (memory alloc, schedule)

The --backend option chooses the lowering target:

cpu_ref (default) — every op uses reference impl
npu_sim — lowering that flows through the cycle model
zynq_ps — runnable on ARM
fpga_board — PL offload candidate ops separated

run

eulernpu run \
    --artifact /tmp/tiny_mlp.artifact \
    --input    examples/tiny_mlp/input.npz \
    --out      /tmp/tiny_mlp.result.npz

Output:

tiny_mlp.result.npz — graph output tensors (usually logits)

Compare Against Golden

eulernpu compare \
    --got      /tmp/tiny_mlp.result.npz \
    --expected examples/tiny_mlp/golden.npz \
    --tol      1e-5

Compare OK: 1 tensor · max abs diff 3.4e-06 < tol 1e-05

The cpu_ref backend is deterministic. Same input + same weights → same output. The golden file uses that determinism as a regression guard.

Swap Backend — One Line

Change only --backend and the same spec is lowered for a different backend:

# cpu_ref (used to generate the golden)
eulernpu compile --spec ... --backend cpu_ref --out /tmp/a

# npu_sim (measure cycle/memory)
eulernpu compile --spec ... --backend npu_sim --out /tmp/b
eulernpu run     --artifact /tmp/b --input ... --out /tmp/b.result.npz
eulernpu compare --got /tmp/b.result.npz --expected /tmp/a.result.npz

Verifying byte-equal outputs across backends is step one in proving determinism.

End-to-End Example — tiny_mlp

EX=examples/tiny_mlp
eulernpu validate $EX/spec.yaml
eulernpu compile  --spec $EX/spec.yaml --weights $EX/weights.npz --out /tmp/mlp
eulernpu run      --artifact /tmp/mlp --input $EX/input.npz --out /tmp/mlp.out.npz
eulernpu compare  --got /tmp/mlp.out.npz --expected $EX/golden.npz

Expected:

Validation OK: 5 operators · 2 components · backend=cpu_ref
Compile  OK: 5 ops lowered · plan written
Run      OK: 1 output tensor (1, 4)
Compare  OK: 1 tensor · max abs diff 0.0 < tol 1e-05

Common Errors

Message	Meaning	Fix
`weights tensor shape mismatch`	spec op shape ≠ weights.npz	Retrain weights or fix spec
`backend lowering missing for op X`	Backend does not support op X	Check capability_matrix, swap backend
`golden tensor key not found`	result.npz vs golden.npz key mismatch	Check naming convention

All in 3-line format with a See: link.

To simulate cycles/memory on the same graph → 04. npu_sim.