//! Elastic Volume-Weighted Moving Average (EVWMA). use std::collections::VecDeque; use crate::error::{Error, Result}; use crate::ohlcv::Candle; use crate::traits::Indicator; /// Christian P. Fries' Elastic Volume-Weighted Moving Average. /// /// Unlike `VWMA` which is a per-bar weighted mean, `EVWMA` runs an /// "elastic" recurrence whose smoothing weight is the bar's volume relative /// to the running window-volume: /// /// ```text /// V_sum_t = Σ volume_i over the last `period` candles /// EVWMA_t = ((V_sum_t - volume_t) * EVWMA_{t-1} + volume_t * close_t) / V_sum_t /// ``` /// /// A bar whose volume is small compared to the window total barely moves the /// average; a bar whose volume dominates the window pulls it strongly toward /// the bar's close. The series is seeded with the close of the first candle /// after the volume window has filled (i.e. after `period` candles). /// /// If `V_sum_t == 0` (every candle in the window has zero volume), the /// recurrence is undefined; the indicator holds its previous value. /// /// Reference: Christian P. Fries, *Wilmott Magazine*, 2001. /// /// # Example /// /// ``` /// use wickra_core::{Candle, Evwma, Indicator}; /// /// let mut evwma = Evwma::new(20).unwrap(); /// let mut last = None; /// for i in 0..40 { /// let p = 100.0 + f64::from(i); /// let candle = Candle::new(p, p + 1.0, p - 1.0, p, 10.0, i64::from(i)).unwrap(); /// last = evwma.update(candle); /// } /// assert!(last.is_some()); /// ``` #[derive(Debug, Clone)] pub struct Evwma { period: usize, /// Rolling window of `(close, volume)` pairs, oldest at the front. window: VecDeque<(f64, f64)>, sum_v: f64, current: Option, } impl Evwma { /// # Errors /// Returns [`Error::PeriodZero`] if `period == 0`. pub fn new(period: usize) -> Result { if period == 0 { return Err(Error::PeriodZero); } Ok(Self { period, window: VecDeque::with_capacity(period), sum_v: 0.0, current: None, }) } /// Configured period. pub const fn period(&self) -> usize { self.period } /// Current value if available. pub const fn value(&self) -> Option { self.current } } impl Indicator for Evwma { type Input = Candle; type Output = f64; fn update(&mut self, candle: Candle) -> Option { let close = candle.close; let volume = candle.volume; if self.window.len() == self.period { let (_, old_v) = self.window.pop_front().expect("window is non-empty"); self.sum_v -= old_v; } self.window.push_back((close, volume)); self.sum_v += volume; if self.window.len() < self.period { return None; } // The volume sum may be zero (every bar in the window had zero // volume); the recurrence is undefined, so seed/hold instead. if self.sum_v <= 0.0 { if self.current.is_none() { self.current = Some(close); } return self.current; } let prev = self.current.unwrap_or(close); let next = ((self.sum_v - volume) * prev + volume * close) / self.sum_v; self.current = Some(next); Some(next) } fn reset(&mut self) { self.window.clear(); self.sum_v = 0.0; self.current = None; } fn warmup_period(&self) -> usize { self.period } fn is_ready(&self) -> bool { self.current.is_some() } fn name(&self) -> &'static str { "EVWMA" } } #[cfg(test)] mod tests { use super::*; use crate::traits::BatchExt; use approx::assert_relative_eq; fn candle(close: f64, volume: f64, ts: i64) -> Candle { Candle::new(close, close, close, close, volume, ts).unwrap() } #[test] fn rejects_zero_period() { assert!(matches!(Evwma::new(0), Err(Error::PeriodZero))); } #[test] fn accessors_and_metadata() { let mut e = Evwma::new(5).unwrap(); assert_eq!(e.period(), 5); assert_eq!(e.warmup_period(), 5); assert_eq!(e.name(), "EVWMA"); assert_eq!(e.value(), None); for i in 0..5 { e.update(candle(10.0, 1.0, i)); } assert!(e.value().is_some()); } #[test] fn constant_series_yields_the_constant() { // A flat close — every (V_sum - v) * prev + v * close reduces to // V_sum * close, so the recurrence preserves the constant after the // first seeded sample. let mut e = Evwma::new(5).unwrap(); let candles: Vec = (0..30).map(|i| candle(42.0, 3.0, i)).collect(); let out = e.batch(&candles); for v in out.iter().skip(4).flatten() { assert_relative_eq!(*v, 42.0, epsilon = 1e-12); } } #[test] fn reference_value_period_2() { // EVWMA(2). Bars: (close, volume) = (10, 1), (20, 3), (30, 1). // Bar 1: window not full (size 1) -> None. // Bar 2: window full, sum_v = 4, prev seeds to 20. // EVWMA = ((4 - 3) * 20 + 3 * 20) / 4 = 80 / 4 = 20. // Bar 3: window slides, sum_v = 4 (drops the 1, gains the 1). // EVWMA = ((4 - 1) * 20 + 1 * 30) / 4 = (60 + 30) / 4 = 22.5. let mut e = Evwma::new(2).unwrap(); assert_eq!(e.update(candle(10.0, 1.0, 0)), None); assert_relative_eq!( e.update(candle(20.0, 3.0, 1)).unwrap(), 20.0, epsilon = 1e-12 ); assert_relative_eq!( e.update(candle(30.0, 1.0, 2)).unwrap(), 22.5, epsilon = 1e-12 ); } #[test] fn warmup_emits_first_value_at_period() { let mut e = Evwma::new(4).unwrap(); for i in 0..3 { assert_eq!(e.update(candle(10.0, 1.0, i)), None); } assert!(e.update(candle(10.0, 1.0, 3)).is_some()); } #[test] fn zero_volume_window_holds_value() { // Every bar has zero volume: no participation, so the recurrence // can't move and EVWMA simply seeds to the first close. let mut e = Evwma::new(3).unwrap(); e.update(candle(10.0, 0.0, 0)); e.update(candle(15.0, 0.0, 1)); let v = e.update(candle(20.0, 0.0, 2)).unwrap(); assert_relative_eq!(v, 20.0, epsilon = 1e-12); // Next bar still flat-zero volume: holds 20. let v2 = e.update(candle(50.0, 0.0, 3)).unwrap(); assert_relative_eq!(v2, 20.0, epsilon = 1e-12); } #[test] fn batch_equals_streaming() { let candles: Vec = (0..60_i64) .map(|i| { let c = 100.0 + (i as f64 * 0.3).sin() * 8.0; candle(c, 1.0 + (i % 7) as f64, i) }) .collect(); let batch = Evwma::new(10).unwrap().batch(&candles); let mut b = Evwma::new(10).unwrap(); let streamed: Vec<_> = candles.iter().map(|c| b.update(*c)).collect(); assert_eq!(batch, streamed); } #[test] fn reset_clears_state() { let mut e = Evwma::new(3).unwrap(); let candles: Vec = (0..10).map(|i| candle(10.0 + i as f64, 2.0, i)).collect(); e.batch(&candles); assert!(e.is_ready()); e.reset(); assert!(!e.is_ready()); assert_eq!(e.update(candle(10.0, 1.0, 0)), None); } }