example_qcnn_forward_pass module
Standalone script for QCNN forward-pass application example: a small quaternion-valued CNN (2 convolutional layers + flatten + dense layer), applied to a batch of synthetic (“dummy”) RGB-D images. Both the direct and proposed-algorithm CUDA backends are timed per layer.
Scope: forward pass only. SGD (backpropagation training) are explicitly out of scope for this illustrative example.
Input encoding: each pixel is represented as a single quaternion, with the three imaginary parts carrying the R, G, B channels and the real part carrying a fourth, synthetic channel (e.g. a depth/LiDAR-intensity-style measurement), so that all four quaternion components are genuinely exercised.
Convolution is implemented as im2col-style unfolding (extracting all k x k receptive fields into columns) followed by a single qmm.dot call, using “same” zero-padding so spatial dimensions (H, W) are preserved across both convolutional layers.
Weight initialization: He-uniform for the two convolutional layers (followed by split QReLU) and Glorot-uniform for the dense layer (no activation on its output), both adapted for the quaternion Hamilton-product structure.
Link to project repository
- example_qcnn_forward_pass.unfold_quaternion(X, k, pad=None)[source]
X: quaternion feature map, shape (B, C_in, H, W, 4). Applies ‘same’ zero-padding by default (pad=(k-1)//2 on each side of H and W, for odd k), so H_out=H, W_out=W; pass pad=0 for a valid (unpadded) convolution. Returns the unfolded matrix, shape (C_in*k*k, B*H_out*W_out, 4), ready to be used as the right-hand factor of a qmm.dot call (weights as the left factor), plus the output spatial size.
- example_qcnn_forward_pass.fold_quaternion(Z, B, H, W)[source]
Inverse reshape: conv output Z, shape (C, B*H*W, 4), back to a feature-map tensor of shape (B, C, H, W, 4), ready as input to the next convolution.
- example_qcnn_forward_pass.he_range(fan_in, kappa=4)[source]
He-uniform range for a quaternion layer followed by (Q)ReLU: R = sqrt(6/(kappa*fan_in)), kappa=4 accounts for the four independent real products per summed term in the quaternion Hamilton-product structure (kappa=1 recovers the standard real-valued He-uniform bound sqrt(6/fan_in)).