QuanTAlib/lib/dynamics/ht_trendmode/HtTrendmode.md

# HT_TRENDMODE: Hilbert Transform Trend vs Cycle Mode

> *Hilbert trend mode classifies the market as trending or cycling — a binary answer from the analytic signal's behavior.*

| Property         | Value                            |
| ---------------- | -------------------------------- |
| **Category**     | Dynamic                        |
| **Inputs**       | Source (close)                          |
| **Parameters**   | None                      |
| **Outputs**      | Single series (HT_TRENDMODE)                       |
| **Output range** | $0$ to $1$                     |
| **Warmup**       | `LOOKBACK` bars                          |
| **PineScript**   | [ht_trendmode.pine](ht_trendmode.pine)                       |

- The Hilbert Transform Trend Mode indicator is a binary regime classifier that determines whether price action is dominated by trending behavior (ou...
- No configurable parameters; computation is stateless per bar.
- Output range: $0$ to $1$.
- Requires `LOOKBACK` bars of warmup before first valid output (IsHot = true).
- Validated against TA-Lib, Skender, and Tulip reference implementations where available.

The Hilbert Transform Trend Mode indicator is a binary regime classifier that determines whether price action is dominated by trending behavior (output = 1) or cyclical/mean-reverting behavior (output = 0). It uses the full Ehlers Hilbert Transform pipeline — 4-bar WMA smoothing, Hilbert FIR filters, homodyne discriminator for period estimation, DC phase extraction, and SineWave indicators — then applies four decision criteria to classify the current regime. The implementation follows TA-Lib's Ehlers-faithful algorithm from the February 2002 publication. Output is discrete {0, 1}, making it a direct strategy selector: deploy trend-following logic when mode = 1, and mean-reversion logic when mode = 0.

## Historical Context

John Ehlers developed the Trend Mode indicator as part of his cycle analysis toolkit, published in "The Instantaneous Trendline" (February 2002) and expanded in *MESA and Trading Market Cycles* (2002). Ehlers recognized that traders face two fundamentally different market regimes requiring opposite strategies. Applying a trend-following system to a cycling market produces losses, and applying a mean-reversion system to a trending market produces losses. The Hilbert Transform provides the mathematical machinery to distinguish these states by analyzing the phase behavior of the dominant cycle. When phase advances at a regular rate (consistent with a sinusoidal cycle), the market is in cycle mode. When phase rate becomes irregular or price deviates significantly from its trendline, the market is trending. The four-criteria decision logic prevents rapid mode flipping during transitional periods by requiring sustained evidence before declaring a regime change.

## Architecture & Physics

### 1. Hilbert Transform Core

The same pipeline as HT_DCPERIOD and HT_SINE:

$$\text{smooth} = \frac{4P_t + 3P_{t-1} + 2P_{t-2} + P_{t-3}}{10}$$

Hilbert FIR filters extract InPhase and Quadrature components, which feed the homodyne discriminator for period estimation:

$$Re = 0.2(I_2 \cdot I_{2,t-1} + Q_2 \cdot Q_{2,t-1}) + 0.8 \cdot Re_{t-1}$$

$$Im = 0.2(I_2 \cdot Q_{2,t-1} - Q_2 \cdot I_{2,t-1}) + 0.8 \cdot Im_{t-1}$$

$$\text{period} = \frac{360}{\arctan(Im/Re) \times \frac{180}{\pi}}$$

$$\text{smoothPeriod} = 0.33 \times \text{period} + 0.67 \times \text{smoothPeriod}_{t-1}$$

### 2. DC Phase and SineWave

DFT accumulation over the dominant cycle period extracts the DC phase:

$$\text{dcPhase} = \arctan\!\left(\frac{\sum \sin(\omega i) \cdot \text{smooth}_i}{\sum \cos(\omega i) \cdot \text{smooth}_i}\right) + 90° + \text{lagComp}$$

$$\text{sine} = \sin(\text{dcPhase}), \quad \text{leadSine} = \sin(\text{dcPhase} + 45°)$$

### 3. Trendline

An SMA over the dominant cycle period, further smoothed with a 4-bar WMA:

$$\text{sma} = \text{Average}(\text{price}, \lfloor\text{dcPeriod}\rfloor)$$

$$\text{trendline} = \frac{4 \cdot \text{sma}_0 + 3 \cdot \text{sma}_1 + 2 \cdot \text{sma}_2 + \text{sma}_3}{10}$$

### 4. Four-Criteria Decision Logic

```
trend = 1  (assume trend by default)

Criterion 1: SineWave crossing resets counter
  if sine crosses leadSine → daysInTrend = 0, trend = 0

Criterion 2: Duration threshold
  daysInTrend++
  if daysInTrend < 0.5 × smoothPeriod → trend = 0

Criterion 3: Phase rate check
  phaseChange = dcPhase - prevDcPhase
  expected = 360 / smoothPeriod
  if 0.67 × expected < phaseChange < 1.5 × expected → trend = 0

Criterion 4: Price deviation override
  if |smoothPrice - trendline| / trendline ≥ 0.015 → trend = 1
```

### 5. Complexity

- **Time:** $O(P)$ per bar for the SMA over dominant cycle period; Hilbert pipeline is $O(1)$
- **Space:** $O(P_{\max})$ — circular buffers for price history and Hilbert state ($P_{\max} = 50$)
- **Warmup:** 63 bars (TA-Lib compatible)

## Mathematical Foundation

### Parameters

No user-configurable parameters. The algorithm self-tunes based on the detected dominant cycle period (clamped to 6-50 bars).

### Decision Criteria Summary

| Criterion | Purpose |
|-----------|---------|
| SineWave crossing | Resets trend counter — new cycle detected |
| Duration threshold | Requires sustained trending before declaration |
| Phase rate check | Normal phase advance indicates cycle mode |
| Price deviation | Large deviation from trendline forces trend mode |

### Mode Transition Patterns

| Pattern | Interpretation |
|---------|---------------|
| 0→1 after breakout | Trend confirmed; deploy momentum strategy |
| 1→0 at extremes | Cycle started; switch to mean-reversion |
| Long run of 1s | Strong, sustained trend |
| Rapid 0/1 flipping | Transitional/choppy — reduce exposure |

## Performance Profile

### Operation Count (Streaming Mode)

HtTrendmode uses the Hilbert Transform DC Period estimation and compares it against a threshold to output binary trend/cycle mode.

**Post-warmup steady state (per bar):**

| Operation | Count | Cost (cycles) | Subtotal |
| :--- | :---: | :---: | :---: |
| Hilbert FIR coefficients × 4 (InPhase, Quad) | 8 | 3 | 24 |
| Phase accumulator update (ATAN2 equivalent) | 1 | 20 | 20 |
| Period smoothing (EMA on period estimate) | 2 | 4 | 8 |
| Trend period threshold comparison | 1 | 1 | 1 |
| History buffer shifts × 4 | 4 | 1 | 4 |
| **Total** | **16** | — | **~57 cycles** |

The ATAN2-equivalent phase computation is the dominant cost. For default parameters: ~57 cycles per bar.

### Batch Mode (SIMD Analysis)

| Operation | Vectorizable? | Notes |
| :--- | :---: | :--- |
| Hilbert FIR (windowed taps) | Partial | Each tap independent; cross-bar state dependency limits |
| Period EMA smoothing | **No** | Recursive IIR — sequential |
| Threshold comparison | Yes | VCMPPD |

The recursive EMA smoothing of the period estimate blocks full vectorization.

### Quality Metrics

| Metric | Score | Notes |
| :--- | :---: | :--- |
| **Accuracy** | 7/10 | Phase estimation inherent noise; binary output loses detail |
| **Timeliness** | 6/10 | Hilbert requires ~32 bar warmup for phase stabilization |
| **Smoothness** | 10/10 | Binary 0/1 output — maximally smooth |
| **Noise Rejection** | 7/10 | EMA-smoothed period estimate reduces mode-flip chatter |

## Resources

- Ehlers, J.F. — "The Instantaneous Trendline" (February 2002)
- Ehlers, J.F. — *MESA and Trading Market Cycles* (John Wiley & Sons, 2002)
- Ehlers, J.F. — *Rocket Science for Traders* (John Wiley & Sons, 2001)
- PineScript reference: `ht_trendmode.pine` in indicator directory