QuanTAlib/lib/trends_FIR/alma/Alma.md

ALMA: Arnaud Legoux Moving Average

Gaussian distributions govern everything from particle diffusion to the distribution of shoe sizes. Applying them to price action isn't 'technical analysis'; it's just physics with a profit motive.

Property	Value
Category	Trend (FIR MA)
Inputs	Source (close)
Parameters	period, offset (default 0.85), sigma (default 6.0)
Outputs	Single series (Alma)
Output range	Tracks input
Warmup	period bars
PineScript	alma.pine
Signature	alma_signature

• ALMA is a Finite Impulse Response (FIR) filter that applies a Gaussian window to price data.
• Similar: FWMA, SinEma | Complementary: ATR for volatility filter | Trading note: Gaussian-weighted FIR filter; offset parameter controls responsiveness vs smoothness tradeoff.
• Validated against Skender, Ooples, and Pandas-TA reference implementations.

ALMA is a Finite Impulse Response (FIR) filter that applies a Gaussian window to price data. Unlike the Simple Moving Average (which treats 10-minute-old data with the same reverence as 1-minute-old data) or the Exponential Moving Average (which holds onto history like a hoarder), ALMA allows you to shape the weight distribution precisely. It lets you define the trade-off between smoothness and lag using standard deviation (\sigma) and offset, rather than arbitrary periods.

Historical Context / The Standard

Arnaud Legoux and Dimitris Kouzis-Loukas published ALMA in 2009. The context was a trading world drowning in "adaptive" moving averages (KAMA, FRAMA) that often adapted too late or overshot the turn.

While Hull (HMA) attempted to solve lag through algebraic subtraction (and created overshoot), and Jurik (JMA) hid behind proprietary black-box math, Legoux returned to first principles: Signal Processing. He applied the Gaussian filter—standard in electrical engineering for noise reduction—to financial time series. It is not a "modern" invention so much as the correct application of established math to a messy domain.

Architecture & Physics

ALMA is a weighted moving average where weights follow a normal distribution (bell curve).

The physics of ALMA rely on shifting the "center of gravity" of the window.

• SMA: Center of gravity is always the middle (0.5). Lag is fixed.
• EMA: Center of gravity is front-loaded but has an infinite tail.
• ALMA: You move the center. An offset of 0.85 pushes the bulk of the weight to the most recent 15% of the window.

This shift allows the indicator to capture momentum (high responsiveness) while the Gaussian decay kills high-frequency noise (smoothness). It behaves less like a lagging indicator and more like a mass-dampener system.

The Compute Challenge

Naive implementations recalculate the Gaussian weights on every tick. This is CPU suicide. QuanTAlib precomputes the weight vector \mathbf{W} upon initialization. The runtime operation effectively becomes a dot product of the price buffer and the weight vector.

\text{Runtime Cost} = O(N) \text{ multiplications}

While heavier than the recursive EMA (O(1)), the memory locality of the arrays allows modern CPUs to vectorise these operations (SIMD), making the penalty negligible for typical window sizes (< 100).

Mathematical Foundation

The weight calculation relies on three inputs:

1. Window (L): The lookback period.
2. Offset (o): Where the Gaussian peak sits (0.0 to 1.0). Default is 0.85.
3. Sigma (\sigma): The width of the bell curve. Default is 6.0.

1. Center and Width Calculation

First, QuanTAlib defines the peak index (m) and the spread (s):

m = o \cdot (L - 1) s = \frac{L}{\sigma}

2. Weight Generation

For each index i from 0 to L-1, the unnormalized weight is calculated:

w_i = \exp \left( - \frac{(i - m)^2}{2s^2} \right)

3. Normalization

The final ALMA value is the weighted sum. The weights are not normalized to sum to 1.0 beforehand; instead, division by the total sum of weights W_{sum} happens at the end.

\text{ALMA}_t = \frac{\sum_{i=0}^{L-1} P_{t-i} \cdot w_{L-1-i}}{W_{sum}}

Note: The weights vector is reversed relative to the price history buffer (most recent price gets the weight at the offset index).

Performance Profile

Operation Count (Streaming Mode, Scalar)

Constructor (one-time precomputation):

Operation	Count	Cost (cycles)	Subtotal
MUL	2N + 2	3	6N + 6
DIV	N	15	15N
EXP	N	50	50N
ADD/SUB	2N	1	2N
Total (init)	—	—	~73N cycles

For period=20: ~1,460 cycles (one-time).

Hot path (per bar):

Operation	Count	Cost (cycles)	Subtotal
MUL	N	3	3N
ADD	N	1	N
DIV	1	15	15
Total	2N + 1	—	~4N + 15 cycles

For period=20: ~95 cycles per bar.

Hot path breakdown:

• Weighted sum: ∑(buffer[i] × weights[i]) → N MUL + N ADD
• Normalization: sum / wSum → 1 DIV (wSum precomputed)

Batch Mode (SIMD)

The dot product ∑(buffer[i] × weights[i]) is highly vectorizable:

Operation	Scalar Ops	SIMD Ops (AVX2)	Speedup
Weighted products	N	N/8	8×
Horizontal sum	N	log₂(8)	~N/3×

Batch efficiency (512 bars, period=20):

Mode	Cycles/bar	Total	Notes
Scalar streaming	~95	~48,640	O(N) per bar
SIMD batch	~25	~12,800	Vectorized dot product
Improvement	~4×	~36K saved	—

Quality Metrics

Metric	Score	Notes
Accuracy	10/10	Matches Gaussian definition to double precision
Timeliness	9/10	Tunable offset (0.85) minimizes group delay
Overshoot	9/10	Gaussian decay prevents the "whip" effect of HMA
Smoothness	8/10	Dependent on σ; higher σ = sharper filter

Implementation Details

// Precomputation (Constructor)
double m = offset * (period - 1);
double s = period / sigma;
double wSum = 0;

for (int i = 0; i < period; i++) {
    double weight = Math.Exp(-((i - m) * (i - m)) / (2 * s * s));
    _weights[i] = weight;
    wSum += weight;
}

// Runtime (Update)
double numerator = 0;
// Note: _buffer holds prices. _weights are pre-aligned.
// Modern JIT unrolls this loop efficiently.
for (int i = 0; i < period; i++) {
    numerator += _buffer[i] * _weights[i];
}
return numerator / wSum;

Validation

QuanTAlib validates against reference implementations that respect the Gaussian math, ignoring those that approximate for speed.

Library	Status	Notes
QuanTAlib	✅	Validated against math definition.
Skender	✅	Matches GetAlma.
Ooples	✅	Matches CalculateArnaudLegouxMovingAverage.
Pandas-TA	✅	Python reference implementation matches.
TA-Lib	❌	Not included in standard C distribution.
Tulip	❌	Not included.

Common Pitfalls

1. Offset Abuse: Setting offset to 0.99 creates a filter that barely filters. It tracks price so closely you might as well use Price[0]. Setting it to 0.5 makes it a centered moving average (great for smoothing, terrible for trading due to repainting if used as such, but ALMA does not repaint). The magic is in the 0.85 region.

2. Sigma Confusion:

   • \sigma = 1: The curve is flat. You have reinvented the Simple Moving Average (badly).
   • \sigma = 10: The curve is a needle. You are sampling one specific bar in history.

3. Cold Start: ALMA requires a full window (L) to be mathematically valid. First L-1 bars are convergence noise. Ignore them.