03. 컴파일 + 실행 (compile / run)

스펙이 validate를 통과하면 → compile → run 순서로 갑니다. 이 단계가 spec(설계)을 artifact(실행 가능한 것)로 바꾸는 단계입니다.

파이프라인

spec.yaml (validate ✓)
   ↓
eulernpu compile  →  artifact (graph IR + lowering plan)
   ↓
eulernpu run      →  result.npz
   ↓
                     vs golden.npz → 정확도/결정성 검증

compile

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

출력:

tiny_mlp.artifact/graph.json — lowered op graph
tiny_mlp.artifact/weights/*.npz — backend-tagged weights
tiny_mlp.artifact/plan.json — execution plan (메모리 할당, 스케줄)

--backend 옵션으로 lowering 대상이 결정됩니다:

cpu_ref (기본) — 모든 op이 reference 구현
npu_sim — cycle model을 통과시키는 lowering
zynq_ps — ARM에서 실행할 수 있는 lowering
fpga_board — PL 오프로드 후보 op 분리

run

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

출력:

tiny_mlp.result.npz — 그래프 출력 텐서 (보통 logits)

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

cpu_ref 백엔드는 결정적입니다. 같은 input + 같은 weights → 같은 output. golden은 그 결정성을 회귀 방지로 사용합니다.

백엔드 바꾸기 — 한 줄 변경

--backend 만 바꾸면 같은 스펙이 다른 백엔드로 lowering됩니다:

# cpu_ref (golden 생성용)
eulernpu compile --spec ... --backend cpu_ref --out /tmp/a

# npu_sim (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

백엔드별로 결과가 byte-equal인지 검증하는 게 결정성(determinism) 보장의 첫 단계입니다.

end-to-end 예시 — 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

기대 출력:

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

자주 보는 에러

메시지	의미	조치
`weights tensor shape mismatch`	스펙의 op shape ≠ weights.npz	weights 재학습 또는 스펙 수정
`backend lowering missing for op X`	그 백엔드가 op X 미지원	capability_matrix 확인 후 백엔드 교체
`golden tensor key not found`	result.npz와 golden.npz key 불일치	naming convention 확인

모두 3줄 포맷 에러 + See: 링크 포함.

다음 단계

같은 그래프를 시뮬레이션해서 cycle/memory를 측정하려면 → 04. npu_sim.