Change VecDeque for fixed-capacity ArrayDeque in LinearRegression (#2667)

Author: nicolad

crates/indicators/src/average/lr.rs

@@ -3,7 +3,7 @@
 //  https://nautechsystems.io
 //
 //  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
-//   You may not use this file except in compliance with the License.
+//  You may not use this file except in compliance with the License.
 //  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
 //
 //  Unless required by applicable law or agreed to in writing, software
@@ -13,15 +13,15 @@
 //  limitations under the License.
 // -------------------------------------------------------------------------------------------------
 
-use std::{
-    collections::VecDeque,
-    fmt::{Debug, Display},
-};
+use std::fmt::{Debug, Display};
 
+use arraydeque::{ArrayDeque, Wrapping};
 use nautilus_model::data::Bar;
 
 use crate::indicator::Indicator;
 
+const MAX_PERIOD: usize = 16_384;
+
 #[repr(C)]
 #[derive(Debug)]
 #[cfg_attr(
@@ -38,7 +38,7 @@ pub struct LinearRegression {
     pub value: f64,
     pub initialized: bool,
     has_inputs: bool,
-    inputs: VecDeque<f64>,
+    inputs: ArrayDeque<f64, MAX_PERIOD, Wrapping>,
     x_sum: f64,
     x_mul_sum: f64,
     divisor: f64,
@@ -54,9 +54,11 @@ impl Indicator for LinearRegression {
     fn name(&self) -> String {
         stringify!(LinearRegression).into()
     }
+
     fn has_inputs(&self) -> bool {
         self.has_inputs
     }
+
     fn initialized(&self) -> bool {
         self.initialized
     }
@@ -83,13 +85,18 @@ impl LinearRegression {
     ///
     /// # Panics
     ///
-    /// Panics if `period` is not positive (> 0).
+    /// * Panics if `period` is zero.
+    /// * Panics if `period` exceeds [`MAX_PERIOD`].
     #[must_use]
     pub fn new(period: usize) -> Self {
         assert!(
             period > 0,
             "LinearRegression: period must be > 0 (received {period})"
         );
+        assert!(
+            period <= MAX_PERIOD,
+            "LinearRegression: period {period} exceeds MAX_PERIOD ({MAX_PERIOD})"
+        );
 
         let n = period as f64;
         let x_sum = 0.5 * n * (n + 1.0);
@@ -104,9 +111,9 @@ impl LinearRegression {
             cfo: 0.0,
             r2: 0.0,
             value: 0.0,
-            inputs: VecDeque::with_capacity(period),
-            has_inputs: false,
             initialized: false,
+            has_inputs: false,
+            inputs: ArrayDeque::new(),
             x_sum,
             x_mul_sum,
             divisor,
@@ -116,13 +123,13 @@ impl LinearRegression {
     /// Updates the linear regression with a new data point.
     ///
     /// # Panics
-    ///
-    /// Panics if there is insufficient data to compute the regression (empty history).
+    /// Panics if called with an empty window – this is protected against by the logic
+    /// that returns early until enough samples have been collected.
     pub fn update_raw(&mut self, close: f64) {
         if self.inputs.len() == self.period {
-            self.inputs.pop_front();
+            let _ = self.inputs.pop_front();
         }
-        self.inputs.push_back(close);
+        let _ = self.inputs.push_back(close);
 
         self.has_inputs = true;
         if self.inputs.len() < self.period {
@@ -135,9 +142,7 @@ impl LinearRegression {
         let x_mul_sum = self.x_mul_sum;
         let divisor = self.divisor;
 
-        let mut y_sum = 0.0;
-        let mut xy_sum = 0.0;
-
+        let (mut y_sum, mut xy_sum) = (0.0, 0.0);
         for (i, &y) in self.inputs.iter().enumerate() {
             let x = (i + 1) as f64;
             y_sum += y;
@@ -147,10 +152,7 @@ impl LinearRegression {
         self.slope = n.mul_add(xy_sum, -(x_sum * y_sum)) / divisor;
         self.intercept = y_sum.mul_add(x_mul_sum, -(x_sum * xy_sum)) / divisor;
 
-        let mut sse = 0.0;
-        let mut y_last = 0.0;
-        let mut e_last = 0.0;
-
+        let (mut sse, mut y_last, mut e_last) = (0.0, 0.0, 0.0);
         for (i, &y) in self.inputs.iter().enumerate() {
             let x = (i + 1) as f64;
             let y_hat = self.slope.mul_add(x, self.intercept);
@@ -194,6 +196,7 @@ mod tests {
     use nautilus_model::data::Bar;
     use rstest::rstest;
 
+    use super::*;
     use crate::{
         average::lr::LinearRegression,
         indicator::Indicator,
@@ -470,4 +473,134 @@ mod tests {
         assert_eq!(lr.x_mul_sum, x_mul_sum, "x_mul_sum must survive reset()");
         assert_eq!(lr.divisor, divisor, "divisor must survive reset()");
     }
+
+    const EPS: f64 = 1e-12;
+
+    #[rstest]
+    #[should_panic]
+    fn new_zero_period_panics() {
+        let _ = LinearRegression::new(0);
+    }
+
+    #[rstest]
+    #[should_panic]
+    fn new_period_exceeds_max_panics() {
+        let _ = LinearRegression::new(MAX_PERIOD + 1);
+    }
+
+    #[rstest(
+        period, value,
+        case(8, 5.0),
+        case(16, -3.1415)
+    )]
+    fn constant_non_zero_series(period: usize, value: f64) {
+        let mut lr = LinearRegression::new(period);
+
+        for _ in 0..period {
+            lr.update_raw(value);
+        }
+
+        assert!(lr.initialized());
+        assert!(lr.slope.abs() < EPS);
+        assert!((lr.intercept - value).abs() < EPS);
+        assert_eq!(lr.degree, 0.0);
+        assert!(lr.r2.is_nan());
+        assert!((lr.cfo).abs() < EPS);
+        assert!((lr.value - value).abs() < EPS);
+    }
+
+    #[rstest(period, case(4), case(32))]
+    fn constant_zero_series_cfo_nan(period: usize) {
+        let mut lr = LinearRegression::new(period);
+
+        for _ in 0..period {
+            lr.update_raw(0.0);
+        }
+
+        assert!(lr.initialized());
+        assert!(lr.cfo.is_nan());
+    }
+
+    #[rstest(period, case(6), case(13))]
+    fn reset_clears_state_but_keeps_constants(period: usize) {
+        let mut lr = LinearRegression::new(period);
+
+        for i in 1..=period {
+            lr.update_raw(i as f64);
+        }
+
+        let x_sum_before = lr.x_sum;
+        let x_mul_sum_before = lr.x_mul_sum;
+        let divisor_before = lr.divisor;
+
+        lr.reset();
+
+        assert!(!lr.initialized());
+        assert!(!lr.has_inputs());
+
+        assert!(lr.slope.abs() < EPS);
+        assert!(lr.intercept.abs() < EPS);
+        assert!(lr.degree.abs() < EPS);
+        assert!(lr.cfo.abs() < EPS);
+        assert!(lr.r2.abs() < EPS);
+        assert!(lr.value.abs() < EPS);
+
+        assert_eq!(lr.x_sum, x_sum_before);
+        assert_eq!(lr.x_mul_sum, x_mul_sum_before);
+        assert_eq!(lr.divisor, divisor_before);
+    }
+
+    #[rstest(period, case(5), case(31))]
+    fn perfect_linear_series(period: usize) {
+        const A: f64 = 2.0;
+        const B: f64 = -3.0;
+        let mut lr = LinearRegression::new(period);
+
+        for x in 1..=period {
+            lr.update_raw(A * x as f64 + B);
+        }
+
+        assert!(lr.initialized());
+        assert!((lr.slope - A).abs() < EPS);
+        assert!((lr.intercept - B).abs() < EPS);
+        assert!((lr.r2 - 1.0).abs() < EPS);
+        assert!((lr.degree.to_radians().tan() - A).abs() < EPS);
+    }
+
+    #[rstest]
+    fn sliding_window_keeps_last_period() {
+        const P: usize = 4;
+        let mut lr = LinearRegression::new(P);
+        for i in 1..=P {
+            lr.update_raw(i as f64);
+        }
+        let slope_first_window = lr.slope;
+
+        lr.update_raw(-100.0);
+        assert!(lr.slope < slope_first_window);
+        assert_eq!(lr.inputs.len(), P);
+        assert_eq!(lr.inputs.front(), Some(&2.0));
+    }
+
+    #[rstest]
+    fn r2_between_zero_and_one() {
+        const P: usize = 32;
+        let mut lr = LinearRegression::new(P);
+        for x in 1..=P {
+            let noise = if x % 2 == 0 { 0.5 } else { -0.5 };
+            lr.update_raw(3.0 * x as f64 + noise);
+        }
+        assert!(lr.r2 > 0.0 && lr.r2 < 1.0);
+    }
+
+    #[rstest]
+    fn reset_before_initialized() {
+        let mut lr = LinearRegression::new(10);
+        lr.update_raw(1.0);
+        lr.reset();
+
+        assert!(!lr.initialized());
+        assert!(!lr.has_inputs());
+        assert_eq!(lr.inputs.len(), 0);
+    }
 }