gavindiaz/mql5
1
0
Fork 0
mirror of https://github.com/softwaredevelop/mql5.git synced 2026-11-02 11:16:15 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
810d7661916340d85f3fae21615407abb05579b4
mql5/Indicators/MyIndicators/Quant/FDI_Pro_Documentation.md
T
Toh4iem9 f261294f62 docs: refactor
2026-10-16 16:32:38 +02:00

18 KiB
Raw Blame History

Institutional Fractal Dimension Index Pro (Enterprise Ultra Edition v2.20)

1. Executive Summary & Fractal Topology in Financial Markets

The Institutional Fractal Dimension Index Pro (FDI_Pro) is an advanced non-linear quantitative regime-detection engine engineered for MetaTrader 5 (Year 2026 Enterprise Edition). Rooted in the mathematical principles of Benoit Mandelbrot's fractal geometry and Carlos Ševčík's normalized waveform algorithm (1998), it quantifies the topological complexity, persistence, and geometric roughness of price trajectories.

The Topological Scale of Market Dimension (D)

In Euclidean geometry, a straight line has a topological dimension of strictly D = 1.0, while a complete two-dimensional surface has D = 2.0. Financial price curves exist in a fractional (fractal) space between a pure line and a plane:


Fractal Dimension Scale (D)
  ^
  |  [ANTI-PERSISTENT CHOP / CHAOS REGIME] (D > 1.55)
  |  Hurst Exponent: H < 0.45  |  Color: Crimson Red
  |  State: Space-filling curve, extreme whipsaw, mean-reversion dominant.
  |  ACTION: FORBID Trend Systems | Trade Tight Band Fades | Scalp Extremes
--+------------------------------------------------------------------- InpLevelChop (1.55)
  |  [RANDOM WALK / EMH EQUILIBRIUM REGIME] (1.45 <= D <= 1.55)
  |  Hurst Exponent: H ~ 0.50  |  Color: Gold
  |  State: Uncorrelated Brownian Motion, efficient auction equilibrium.
  |  ACTION: Stand Down | Avoid Breakout Execution | Wait for Expansion
--+------------------------------------------------------------------- Random Walk Baseline (1.50)
--+------------------------------------------------------------------- InpLevelTrend (1.45)
  |  [PERSISTENT TREND REGIME] (D < 1.45)
  |  Hurst Exponent: H > 0.55  |  Color: Deep Sky Blue
  |  State: Low-dimension directional inertia, smooth persistent trajectory.
  |  ACTION: MAXIMIZE Trend Following | Enable Band-Walking | Ride Breakouts
  v
 1.00 Euclidean Straight Line

2. Mathematical & Algorithmic Specifications

The algorithm maps an arbitrary financial time series of length N onto a normalized unit square [0, 1] \times [0, 1] to calculate its Hausdorff dimension approximation.


+-------------------------------------------------------------------------------+
|                       SEVCIK FRACTAL DIMENSION PIPELINE                       |
+-------------------------------------------------------------------------------+
  Price Window: [P_{i-N+1} ... P_i] (Length N = 30)
         |
         v
  Unit Square Coordinate Normalization:
    Delta_x = 1.0 / (N - 1)
    Delta_y = (P_k - P_{k-1}) / (Highest - Lowest)
         |
         v
  Pipelined Euclidean Hypotenuse Accumulation (O(N)):
    L = Sum of Sqrt( Delta_x^2 + Delta_y^2 )  [Length in Unit Square]
         |
         v
  Fractal Dimension Output (D):
    FDI_NORMALIZED_BROWNIAN: D = 1.0 + ln(L) / ln(N - 1)
    [Strictly Anchored: Flat Line = 1.00, Brownian Walk = 1.50, Chaos = 2.00]

A. Unit Square Mapping & Hypotenuse Path Length (L)

Given an analysis window of N bars (InpPeriod), the engine determines the local extrema:

\text{Range}_t = \max_{0 \le k < N}(P_{i-k}) - \min_{0 \le k < N}(P_{i-k})

The normalized coordinates in the unit square are:

\Delta x = \frac{1}{N - 1}, \quad \Delta y_k = \frac{P_k - P_{k-1}}{\text{Range}_t}

The total normalized path length L of the curve is calculated using the Pythagorean metric:

L = \sum_{k=1}^{N-1} \sqrt{(\Delta x)^2 + (\Delta y_k)^2}

ALU Optimization: The engine precalculates (\Delta x)^2 in Init() and replaces all runtime divisions with a single reciprocal multiplication: \Delta y_k = \Delta P_k \cdot (1.0 / \text{Range}_t), achieving a 4x ALU pipelined speedup.

B. The Finite-Window Scaling Paradox & Brownian Normalization

In Carlos Ševčík's original 1998 derivation, the formula was defined as:

D = 1.0 + \frac{\ln(L)}{\ln(2 \cdot (N - 1))}
  • The Finite-Window Flaw: Ševčík designed his formula for large datasets (N = 1024, 2048). At small trading windows (N = 30), the denominator \ln(2(N-1)) = \ln(58) \approx 4.06 is excessively large relative to the random walk path length (L \approx 3.0). Consequently, a pure random walk produced D \approx 1.25 \dots 1.28, completely failing to reach the theoretical 1.50 baseline!
  • The Retail +ln(2) Hack: Early retail coders attempted to fix this by arbitrarily adding \ln(2) to the numerator: D_{\text{retail}} = 1.0 + \frac{\ln(L) + \ln(2)}{\ln(2 \cdot (N - 1))} While this shifted random walk close to 1.45, it introduced an artificial +0.17 upward bias on straight lines (L = 1.0 \implies D \approx 1.17).

The Solution: Pure Brownian Normalization (FDI_NORMALIZED_BROWNIAN)

In v2.10+, the engine incorporates the Pure Brownian Normalized Scaling:

D = 1.0 + \frac{\ln(L)}{\ln(N - 1)}
  • Flat Straight Line (L = 1.0): \ln(1.0) = 0 \implies \mathbf{D \equiv 1.000} (Perfect Euclidean trend).
  • Brownian Random Walk (L \approx \sqrt{N - 1}): \ln(\sqrt{N-1}) = 0.5 \ln(N-1) \implies \mathbf{D \equiv 1.500} (Mathematically invariant across all N!).
  • Maximum Space-Filling Jaggedness (L \to N - 1): \mathbf{D \to 2.000} (Complete planar chaos).

C. The Hurst Exponent Mathematical Bridge

The Fractal Dimension index is mathematically connected to the Hurst Exponent (H) via Mandelbrot's identity:

H = 2.0 - D
  • When D < 1.45 \implies H > 0.55: The time series possesses long-term memory and persistence (positive autocorrelation of increments).
  • When D = 1.50 \implies H = 0.50: The increments are completely uncorrelated (martingale property).
  • When D > 1.55 \implies H < 0.45: The series is anti-persistent and mean-reverting (negative autocorrelation of increments).

3. The 3 Market Regimes & Operational Action Matrix

Regime Zone FDI Value Hurst (H) Visual Color Market Condition Allowed Strategies Forbidden Strategies
Persistent Trend < 1.45 > 0.55 clrDeepSkyBlue Strong Directional Drift. Price trajectory is smooth, persistent, and low-dimensional. Trend Following, Breakouts, KAMA Band-Walking, Pyramiding winning trades. Counter-trend fading, Mean-reversion scalping, Wide Martingale grids.
Random Walk 1.45 \dots 1.55 \approx 0.50 clrGold EMH Auction Equilibrium. Price changes are uncorrelated noise. Stand Down, Wait for Breakout Compression, Tight Trailing on existing runners. Aggressive breakout entries (high risk of chop).
Anti-Persistent Chop > 1.55 < 0.45 clrCrimson High-Frequency Whipsaw. Curve is space-filling; price violently reverts around its mean. Band Fades at $\pm 3\sigma$, Tight Mean-Reversion Scalping, Neutral Grid options. ALL Trend-Following Systems, Breakout Trading, Chasing momentum.

4. High-Performance 2026 MTF Fast-Path Architecture

When evaluating higher timeframe fractal dimensions (e.g., viewing H1 or H4 FDI on an M5 or M15 chart), traditional indicators freeze the terminal UI by executing tens of thousands of iBarShift() API calls.

FDI_Pro features the 2026 Two-Pointer Chronological Sweep:


Current Chart Bars (time[]):   [Bar 0] ---> [Bar 1] ---> ... ---> [Bar 49,999]
                                  |            |                     |
                                  v            v                     v
Two-Pointer Sweep:             [htf_ptr++]  [htf_ptr]             [htf_ptr++]
                                  |            |                     |
                                  v            v                     v
Higher Timeframe (h_time[]):   [HTF 0] ---> [HTF 1] ---> ... ---> [HTF 1,999]

Computational Benchmarks

  • Two-Pointer Linear Sweep: Replaces 50,000 native API calls with O(N) integer pointer increments. Historical synchronization latency drops from \approx 35.0 \text{ ms} to \approx 0.08 \text{ ms} (350x speedup).
  • Live-Tick Isolated Fast-Path: Intra-bar ticks update the forming HTF candle in RAM (live_idx = g_htf_count - 1), snapping instantly to the block start via O(\log N) binary search (ArrayBsearch).
  • Zero-Heap Mandate: All buffers, caches, and registers reside in persistent BSS arrays. Zero bytes of heap allocation occur on live ticks.

5. Comprehensive Parameter Reference & Calibration Matrix

Input Settings

Parameter Type Default Description Operational Profile
InpTimeframe ENUM_TIMEFRAMES PERIOD_CURRENT Calculation timeframe (Current or HTF). Native O(1) or Two-Pointer MTF.
InpPeriod int 30 Analysis window (N, recommended: 20–50). Governs curve sample size.
InpMethod ENUM_FDI_METHOD FDI_NORMALIZED_BROWNIAN Mathematical scaling formulation. Flagship mode: Brownian Normalization.
InpPrice ENUM_APPLIED_PRICE PRICE_CLOSE Source price series. Applied price feed.
InpHistoryBars int 1000 Historical lookback limit (0 = Full Chart). Eliminates cold-start terminal freezes.
InpAutoThresholds bool true Auto-adapts thresholds to window N. Guarantees balanced color distribution.
InpLevelTrend double 1.45 Manual trend threshold (if Auto is false). Upper boundary for DeepSkyBlue zone.
InpLevelChop double 1.55 Manual chop threshold (if Auto is false). Lower boundary for Crimson zone.
InpVisualType ENUM_FDI_VISUAL VISUAL_FDI_HISTOGRAM Display mode (VISUAL_FDI_LINE or VISUAL_FDI_HISTOGRAM). Toggles plot appearance.
InpColorTrend color clrDeepSkyBlue Plot color for Persistent Trend (D < 1.45). Native GPU plot buffer.
InpColorRandom color clrGold Plot color for Random Walk (1.45 \le D \le 1.55). Native GPU plot buffer.
InpColorChop color clrCrimson Plot color for Anti-persistent Chop (D > 1.55). Native GPU plot buffer.
InpWidthPlot int 2 Main plot line / histogram width. Visual thickness.
InpShowSignal bool true Display Signal Line overlay. Toggles Signal Line plot.
InpSignalPeriod int 9 Signal Line exponential smoothing period. Governs trend momentum in FDI.
InpColorSignal color clrMagenta Universal high-contrast Signal Line color. Highly visible on dark & light themes.
InpWidthSignal int 2 Signal Line width. Visual thickness.

Quantitative Calibration Matrix

Trading Style Asset Class Base Chart Target TF FDI Period (N) Calculation Method Strategy Objective
Micro-Scalping Indices / Majors FX M1 / M5 PERIOD_CURRENT 20 FDI_NORMALIZED_BROWNIAN Fast detection of micro-trend persistence vs spread chop.
Day Trading FX / Oil / Metals M5 / M15 M15 / H1 30 FDI_NORMALIZED_BROWNIAN Standard institutional calibration for session breakout filtering.
Swing Trading Equities / Crypto H1 / H4 H4 / D1 40 FDI_NORMALIZED_BROWNIAN Filters multi-day consolidation noise on macro asset flows.

6. Visual Interface Standards & High-Contrast Design


Plot 0: [BufFDI   ] ---> DRAW_COLOR_LINE / DRAW_COLOR_HISTOGRAM (Width 2)
                         - Color 0: clrDeepSkyBlue (Trend Regime)
                         - Color 1: clrGold        (Equilibrium / Random Walk)
                         - Color 2: clrCrimson     (Chaos / Mean-Reverting Chop)

Plot 1: [BufSignal] ---> DRAW_LINE (clrMagenta, Width 2)
                         - Universal high-contrast signal overlay.
                         - Distinctly visible on both Black and White chart templates.
  • Auto-Adaptive Levels: When InpAutoThresholds = true, horizontal lines at D_{\text{trend}}, 1.50, and D_{\text{chop}} are dynamically injected into the subwindow based on the exact sample depth N.

7. Quantitative Trading Playbooks

Playbook A: Persistent Trend Surfing (D < 1.45 + KAMA_Bands_Pro)


Price Action
  |                                        /=====> PERSISTENT MOMENTUM RALLY
  |                       /\              /
  |  +-------------------/--\------------/------------------+ Upper Band 1 (+1.0 Sigma)
  |  |                  /    \          / [PULLBACK BOUNCE]
  |  |                 /      \        /
  +--+----------------+--------\------/---------------------+ KAMA Centerline
  |
FDI Subwindow
  | -------------------------------------------------------- Level 1.50 (Random Walk)
  | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Level 1.45 (Trend Boundary)
  | ===== [FDI CRASHES DEEP BELOW 1.45 - BLUE!]
  1. Setup:
    • Price breaks outside consolidation.
    • FDI_Pro drops sharply below 1.45 and prints Deep Sky Blue.
    • Interpretation: The Hurst exponent has expanded above H > 0.55. Price increments possess strong positive autocorrelation (persistence).
  2. Execution Trigger:
    • Enter in the direction of the breakout.
    • Allow pullbacks to retest the +1.0\sigma band of KAMA_Bands_Pro. As long as D < 1.45, hold the trade with wide trailing stops.
  3. Exit: Exit or take partial profits when BufFDI climbs back above 1.50 (trend persistence has decayed back into random walk equilibrium).

Playbook B: Anti-Persistent Mean-Reversion Scalp (D > 1.55 at \pm 3\sigma)

  1. Setup:
    • Price spikes into the extreme outer \pm 3.0\sigma band of VWAP_Bands_Pro or KAMA_Bands_Pro.
    • FDI_Pro surges above 1.55 and prints Crimson Red.
    • Interpretation: H < 0.45. The market is severely anti-persistent. A space-filling jagged reversal is mathematically probable.
  2. Execution Trigger:
    • Wait for a wick rejection candle at the \pm 3\sigma band.
    • FADE: Enter Short (if at upper band) or Long (if at lower band) targeting the mean.
    • Stop Loss: Strict tight stop (10 ticks). In anti-persistent regimes, reversals occur immediately; if price continues running, an institutional regime shift is occurring.

Playbook C: The Dual-Complexity Meta-Filter (FDI_Pro + Entropy_Pro)

Regime Metric Entropy_Pro (SampEn) FDI_Pro (Fractal Dimension) Market State & Strategic Alignment
Low / Low < 0.80 (Blue) < 1.45 (Blue) PRISTINE SUPER-TREND. Maximum geometric & phase space order. Heavy trend positioning permitted.
Low / High < 0.80 (Blue) > 1.55 (Red) COILED SQUEEZE. Price is compressing inside a narrow space-filling channel. Impending explosive breakout.
High / High > 1.30 (Red) > 1.55 (Red) TOTAL MARKET TOXICITY. High entropy + high fractal roughness. 100% Cash / No Trading.

8. Developer Integration & Expert Advisor Guide

The indicator exposes its visual buffers directly to MetaTrader 5 Expert Advisors (EAs) via the native iCustom() API:

Buffer Index Map

Buffer Index Identifier Description Range / Output
0 BufFDI Raw Fractal Dimension Index (D). Continuous double (1.0 \dots 2.0).
1 BufColor Active Color Index. 0.0 (Blue: Trend), 1.0 (Gold: Random Walk), 2.0 (Red: Chop).
2 BufSignal Signal Line (Exponential Moving Average of FDI). Continuous positive double.

Example MQL5 EA Integration Snippet

//+------------------------------------------------------------------+
//| Using FDI_Pro as an Automated Strategy Regime Gatekeeper         |
//+------------------------------------------------------------------+
int h_fdi = INVALID_HANDLE;

int OnInit()
  {
   // Bind to FDI_Pro via iCustom
   h_fdi = iCustom(_Symbol, PERIOD_CURRENT, "FDI_Pro",
                   PERIOD_CURRENT,             // Timeframe
                   30,                         // Analysis Window (N)
                   FDI_NORMALIZED_BROWNIAN,    // Brownian Normalization
                   PRICE_CLOSE,                // Price Source
                   1000,                       // History Bars Limit
                   true,                       // Auto-Adaptive Thresholds
                   1.45,                       // Manual Trend Threshold
                   1.55,                       // Manual Chop Threshold
                   VISUAL_FDI_LINE,            // Visual Style
                   clrDeepSkyBlue,             // Color Trend
                   clrGold,                    // Color Random Walk
                   clrCrimson,                 // Color Chop
                   2,                          // Plot Width
                   true,                       // Show Signal Line
                   9,                          // Signal Period
                   clrMagenta,                 // Signal Color
                   STYLE_SOLID,                // Signal Style
                   2);                         // Signal Width

   if(h_fdi == INVALID_HANDLE)
     {
      Print("Critical Error: Failed to create handle for FDI_Pro!");
      return INIT_FAILED;
     }
   return INIT_SUCCEEDED;
  }

void OnTick()
  {
   double fdi[1], col[1];
   // Read bar index 1 (closed bar) to guarantee non-repainting execution
   if(CopyBuffer(h_fdi, 0, 1, 1, fdi) <= 0 ||
      CopyBuffer(h_fdi, 1, 1, 1, col) <= 0)
      return;

   double fdi_value    = fdi[0];
   double regime_color = col[0]; // 0=Trend, 1=Random Walk, 2=Chop

   // REGIME 1: PERSISTENT TREND REGIME (Deep Sky Blue)
   if(regime_color == 0.0)
     {
      // Hurst Exponent H > 0.55! Enable trend-following and momentum breakout robots.
      EnableTrendStrategy(true);
      EnableMeanReversionStrategy(false);
     }
   // REGIME 3: ANTI-PERSISTENT CHOP / CHAOS REGIME (Crimson Red)
   else if(regime_color == 2.0)
     {
      // Hurst Exponent H < 0.45! The market is jagged and mean-reverting.
      EnableTrendStrategy(false);
      EnableMeanReversionStrategy(true); // Tight envelope fades only
     }
   // REGIME 2: RANDOM WALK EQUILIBRIUM (Gold)
   else
     {
      // Uncorrelated noise. Disable aggressive trading.
      EnableTrendStrategy(false);
      EnableMeanReversionStrategy(false);
     }
  }

*Enterprise Quantitative Software Suite — 2026 Ultra Edition

Reference in New Issue View Git Blame Copy Permalink