Developer_Contributed: add 04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON

[midhatn]

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 for
building 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 bfloat16 kernel
that compiles and runs on the NPU.

It covers:

1. Math: the causal complex FIR equation, real/imaginary decomposition, and
   complex-multiplication identity.
2. Kernel: an AIE2 tile kernel (fir_complex_kernel.cc, 126 lines) that
   computes the real and imaginary output channels in a single pass using
   bfloat16 input and output with float32 taps and accumulation.
3. Host: an IRON Python eDSL program (test_fir_complex_m19.py, 372 lines)
   that generates a deterministic 4096-element bfloat16 I/Q input, compiles
   the kernel with Peano, dispatches it to the Phoenix NPU through XRT, and
   reads the result through the public tensor API.
4. Verify: five deterministic host-side checks (I impulse, Q impulse, DC,
   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:

• Host: ASUS TUF Gaming A15 FA507XI
• Processor: AMD Ryzen 9 7940HS
• NPU: Phoenix XDNA1 / AIE2, reported by XRT as NPU Phoenix
• OS: Windows 11 Pro build 26200.9168
• XRT runtime: 2.21.0
• XRT SDK package: 2.21.75
• XDNA driver: 32.0.20102.3930
• NPU firmware: 1.5.5.391
• Python: 3.13.15
• MLIR-AIE Python package: 1.4.1
• MLIR-AIE source revision used for the recorded run:
  3ca0193cea9e2c39ec670a65f93e1dd43c969f22
• LLVM-AIE Peano: 21.0.0.2026080301+c9c5ecb7
• NumPy: 2.5.2
• ml_dtypes: 0.6.0

The included scripts/run_tutorial.ps1 performs 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:

Maximum absolute error: 0.007812
SUCCESS: the NPU output is finite and satisfies the absolute-tolerance contract (<= 0.010000).
PASS!

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.py selects the matching mlir_aie==1.4.1 release wheel and
the repository-pinned Peano package.

What was changed

• Added:
  Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/, containing
  10 source, script, documentation, license, and provenance files.
• Modified: Developer_Contributed/README.md, adding tutorial 04 to the
  tutorial index and repairing the missing opening <tr> tags for the existing
  tutorial 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, a
personal open-source project containing Phoenix-NPU DSP and PQC kernels. The
tutorial version was reviewed and adapted for a self-contained upstream
submission.

• Project roadmap item C4:
  https://github.com/midhatn/phoenix-sdr-dsp/blob/main/docs/ROADMAP_v1.1.0.md
• Recorded source revision:
  4bc0f158e9208469cf356d1349cef1aff55e8e47

The immutable source provenance is also recorded in the tutorial NOTICE.

Legal information for review

• License: MIT. See
  Developer_Contributed/04-Complex_FIR_on_Ryzen_AI_NPU_with_IRON/LICENSE.
• Copyright: © 2026 Midhat Nashar. The contributor holds the copyright and
  provides the contribution under the MIT License.
• Third-party code: None is vendored or included. MLIR-AIE, LLVM-AIE, XRT,
  NumPy, and ml_dtypes are external dependencies and are not shipped in this
  PR.
• AI-assisted preparation: the source and documentation were prepared with
  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:

Signed-off-by: MIDHAT NASHAR <medhat.nashar@gmail.com>

Target branch

2026.1, matching the Vitis-Tutorials release branch selected for this
submission.

[Copilot]

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.md to 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.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.