QuanTAlib/lib/dynamics/alligator/Alligator.md

ALLIGATOR: Williams Alligator

Three displaced moving averages form jaw, teeth, and lips — when they diverge the Alligator feeds, when they converge it sleeps.

Property	Value
Category	Dynamic
Inputs	OHLCV bar (TBar)
Parameters	jawPeriod, jawOffset, teethPeriod, teethOffset, lipsPeriod, lipsOffset
Outputs	Multiple series (Jaw, Teeth, Lips)
Output range	Varies (see docs)
Warmup	Math.Max(Math.Max(jawPeriod, teethPeriod), lipsPeriod) bars
PineScript	alligator.pine

• The Williams Alligator is a trend-following system that uses three Smoothed Moving Averages (SMMA/RMA) with different periods and forward display o...
• Similar: AMAT, Ichimoku | Complementary: Fractal indicator for entry signals | Trading note: Bill Williams' Alligator; three displaced SMAs (Jaw/Teeth/Lips) indicate trend state.
• Validated against TA-Lib, Skender, and Tulip reference implementations where available.

The Williams Alligator is a trend-following system that uses three Smoothed Moving Averages (SMMA/RMA) with different periods and forward display offsets to visualize market phases. The Jaw (13-period, offset 8), Teeth (8-period, offset 5), and Lips (5-period, offset 3) create a layered structure where intertwined lines indicate consolidation ("sleeping") and separated, aligned lines indicate trending conditions ("eating"). The metaphor maps directly to position management: stay out when the alligator sleeps, ride when it eats. Each line uses Wilder's smoothing (\alpha = 1/N), which is heavier than standard EMA, providing superior noise rejection at the cost of additional lag.

Historical Context

Bill Williams introduced the Alligator in Trading Chaos (1995) as part of his broader chaos theory framework for trading. The metaphor is biological: markets alternate between feeding (trending) and sleeping (ranging) states, and the three moving averages at different timescales reveal which phase is active. The Jaw represents the long-term balance line (the "blue line" on most charting platforms), the Teeth the intermediate balance (red), and the Lips the short-term momentum (green). Williams paired the Alligator with Fractals for entry timing and the Awesome Oscillator for momentum confirmation, creating a complete systematic framework. The forward offsets are display-only transformations — the underlying SMMA calculation uses the current bar's price — but they create visual separation that makes trend direction immediately apparent on charts.

Architecture & Physics

1. Three-Line SMMA Structure

Each line is an independent SMMA (Wilder's RMA) with \alpha = 1/N:

Line	Period (N)	Display Offset	Role
Jaw	13	8 bars forward	Long-term trend (slowest)
Teeth	8	5 bars forward	Intermediate trend
Lips	5	3 bars forward	Short-term momentum (fastest)

2. SMMA Recursion

\text{SMMA}_t = \frac{1}{N} \cdot P_t + \frac{N-1}{N} \cdot \text{SMMA}_{t-1}

Equivalently using FMA notation:

\text{SMMA}_t = \text{FMA}(\text{SMMA}_{t-1},\; \tfrac{N-1}{N},\; \tfrac{1}{N} \cdot P_t)

3. Default Input

Typical price (HLC/3):

\text{Source} = \frac{H + L + C}{3}

4. Forward Offset

The offsets shift plotted values forward in time for display purposes only. The calculation itself is not shifted — the current SMMA value represents the current bar's computation.

5. Complexity

• Time: O(1) per bar — three parallel SMMA updates
• Space: O(1) — three scalar states (no buffers needed)
• Warmup: 13 bars (Jaw period, the slowest line)

Mathematical Foundation

Parameters

Symbol	Parameter	Default	Constraint
N_j	jawPeriod	13	N_j \geq 1
O_j	jawOffset	8	O_j \geq 0
N_t	teethPeriod	8	N_t \geq 1
O_t	teethOffset	5	O_t \geq 0
N_l	lipsPeriod	5	N_l \geq 1
O_l	lipsOffset	3	O_l \geq 0

Market Phase Detection

Phase	Line Configuration	Action
Sleeping	Lines intertwined, crossing	No position; market is consolidating
Awakening	Lines begin separating	Prepare for entry
Eating (bullish)	Lips > Teeth > Jaw, all rising	Long; trend is strong
Eating (bearish)	Lips < Teeth < Jaw, all falling	Short; trend is strong
Sated	Lines converging	Take profits; trend weakening

Output Interpretation

• Three values per bar: Jaw, Teeth, Lips (each a smoothed price level)
• Separation width: Proportional to trend strength
• Line ordering: Determines trend direction
• Intertwining: Signals consolidation — the highest-probability losing zone for trend followers

Performance Profile

Operation Count (Streaming Mode)

The Alligator runs three SMMA (Wilder RMA) instances with different periods and bar shifts.

Post-warmup steady state (per bar):

Operation	Count	Cost (cycles)	Subtotal
Median price (H+L)/2	2	1	2
FMA × 3 (SMMA jaw, teeth, lips updates)	3	4	12
RingBuffer writes × 3 (shift lag storage)	3	1	3
RingBuffer reads × 3 (shifted output)	3	1	3
Total	11	—	~20 cycles

Three independent SMMA streams run in parallel with look-ahead shift buffers. For default periods (13/8/5) with shifts (8/5/3): warmup is 13+8 = 21 bars. Steady state: ~20 cycles per bar.

Batch Mode (SIMD Analysis)

Operation	Vectorizable?	Notes
Median price computation	Yes	VADDPD + VMULPD (×0.5)
SMMA (Wilder RMA)	No	Recursive IIR — sequential per stream
Shifted output reads	Yes	Array offset reads, no dependencies

Three independent recursive streams. No cross-stream dependencies, but each stream is itself sequential. Cannot batch-vectorize across bars, but the three streams can run on separate cores.

Quality Metrics

Metric	Score	Notes
Accuracy	9/10	FMA-precise RMA; independent streams eliminate cross-contamination
Timeliness	4/10	Longest jaw (21 bars warmup + 8-bar shift = 29 bars before output)
Smoothness	9/10	Wilder smoothing on all three lines; Williams designed for low noise
Noise Rejection	8/10	Triple staggered RMAs with shifts effectively filter market noise

Resources

• Williams, B. — Trading Chaos (John Wiley & Sons, 1995)
• Williams, B. — New Trading Dimensions (John Wiley & Sons, 1998)
• PineScript reference: alligator.pine in indicator directory