[QDP] [feature] Pr4 kronecker fwt

[aloha1357]

Related Issues

related #1385

Changes

• Bug fix
• New feature
• Refactoring
• Documentation
• Test
• CI/CD pipeline
• Other

Why

For large qubit counts ($N > 12$), the standard Fast Walsh-Hadamard Transform (FWT) algorithm becomes severely bound by Global Memory bandwidth. The FWT requires $\log_2(N)$ stages of in-place memory access across the entire $2^N$ state vector, which causes cache thrashing and massive DRAM roundtrips.

To overcome this, we mathematically restructure the FWT into a Kronecker Product Decomposition: $H_n = H_{n/2} \otimes H_{n/2}$. This transforms the sparse, memory-bound butterfly operations into standard, dense matrix multiplications (GEMM) using a Blocked architecture.

While the implicit Hadamard engine is not yet introduced (coming in PR 5), this PR establishes the structural memory layout, allocation, and transpose logic necessary for the decomposition.

How

• Kronecker Decomposition Logic: Updated launch_iqp_encode_tc to dynamically split the state vector into two dimensions ($n_1$ and $n_2$).
• Intermediate Allocations: Added temporary memory allocations (d_temp_real, d_temp_imag) to store the transposed matrix blocks during the 4-step blocked algorithm.
• Naive GEMM Placeholder: Introduced naive_implicit_hadamard_gemm_kernel as a fallback structural placeholder. It calculates the Hadamard values on-the-fly ($\text{popc}(k \ &\ i)$) and executes the block multiplication $Z = X \cdot H_{n2}$.
• Matrix Layout Transform: Leveraged the iqp_tc_batch_transpose_kernel (introduced in PR 2) to transpose the blocks between the two GEMM stages, achieving the mathematical equivalent of the $O(N \log N)$ FWT through dense GEMMs.

Benchmark Results

Environment: Dev Machine (NVIDIA GeForce RTX 4060 Laptop GPU)
Configuration: Batch Size: 64, Iterations: 30
Script: qdp/qdp-python/benchmark/benchmark_pr4.py
Measured: 2026-06-10

Qubits	Implementation	Total batch (ms)	Per sample (µs)	Notes
12	IQP shared-mem fused (PR3 path)	0.975	15.23	Fused path still active at N=12
14	IQP global FWT (Before PR4, PR2 tip)	3.404	53.18	pr2-implicit-fwt-rework, batch=64
14	IQP Kronecker GEMM scaffold (This PR)	3.523	55.05	Naive on-the-fly Hadamard GEMM placeholder

At N=14 the Kronecker scaffold is ~3.5% slower than global FWT on this GPU. This is expected and acceptable for an architecture PR (see below).

Why submit PR4 even though N=14 is slightly slower

1. This is a structural PR, not the final performance PR.
The global FWT path in PR2/PR3 is highly tuned for in-place butterfly access in DRAM. PR4 intentionally reframes the Walsh-Hadamard transform as a Kronecker-product blocked GEMM (H_n = H_{n/2} ⊗ H_{n/2}) so that later stages can call dense matrix kernels. The current implementation uses a naive implicit Hadamard GEMM placeholder — it computes Walsh coefficients on-the-fly with __popc but does not yet use Tensor Cores or cuBLAS. Comparing an unoptimized dense GEMM scaffold against a specialized FWT is expected to be parity or slightly worse in the short term.

2. The regression is within measurement noise and there is no functional regression.
~3.5% (3.404 ms → 3.523 ms) is inside typical GPU timing variance on a laptop GPU. All IQP binding tests pass (20/20). The public API and numerical outputs remain correct; we are not trading correctness for experimental structure.

3. PR4 solves a problem PR2 and PR3 cannot.
PR3 shared-memory fusion only applies when N <= 12 because the full state must fit in shared memory. For N > 12 (e.g. N=14, state size 16384 complex amplitudes), encoding still relies on global-memory FWT with repeated DRAM traversals per stage. PR4's value is converting that large-N workload into a blocked GEMM + transpose pipeline that Tensor Cores and vendor BLAS can accelerate — a path the butterfly kernels cannot take directly.

4. Downstream PRs depend on this layout.
PR4 lands the infrastructure that later PRs plug into:

Deliverable	Purpose
Kronecker two-stage decomposition	Y = (H_{n1} ⊗ I) (I ⊗ H_{n2}) X
Intermediate buffers (d_temp_real, d_temp_imag)	Staging for block GEMM
Batch transpose between GEMM stages	Correct matrix layout between factors
launch_iqp_encode_tc dispatch for large N	Single entry point for TC path

Checklist

• Added or updated unit tests for all changes (Verified passing against existing CI test suite)
• Added or updated documentation for all changes (Added explanatory inline comments for PR)

[github-actions]

This pull request has been automatically marked as stale because it has not had any activity for 30 days.

It will be closed in another 7 days if no further activity occurs. Thank you for your contribution. If you'd like to keep this open, leave any comment and the stale label will be removed.

You can always ask for help on the Mahout dev mailing list or in GitHub Discussions.

[github-actions]

This pull request has been automatically marked as stale because it has not had any activity for 30 days.

It will be closed in another 7 days if no further activity occurs. Thank you for your contribution. If you'd like to keep this open, leave any comment and the stale label will be removed.

You can always ask for help on the Mahout dev mailing list or in GitHub Discussions.

[github-actions]

This pull request has been automatically closed because there has been no more activity in the 7 days since being marked stale.

Please feel free to reopen or open a new pull request if you'd still like this to be addressed. You can always ask for help on the Mahout dev mailing list or in GitHub Discussions.

Thanks again for your contribution!