kingchencandGitHub
05fe7ffa90
## Summary - Dedicated batch fast paths for **EMA, RSI, Bollinger, MACD and ATR** (used by the Python bindings): one allocation filled in a single pass, warmup encoded as `NaN`, no per-element `Option` or input re-validation. Each is **bit-for-bit equal** to replaying `update` — SMA/Bollinger keep the drift-reseed cadence, the EMA-family keep the seed division and `mul_add` recurrences. Adds the `BatchNanExt` extension trait. - **Cross-library benchmark refresh**: `compare_libraries.py` reports the median across timing rounds (`--rounds` / `--streaming-rounds`), gains `--skip-batch` / `--skip-streaming`, and runs every peer through the streaming arena (recompute for batch-only libraries). `wickra-bench` drives the batch fast paths against `kand`. - **README** benchmark section reordered streaming-first (the order-of-magnitude result), with measured TA-Lib/tulipy/pandas-ta numbers in place of the CI-only placeholders. ## Impact - Python batch ~2× faster on EMA/RSI/MACD/ATR; streaming path unchanged. - The `batch == streaming` equivalence stays bit-exact. ## Verification - `cargo fmt` · `cargo clippy --workspace --all-targets --all-features -- -D warnings` (clean) - `cargo test --workspace --all-features` — 3782 unit + 420 doc tests pass - Python `pytest` — streaming-vs-batch, known-values, input-validation, smoke pass ## Notes - Node/WASM bindings keep their existing batch; the fast paths are Python-only for now.
454 lines
15 KiB
Rust
454 lines
15 KiB
Rust
//! Moving Average Convergence Divergence (MACD).
|
||
|
||
use crate::error::{Error, Result};
|
||
use crate::indicators::ema::Ema;
|
||
use crate::traits::Indicator;
|
||
|
||
/// MACD output: the three classic series at a given step.
|
||
#[derive(Debug, Clone, Copy, PartialEq)]
|
||
pub struct MacdOutput {
|
||
/// Fast EMA − slow EMA.
|
||
pub macd: f64,
|
||
/// EMA of `macd` over the signal period.
|
||
pub signal: f64,
|
||
/// `macd − signal`.
|
||
pub histogram: f64,
|
||
}
|
||
|
||
/// MACD = EMA(fast) − EMA(slow), with a signal EMA on top.
|
||
///
|
||
/// Standard parameters are `fast = 12`, `slow = 26`, `signal = 9`. The signal EMA
|
||
/// is seeded from the first `signal` raw MACD values, so the first full
|
||
/// [`MacdOutput`] is emitted after `slow + signal − 1` inputs (assuming the
|
||
/// slow EMA seeded by then).
|
||
///
|
||
/// # Example
|
||
///
|
||
/// ```
|
||
/// use wickra_core::{Indicator, MacdIndicator};
|
||
///
|
||
/// let mut indicator = MacdIndicator::new(3, 6, 3).unwrap();
|
||
/// let mut last = None;
|
||
/// for i in 0..80 {
|
||
/// last = indicator.update(100.0 + f64::from(i));
|
||
/// }
|
||
/// assert!(last.is_some());
|
||
/// ```
|
||
#[derive(Debug, Clone)]
|
||
pub struct MacdIndicator {
|
||
fast: Ema,
|
||
slow: Ema,
|
||
signal_ema: Ema,
|
||
fast_period: usize,
|
||
slow_period: usize,
|
||
signal_period: usize,
|
||
last: Option<MacdOutput>,
|
||
}
|
||
|
||
impl MacdIndicator {
|
||
/// Construct a MACD with the given periods.
|
||
///
|
||
/// # Errors
|
||
///
|
||
/// Returns [`Error::PeriodZero`] if any period is zero, and
|
||
/// [`Error::InvalidPeriod`] if `fast >= slow`.
|
||
pub fn new(fast: usize, slow: usize, signal: usize) -> Result<Self> {
|
||
if fast == 0 || slow == 0 || signal == 0 {
|
||
return Err(Error::PeriodZero);
|
||
}
|
||
if fast >= slow {
|
||
return Err(Error::InvalidPeriod {
|
||
message: "fast period must be strictly less than slow period",
|
||
});
|
||
}
|
||
Ok(Self {
|
||
fast: Ema::new(fast)?,
|
||
slow: Ema::new(slow)?,
|
||
signal_ema: Ema::new(signal)?,
|
||
fast_period: fast,
|
||
slow_period: slow,
|
||
signal_period: signal,
|
||
last: None,
|
||
})
|
||
}
|
||
|
||
/// Default `(12, 26, 9)` configuration, matching every classical chart package.
|
||
pub fn classic() -> Self {
|
||
Self::new(12, 26, 9).expect("classic MACD periods are valid")
|
||
}
|
||
|
||
/// Configured periods as `(fast, slow, signal)`.
|
||
pub const fn periods(&self) -> (usize, usize, usize) {
|
||
(self.fast_period, self.slow_period, self.signal_period)
|
||
}
|
||
|
||
/// Most recent fully-computed output if available.
|
||
pub const fn value(&self) -> Option<MacdOutput> {
|
||
self.last
|
||
}
|
||
|
||
/// Vectorized flat batch for bindings: `n * 3` values laid out as
|
||
/// `[macd, signal, histogram]` per input row, warmup rows all `NaN`.
|
||
///
|
||
/// For a fresh, all-finite slice long enough for a full output it runs the
|
||
/// fast EMA, slow EMA and signal EMA as three recurrences fused into a single
|
||
/// pass with one allocation — no `Option` per tick, no per-EMA intermediate
|
||
/// buffers, identical SMA-mean seeds (division) and `mul_add` recurrences. The
|
||
/// result is *bit-for-bit* equal to replaying `update`. Anything else (not
|
||
/// fresh, non-finite, or too short to emit) defers to the exact `update`
|
||
/// replay.
|
||
///
|
||
/// Separate from the trait [`batch`](crate::BatchExt::batch), which stays a
|
||
/// bit-identical `update` replay; only the bindings call this.
|
||
pub fn batch_macd(&mut self, inputs: &[f64]) -> Vec<f64> {
|
||
let n = inputs.len();
|
||
let (fp, sp, gp) = (self.fast_period, self.slow_period, self.signal_period);
|
||
// First full output needs the slow EMA seeded (index sp-1) plus gp signal
|
||
// values: index sp + gp - 2. Below that, or non-fresh/non-finite, replay.
|
||
if self.last.is_some()
|
||
|| !self.fast.is_fresh()
|
||
|| !self.slow.is_fresh()
|
||
|| !self.signal_ema.is_fresh()
|
||
|| n < sp + gp - 1
|
||
|| !inputs.iter().all(|x| x.is_finite())
|
||
{
|
||
let mut out = vec![f64::NAN; n * 3];
|
||
for (i, &x) in inputs.iter().enumerate() {
|
||
if let Some(o) = self.update(x) {
|
||
out[i * 3] = o.macd;
|
||
out[i * 3 + 1] = o.signal;
|
||
out[i * 3 + 2] = o.histogram;
|
||
}
|
||
}
|
||
return out;
|
||
}
|
||
|
||
// Pre-sized output: warmup rows stay NaN, full-output rows are written in
|
||
// place by index — no per-row `push` length/capacity check.
|
||
let mut out = vec![f64::NAN; n * 3];
|
||
let (fa, fo) = (self.fast.alpha(), 1.0 - self.fast.alpha());
|
||
let (sa, so) = (self.slow.alpha(), 1.0 - self.slow.alpha());
|
||
let (ga, go) = (self.signal_ema.alpha(), 1.0 - self.signal_ema.alpha());
|
||
let (fp_f, sp_f, gp_f) = (fp as f64, sp as f64, gp as f64);
|
||
|
||
let (mut fast_val, mut slow_val, mut sig) = (0.0_f64, 0.0_f64, 0.0_f64);
|
||
let (mut fsum, mut ssum, mut gsum) = (0.0_f64, 0.0_f64, 0.0_f64);
|
||
let mut sig_count = 0usize; // signal-EMA seed progress (raw MACD values seen)
|
||
let mut sig_seeded = false;
|
||
let mut last = MacdOutput {
|
||
macd: 0.0,
|
||
signal: 0.0,
|
||
histogram: 0.0,
|
||
};
|
||
|
||
for (i, &x) in inputs.iter().enumerate() {
|
||
// Fast EMA: SMA-seeded at index fp-1, then recurrence.
|
||
if i < fp {
|
||
fsum += x;
|
||
if i == fp - 1 {
|
||
fast_val = fsum / fp_f;
|
||
}
|
||
} else {
|
||
fast_val = fa.mul_add(x, fo * fast_val);
|
||
}
|
||
// Slow EMA: SMA-seeded at index sp-1, then recurrence.
|
||
if i < sp {
|
||
ssum += x;
|
||
if i == sp - 1 {
|
||
slow_val = ssum / sp_f;
|
||
}
|
||
} else {
|
||
slow_val = sa.mul_add(x, so * slow_val);
|
||
}
|
||
if i + 1 < sp {
|
||
continue; // slow EMA not seeded yet → no raw MACD line
|
||
}
|
||
let macd = fast_val - slow_val;
|
||
// Signal EMA over the MACD line: SMA-seeded over its first gp values.
|
||
let signal = if sig_seeded {
|
||
sig = ga.mul_add(macd, go * sig);
|
||
sig
|
||
} else {
|
||
gsum += macd;
|
||
sig_count += 1;
|
||
if sig_count < gp {
|
||
continue; // signal EMA still seeding → no full output
|
||
}
|
||
sig = gsum / gp_f;
|
||
sig_seeded = true;
|
||
sig
|
||
};
|
||
let histogram = macd - signal;
|
||
out[i * 3] = macd;
|
||
out[i * 3 + 1] = signal;
|
||
out[i * 3 + 2] = histogram;
|
||
last = MacdOutput {
|
||
macd,
|
||
signal,
|
||
histogram,
|
||
};
|
||
}
|
||
|
||
// Leave every sub-EMA and `last` where a full `update` replay would.
|
||
self.fast.seed_to(fast_val);
|
||
self.slow.seed_to(slow_val);
|
||
self.signal_ema.seed_to(sig);
|
||
self.last = Some(last);
|
||
out
|
||
}
|
||
}
|
||
|
||
impl Indicator for MacdIndicator {
|
||
type Input = f64;
|
||
type Output = MacdOutput;
|
||
|
||
fn update(&mut self, input: f64) -> Option<MacdOutput> {
|
||
if !input.is_finite() {
|
||
return self.last;
|
||
}
|
||
|
||
let fast = self.fast.update(input);
|
||
let slow = self.slow.update(input);
|
||
|
||
match (fast, slow) {
|
||
(Some(f), Some(s)) => {
|
||
let macd = f - s;
|
||
let signal = self.signal_ema.update(macd)?;
|
||
let out = MacdOutput {
|
||
macd,
|
||
signal,
|
||
histogram: macd - signal,
|
||
};
|
||
self.last = Some(out);
|
||
Some(out)
|
||
}
|
||
_ => None,
|
||
}
|
||
}
|
||
|
||
fn reset(&mut self) {
|
||
self.fast.reset();
|
||
self.slow.reset();
|
||
self.signal_ema.reset();
|
||
self.last = None;
|
||
}
|
||
|
||
fn warmup_period(&self) -> usize {
|
||
// Slow EMA needs `slow` inputs to seed; signal EMA needs another `signal - 1`.
|
||
self.slow_period + self.signal_period - 1
|
||
}
|
||
|
||
fn is_ready(&self) -> bool {
|
||
self.last.is_some()
|
||
}
|
||
|
||
fn name(&self) -> &'static str {
|
||
"MACD"
|
||
}
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
use crate::traits::BatchExt;
|
||
use approx::assert_relative_eq;
|
||
|
||
#[test]
|
||
fn rejects_fast_geq_slow() {
|
||
assert!(matches!(
|
||
MacdIndicator::new(26, 12, 9),
|
||
Err(Error::InvalidPeriod { .. })
|
||
));
|
||
assert!(matches!(
|
||
MacdIndicator::new(12, 12, 9),
|
||
Err(Error::InvalidPeriod { .. })
|
||
));
|
||
}
|
||
|
||
/// Cover the const accessors `periods` / `value` (81-88) and the
|
||
/// Indicator-impl `name` body (135-137). `warmup_period` is exercised
|
||
/// elsewhere.
|
||
#[test]
|
||
fn accessors_and_metadata() {
|
||
let mut m = MacdIndicator::new(12, 26, 9).unwrap();
|
||
assert_eq!(m.periods(), (12, 26, 9));
|
||
assert_eq!(m.name(), "MACD");
|
||
assert!(m.value().is_none());
|
||
for i in 1..=m.warmup_period() {
|
||
m.update(100.0 + f64::from(u32::try_from(i).unwrap()));
|
||
}
|
||
assert!(m.value().is_some());
|
||
}
|
||
|
||
#[test]
|
||
fn rejects_zero_periods() {
|
||
assert!(matches!(
|
||
MacdIndicator::new(0, 26, 9),
|
||
Err(Error::PeriodZero)
|
||
));
|
||
assert!(matches!(
|
||
MacdIndicator::new(12, 0, 9),
|
||
Err(Error::PeriodZero)
|
||
));
|
||
assert!(matches!(
|
||
MacdIndicator::new(12, 26, 0),
|
||
Err(Error::PeriodZero)
|
||
));
|
||
}
|
||
|
||
#[test]
|
||
fn first_emission_matches_warmup_period() {
|
||
let prices: Vec<f64> = (1..=60).map(f64::from).collect();
|
||
let mut macd = MacdIndicator::classic();
|
||
let out = macd.batch(&prices);
|
||
let warmup = macd.warmup_period();
|
||
// Indices 0..warmup-1 are None, index warmup-1 might be Some or might still need
|
||
// the signal EMA's seeding. Our warmup_period is the index at which the first
|
||
// signal value appears: slow + signal - 1.
|
||
for x in out.iter().take(warmup - 1) {
|
||
assert!(x.is_none(), "expected None within warmup");
|
||
}
|
||
assert!(
|
||
out[warmup - 1].is_some(),
|
||
"expected first emission at warmup_period - 1 ({warmup} idx)"
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn histogram_equals_macd_minus_signal() {
|
||
let prices: Vec<f64> = (1..=80).map(|i| f64::from(i) * 0.5).collect();
|
||
let mut macd = MacdIndicator::classic();
|
||
for v in macd.batch(&prices).into_iter().flatten() {
|
||
assert_relative_eq!(v.histogram, v.macd - v.signal, epsilon = 1e-12);
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn constant_series_yields_zero_macd_eventually() {
|
||
let mut macd = MacdIndicator::classic();
|
||
let out = macd.batch(&[100.0_f64; 200]);
|
||
// Both EMAs converge to 100, so MACD must approach 0.
|
||
let last = out.iter().rev().flatten().next().expect("emits a value");
|
||
assert_relative_eq!(last.macd, 0.0, epsilon = 1e-9);
|
||
assert_relative_eq!(last.signal, 0.0, epsilon = 1e-9);
|
||
assert_relative_eq!(last.histogram, 0.0, epsilon = 1e-9);
|
||
}
|
||
|
||
#[test]
|
||
fn rising_series_macd_positive_then_signal_catches_up() {
|
||
let prices: Vec<f64> = (1..=200).map(f64::from).collect();
|
||
let mut macd = MacdIndicator::classic();
|
||
let out = macd.batch(&prices);
|
||
let last = out.iter().rev().flatten().next().unwrap();
|
||
assert!(last.macd > 0.0, "rising series must yield positive MACD");
|
||
}
|
||
|
||
#[test]
|
||
fn batch_equals_streaming() {
|
||
let prices: Vec<f64> = (1..=100)
|
||
.map(|i| (f64::from(i) * 0.4).cos() * 10.0)
|
||
.collect();
|
||
let mut a = MacdIndicator::classic();
|
||
let mut b = MacdIndicator::classic();
|
||
assert_eq!(
|
||
a.batch(&prices),
|
||
prices.iter().map(|p| b.update(*p)).collect::<Vec<_>>()
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn reset_clears_state() {
|
||
let mut macd = MacdIndicator::classic();
|
||
macd.batch(&(1..=80).map(f64::from).collect::<Vec<_>>());
|
||
assert!(macd.is_ready());
|
||
macd.reset();
|
||
assert!(!macd.is_ready());
|
||
assert_eq!(macd.update(1.0), None);
|
||
}
|
||
|
||
fn bits_eq(a: &[f64], b: &[f64]) -> bool {
|
||
a.len() == b.len()
|
||
&& a.iter()
|
||
.zip(b)
|
||
.all(|(x, y)| x == y || (x.is_nan() && y.is_nan()))
|
||
}
|
||
|
||
/// Flat `n*3` `[macd, signal, histogram]` replay of `update`.
|
||
fn macd_replay(series: &[f64]) -> Vec<f64> {
|
||
let mut m = MacdIndicator::classic();
|
||
let mut out = Vec::with_capacity(series.len() * 3);
|
||
for &x in series {
|
||
match m.update(x) {
|
||
Some(o) => out.extend_from_slice(&[o.macd, o.signal, o.histogram]),
|
||
None => out.extend_from_slice(&[f64::NAN; 3]),
|
||
}
|
||
}
|
||
out
|
||
}
|
||
|
||
#[test]
|
||
fn batch_macd_fast_path_is_bit_identical() {
|
||
let series: Vec<f64> = (0..300)
|
||
.map(|i| (f64::from(i) * 0.4).cos() * 10.0 + 100.0)
|
||
.collect();
|
||
let mut macd = MacdIndicator::classic();
|
||
let got = macd.batch_macd(&series);
|
||
assert!(bits_eq(&got, &macd_replay(&series)));
|
||
// Sub-EMA + last state left where the replay would: continued update agrees.
|
||
let mut ref_macd = MacdIndicator::classic();
|
||
for &x in &series {
|
||
ref_macd.update(x);
|
||
}
|
||
let (a, b) = (macd.update(101.0), ref_macd.update(101.0));
|
||
assert_eq!(a.is_some(), b.is_some());
|
||
assert_relative_eq!(a.unwrap().macd, b.unwrap().macd, epsilon = 1e-12);
|
||
}
|
||
|
||
#[test]
|
||
fn batch_macd_falls_back_on_non_finite() {
|
||
let mut series: Vec<f64> = (0..60).map(|i| f64::from(i) + 100.0).collect();
|
||
series[40] = f64::NAN;
|
||
let mut macd = MacdIndicator::classic();
|
||
assert!(bits_eq(&macd.batch_macd(&series), &macd_replay(&series)));
|
||
}
|
||
|
||
#[test]
|
||
fn batch_macd_falls_back_when_not_fresh() {
|
||
let series: Vec<f64> = (0..60).map(|i| f64::from(i) + 100.0).collect();
|
||
let mut macd = MacdIndicator::classic();
|
||
macd.update(50.0);
|
||
let mut ref_macd = MacdIndicator::classic();
|
||
ref_macd.update(50.0);
|
||
let mut want = Vec::new();
|
||
for &x in &series {
|
||
match ref_macd.update(x) {
|
||
Some(o) => want.extend_from_slice(&[o.macd, o.signal, o.histogram]),
|
||
None => want.extend_from_slice(&[f64::NAN; 3]),
|
||
}
|
||
}
|
||
assert!(bits_eq(&macd.batch_macd(&series), &want));
|
||
}
|
||
|
||
#[test]
|
||
fn batch_macd_too_short_for_output_falls_back() {
|
||
// n < slow + signal - 1 (= 34): no full output, routed to the replay.
|
||
let series: Vec<f64> = (0..20).map(|i| f64::from(i) + 100.0).collect();
|
||
let mut macd = MacdIndicator::classic();
|
||
let got = macd.batch_macd(&series);
|
||
assert!(bits_eq(&got, &macd_replay(&series)));
|
||
assert!(got.iter().all(|x| x.is_nan()));
|
||
}
|
||
|
||
#[test]
|
||
fn ignores_non_finite_input() {
|
||
let mut macd = MacdIndicator::classic();
|
||
macd.batch(&(1..=80).map(f64::from).collect::<Vec<_>>());
|
||
let before = macd.value();
|
||
assert!(before.is_some());
|
||
// Non-finite inputs return the last value without advancing any EMA.
|
||
assert_eq!(macd.update(f64::NAN), before);
|
||
assert_eq!(macd.update(f64::INFINITY), before);
|
||
assert_eq!(macd.value(), before);
|
||
}
|
||
}
|