[Feature]: Filtering 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 machine learning engineer, I want to apply a wide range of standard digital filters (e.g., for noise reduction, equalization, feature extraction) to signals represented as Rune tensors, so that I can build advanced, end-to-end differentiable signal processing and deep learning pipelines in OCaml.

As a DSP engineer, I want a robust, composable, and purely functional filtering library, so that I can build complex, multi-stage processing chains that are easy to reason about, test, and maintain.

Acceptance Criteria (Definition of Done)

• A new top-level module SoundML.Filter is created to house all filtering functionality.
  • The module contains submodules for distinct filter families, including Filter.IIR and Filter.FIR.
  • Core data types for representing filter coefficients and state are defined using Rune.t. This includes types for fir_coeffs, iir_coeffs, and the numerically-preferred sos_coeffs (second-order sections).
• A primary set of pure, stateless filter application functions are available:
  • lfilter: A general-purpose function for applying filters defined by numerator (b) and denominator (a) coefficients, suitable for both FIR and monolithic IIR filters.
  • sosfilt: A function for applying IIR filters defined as a cascade of second-order sections, which is the recommended approach for numerical stability.
  • filtfilt: A function for zero-phase filtering that processes a signal forward and backward, eliminating phase distortion. A sosfiltfilt variant is also provided.
• The core API follows a functional, explicit-state-passing paradigm: (state, input) -> (new_state, output), making it suitable for both batch and streaming applications without requiring separate APIs.
• All filtering operations are implemented using Rune primitives, making them fully differentiable by default.
• Comprehensive documentation is provided for the module architecture, core functions, and the trade-offs between FIR and IIR filters.

Proposed Solution or Technical Approach (Optional)

The proposed architecture is a hierarchical module structure: SoundML.Filter will contain the core application functions and shared types, with nested modules for IIR and FIR filters. Each of these will contain a further nested Design submodule for coefficient generation.

module Filter = struct
  (* Core application functions and shared types *)

  module IIR = struct
    module Design = struct (*... *) end
    (*... *)
  end

  module FIR = struct
    module Design = struct (*... *) end
    (*... *)
  end
end

The key design principle is a functional-first, explicit-state API.

Additional Context (Mockups, Links, etc.)

This parent issue tracks the overall creation of the Filter module. The specific implementations for IIR and FIR filters are detailed in the following child issues:

• IIR Submodule: [Feature]: IIR submodule for the Filter module #22
• FIR Submodule: [Feature]: FIR submodule for the Filter module #23

To guide users, the documentation should include a comparison of the two main filter families:

Table: FIR vs. IIR Filter Characteristics Summary

Feature	FIR (Finite Impulse Response)	IIR (Infinite Impulse Response)
Stability	Always stable.	Stability is not guaranteed; depends on pole locations.
Phase Response	Can have perfect linear phase.	Inherently non-linear phase response.
Computational Cost	Higher order needed for sharp cutoffs, thus more computationally intensive.	Achieves sharp cutoffs with a much lower order; computationally efficient.
Latency/Delay	Higher group delay.	Lower group delay, better for real-time applications.
Numerical Precision	Less sensitive to coefficient quantization errors.	More sensitive to quantization, which can lead to instability or limit cycles.

References

• Oppenheim, A. V., & Schafer, R. W. (2010). Discrete-time Signal Processing. Pearson. [18, 19]
• SciPy Signal Processing Documentation (scipy.signal): https://docs.scipy.org/doc/scipy/reference/signal.html

Code of Conduct

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