mirror of
https://github.com/softwaredevelop/mql5.git
synced 2026-11-02 11:16:15 +00:00
docs: refactor
This commit is contained in:
Toh4iem9
@@ -0,0 +1,338 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
|
||||
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.
|
||||
|
||||
```text
|
||||
|
||||
+-------------------------------------------------------------------------------+
|
||||
| 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**:
|
||||
|
||||
```text
|
||||
|
||||
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
|
||||
|
||||
```text
|
||||
|
||||
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`)
|
||||
|
||||
```text
|
||||
|
||||
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
|
||||
|
||||
```mql5
|
||||
//+------------------------------------------------------------------+
|
||||
//| 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
Block a user