[Feature]: FIR submodule for the Filter module

[gabyfle]

Initial Checklist

• I have searched the existing issues to ensure this feature has not already been requested.

Problem Statement & User Value

As a signal processing engineer, I want to design and apply linear-phase FIR filters so that I can perform filtering without introducing phase distortion, which is critical for applications like high-fidelity audio processing, image processing, and data smoothing where waveform preservation is paramount.

Acceptance Criteria (Definition of Done)

• A new submodule SoundML.Filter.FIR is created as part of the main Filter module.
• A nested Design submodule (Filter.FIR.Design) is available for coefficient generation.
  • A firwin function is implemented for designing standard FIR filters (low-pass, high-pass, etc.) using the window method.[5]
  • A remez function is implemented for designing optimal equiripple filters using the Parks-McClellan algorithm, allowing for more complex and arbitrary frequency responses.[28, 29]
• The core Filter.lfilter function (with denominator a=[1.0]) correctly applies FIR filters by performing convolution.
• The filter application logic automatically selects the most efficient convolution method (direct-form vs. FFT-based) based on the signal and filter lengths to ensure optimal performance.
• All filter application and design operations are differentiable.

Proposed Solution or Technical Approach (Optional)

The Filter.FIR.Design module will support the two primary FIR design methodologies:

1. Window Method (firwin): This intuitive method works by truncating the ideal, infinite-length impulse response of a filter with a finite-length window function (e.g., Hamming, Blackman). The choice of window determines the trade-off between transition bandwidth and stopband attenuation. This is suitable for standard filter types.
2. Parks-McClellan Algorithm (remez): This iterative algorithm designs an optimal equiripple filter that minimizes the maximum error between the desired and actual frequency responses for a given filter length. It offers finer control and is ideal for filters with arbitrary magnitude responses.

The proposed function signatures will be modeled after those in scipy.signal:

(* In module SoundML.Filter.FIR.Design *)

val firwin : numtaps:int -> cutoff:float array ->?window:[...] -> fs:float -> Rune.Tensor.t

val remez : numtaps:int -> bands:float array -> desired:float array ->?weight:float array -> fs:float -> Rune.t

For filter application (convolution), performance is key. The implementation should automatically dispatch to the most efficient algorithm:

• Direct-Form Convolution: For short filters, a direct sum-of-products is most efficient, with complexity $O(N \cdot M)$.
• FFT-Based Convolution: For long filters, convolution in the frequency domain via FFT is significantly faster, with complexity $O(N \log N)$.

This auto-selection, similar to scipy.signal.convolve's method='auto', will provide optimal performance without requiring user intervention.

Additional Context (Mockups, Links, etc.)

Table: Common Window Functions for FIR Design

Window	Min. Stopband Attenuation (approx. dB)	Approx. Main-Lobe Width ($\Delta\omega$)
Rectangular	-21	$4\pi / M$
Bartlett (Triangular)	-25	$8\pi / M$
Hann (Hanning)	-44	$8\pi / M$
Hamming	-53	$8\pi / M$
Blackman	-74	$12\pi / M$

• Note: $M$ is the filter order (numtaps - 1). The main-lobe width dictates the transition bandwidth.

References

• All About Circuits. (2019). Design Examples of FIR Filters Using the Window Method.
• Oppenheim, A. V., & Schafer, R. W. (2010). Discrete-time Signal Processing. Pearson.
• SciPy Documentation. scipy.signal.firwin.
• Wolfram Language Documentation. Digital Filter Design.

Code of Conduct

• I agree to follow this project's Code of Conduct.