[QDP] Pr2 batch throughput opt

[aloha1357]

Related Issues

related #1385

Changes

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

Why

As part of the IQP Encoding Optimization PR Split Plan, PR 2 focuses on "Batch throughput optimization" and lays the structural groundwork for Tensor Core (TC) acceleration (which will be fully introduced in PR 5 & 6).

Architectural Philosophy: Dual-Path Explicit Opt-in
It is crucial to note that these new Tensor Core optimizations do not automatically replace or override the existing standard algorithms. We are adopting a Dual-Path Architecture:

1. Standard Path (encode_batch): The original, hardware-agnostic FP64 FWT path is fully preserved. This ensures that users on older hardware (without Tensor Cores) or those requiring strict IEEE 754 standard FP64 behavior without any mixed-precision artifacts can continue running unmodified.
2. Tensor Core Path (encode_batch_tc): This is a new, highly specialized API path introduced here. Because Tensor Cores utilize INT8 mixed-precision arithmetic (compensated via the Chinese Remainder Theorem later in PR 6), there are microscopic floating-point differences. In HPC and quantum simulation, auto-dispatching to mixed-precision can cause difficult-to-debug numerical artifacts. Therefore, the TC pipeline is strictly an explicit opt-in for advanced users seeking maximum throughput on supported hardware (Turing/Ampere/Hopper).

To prepare for this encode_batch_tc pipeline, we need a robust scaffolding for batch data transformation. The original code processed matrices sequentially; this refactoring introduces batched layouts and kernels required for the Kronecker-based matrix multiplication that Tensor Cores will eventually execute.

How

• Created iqp_tc.cu: Introduced new kernels specifically designed to manage memory layout for batched operations.
• Phase Split Kernel (iqp_phase_split_kernel): Unrolls the batch and splits the initial phase computation into pure real and imaginary parts to prepare for INT8 matrix multiplication.
• Batch Transpose Kernel (iqp_tc_batch_transpose_kernel): Implemented a Shared Memory Bank-Conflict-Free matrix transpose kernel, essential for efficiently reordering data between Tensor Core FWT stages.
• Recombine Kernel (recombine_complex_kernel): Restores the split real and imaginary parts back into the standard cuDoubleComplex format expected by downstream processes.
• Rust Integration: Updated lib.rs and iqp.rs to expose and call the new launch_iqp_encode_tc function from Rust, laying the structural groundwork for the full Tensor Core pipeline.

Benchmark Results (copy into PR)

Environment: Dev Machine (NVIDIA GeForce RTX 4060 Laptop GPU)
Configuration: Batch Size: 128, Iterations: 30 (N=14 batch=64 shown separately)
Script: qdp/qdp-python/benchmark/benchmark_pr2.py
Measured: 2026-06-10
Compare: 29ff2c44c (before PR2, parent of d2bacdf96) vs pr2-implicit-fwt-rework (this PR)

Qubits	Implementation	Total batch (µs)	Per sample (µs)	Notes
2	IQP naive O(4^n) batch (Before PR2)	333.0	2.60	num_qubits < FWT_MIN_QUBITS
2	IQP implicit FWT batch (This PR)	264.0	2.06	~26% faster
3	IQP naive O(4^n) batch (Before PR2)	323.8	2.53
3	IQP implicit FWT batch (This PR)	354.4	2.77	Within noise (same order of magnitude)
4	IQP global FWT batch (Before PR2)	366.5	2.86	Both sides already on FWT at N≥4
4	IQP implicit FWT batch (This PR)	252.6	1.97	~31% faster (run variance)
8	IQP global FWT batch (Before PR2)	317.2	2.48	Batch path unchanged at N≥4
8	IQP implicit FWT batch (This PR)	361.3	2.82	Parity (~within 15%)
10	IQP global FWT batch (Before PR2)	535.8	4.19
10	IQP implicit FWT batch (This PR)	552.3	4.32	Parity
12	IQP global FWT batch (Before PR2)	1563.8	12.22
12	IQP implicit FWT batch (This PR)	1772.3	13.85	Parity
14	IQP global FWT batch (Before PR2, batch=128)	7375.8	57.62
14	IQP implicit FWT batch (This PR, batch=128)	7689.9	60.08	Parity
14	IQP implicit FWT batch (This PR, batch=64)	3290.2	51.41	Reference for PR4 comparison

Checklist

• Added or updated unit tests for all changes (Verified that existing tests pass, and batching logic doesn't break qdp-core)
• Added or updated documentation for all changes (Added explicit comments describing the purpose of the new kernels)

[ryankert01]

kernel speed only matters when qubits > 16. (unless it's too small, from my experience)

[aloha1357]

Do you want me to remove it or change the size?
I'm fine with both.
This case just should the speed of the throughput, I can also increase the qubits size if that's better?

[ryankert01]

Oops my bad, I thought it's a benchmark because the throughput keyword lol. Nevermind!

[aloha1357]

LOL I also changed it but if you already review it I can also take it back and add it into the next PR.
I rarely put benchmark here, since it's not the final PR of this road map.