adaptif 0.0.1

use crate::types::buffers::NoiseWindowView;
use crate::types::{Float, WindowSize};
use crate::{Error, Result};

use crate::algorithms::Algorithm;

/// Normalized least mean squares algorithm.
#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
pub struct Nlms<F: Float> {
    /// Step size for weight updates.
    mu: F,
    /// Regularization term to avoid division by zero.
    eps: F,
    /// Number of noise samples processed at a time.
    window_size: WindowSize,
}
impl<F: Float> Nlms<F> {
    /// # Errors
    ///
    /// Returns an error if mu <= 0.0.
    /// Returns an error if eps <= 0.0.
    pub fn new(mu: F, eps: F, window_size: WindowSize) -> Result<Self> {
        if mu <= F::zero() {
            return Err(Error::NonPositiveStepSize);
        }

        if eps <= F::zero() {
            return Err(Error::NonPositiveEpsilon);
        }

        Ok(Nlms {
            mu,
            eps,
            window_size,
        })
    }
}
impl<F: Float> Algorithm<F> for Nlms<F> {
    /// Updates the filter weights using the following equation:
    ///
    /// $w_{n+1} = ``w_n`` + \frac{\mu}{\epsilon + \|``x_n``\|^2} ``e_n`` ``x_n``$
    /// where $``e_n``$ is the scalar error for the current sample,
    /// and $``x_n``$ is a vector of length `window_size` of the
    /// most recent noise reference samples.
    fn update_step(&mut self, weights: &mut [F], error: F, noise_window: NoiseWindowView<F>) {
        let norm_squared = noise_window.iter().map(|x| x * x).sum();
        let mu_normalized = self.mu / (self.eps + norm_squared);

        for (w, x) in weights.iter_mut().zip(noise_window.iter()) {
            *w += mu_normalized * error * x;
        }
    }

    fn window_size(&self) -> WindowSize {
        self.window_size
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::indexing_slicing, reason = "Tests")]
mod tests {
    use super::*;
    use crate::{
        test_utils::all_approx_equal,
        types::buffers::NoiseBuffer,
        types::{BlockSize, FilterWeights, WindowSize},
    };

    #[test]
    fn update_nlms_1() {
        let window_size = WindowSize::new(2).unwrap();
        let block_size = BlockSize::new(1).unwrap();

        let mut nlms = Nlms::new(0.5, 1e-8, window_size).unwrap();
        let e_n = 2.0;
        let x_n = NoiseBuffer::from_slice(&[1.0, -1.0], window_size, block_size);
        let expected = [1.0 / (2.0 + nlms.eps), -1.0 / (2.0 + nlms.eps)];
        let mut weights = FilterWeights::new(window_size);

        nlms.update_step(&mut weights, e_n, x_n.window(0).unwrap());

        assert!(all_approx_equal(weights.iter(), expected.iter()));
    }

    #[test]
    fn update_nlms_2() {
        let window_size = WindowSize::new(2).unwrap();
        let block_size = BlockSize::new(1).unwrap();

        let mut nlms = Nlms::new(1.0, 1e-8, window_size).unwrap();
        let e_n = 1.0;
        let x_n = NoiseBuffer::from_slice(&[5.0, 2.0], window_size, block_size);
        let expected = [(5.0 / (29.0 + nlms.eps)), (2.0 / (29.0 + nlms.eps))];
        let mut weights = FilterWeights::new(window_size);

        nlms.update_step(&mut weights, e_n, x_n.window(0).unwrap());

        assert!(all_approx_equal(weights.iter(), expected.iter()));
    }

    #[test]
    fn mu_range() {
        let window_size = WindowSize::new(16).unwrap();

        Nlms::new(1.0, 1e-8, window_size).unwrap();
        Nlms::new(f64::MAX, 1e-8, window_size).unwrap();

        assert!(matches!(
            Nlms::new(0.0, 1e-8, window_size),
            Err(Error::NonPositiveStepSize)
        ));
        assert!(matches!(
            Nlms::new(-1.0, 1e-8, window_size),
            Err(Error::NonPositiveStepSize)
        ));
    }

    #[test]
    fn eps_range() {
        let window_size = WindowSize::new(16).unwrap();

        Nlms::new(1.0, 1e-8, window_size).unwrap();

        assert!(matches!(
            Nlms::new(1.0, 0.0, window_size),
            Err(Error::NonPositiveEpsilon)
        ));
        assert!(matches!(
            Nlms::new(1.0, -1.0, window_size),
            Err(Error::NonPositiveEpsilon)
        ));
    }

    #[test]
    fn window_size_works() {
        let window_size = WindowSize::new(16).unwrap();

        let nlms = Nlms::new(0.1, 1e-8, window_size).unwrap();

        assert_eq!(nlms.window_size(), window_size);
    }
}