Developer_Contributed: add 04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON - #511
Developer_Contributed: add 04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON#511midhatn wants to merge 2 commits into
Conversation
Signed-off-by: MIDHAT NASHAR <medhat.nashar@gmail.com>
There was a problem hiding this comment.
Pull request overview
This PR adds a new self-contained “Developer Contributed” tutorial demonstrating an end-to-end 8‑tap complex FIR running on a Ryzen AI (Phoenix XDNA1 / AIE2) NPU via the open-source IRON / MLIR-AIE Python flow, plus updates the Developer_Contributed index to include it.
Changes:
- Adds tutorial
04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/including AIE2 C++ kernel, IRON host program, environment preflight, runner script, and supporting documentation. - Updates
Developer_Contributed/README.mdto fix table row markup and add the new tutorial entry.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| Developer_Contributed/README.md | Fixes missing <tr> tags and adds the new tutorial row to the index table. |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/README.md | Tutorial landing page describing scope, setup entry points, and validation contract. |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/NOTICE | Records upstream provenance (repo + immutable revision + originating paths). |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/LICENSE | MIT license text for the contributed tutorial. |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/src/test_fir_complex_m19.py | IRON host program: builds/dispatches kernel, runs deterministic reference checks, and validates silicon output vs NumPy reference. |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/src/fir_complex_kernel.cc | AIE2 kernel implementing the fixed-size 2048-sample complex FIR and writing interleaved bfloat16 output. |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/src/check_environment.py | Preflight script verifying required Python package versions and basic imports. |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/scripts/run_tutorial.ps1 | PowerShell runner that executes preflight and the tutorial, propagating failures via exit code. |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/doc/SETUP.md | Windows-native setup guide with tested baseline and reproducible environment creation steps. |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/doc/WALKTHROUGH.md | Walkthrough of math, kernel structure, host program flow, and validation steps. |
| Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/doc/M19_DESIGN.md | Design/spec reference: mathematical formulation, data layout, validation rule, and IRON mapping. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
midhatn
changed the title
Signed-off-by: MIDHAT NASHAR <medhat.nashar@gmail.com>
|
Maintainers, the final files in this contribution have now been revalidated from their location in the Vitis-Tutorials 2026.1 tree on a Ryzen 9 7940HS Phoenix XDNA1 NPU using MLIR-AIE/IRON 1.4.1 and LLVM-AIE 21.0.0.2026080301+c9c5ecb7. The complete tutorial run passed all host-side reference checks and the NPU dispatch, with a maximum absolute error of 0.007812 against the documented 0.010000 acceptance limit. The follow-up Copilot review also reported no new comments after the dependency-preflight fix. I am happy to rebase, separate the index change, or reduce the example further if that would make review easier. Could you please advise which maintainer or team handles Developer_Contributed reviews for the 2026.1 branch? |
What does this PR do?
Adds a new Developer Contributed tutorial:
04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON, an end-to-end tutorial forbuilding and validating an 8-tap complex FIR filter (complex taps × complex
I/Q) on an AMD Phoenix NPU (XDNA1 / AIE2) from a Windows 11 host using the
IRON Python eDSL.
The tutorial is intended for developers with a Phoenix XDNA1 NPU visible to
XRT who want a small, self-contained example of an SDR-style
bfloat16kernelthat compiles and runs on the NPU.
It covers:
complex-multiplication identity.
fir_complex_kernel.cc, 126 lines) thatcomputes the real and imaginary output channels in a single pass using
bfloat16input and output withfloat32taps and accumulation.test_fir_complex_m19.py, 372 lines)that generates a deterministic 4096-element
bfloat16I/Q input, compilesthe kernel with Peano, dispatches it to the Phoenix NPU through XRT, and
reads the result through the public tensor API.
complex tone, and real-FIR algebraic reduction), followed by a random-I/Q
silicon comparison against an independent NumPy reference. The silicon
comparison rejects shape mismatches and non-finite output and applies an
absolute-only functional tolerance of
0.01.Why this tutorial fills a gap in the existing Developer_Contributed set
The current tutorials index contains three entries targeted at Versal,
VCK190, or ZCU102 platforms. The related MLIR-AIE FIR tutorials elsewhere in
the repository target Versal AIE flows and real-valued filters. This tutorial
instead demonstrates a complex-valued FIR with complex I/Q data on the Phoenix
XDNA1 NPU through the IRON / MLIR-AIE Python flow, which is a practical
software-defined-radio use case.
Verification
The exact files in this branch were validated end-to-end on a real Phoenix NPU
on Windows 11:
NPU Phoenix3ca0193cea9e2c39ec670a65f93e1dd43c969f2221.0.0.2026080301+c9c5ecb7The included
scripts/run_tutorial.ps1performs package preflight checks,propagates native Python failures under Windows PowerShell 5.1 and PowerShell
7, runs all host reference checks, compiles the kernel, dispatches it to the
NPU, and validates the silicon output.
The recorded run completed with:
For a reproducible reader setup, the documentation uses the immutable
MLIR-AIE v1.4.1 tag at revision
601fc859532f2539bebb33ac89139584c76ae8a2. At that tag,utils/iron_setup.pyselects the matchingmlir_aie==1.4.1release wheel andthe repository-pinned Peano package.
What was changed
Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/, containing10 source, script, documentation, license, and provenance files.
Developer_Contributed/README.md, adding tutorial 04 to thetutorial index and repairing the missing opening
<tr>tags for the existingtutorial 02 and 03 rows. The existing UTF-8 BOM is preserved.
No binary files, generated bytecode, compiled objects, NPU binaries, or
compressed archives are included.
Upstream project
The kernel and Python reference originate from
midhatn/phoenix-sdr-dsp, apersonal open-source project containing Phoenix-NPU DSP and PQC kernels. The
tutorial version was reviewed and adapted for a self-contained upstream
submission.
https://github.com/midhatn/phoenix-sdr-dsp/blob/main/docs/ROADMAP_v1.1.0.md
4bc0f158e9208469cf356d1349cef1aff55e8e47The immutable source provenance is also recorded in the tutorial
NOTICE.Legal information for review
Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/LICENSE.provides the contribution under the MIT License.
NumPy, and
ml_dtypesare external dependencies and are not shipped in thisPR.
AI assistance and reviewed by the human author, @midhatn. The DCO sign-off is
the author's attestation that they have the right to submit the work under
the stated license.
Commit sign-off (DCO)
The single commit in this PR is signed off:
Target branch
2026.1, matching the Vitis-Tutorials release branch selected for thissubmission.