nautilus_indicators/average/
sma.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2025 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16use std::fmt::Display;
17
18use arraydeque::{ArrayDeque, Wrapping};
19use nautilus_model::{
20    data::{Bar, QuoteTick, TradeTick},
21    enums::PriceType,
22};
23
24use crate::indicator::{Indicator, MovingAverage};
25
26const MAX_PERIOD: usize = 1_024;
27
28#[repr(C)]
29#[derive(Debug)]
30#[cfg_attr(
31    feature = "python",
32    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.indicators")
33)]
34pub struct SimpleMovingAverage {
35    pub period: usize,
36    pub price_type: PriceType,
37    pub value: f64,
38    sum: f64,
39    pub count: usize,
40    buf: ArrayDeque<f64, MAX_PERIOD, Wrapping>,
41    pub initialized: bool,
42}
43
44impl Display for SimpleMovingAverage {
45    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
46        write!(f, "{}({})", self.name(), self.period)
47    }
48}
49
50impl Indicator for SimpleMovingAverage {
51    fn name(&self) -> String {
52        stringify!(SimpleMovingAverage).into()
53    }
54
55    fn has_inputs(&self) -> bool {
56        self.count > 0
57    }
58
59    fn initialized(&self) -> bool {
60        self.initialized
61    }
62
63    fn handle_quote(&mut self, quote: &QuoteTick) {
64        self.process_raw(quote.extract_price(self.price_type).into());
65    }
66
67    fn handle_trade(&mut self, trade: &TradeTick) {
68        self.process_raw(trade.price.into());
69    }
70
71    fn handle_bar(&mut self, bar: &Bar) {
72        self.process_raw(bar.close.into());
73    }
74
75    fn reset(&mut self) {
76        self.value = 0.0;
77        self.sum = 0.0;
78        self.count = 0;
79        self.buf.clear();
80        self.initialized = false;
81    }
82}
83
84impl MovingAverage for SimpleMovingAverage {
85    fn value(&self) -> f64 {
86        self.value
87    }
88
89    fn count(&self) -> usize {
90        self.count
91    }
92
93    fn update_raw(&mut self, value: f64) {
94        self.process_raw(value);
95    }
96}
97
98impl SimpleMovingAverage {
99    /// Creates a new [`SimpleMovingAverage`] instance.
100    ///
101    /// # Panics
102    ///
103    /// Panics if `period` is not positive (> 0).
104    #[must_use]
105    pub fn new(period: usize, price_type: Option<PriceType>) -> Self {
106        assert!(period > 0, "SimpleMovingAverage: period must be > 0");
107        assert!(
108            period <= MAX_PERIOD,
109            "SimpleMovingAverage: period {period} exceeds MAX_PERIOD ({MAX_PERIOD})"
110        );
111
112        Self {
113            period,
114            price_type: price_type.unwrap_or(PriceType::Last),
115            value: 0.0,
116            sum: 0.0,
117            count: 0,
118            buf: ArrayDeque::new(),
119            initialized: false,
120        }
121    }
122
123    fn process_raw(&mut self, price: f64) {
124        if self.count == self.period {
125            if let Some(oldest) = self.buf.pop_front() {
126                self.sum -= oldest;
127            }
128        } else {
129            self.count += 1;
130        }
131
132        let _ = self.buf.push_back(price);
133        self.sum += price;
134
135        self.value = self.sum / self.count as f64;
136        self.initialized = self.count >= self.period;
137    }
138}
139
140#[cfg(test)]
141mod tests {
142    use arraydeque::{ArrayDeque, Wrapping};
143    use nautilus_model::{
144        data::{QuoteTick, TradeTick},
145        enums::PriceType,
146    };
147    use rstest::rstest;
148
149    use super::MAX_PERIOD;
150    use crate::{
151        average::sma::SimpleMovingAverage,
152        indicator::{Indicator, MovingAverage},
153        stubs::*,
154    };
155
156    #[rstest]
157    fn sma_initialized_state(indicator_sma_10: SimpleMovingAverage) {
158        let display_str = format!("{indicator_sma_10}");
159        assert_eq!(display_str, "SimpleMovingAverage(10)");
160        assert_eq!(indicator_sma_10.period, 10);
161        assert_eq!(indicator_sma_10.price_type, PriceType::Mid);
162        assert_eq!(indicator_sma_10.value, 0.0);
163        assert_eq!(indicator_sma_10.count, 0);
164        assert!(!indicator_sma_10.initialized());
165        assert!(!indicator_sma_10.has_inputs());
166    }
167
168    #[rstest]
169    fn sma_update_raw_exact_period(indicator_sma_10: SimpleMovingAverage) {
170        let mut sma = indicator_sma_10;
171        for i in 1..=10 {
172            sma.update_raw(f64::from(i));
173        }
174        assert!(sma.has_inputs());
175        assert!(sma.initialized());
176        assert_eq!(sma.count, 10);
177        assert_eq!(sma.value, 5.5);
178    }
179
180    #[rstest]
181    fn sma_reset_smoke(indicator_sma_10: SimpleMovingAverage) {
182        let mut sma = indicator_sma_10;
183        sma.update_raw(1.0);
184        assert_eq!(sma.count, 1);
185        sma.reset();
186        assert_eq!(sma.count, 0);
187        assert_eq!(sma.value, 0.0);
188        assert!(!sma.initialized());
189    }
190
191    #[rstest]
192    fn sma_handle_single_quote(indicator_sma_10: SimpleMovingAverage, stub_quote: QuoteTick) {
193        let mut sma = indicator_sma_10;
194        sma.handle_quote(&stub_quote);
195        assert_eq!(sma.count, 1);
196        assert_eq!(sma.value, 1501.0);
197    }
198
199    #[rstest]
200    fn sma_handle_multiple_quotes(indicator_sma_10: SimpleMovingAverage) {
201        let mut sma = indicator_sma_10;
202        let q1 = stub_quote("1500.0", "1502.0");
203        let q2 = stub_quote("1502.0", "1504.0");
204
205        sma.handle_quote(&q1);
206        sma.handle_quote(&q2);
207        assert_eq!(sma.count, 2);
208        assert_eq!(sma.value, 1502.0);
209    }
210
211    #[rstest]
212    fn sma_handle_trade(indicator_sma_10: SimpleMovingAverage, stub_trade: TradeTick) {
213        let mut sma = indicator_sma_10;
214        sma.handle_trade(&stub_trade);
215        assert_eq!(sma.count, 1);
216        assert_eq!(sma.value, 1500.0);
217    }
218
219    #[rstest]
220    #[case(1)]
221    #[case(3)]
222    #[case(5)]
223    #[case(16)]
224    fn count_progression_respects_period(#[case] period: usize) {
225        let mut sma = SimpleMovingAverage::new(period, None);
226
227        for i in 0..(period * 3) {
228            sma.update_raw(i as f64);
229
230            assert!(
231                sma.count() <= period,
232                "period={period}, step={i}, count={}",
233                sma.count()
234            );
235
236            let expected = usize::min(i + 1, period);
237            assert_eq!(
238                sma.count(),
239                expected,
240                "period={period}, step={i}, expected={expected}, was={}",
241                sma.count()
242            );
243        }
244    }
245
246    #[rstest]
247    #[case(1)]
248    #[case(4)]
249    #[case(10)]
250    fn count_after_reset_is_zero(#[case] period: usize) {
251        let mut sma = SimpleMovingAverage::new(period, None);
252
253        for i in 0..(period + 2) {
254            sma.update_raw(i as f64);
255        }
256        assert_eq!(sma.count(), period, "pre-reset saturation failed");
257
258        sma.reset();
259        assert_eq!(sma.count(), 0, "count not reset to zero");
260        assert_eq!(sma.value(), 0.0, "value not reset to zero");
261        assert!(!sma.initialized(), "initialized flag not cleared");
262    }
263
264    #[rstest]
265    fn count_edge_case_period_one() {
266        let mut sma = SimpleMovingAverage::new(1, None);
267
268        sma.update_raw(10.0);
269        assert_eq!(sma.count(), 1);
270        assert_eq!(sma.value(), 10.0);
271
272        sma.update_raw(20.0);
273        assert_eq!(sma.count(), 1, "count exceeded 1 with period==1");
274        assert_eq!(sma.value(), 20.0, "value not equal to latest price");
275    }
276
277    #[rstest]
278    fn sliding_window_correctness() {
279        let mut sma = SimpleMovingAverage::new(3, None);
280
281        let prices = [1.0, 2.0, 3.0, 4.0, 5.0];
282        let expect_avg = [1.0, 1.5, 2.0, 3.0, 4.0];
283
284        for (i, &p) in prices.iter().enumerate() {
285            sma.update_raw(p);
286            assert!(
287                (sma.value() - expect_avg[i]).abs() < 1e-9,
288                "step {i}: expected {}, was {}",
289                expect_avg[i],
290                sma.value()
291            );
292        }
293    }
294
295    #[rstest]
296    #[case(2)]
297    #[case(6)]
298    fn initialized_transitions_with_count(#[case] period: usize) {
299        let mut sma = SimpleMovingAverage::new(period, None);
300
301        for i in 0..(period - 1) {
302            sma.update_raw(i as f64);
303            assert!(
304                !sma.initialized(),
305                "initialized early at i={i} (period={period})"
306            );
307        }
308
309        sma.update_raw(42.0);
310        assert_eq!(sma.count(), period);
311        assert!(sma.initialized(), "initialized flag not set at period");
312    }
313
314    #[rstest]
315    #[should_panic(expected = "period must be > 0")]
316    fn sma_new_with_zero_period_panics() {
317        let _ = SimpleMovingAverage::new(0, None);
318    }
319
320    #[rstest]
321    fn sma_rolling_mean_exact_values() {
322        let mut sma = SimpleMovingAverage::new(3, None);
323        let inputs = [1.0, 2.0, 3.0, 4.0, 5.0];
324        let expected = [1.0, 1.5, 2.0, 3.0, 4.0];
325
326        for (&price, &exp_mean) in inputs.iter().zip(expected.iter()) {
327            sma.update_raw(price);
328            assert!(
329                (sma.value() - exp_mean).abs() < 1e-12,
330                "input={price}, expected={exp_mean}, was={}",
331                sma.value()
332            );
333        }
334    }
335
336    #[rstest]
337    fn sma_matches_reference_implementation() {
338        const PERIOD: usize = 5;
339        let mut sma = SimpleMovingAverage::new(PERIOD, None);
340        let mut window: ArrayDeque<f64, PERIOD, Wrapping> = ArrayDeque::new();
341
342        for step in 0..20 {
343            let price = f64::from(step) * 10.0;
344            sma.update_raw(price);
345
346            if window.len() == PERIOD {
347                window.pop_front();
348            }
349            let _ = window.push_back(price);
350
351            let ref_mean: f64 = window.iter().sum::<f64>() / window.len() as f64;
352            assert!(
353                (sma.value() - ref_mean).abs() < 1e-12,
354                "step={step}, expected={ref_mean}, was={}",
355                sma.value()
356            );
357        }
358    }
359
360    #[rstest]
361    #[case(f64::NAN)]
362    #[case(f64::INFINITY)]
363    #[case(f64::NEG_INFINITY)]
364    fn sma_handles_bad_floats(#[case] bad: f64) {
365        let mut sma = SimpleMovingAverage::new(3, None);
366        sma.update_raw(1.0);
367        sma.update_raw(bad);
368        sma.update_raw(3.0);
369        assert!(
370            sma.value().is_nan() || !sma.value().is_finite(),
371            "bad float not propagated"
372        );
373    }
374
375    #[rstest]
376    fn deque_and_count_always_match() {
377        const PERIOD: usize = 8;
378        let mut sma = SimpleMovingAverage::new(PERIOD, None);
379        for i in 0..50 {
380            sma.update_raw(f64::from(i));
381            assert!(
382                sma.buf.len() == sma.count,
383                "buf.len() != count at step {i}: {} != {}",
384                sma.buf.len(),
385                sma.count
386            );
387        }
388    }
389
390    #[rstest]
391    fn sma_multiple_resets() {
392        let mut sma = SimpleMovingAverage::new(4, None);
393        for cycle in 0..5 {
394            for x in 0..4 {
395                sma.update_raw(f64::from(x));
396            }
397            assert!(sma.initialized(), "cycle {cycle}: not initialized");
398            sma.reset();
399            assert_eq!(sma.count(), 0);
400            assert_eq!(sma.value(), 0.0);
401            assert!(!sma.initialized());
402        }
403    }
404
405    #[rstest]
406    fn sma_buffer_never_exceeds_capacity() {
407        const PERIOD: usize = MAX_PERIOD;
408        let mut sma = super::SimpleMovingAverage::new(PERIOD, None);
409
410        for i in 0..(PERIOD * 2) {
411            sma.update_raw(i as f64);
412
413            assert!(
414                sma.buf.len() <= PERIOD,
415                "step {i}: buf.len()={}, exceeds PERIOD={PERIOD}",
416                sma.buf.len(),
417            );
418        }
419        assert!(
420            sma.buf.is_full(),
421            "buffer not reported as full after saturation"
422        );
423        assert_eq!(
424            sma.count(),
425            PERIOD,
426            "count diverged from logical window length"
427        );
428    }
429
430    #[rstest]
431    fn sma_deque_eviction_order() {
432        let mut sma = super::SimpleMovingAverage::new(3, None);
433
434        sma.update_raw(1.0);
435        sma.update_raw(2.0);
436        sma.update_raw(3.0);
437        sma.update_raw(4.0);
438
439        assert_eq!(sma.buf.front().copied(), Some(2.0), "oldest element wrong");
440        assert_eq!(sma.buf.back().copied(), Some(4.0), "newest element wrong");
441
442        assert!(
443            (sma.value() - 3.0).abs() < 1e-12,
444            "unexpected mean after eviction: {}",
445            sma.value()
446        );
447    }
448
449    #[rstest]
450    fn sma_sum_consistent_with_buffer() {
451        const PERIOD: usize = 7;
452        let mut sma = super::SimpleMovingAverage::new(PERIOD, None);
453
454        for i in 0..40 {
455            sma.update_raw(f64::from(i));
456
457            let deque_sum: f64 = sma.buf.iter().copied().sum();
458            assert!(
459                (sma.sum - deque_sum).abs() < 1e-12,
460                "step {i}: internal sum={} differs from buf sum={}",
461                sma.sum,
462                deque_sum
463            );
464        }
465    }
466}
nautilus_indicators/average/sma.rs

nautilus_indicators/average/
sma.rs
