add functions documents

docs/functions/CycleIndicators/HT_DCPERIOD.md

@@ -0,0 +1,250 @@
+# HT_DCPERIOD - Hilbert Transform - Dominant Cycle Period
+
+## Description
+
+The Hilbert Transform Dominant Cycle Period (HT_DCPERIOD) is a cycle indicator that uses the Hilbert Transform to identify the dominant cycle period in price data. It's part of the MESA (MESA Adaptive Moving Average) suite of indicators developed by John Ehlers. The indicator helps identify the current cycle length, which can be used for adaptive moving averages and cycle-based trading strategies.
+
+## Category
+Cycle Indicators
+
+## Author
+John Ehlers
+
+## Calculation
+
+HT_DCPERIOD uses the Hilbert Transform to identify the dominant cycle period:
+
+### Step 1: Hilbert Transform
+```
+Hilbert Transform = arctan(Imaginary / Real)
+```
+
+Where:
+- Real and Imaginary are derived from price data using Hilbert Transform
+- The transform identifies cyclical components
+
+### Step 2: Cycle Period Calculation
+```
+Cycle Period = 2π / (dHilbert/dt)
+```
+
+Where:
+- dHilbert/dt = rate of change of Hilbert Transform
+- 2π = full cycle in radians
+
+### Step 3: Smoothing
+The raw cycle period is smoothed to reduce noise and provide a stable estimate of the dominant cycle.
+
+## Parameters
+
+None - HT_DCPERIOD is a cycle detection function
+
+## Inputs
+- Price data: `double[]` (typically closing prices)
+
+## Outputs
+- Cycle period values: `double[]` (period in bars)
+
+## Interpretation
+
+### Cycle Period Values
+- **Short Periods (5-15)**: Fast cycles, high frequency
+- **Medium Periods (15-30)**: Medium cycles, moderate frequency
+- **Long Periods (30-50)**: Slow cycles, low frequency
+- **Very Long (>50)**: Very slow cycles, trend-like
+
+### Trading Applications
+
+1. **Adaptive Moving Averages**:
+   - Use cycle period for MAMA calculation
+   - Adjust smoothing based on cycle length
+   - More responsive in fast cycles
+   - More smoothing in slow cycles
+
+2. **Cycle-Based Trading**:
+   - Enter at cycle bottoms
+   - Exit at cycle tops
+   - Use cycle length for position sizing
+   - Time entries with cycle phases
+
+3. **Trend Analysis**:
+   - Short cycles = high volatility
+   - Long cycles = trending markets
+   - Cycle changes = market regime changes
+   - Multiple timeframe analysis
+
+## Usage Example
+
+```c
+// C/C++ Example
+double closePrices[100];
+double cyclePeriod[100];
+int outBegIdx, outNBElement;
+
+// Calculate dominant cycle period
+TA_RetCode retCode = TA_HT_DCPERIOD(
+    0,                    // start index
+    99,                   // end index
+    closePrices,          // input price data
+    &outBegIdx,           // output: beginning index
+    &outNBElement,        // output: number of elements
+    cyclePeriod           // output: cycle periods
+);
+```
+
+## Implementation Details
+
+The TA-Lib HT_DCPERIOD implementation:
+
+1. **Hilbert Transform**: Applies Hilbert Transform to price data
+2. **Cycle Detection**: Identifies cyclical components
+3. **Period Calculation**: Calculates cycle period from transform
+4. **Smoothing**: Smooths raw cycle period
+5. **Lookback**: Requires significant lookback for accurate calculation
+
+## Trading Strategies
+
+### 1. Adaptive Moving Average Strategy
+- **Setup**: Use cycle period for MAMA
+- **Entry**: MAMA signals based on cycle
+- **Exit**: Cycle-based exits
+- **Best in**: Cyclical markets
+
+### 2. Cycle-Based Trading Strategy
+- **Setup**: Identify cycle bottoms and tops
+- **Entry**: At cycle bottoms
+- **Exit**: At cycle tops
+- **Best in**: Strong cyclical markets
+
+### 3. Cycle + Trend Strategy
+- **Setup**: Use cycle for timing
+- **Entry**: Trend direction with cycle timing
+- **Exit**: Cycle-based or trend-based
+- **Best in**: Trending cyclical markets
+
+### 4. Multiple Cycle Strategy
+- **Setup**: Identify multiple cycles
+- **Entry**: When cycles align
+- **Exit**: When cycles diverge
+- **Best in**: Complex cyclical markets
+
+## Cycle Analysis
+
+### 1. Short Cycles (5-15 bars)
+- **Characteristics**: High frequency, high volatility
+- **Trading**: Short-term strategies
+- **Risk**: High noise, many false signals
+- **Best in**: Day trading, scalping
+
+### 2. Medium Cycles (15-30 bars)
+- **Characteristics**: Moderate frequency, balanced
+- **Trading**: Swing trading strategies
+- **Risk**: Moderate noise, good signals
+- **Best in**: Swing trading, position trading
+
+### 3. Long Cycles (30-50 bars)
+- **Characteristics**: Low frequency, trending
+- **Trading**: Position trading strategies
+- **Risk**: Low noise, fewer signals
+- **Best in**: Position trading, trend following
+
+### 4. Very Long Cycles (>50 bars)
+- **Characteristics**: Very low frequency, trend-like
+- **Trading**: Long-term strategies
+- **Risk**: Very low noise, very few signals
+- **Best in**: Long-term investing, trend following
+
+## Advantages
+
+1. **Adaptive**: Automatically adjusts to market cycles
+2. **Objective**: Mathematical cycle detection
+3. **Universal**: Works across all markets
+4. **Sophisticated**: Advanced cycle analysis
+5. **MESA Integration**: Works with other MESA indicators
+
+## Limitations
+
+1. **Complex**: Requires understanding of cycles
+2. **Lagging**: Based on historical data
+3. **Noisy**: Raw cycle period can be noisy
+4. **Context Dependent**: Needs market context
+5. **Learning Curve**: Requires experience to use effectively
+
+## Related Functions
+
+- **HT_DCPHASE**: Hilbert Transform - Dominant Cycle Phase
+- **HT_PHASOR**: Hilbert Transform - Phasor Components
+- **HT_SINE**: Hilbert Transform - Sine Wave
+- **MAMA**: MESA Adaptive Moving Average - uses cycle period
+
+## References
+
+- **Book**: *Rocket Science for Traders* by John Ehlers
+- [TA-Lib Source Code: ta_HT_DCPERIOD.c](https://github.com/TA-Lib/ta-lib/blob/main/src/ta_func/ta_HT_DCPERIOD.c)
+- [Investopedia: Hilbert Transform](https://www.investopedia.com/terms/h/hilbert-transform.asp)
+- [MESA Software](http://www.mesasoftware.com/)
+
+## Additional Notes
+
+John Ehlers developed the Hilbert Transform cycle indicators as part of his work on adaptive trading systems. The key insight is that markets have cyclical components that can be identified and used for adaptive trading strategies.
+
+### Key Insights
+
+1. **Cycle Detection**:
+   - Markets have cyclical components
+   - Cycles can be identified mathematically
+   - Cycle length varies over time
+   - Adaptive systems can use cycle information
+
+2. **Adaptive Trading**:
+   - Use cycle period for MAMA
+   - Adjust strategies based on cycle length
+   - Short cycles = more responsive
+   - Long cycles = more smoothing
+
+3. **Best Applications**:
+   - Cyclical markets
+   - Adaptive moving averages
+   - Cycle-based trading
+   - Market regime identification
+
+4. **Cycle Analysis**:
+   - Short cycles = high volatility
+   - Long cycles = trending markets
+   - Cycle changes = regime changes
+   - Multiple timeframe analysis
+
+5. **Combination Strategies**:
+   - Use with MAMA for adaptive smoothing
+   - Combine with trend indicators
+   - Use for cycle-based entries
+   - Multiple timeframe confirmation
+
+### Practical Tips
+
+**For Cycle-Based Trading**:
+- Identify dominant cycle period
+- Use cycle for entry timing
+- Enter at cycle bottoms
+- Exit at cycle tops
+
+**For Adaptive Systems**:
+- Use cycle period for MAMA
+- Adjust smoothing based on cycle
+- Short cycles = more responsive
+- Long cycles = more smoothing
+
+**For Market Analysis**:
+- Short cycles = high volatility
+- Long cycles = trending markets
+- Cycle changes = regime changes
+- Use for market classification
+
+**For Risk Management**:
+- Cycle length affects position sizing
+- Short cycles = smaller positions
+- Long cycles = larger positions
+- Use cycle for stop placement
+
+HT_DCPERIOD is particularly valuable for traders who want to understand the cyclical nature of markets and use this information for adaptive trading strategies. It's an advanced tool that requires understanding of cycle analysis but can provide significant advantages in cyclical markets.
+