QuanTAlib/lib/cycles/ht_dcperiod/HtDcperiod.md

# HT_DCPERIOD: Ehlers Hilbert Transform Dominant Cycle Period

| Property         | Value                            |
| ---------------- | -------------------------------- |
| **Category**     | Cycle                        |
| **Inputs**       | Source (close)                          |
| **Parameters**   | None                      |
| **Outputs**      | Single series (HT_DCPERIOD)                       |
| **Output range** | Varies (see docs)                     |
| **Warmup**       | `LOOKBACK` bars                          |

### TL;DR

- HT_DCPERIOD estimates the period of the dominant market cycle using Ehlers' Hilbert Transform cascade.
- No configurable parameters; computation is stateless per bar.
- Output range: Varies (see docs).
- Requires `LOOKBACK` bars of warmup before first valid output (IsHot = true).
- Validated against TA-Lib, Skender, and Tulip reference implementations where available.

HT_DCPERIOD estimates the period of the dominant market cycle using Ehlers' Hilbert Transform cascade. The algorithm extracts In-Phase and Quadrature components from price, computes instantaneous phase via homodyne discrimination, and derives the period from the phase rate of change. Output is a continuously varying period (typically 6-50 bars) compatible with TA-Lib's `HT_DCPERIOD` function. The indicator enables dynamic tuning of other indicators to the market's actual rhythm rather than fixed-parameter assumptions.

## Historical Context

John Ehlers introduced the Hilbert Transform Dominant Cycle Period in *Rocket Science for Traders* (2001) to overcome the fundamental limitation of fixed-period technical indicators. Markets cycle at variable rates, yet traditional indicators like RSI-14 or SMA-20 assume constant periodicity. HT_DCPERIOD measures the actual cycle length present in price data, enabling adaptive parameter selection. The TA-Lib implementation codified specific Hilbert Transform coefficients ($A = 0.0962$, $B = 0.5769$) and smoothing algorithms that became the de facto standard. QuanTAlib matches the TA-Lib implementation within floating-point tolerance, including the 32-bar lookback convention.

## Architecture & Physics

### 1. WMA Price Smoothing

A 4-bar weighted moving average removes Nyquist-frequency noise:

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

### 2. Hilbert Transform FIR

The discrete Hilbert approximation generates the detrender and quadrature components using coefficients $A = 0.0962$ and $B = 0.5769$. The detrender, $Q_1$, and Hilbert transforms of $I_1$ and $Q_1$ ($jI$, $jQ$) are all computed with the same 4-tap FIR structure.

### 3. Phasor Components

$$I_{2,t} = I_{1,t} - jQ_t, \qquad Q_{2,t} = Q_{1,t} + jI_t$$

Both smoothed with EMA ($\alpha = 0.2$).

### 4. Homodyne Period Extraction

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

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

$$Period_{raw} = \frac{2\pi}{\arctan(Im_t / Re_t)}$$

### 5. Period Smoothing

Clamped to $[6, 50]$ bars, then smoothed:

$$Period_t = 0.33 \cdot Period_{raw} + 0.67 \cdot Period_{t-1}$$

### 6. Complexity

$O(1)$ per bar. Fixed Hilbert cascade with circular buffers totaling approximately 1.2 KB per instance. Warmup: 32 bars (TA-Lib lookback).

## Mathematical Foundation

### Parameters

| Parameter | Description | Default | Constraint |
|-----------|-------------|---------|------------|
| (none) | No user-configurable parameters | | |

The period range [6, 50] and all smoothing constants are fixed by the TA-Lib specification.

### Pseudo-code

```
function HT_DCPERIOD(source):
    A ← 0.0962; B ← 0.5769
    smoothBuf ← CircularBuffer(7)
    detBuf, q1Buf, i1Buf ← CircularBuffers

    I2 ← 0; Q2 ← 0
    Re ← 0; Im ← 0
    period ← 15   // initial estimate

    for each price in source:
        // Step 1: WMA smooth
        smooth ← (4·price + 3·p[1] + 2·p[2] + p[3]) / 10

        // Step 2: Hilbert FIR (adaptive to period)
        adj ← A + B   // coefficient adjustment
        det ← adj·(smooth[0] - smooth[6]) + B·(smooth[2] - smooth[4])
        Q1 ← adj·(det[0] - det[6]) + B·(det[2] - det[4])
        I1 ← det[3]
        jI ← adj·(I1[0] - I1[6]) + B·(I1[2] - I1[4])
        jQ ← adj·(Q1[0] - Q1[6]) + B·(Q1[2] - Q1[4])

        // Step 3: Phasor (EMA smoothed)
        I2 ← 0.2·(I1 - jQ) + 0.8·I2
        Q2 ← 0.2·(Q1 + jI) + 0.8·Q2

        // Step 4: Homodyne discriminator
        Re ← 0.2·(I2·I2_prev + Q2·Q2_prev) + 0.8·Re
        Im ← 0.2·(I2·Q2_prev - Q2·I2_prev) + 0.8·Im

        // Step 5: Period
        if Im ≠ 0 and Re ≠ 0:
            p ← 2π / atan(Im / Re)
        p ← clamp(p, 6, 50)
        period ← 0.33·p + 0.67·period

        emit period
```

### Output Interpretation

| Output | Meaning |
|--------|---------|
| `period` $\approx 6$-$15$ | Short-cycle market; fast oscillator settings appropriate |
| `period` $\approx 15$-$30$ | Medium-cycle; standard indicator periods work |
| `period` $\approx 30$-$50$ | Long-cycle or trending; period drifting toward upper bound suggests trend |
| Stable value | Regular cyclical market, ideal for oscillator-based strategies |

## Performance Profile

### Operation Count (Streaming Mode)

| Operation | Count per bar | Notes |
|-----------|--------------|-------|
| 4-bar WMA | ~5 | 3 MUL + 1 ADD + 1 MUL(×0.1) |
| Hilbert FIR (detrender) | ~7 | 4-tap FIR with period-adaptive coefficients |
| Hilbert FIR (Q1) | ~7 | Same structure applied to detrender buffer |
| Hilbert FIR (jI) | ~7 | Applied to I1 history buffer |
| Hilbert FIR (jQ) | ~7 | Applied to Q1 history buffer |
| Phasor EMA (I2, Q2) | ~8 | 2 SUB/ADD + 4 FMA |
| Homodyne mixing + EMA | ~12 | 4 MUL + 2 ADD/SUB + 2 FMA |
| ATAN | ~15 | `Math.Atan` transcendental |
| Period division (2π/θ) | ~2 | 1 DIV |
| Clamp + EMA smoothing | ~4 | 2 comparisons + 1 FMA |
| Buffer management | ~10 | 4 circular buffer writes + index arithmetic |
| **Total** | **~84** | **O(1) fixed; identical pipeline to HOMOD** |

### Batch Mode (SIMD Analysis)

| Aspect | Assessment |
|--------|------------|
| SIMD vectorizable | No: full Hilbert cascade is sequentially dependent IIR chain |
| Bottleneck | `Math.Atan` transcendental + 4 Hilbert FIR passes per bar |
| Parallelism | None: each bar's phasor depends on previous bar's EMA state |
| Memory | O(1): 4 circular buffers (7 elements each) + 6 scalar EMA states (~280 bytes) |
| Throughput | Moderate; ~3× slower than simple EMA; matches HOMOD performance |

## Resources

- **Ehlers, J.F.** *Rocket Science for Traders*. Wiley, 2001.
- **TA-Lib** `TA_HT_DCPERIOD()` reference implementation.
- **Ehlers, J.F.** *Cybernetic Analysis for Stocks and Futures*. Wiley, 2004.