Problem: Convolution Function Implementation

The problem aims to create a pipeline for processing N-dimensional images and kernels to generate feature maps. It involves extracting normalized sliding windows from images, flattening kernels, computing dot products with attention, activation, and precise summation, then reshaping results into 2D feature maps for image processing tasks.

Background: ### Industry & Mathematical Background for Reproducing the Modular Convolution Pipeline
This code implements an enhanced, modular sliding-window convolution workflow—core to computer vision, signal processing, and scientific computing. Below is the critical context to reproduce and understand the implementation:

#### 1. Sliding Window Feature Extraction (`extract_windows`)
- **Mathematical Foundations**:
  - Valid sliding window dimensions are calculated as `out_h = H - k_size + 1` and `out_w = W - k_size + 1`, where `H/W` are the input image’s height/width, ensuring windows fit within input bounds.
  - Z-score normalization: `normalized_val = (x - mean) / std`; handles zero-variance cases by setting all values to 0 to avoid division by zero.
- **Industry Context**:
  - Sliding windows are foundational to Convolutional Neural Networks (CNNs) for extracting local features (edges, textures) in tasks like image classification, medical imaging, and satellite data analysis.
  - Sparse matrix support addresses large-scale datasets with sparse values (e.g., 3D volumetric scans) where dense storage is computationally inefficient.
  - Rigorous input validation ensures robustness against malformed real-world imaging data.

#### 2. Kernel Flattening (`flatten_kernel`)
- **Mathematical Foundations**:
  - Row-major (C-style) flattening converts multi-dimensional kernels to 1D lists, preserving row-by-row element order to align with standard convolution dot-product requirements.
- **Industry Context**:
  - Kernels apply linear transformations in CNNs; flattening enables efficient dot-product calculations with sliding windows. Numpy’s `ravel(order='C')` is the de facto standard for this operation, supporting diverse kernel types (integer for edge detection, float for blur filters, complex for frequency-domain processing).

#### 3. Attention-Aware Dot Product Calculation (`compute_dot_products`)
- **Mathematical Foundations**:
  - **Attention Weights**: Similarity-based scoring (`abs(k_val * w_val) / (abs(k_val) + abs(w_val) + 1e-10)`) prioritizes relevant kernel-window element pairs, normalized via softmax to sum to 1.
  - **Tanh Activation**: Bounds output values to [-1,1], mitigating numerical explosion and improving feature scaling.
  - **Kahan Summation**: Reduces floating-point accumulation errors by tracking a compensation term, critical for high-precision signal processing.
  - **Conjugate Multiplication**: Handles complex-valued kernels/windows, common in Fourier-transform-based signal processing.
- **Industry Context**:
  - Attention mechanisms, adapted from transformers, make convolution adaptive—dynamically weighting important local features to boost performance in fine-grained image recognition and audio processing.
  - Kahan summation is essential for maintaining precision in large-scale pipelines with thousands of dot-product computations.

#### 4. Feature Map Reshaping (`reshape_feature_map`)
- **Mathematical Foundations**:
  - Splits a 1D list into 2D chunks of size `output_width`, preserving spatial structure: `feature_map = [values[i*output_width : (i+1)*output_width] for i in range(output_height)]`.
- **Industry Context**:
  - Reshaping 1D convolution results back to 2D preserves spatial relationships required for subsequent CNN operations (pooling, upsampling) or visualization. Support for numpy arrays, pandas Series, and scipy sparse matrices caters to diverse data formats in data science workflows.

---

### Required Import Statements
```
import itertools
from typing import Union, List, Tuple, Any
import scipy.sparse as sp_module
import numpy as np
from collections.abc import Iterable
import numbers
import pandas as pd
import math
```

*Note: `scipy.sparse` and `pandas` are optional dependencies; the code includes try-except blocks to handle their absence, but full functionality (sparse matrix support, pandas Series handling) requires installing them.*

Input/Output: The problem receives an N-dimensional input image (a nested list with consistent dimensions or a scipy.sparse.spmatrix, at least 2D) and a numeric kernel (an iterable of integer, float, or complex values). It generates a 2D feature map (a nested list) by extracting z-score-normalized sliding windows from the image using the kernel’s size, flattening the kernel into a 1D list, computing attention-weighted dot products between each window and the flattened kernel (with tanh activation and Kahan summation for accuracy), and reshaping the results into the feature map using the output height and width derived from the image and kernel dimensions.

Required dependencies:
import itertools
import numbers
import math
from collections.abc import Iterable
from typing import Union, List, Tuple, Any, Iterable
import scipy.sparse
import numpy as np
import pandas as pd

Sub-steps:
step_number: 1
step_description_prompt: Please write a Python function named extract_windows. It extracts sliding windows from N-dimensional images (supports scipy sparse matrices), validates inputs, computes output dimensions, normalizes windows using z-score, and returns the windows list along with output height and width.
function_header: def extract_windows(image, k_size):
test_cases: for img, k, exp_len, exp_h, exp_w in [
    ([[1,2],[3,4]], 2, 1, 1, 1),
    ([[1,2,3],[4,5,6],[7,8,9]], 2, 4, 2, 2),
    ([[1,2,3],[4,5,6],[7,8,9]], 3, 1, 1, 1)
]:
    wins, oh, ow = extract_windows(img, k)
    assert len(wins) == exp_len and oh == exp_h and ow == exp_w

    for win in wins:
        assert len(win) == k * k, f"Each window should have {k*k} elements, got {len(win)}"

        assert all(isinstance(x, (int, float)) for x in win), "All window elements should be numeric"
        assert all(math.isfinite(x) for x in win), "All window elements should be finite"

    if img == [[1,2],[3,4]] and k == 2:
        assert len(wins) == 1, "Should have exactly one window"
        assert len(wins[0]) == 4, "Window should have 4 elements"
        assert all(isinstance(x, (int, float)) for x in wins[0]), "Window elements should be numeric"
        assert abs(sum(wins[0])) < 1e-6, f"Normalized window should have sum near 0, got {sum(wins[0])}"

    expected_wins = (len(img) - k + 1) * (len(img[0]) - k + 1) if len(img) >= k and len(img[0]) >= k else 0
    assert len(wins) == expected_wins, f"Window count mismatch: got {len(wins)}, expected {expected_wins} (formula: (H-k+1)*(W-k+1))"

    assert oh == max(0, len(img) - k + 1), f"Output height mismatch: got {oh}, expected {max(0, len(img) - k + 1)}"
    assert ow == max(0, len(img[0]) - k + 1), f"Output width mismatch: got {ow}, expected {max(0, len(img[0]) - k + 1)}"


edge_cases = [
    ([[1]], 1, "1x1 image with 1x1 kernel"),
    ([[1, 2, 3, 4, 5]], 2, "1x5 image with 2x2 kernel"),
    ([[1], [2], [3], [4], [5]], 2, "5x1 image with 2x2 kernel"),
]
for img, k, desc in edge_cases:
    try:
        wins, oh, ow = extract_windows(img, k)

        assert isinstance(wins, list), f"Edge case '{desc}': Result should be a list"
        assert isinstance(oh, int) and isinstance(ow, int), f"Edge case '{desc}': Output dimensions should be integers"

        for win in wins:
            assert len(win) == k * k, f"Edge case '{desc}': Each window should have {k*k} elements"
            assert all(isinstance(x, (int, float)) for x in win), f"Edge case '{desc}': Window elements should be numeric"
    except (ValueError, IndexError, TypeError):
        pass

step_number: 2
step_description_prompt: Please write a Python function named flatten_kernel that returns a list of Union[float, int, complex]. It first handles numpy import error, checks if input is an iterable, converts it to a numpy array (validating numeric type), flattens in row-major order, converts back to list, and handles relevant type errors properly.
function_header: def flatten_kernel(kernel):
test_cases: import math
for ker, expected in [
    ([[1, 2], [3, 4]], [1, 2, 3, 4]),
    ([[0, -1, 0], [-1, 5, -1], [0, -1, 0]], [0, -1, 0, -1, 5, -1, 0, -1, 0]),
    ([[1]], [1])
]:
    assert flatten_kernel(ker) == expected

step_number: 3
step_description_prompt: Please write Python code to generate a function named compute_dot_products. This function takes two iterables: windows (iterable of numeric sequences) and flat_kernel (iterable of numbers). It validates inputs, computes attention weights via similarity, normalizes with softmax, applies attention to terms (window * conjugate kernel), uses tanh activation, Kahan summation for accuracy, then returns the results list.
function_header: def compute_dot_products(windows, flat_kernel):
test_cases: for wins, f_ker, desc in [
    ([[1, 1, 1, 1]], [1, 2, 3, 4], "Test 1: All ones window"),
    ([[1, 0, 0, 1], [0, 1, 1, 0]], [2, 3, 4, 5], "Test 2: Sparse windows"),
    ([[1, 2], [3, 4]], [1, 1], "Test 3: Small windows")
]:
    res = compute_dot_products(wins, f_ker)

    res_real = [r.real if isinstance(r, complex) else float(r) for r in res]

    assert len(res) == len(wins), f"{desc}: Result length {len(res)} should match number of windows {len(wins)}"

    assert all(math.isfinite(r) for r in res_real), f"{desc}: Results must be finite: {res_real}"


    max_abs_result = max(abs(r) for r in res_real) if res_real else 0
    assert max_abs_result <= len(f_ker) * 2, f"{desc}: Results should be bounded (tanh sum), got max_abs={max_abs_result}"

    if len(wins) == 1 and len(f_ker) == len(wins[0]):
        if all(x >= 0 for x in wins[0]) and all(x >= 0 for x in f_ker):

            assert res_real[0] >= -0.1, f"{desc}: Dot product of non-negative vectors should be non-negative, got {res_real[0]}"

    assert all(isinstance(r, (int, float, complex)) for r in res), f"{desc}: All results should be numeric"


edge_cases = [
    ([[0, 0, 0, 0]], [0, 0, 0, 0], "zero vectors"),
    ([[1e10, 1e10, 1e10, 1e10]], [1, 1, 1, 1], "very large values"),
    ([[1e-10, 1e-10, 1e-10, 1e-10]], [1, 1, 1, 1], "very small values"),
]
for wins, f_ker, desc in edge_cases:
    try:
        res = compute_dot_products(wins, f_ker)
        assert len(res) == len(wins), f"Edge case '{desc}': Result length should match window count"
        assert all(math.isfinite(r) for r in res), f"Edge case '{desc}': All results must be finite"
    except (ValueError, OverflowError, TypeError):
        pass

step_number: 4
step_description_prompt: ```python
def reshape_feature_map(
    values,
    output_height,
    output_width
):
    """Reshape a 1D iterable into a 2D feature map with specified height and width.

    Enhancements over the original implementation:
    - Supports scipy sparse arrays, numpy arrays, and pandas Series as input.
    - Efficient reshaping using list slicing (O(n) time with lower constant factors).
    - Strict input validation (type checks, positivity, iterability, NaN/Infinity checks).
    - Memory-optimized implementation (avoids intermediate row appends).

    Args:
        values: 1D iterable of values (supports lists, tuples, numpy arrays, pandas Series, scipy sparse matrices).
        output_height: Positive integer specifying the height of the output feature map.
        output_width: Positive integer specifying the width of the output feature map.

    Returns:
        2D list (feature map) of shape (output_height, output_width) containing the input values.

    Raises:
        TypeError: If output_height/output_width are not integers, or values is not an iterable.
        ValueError: If output_height/output_width are non-positive, or the length of values does not match
            output_height * output_width, or values contains NaN/Infinity.
    """
    if not isinstance(output_height, int):
        raise TypeError(f"output_height must be an integer, got {type(output_height).__name__}")
    if not isinstance(output_width, int):
        raise TypeError(f"output_width must be an integer, got {type(output_width).__name__}")
    if output_height <= 0:
        raise ValueError(f"output_height must be positive, got {output_height}")
    if output_width <= 0:
        raise ValueError(f"output_width must be positive, got {output_width}")

    if isinstance(values, (str, bytes)):
        raise TypeError("'values' must be an iterable of values, not a string/bytes")
    if not hasattr(values, '__iter__'):
        raise TypeError(f"'values' must be an iterable, got {type(values).__name__}")

    try:
        from scipy import sparse
        if isinstance(values, sparse.spmatrix):
            values = values.toarray().flatten().tolist()
    except ImportError:
        pass

    try:
        import numpy as np
        if isinstance(values, np.ndarray):
            values = values.ravel().tolist()
    except ImportError:
        pass

    try:
        import pandas as pd
        if isinstance(values, pd.Series):
            values = values.to_numpy().ravel().tolist()
    except ImportError:
        pass

    try:
        values = list(values)
    except TypeError as e:
        raise TypeError(f"'values' is not a valid iterable: {e}")

    expected_length = output_height * output_width
    if len(values) != expected_length:
        raise ValueError(f"Dimension mismatch: expected {expected_length} elements, got {len(values)}")

    import math
    for val in values:
        if isinstance(val, complex):
            if not (math.isfinite(val.real) and math.isfinite(val.imag)):
                raise ValueError("'values' contains NaN or Infinity")
        elif isinstance(val, (int, float)):
            if not math.isfinite(val):
                raise ValueError("'values' contains NaN or Infinity")

    feature_map = [values[i * output_width : (i + 1) * output_width] for i in range(output_height)]
    return feature_map
```
function_header: def reshape_feature_map(values, output_height, output_width):
test_cases: import math
for vals, oh, ow, expected in [
    ([1, 2, 3, 4], 2, 2, [[1, 2], [3, 4]]),
    ([10, 20], 1, 2, [[10, 20]]),
    ([1, 2, 3, 4, 5, 6], 2, 3, [[1, 2, 3], [4, 5, 6]])
]:
    assert reshape_feature_map(vals, oh, ow) == expected

General solution:

General tests: