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
1a08296eecdeb758ac96b12a92529333d04a6fca
mql5/Indicators/MyIndicators/Quant/VolatilityRegime_Pro_Documentation.md
T
Toh4iem9 7f43e8f649 docs: refactor
2026-10-20 20:14:24 +02:00

20 KiB
Raw Blame History

Institutional Volatility Regime Pro (Enterprise Ultra Edition v2.40)

1. Executive Summary & The Volatility Cycle

The Institutional Volatility Regime Pro (VolatilityRegime_Pro) is an institutional-grade volatility state classifier and regime-detection engine developed for MetaTrader 5 (Year 2026 Enterprise Edition). By evaluating the mathematical ratio between a rapid, short-term Average True Range (Fast ATR) and a long-term baseline Average True Range (Slow ATR), it computes an asset-independent, unitless volatility ratio:

\text{VR}_t = \frac{\text{ATR}_{\text{fast}}(t)}{\text{ATR}_{\text{slow}}(t)}

The Universal Market Truth: The Volatility Cycle

Financial markets are non-stationary systems governed by cyclical phase transitions. Market price action eternally rotates through four predictable thermodynamic phases:


+-------------------------------------------------------------------------------+
|                       THE UNIVERSAL VOLATILITY CYCLE                          |
+-------------------------------------------------------------------------------+
       Phase 1: DEEP SQUEEZE (VR < 0.75)  [Energy Accumulation]
                         |
                         v
       Phase 2: ACTIVE EXPANSION (VR > 1.00) [Kinetic Breakout / Trend]
                         |
                         v
       Phase 3: VOLATILITY CLIMAX (VR >= 1.50) [Exhaustion Blowout]
                         |
                         v
       Phase 4: NORMAL CONTRACTION (0.75 <= VR < 1.00) [Auction Equilibrium]
                         |
                         +---> Loops back to Phase 1

Scale Invariance Across Asset Classes

Unlike raw volatility indicators (such as raw ATR in points or pips) which differ drastically between instruments (e.g., Bitcoin moving 2,500 points vs. EURUSD moving 0.00060 points), the Volatility Ratio is completely normalized and scale-invariant:

  • \text{VR} = 1.00 mathematically signifies that immediate volatility precisely equals the baseline expectation.
  • \text{VR} = 1.35 indicates an identical 35% volatility expansion whether trading Crypto, FX, Indices, or Crude Oil.

2. Mathematical & DSP Engine Specifications

The indicator is powered by Wilder's Relative Moving Average (RMA) ATR engine (CATRCalculator / CATRCalculator_HA) combined with the unified moving average smoothing engine (CMovingAverageCalculator).


Price Stream (OHLC / Heikin Ashi)
         |
         +---------------------------------------+
         |                                       |
         v                                       v
+-----------------------------+     +-----------------------------+
| Fast ATR Engine (P_f = 5)   |     | Slow ATR Engine (P_s = 50)  |
| Wilder RMA Fused Smoothing  |     | Wilder RMA Baseline Memory  |
+-----------------------------+     +-----------------------------+
         |                                       |
         +-------------------+-------------------+
                             |
                             v
               +---------------------------+
               | Volatility Ratio (VR):    |
               | VR = ATR_fast / ATR_slow  |
               +---------------------------+
                             |
                             +-----------------------------------+
                             |                                   |
                             v                                   v
               +---------------------------+       +---------------------------+
               | 4-Zone Regime Classifier  |       | Unified Signal MA Engine  |
               | (Blue, Gray, Lime, Orange)|       | (SMA, EMA, SMMA, LWMA...) |
               +---------------------------+       +---------------------------+

A. Discrete Formulation of Normalized True Range

For every bar t, the True Range is normalized against price gaps:

\text{TR}_t = \max\big( (H_t - L_t), \, |H_t - C_{t-1}|, \, |L_t - C_{t-1}| \big)

Wilder's RMA smoothing is computed via pipelined Fused Multiply-Add (FMA) multipliers (m\_decay and m\_inv\_period), completely eliminating runtime divisions:

\text{ATR}_t = \text{ATR}_{t-1} \cdot \left( \frac{N - 1}{N} \right) + \text{TR}_t \cdot \left( \frac{1}{N} \right)

B. Signal Line Integration via MovingAverage_Engine.mqh

To determine whether volatility is expanding or contracting in real time, the Volatility Ratio is smoothed using the unified CMovingAverageCalculator::CalculateOnArray() engine, supporting 7 institutional MA types:

  • SMA: Simple Moving Average
  • EMA: Exponential Moving Average (Default, high responsiveness)
  • SMMA: Smoothed Moving Average (Wilder's RMA equivalent)
  • LWMA: Linear Weighted Moving Average (Front-weighted, zero lag)
  • DEMA: Double Exponential Moving Average
  • TEMA: Triple Exponential Moving Average
  • VWMA: Volume-Weighted Moving Average

3. The 4 Institutional Volatility Regimes (Action Matrix)

The subwindow dynamically categorizes market conditions into four operational zones:


Volatility Ratio Scale (VR)
  ^
  |  [REGIME 4: VOLATILITY CLIMAX / BLOWOUT] (VR >= 1.50)
  |  Color: Dark Orange  |  State: Extreme Volatility Surge, Panic / Exhaustion
  |  ACTION: TIGHTEN STOPS | Prepare for Mean-Reversion Fades | Do NOT Chase
--+------------------------------------------------------------------- InpLevelClimax (1.50)
  |  [REGIME 3: ACTIVE EXPANSION / TREND] (1.00 <= VR < 1.50)
  |  Color: Lime Green  |  State: Healthy Institutional Trend Expansion
  |  ACTION: MAXIMIZE Trend-Following | Enable Breakouts | Band-Walking
--+------------------------------------------------------------------- InpLevelExpansion (1.00 - Baseline)
  |  [REGIME 2: NORMAL CONTRACTION / QUIET] (0.75 <= VR < 1.00)
  |  Color: Gray  |  State: Sub-baseline Market Equilibrium, Consolidation
  |  ACTION: Standard Range Trading | Patiently Wait for Setup
--+------------------------------------------------------------------- InpLevelSqueeze (0.75)
  |  [REGIME 1: DEEP SQUEEZE / COILED SPRING] (VR < 0.75)
  |  Color: Dodger Blue  |  State: Severe Volatility Compression
  |  ACTION: PREPARE FOR EXPLOSIVE BREAKOUT | Arm Breakout EAs
  v
 0.00 Floor Baseline

The Institutional Trading Action Matrix

Regime Zone Ratio Value (\text{VR}) Color Code Market Phase Allowed Strategies Forbidden Strategies
Zone 1: Deep Squeeze < 0.75 clrDodgerBlue Severe Compression. Market energy is coiled like a compressed spring. An explosive move is imminent. Arming Breakout Orders (Buy/Sell Stops), Straddles, Preparing momentum entries. Trading trend-continuation inside the squeeze (high chop risk).
Zone 2: Contraction 0.75 \dots 1.00 clrGray Auction Equilibrium. Volatility is below its 50-period average. Normal price rotation. Range trading between support/resistance, VWAP centerline mean-reversion. Aggressive breakout chasing (low follow-through probability).
Zone 3: Expansion 1.00 \dots 1.50 clrLime Institutional Expansion. Short-term volatility dominates baseline. Strong directional trend. Trend-Following, Breakout Execution, Riding KAMA Bands, Adding to winners. Counter-trend fading, Selling into green expansion bars.
Zone 4: Climax \ge 1.50 clrDarkOrange Volatility Blowout. Overextended momentum climax. Institutional profit-taking likely. Taking Profit on Trend Runners, Fading outer \pm 3.0\sigma bands, Tight trailing stops. Entering fresh breakout positions (high risk of buying tops/selling bottoms).

4. High-Performance 2026 MTF Fast-Path Architecture

When calculating higher timeframe volatility regimes (e.g., viewing H1 or H4 Volatility Ratio on an M5 execution chart), traditional indicators freeze the terminal UI by executing tens of thousands of iBarShift() API calls.

VolatilityRegime_Pro incorporates 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 calculation arrays (m_atr_fast, m_atr_slow, h_double_vol) reside in persistent BSS memory. 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.
InpPeriodFast int 5 Short-term Fast ATR period. Captures immediate impulse volatility.
InpPeriodSlow int 50 Long-term Slow ATR baseline period. Defines the benchmark normal volatility.
InpCandleSource ENUM_CANDLE_SOURCE CANDLE_STANDARD Candle source (Standard / Heikin Ashi). Toggles Heikin Ashi ATR smoothing.
InpHistoryBars int 1000 Historical lookback limit (0 = Full Chart). Eliminates cold-start terminal freezes.
InpLevelSqueeze double 0.75 Squeeze threshold boundary. Upper boundary for Blue Squeeze zone.
InpLevelExpansion double 1.00 Expansion baseline threshold. Demarcation between Gray and Lime.
InpLevelClimax double 1.50 Volatility Climax threshold. Lower boundary for Dark Orange zone.
InpVisualType ENUM_VOLA_VISUAL VISUAL_VOLA_HISTOGRAM Display mode (Histogram vs Line). Toggles plot appearance.
InpColorSqueeze color clrDodgerBlue Plot color for Squeeze (\text{VR} < 0.75). Native GPU plot buffer.
InpColorQuiet color clrGray Plot color for Contraction (0.75 \dots 1.00). Native GPU plot buffer.
InpColorExpand color clrLime Plot color for Expansion (1.00 \dots 1.50). Native GPU plot buffer.
InpColorClimax color clrDarkOrange Plot color for Climax (\text{VR} \ge 1.50). 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 smoothing period. Governs trend momentum in volatility.
InpSignalType ENUM_MA_TYPE EMA Signal Line MA Method (SMA, EMA, etc.). Unified Moving Average Engine.
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 Execution TF Fast / Slow ATR Target Volatility Focus
Micro-Scalping Crypto / Liquid Indices M1 / M3 3 / 30 Ultra-fast detection of order book sweeps and liquidity breaks.
Session Trading Majors FX / Metals M5 / M15 5 / 50 Standard institutional calibration for London/NY open expansions.
Swing Structure Equities / Commodities H1 / H4 7 / 70 Macro regime shifts filtering out multi-day consolidations.

6. Visual Interface Standards & Multi-Plot Layout


Plot 0: [BufRatio ] ---> DRAW_COLOR_HISTOGRAM / DRAW_COLOR_LINE (Width 2)
                         - Color 0: clrDodgerBlue (Deep Squeeze < 0.75)
                         - Color 1: clrGray       (Contraction 0.75 - 1.00)
                         - Color 2: clrLime       (Active Expansion 1.00 - 1.50)
                         - Color 3: clrDarkOrange (Volatility Climax >= 1.50)

Plot 1: [BufSignal] ---> DRAW_LINE (clrMagenta, Width 2)
                         - Driven by CMovingAverageCalculator::CalculateOnArray()
                         - High-contrast overlay clearly visible on all chart themes.
  • 0.00 Floor Baseline: The indicator locks its subwindow base at INDICATOR_MINIMUM = 0.0. All histogram bars rise cleanly from the zero floor without floating artifacts.
  • Horizontal Benchmark Grid: Includes three silver dotted levels at 0.75, 1.00, and 1.50.

7. Quantitative Trading Playbooks

Playbook A: The Coiled Squeeze Breakout (Blue \to Lime Surge)


Price Action
  |                         [COILED CONSOLIDATION]        /=====> POWERFUL BREAKOUT RALLY
  |                   ================================   /
  |------------------/                                \-/------------------------------ Resistance
  |                                                     ^
  |                                                     |-- BUY ENTRY (Ratio crosses 1.00)
  +------------------------------------------------------------------------------------ Time
Volatility Subwindow
  | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Level 1.50 (Climax)
  | ---------------------------------------------------||||||||||||||||||||||||||||||- Level 1.00 (Expansion)
  | ...................................................||||||||||||||||||||||||||||||. Level 0.75 (Squeeze)
  | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
  | [DODGER BLUE: DEEP SQUEEZE]                        [LIME: ACTIVE EXPANSION]
  1. Setup:
    • Price consolidates inside a tight range.
    • VolatilityRegime_Pro prints consecutive Dodger Blue bars (\text{VR} < 0.75).
    • Interpretation: Volatility is severely suppressed. A massive volume explosion is mathematically brewing.
  2. Execution Trigger:
    • Price breaks outside the consolidation boundaries.
    • The Volatility Ratio surges above 1.00 and turns Lime Green, crossing above its Magenta Signal Line.
    • BUY/SELL: Enter immediately in the direction of the price breakout.
  3. Exit: Hold trade while bars remain Lime. Tighten trailing stop when bars turn Dark Orange (\text{VR} \ge 1.50).

Playbook B: Volatility Climax Fade (Dark Orange Exhaustion)


Price Action
  |                                            /\  [PARABOLIC BLOWOUT TOP]
  |                                           /  \
  |  +---------------------------------------/----\------------------------------------+ +3.0 Sigma Band
  |                                         ^      \_____ [SHARP MEAN-REVERSION DROP]
  |                                         |-- FADE SHORT ENTRY (Ratio >= 1.50)
  +------------------------------------------------------------------------------------ Time
Volatility Subwindow
  |                                          ||||  [DARK ORANGE: CLIMAX SURGE >= 1.50]
  | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~||||~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Level 1.50 (Climax)
  | -----------------------------------------||||-------------------------------------- Level 1.00 (Expansion)
  1. Setup:
    • Market goes parabolic in a runaway trend.
    • Price pierces the extreme +3.0\sigma upper band of KAMA_Bands_Pro or VWAP_Bands_Pro.
    • VolatilityRegime_Pro surges above 1.50 and prints Dark Orange.
  2. Execution Trigger:
    • Wait for a rejection wick at the +3.0\sigma band.
    • The Volatility Ratio peaks and crosses back below its Signal Line.
    • SELL: Fade the blowout move targeting the +1.0\sigma band or the KAMA centerline.

Playbook C: The Quad-Suite Alignment Meta-Filter

Combine all four core suite engines for maximum statistical edge:

  1. Regime State (Entropy_Pro): SampEn < 0.80 (Structural Order confirmed).
  2. Volatility Trigger (VolatilityRegime_Pro): Ratio surges from Blue (< 0.75) into Lime (> 1.00).
  3. Trend Geometry (KAMA_Bands_Pro): Price band-walks along +1.0\sigma.
  4. Order Flow Anchor (Absorption_Pro): Backed by an intact Demand Zone.
  • Trade Quality: Institutional Grade A+ Setup.

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 BufRatio Raw Volatility Ratio (\text{ATR}_{\text{fast}} / \text{ATR}_{\text{slow}}). Continuous positive double (0.0 \dots 3.0+).
1 BufColors Active Color Index. 0.0 (Blue: Squeeze), 1.0 (Gray: Quiet), 2.0 (Lime: Expansion), 3.0 (Orange: Climax).
2 BufSignal Signal Line (Unified Moving Average). Continuous positive double.

Example MQL5 EA Integration Snippet

//+------------------------------------------------------------------+
//| Using VolatilityRegime_Pro as an Automated Breakout/Trend Gate   |
//+------------------------------------------------------------------+
int h_vola = INVALID_HANDLE;

int OnInit()
  {
   // Bind to VolatilityRegime_Pro via iCustom
   h_vola = iCustom(_Symbol, PERIOD_CURRENT, "VolatilityRegime_Pro",
                    PERIOD_CURRENT,         // Timeframe
                    5,                      // Fast ATR Period
                    50,                     // Slow ATR Period
                    CANDLE_STANDARD,        // Candle Source
                    1000,                   // History Bars Limit
                    0.75,                   // Squeeze Threshold
                    1.00,                   // Expansion Threshold
                    1.50,                   // Climax Threshold
                    VISUAL_VOLA_HISTOGRAM,  // Visual Style
                    clrDodgerBlue,          // Color Squeeze
                    clrGray,                // Color Quiet
                    clrLime,                // Color Expansion
                    clrDarkOrange,          // Color Climax
                    2,                      // Plot Width
                    true,                   // Show Signal Line
                    9,                      // Signal Period
                    EMA,                    // Signal MA Method (ENUM_MA_TYPE)
                    clrMagenta,             // Signal Color
                    STYLE_SOLID,            // Signal Style
                    2);                     // Signal Width

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

void OnTick()
  {
   double ratio[1], color_idx[1], signal_val[1];
   // Read bar index 1 (closed bar) to guarantee non-repainting execution
   if(CopyBuffer(h_vola, 0, 1, 1, ratio) <= 0 ||
      CopyBuffer(h_vola, 1, 1, 1, color_idx) <= 0 ||
      CopyBuffer(h_vola, 2, 1, 1, signal_val) <= 0)
      return;

   double vr_ratio     = ratio[0];
   double regime_state = color_idx[0]; // 0=Squeeze, 1=Quiet, 2=Expansion, 3=Climax
   double signal_line  = signal_val[0];

   // RULE 1: BREAKOUT & TREND FILTER
   // Only execute trend-following orders when volatility is expanding above baseline!
   bool is_expansion_active = (regime_state == 2.0 && vr_ratio > signal_line);

   if(is_expansion_active)
     {
      // Volatility is expanding with accelerating momentum!
      EnableBreakoutStrategy(true);
     }
   else
     {
      // Sub-baseline or exhausted volatility!
      EnableBreakoutStrategy(false);
     }

   // RULE 2: PROFIT-TAKING ON VOLATILITY CLIMAX
   if(regime_state == 3.0)
     {
      // Market has reached an unsustainable volatility blowout (VR >= 1.50)!
      TightenTrailingStops();
     }
  }

*Enterprise Quantitative Software Suite — 2026 Ultra Edition

Reference in New Issue View Git Blame Copy Permalink