QuanTAlib/lib/cycles/ht_dcperiod/HtDcperiod.md

HT_DCPERIOD: Ehlers Hilbert Transform Dominant Cycle Period

The Hilbert Transform extracts the dominant cycle period by converting price into an analytic signal and measuring its phase rate.

Property	Value
Category	Cycle
Inputs	Source (close)
Parameters	None
Outputs	Single series (HT_DCPERIOD)
Output range	Varies (see docs)
Warmup	LOOKBACK bars
PineScript	ht_dcperiod.pine

• 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.

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.