QuanTAlib/lib/trends/mama/Mama.md

MAMA: MESA Adaptive Moving Average

"John Ehlers again. This time, he built a moving average that doesn't just adapt to volatility—it adapts to the phase of the market cycle. It's like having a GPS for your trend."

MAMA (MESA Adaptive Moving Average) is a unique adaptive moving average that uses the Hilbert Transform to determine the phase rate of change of the market cycle. It produces two outputs: MAMA (the adaptive average) and FAMA (Following Adaptive Moving Average), which acts as a slower, confirming signal.

Historical Context

Introduced by John Ehlers in MESA and Trading Market Cycles, MAMA was designed to solve the problem of lag in a fundamentally different way. Instead of using price volatility (like KAMA or VIDYA), it uses the cycle period. When the cycle is short (fast market), MAMA speeds up. When the cycle is long (slow market), MAMA slows down.

Architecture & Physics

The architecture is a direct application of the Hilbert Transform Homodyne Discriminator.

1. Hilbert Transform: Decomposes price into In-Phase (I) and Quadrature (Q) components.
2. Phase Calculation: Computes the phase angle from I and Q.
3. Alpha Adaptation: The smoothing alpha is derived from the rate of change of the phase.
   • Fast Phase Change = High Alpha (Fast MA).
   • Slow Phase Change = Low Alpha (Slow MA).

Zero-Allocation Design

We maintain the complex state required for the Hilbert Transform without heap allocations.

• RingBuffers: For the delay lines needed by the Hilbert Transform.
• State Struct: Stores the phasors (I, Q, Re, Im) and previous values.
• Fixed Pipeline: The DSP pipeline is fixed-length, allowing for static optimization.

Mathematical Foundation

\text{Phase} = \arctan(Q / I) \alpha = \frac{\text{FastLimit}}{\Delta \text{Phase}} \text{MAMA}_t = \alpha \cdot P_t + (1 - \alpha) \cdot \text{MAMA}_{t-1} \text{FAMA}_t = 0.5 \alpha \cdot \text{MAMA}_t + (1 - 0.5 \alpha) \cdot \text{FAMA}_{t-1}

Performance Profile

MAMA is computationally intensive due to the trigonometry (Atan, Sin, Cos) involved in the Hilbert Transform.

Metric	Score	Notes
Throughput	Low	Trigonometry involved
Complexity	O(1)	Constant time update
Accuracy	8/10	Adapts to market cycle phase
Timeliness	9/10	Extremely fast response to phase shifts
Overshoot	6/10	Can overshoot on sudden cycle changes
Smoothness	6/10	Can be stepped/jagged in transitions

Validation

Validated against Ehlers' original EasyLanguage code.

Provider	Error Tolerance	Notes
Ehlers	N/A	Logic matches MESA and Trading Market Cycles

Common Pitfalls

1. Crossover Signals: The MAMA/FAMA crossover is the primary signal. MAMA crossing over FAMA is bullish.
2. Parameters: FastLimit controls the maximum speed (usually 0.5). SlowLimit controls the minimum speed (usually 0.05).
3. Whipsaws: While adaptive, MAMA can still get chopped up in markets with no clear cycle (white noise).