[Feature]: IIR 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 DSP engineer, I want to design and apply high-performance, numerically stable IIR filters (Butterworth, Chebyshev, Elliptic) so that I can implement computationally efficient filtering for applications like audio equalization, synthesis, and real-time signal analysis where low latency is critical.

Acceptance Criteria (Definition of Done)

• A new submodule SoundML.Filter.IIR is created as part of the main Filter module.
• A nested Design submodule (Filter.IIR.Design) is available for coefficient generation.
• Design functions for classical analog prototypes are implemented: butter, cheby1, cheby2, and ellip.
• All design functions default to returning coefficients in the numerically stable Second-Order Sections (SOS) format ([num_sections; 6] tensor).
• Design functions provide an optional argument to return coefficients in other standard formats like BA (numerator/denominator) or ZPK (zeros/poles/gain) for advanced use cases.
  • Corresponding order estimation functions (buttord, cheb1ord, etc.) are implemented to help users determine the minimum filter order required to meet their specifications.
  • The Filter.sosfilt function correctly applies filters defined by SOS coefficients.
  • The Filter.lfilter function correctly applies monolithic IIR filters defined by b and a coefficient vectors.
• All filter application and design operations are differentiable with respect to their inputs (including filter parameters).

Proposed Solution or Technical Approach (Optional)

The design methodology will follow the canonical approach of transforming well-understood analog filter prototypes into the digital domain. This process involves:

1. Frequency Pre-warping: The target digital frequencies are transformed into the analog domain to counteract the non-linear frequency mapping of the bilinear transform.
2. Analog Prototype Design: A standard analog low-pass filter (e.g., Butterworth, Chebyshev) is designed in the s-plane using the pre-warped frequencies.
3. Bilinear Transform: The analog filter's transfer function H(s) is converted to a digital transfer function H(z) using the bilinear transform, which maps the left-half of the s-plane to the inside of the z-plane's unit circle.

The design functions will default to factoring the filter into a cascade of second-order sections (SOS), or biquads.

The proposed function signatures in Filter.IIR.Design:

type output_format = SOS | BA | ZPK

val butter : order:int -> wn:float array ->?btype:[...] ->?output:output_format -> fs:float -> Rune.t
(*... similar signatures for cheby1, cheby2, ellip... *)

val buttord : wp:float array -> ws:float array -> gpass:float -> gstop:float -> fs:float -> (int * float array)
(*... and cheb1ord, cheb2ord, ellipord... *)

Additional Context (Mockups, Links, etc.)

Table: Comparison of IIR Analog Prototype Filters

Filter Type	Passband Characteristics	Stopband Characteristics	Transition Width	Primary Use Case
Butterworth	Maximally flat; no ripple.	Monotonically decreasing.	Widest.	Applications where passband flatness is the highest priority.
Chebyshev I	Equiripple.	Monotonically decreasing.	Sharper than Butterworth.	When a sharper cutoff is needed and passband ripple is tolerable.
Chebyshev II	Maximally flat.	Equiripple.	Sharper than Butterworth.	When a flat passband is required but stopband ripple is acceptable.
Elliptic (Cauer)	Equiripple.	Equiripple.	Sharpest possible for a given order.	Applications demanding maximum efficiency in transition width.

References

• Hinton, O. (n.d.). Chapter 5: IIR Filter Design. EEE305 Digital Signal Processing.
• MathWorks Documentation. (n.d.). IIR Filter Design.
• Wikipedia. (2025). Digital biquad filter.
• SciPy Documentation. scipy.signal.sosfilt.

Code of Conduct

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