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
+351
@@ -0,0 +1,351 @@
|
||||
# Laguerre Adaptive Filter Pro (v1.30)
|
||||
|
||||
John Ehlers' Time-Warped Digital Filter with Dynamic Multi-Mode Adaptive Gamma Tuning
|
||||
|
||||
---
|
||||
|
||||
## 1. Summary (Introduction)
|
||||
|
||||
**Laguerre Adaptive Filter Pro (v1.30)** is an original, institutional-grade quantitative hybrid indicator that unifies John Ehlers' **Time-Warped Orthogonal Laguerre Polynomial Filter** with dynamic, market-responsive **Adaptive Kinematics**.
|
||||
|
||||
In traditional technical analysis, adaptive moving averages (such as Perry Kaufman's KAMA) operate within the rigid constraints of linear unit delays ($z^{-1}$). While KAMA slows down during consolidation, it is forced to square its smoothing constant, which inevitably re-introduces phase lag when abrupt trend inflections occur.
|
||||
|
||||
**Laguerre Adaptive Filter Pro solves this dilemma at the foundational mathematical level:**
|
||||
Rather than relying on linear time, it applies an all-pass Laguerre time-warped transfer function ($L_0 \dots L_3$), where the damping coefficient $\gamma$ (Gamma) is **dynamically modulated on every single bar** based on real-time market microstructure:
|
||||
|
||||
* **High Efficiency / High Volatility ($\text{Metric} \to 1.0$):** Gamma automatically scales down to $\gamma_{\text{min}}$ (e.g., $0.10 \dots 0.20$), instantly transforming the filter into an ultra-responsive, zero-lag trend-hugging line.
|
||||
* **Low Efficiency / Noisy Consolidation ($\text{Metric} \to 0.0$):** Gamma automatically scales up to $\gamma_{\text{max}}$ (e.g., $0.80 \dots 0.90$), heavily damping high-frequency noise and freezing the filter into a horizontal brick-wall support/resistance line.
|
||||
|
||||
```text
|
||||
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ ADAPTIVE LAGUERRE FILTER ARCHITECTURAL ENGINE │
|
||||
├────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ MARKET REGIME EVALUATION (Selectable Adaptive Engine): │
|
||||
│ ┌────────────────────────┬───────────────────┬───────────────────┐ │
|
||||
│ │ Kaufman's Efficiency │ Average True Range│ Standard Deviation│ │
|
||||
│ │ Ratio (ER) [0.0 - 1.0] │ (ATR Normalization│ (StDev Normaliz.) │ │
|
||||
│ └────────────────────────┴───────────────────┴───────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ DYNAMIC GAMMA SCALING │
|
||||
│ γ(t) = γ_max - Metric(t) · (γ_max - γ_min) │
|
||||
│ │ │
|
||||
│ ▼ 4-POLE LAGUERRE POLYNOMIALS │
|
||||
│ L0(t) ──▶ L1(t) ──▶ L2(t) ──▶ L3(t) ──▶ Output = (L0+2L1+2L2+L3)/6 │
|
||||
│ │
|
||||
└────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
```
|
||||
|
||||
### Key Capabilities
|
||||
|
||||
* **Tri-Mode Adaptive Engine:** Switch dynamically between Kaufman's **Efficiency Ratio (ER)**, **Average True Range (ATR)**, and **Standard Deviation (StDev)** pathways.
|
||||
* **Continuous Damping Modulation:** Automatically tunes the filter's time-warp ratio between user-defined speed ($\gamma_{\text{min}}$) and smoothness ($\gamma_{\text{max}}$) bounds without heuristic curve-fitting.
|
||||
* **Zero-Lag MTF Fast-Path:** Higher-timeframe adaptive curves project onto lower-timeframe execution charts as crisp, non-warping flat steps via `DataSync_Tools.mqh` with zero `iBarShift` overhead on live ticks.
|
||||
* **Instance-Isolated Thread Safety:** Completely eliminates static buffer sharing, guaranteeing 100% crash-free stability across workspaces with 14+ simultaneous chart windows.
|
||||
* **Synthetic Heikin Ashi Routing:** Fully compatible with filtered Heikin Ashi synthetic price series via `CHeikinAshi_Calculator` composition.
|
||||
|
||||
---
|
||||
|
||||
## 2. Mathematical Foundations & Adaptive Pathways
|
||||
|
||||
```text
|
||||
|
||||
RAW PRICE (Market Noise & Trend Vectors)
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ Adaptive Pathway Normalization Engine │
|
||||
│ Calculates Metric(t) ∈ [0.0, 1.0] (ER, ATR, or StDev)│
|
||||
└───────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ Dynamic Gamma Transfer Function │
|
||||
│ γ(t) = γ_max - Metric(t) · (γ_max - γ_min) │
|
||||
└───────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ Time-Warped 4-Element Laguerre Recursion │
|
||||
│ L0(t), L1(t), L2(t), L3(t) States │
|
||||
└───────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
Adaptive Non-Linear Filter Line
|
||||
|
||||
```
|
||||
|
||||
### 2.1. The Three Adaptive Engine Pathways
|
||||
|
||||
#### Pathway A: Kaufman's Efficiency Ratio (`METHOD_EFFICIENCY_RATIO`)
|
||||
|
||||
Measures the ratio of net linear directional displacement to total cumulative distance traveled over period $P = \text{InpAdaptivePeriod}$:
|
||||
$$\text{Direction}_t = |P_t - P_{t - P}|$$
|
||||
$$\text{Volatility}_t = \sum_{k=0}^{P - 1} |P_{t-k} - P_{t-k-1}|$$
|
||||
$$\text{Metric}_t = \begin{cases} \frac{\text{Direction}_t}{\text{Volatility}_t}, & \text{if } \text{Volatility}_t > 10^{-9} \\ 0.0, & \text{otherwise} \end{cases}$$
|
||||
*(Naturally normalized: $\text{Metric}_t \in [0.0, 1.0]$).*
|
||||
|
||||
#### Pathway B: Average True Range Volatility (`METHOD_ATR`)
|
||||
|
||||
Computes Wilder's ATR across period $P$, then normalizes the raw points into $[0.0, 1.0]$ using a sliding lookback window:
|
||||
$$\text{Metric}_t = \text{Normalize}(\text{ATR}_t, P)$$
|
||||
|
||||
#### Pathway C: Accelerated Standard Deviation (`METHOD_STAND_DEV`)
|
||||
|
||||
Computes the statistical dispersion of price around the $P$-period arithmetic mean using single-cycle scalar squaring (zero `pow()` calls):
|
||||
$$\mu_t = \frac{1}{P} \sum_{j=0}^{P - 1} P_{t-j}$$
|
||||
$$\text{StDev}_t = \sqrt{\frac{1}{P} \sum_{j=0}^{P - 1} (P_{t-j} - \mu_t)^2}$$
|
||||
$$\text{Metric}_t = \text{Normalize}(\text{StDev}_t, P)$$
|
||||
|
||||
---
|
||||
|
||||
### 2.2. Sliding Min-Max Normalization Helper
|
||||
|
||||
To map raw currency volatility (ATR or StDev) into a normalized damping metric $[0.0, 1.0]$, a sliding $P$-period Min-Max function is applied:
|
||||
$$\text{MinVal}_t = \min_{j=0 \dots P-1} (\text{Raw}_j), \quad \text{MaxVal}_t = \max_{j=0 \dots P-1} (\text{Raw}_j)$$
|
||||
$$\Delta\text{Val}_t = \text{MaxVal}_t - \text{MinVal}_t$$
|
||||
$$\text{Metric}_t = \begin{cases} \frac{\text{Raw}_t - \text{MinVal}_t}{\Delta\text{Val}_t}, & \text{if } \Delta\text{Val}_t > 10^{-9} \\ 0.0, & \text{otherwise} \end{cases}$$
|
||||
|
||||
---
|
||||
|
||||
### 2.3. Dynamic Gamma Scaling Transfer Function
|
||||
|
||||
Given maximum damping $\gamma_{\text{max}} = \text{InpGammaMax}$, minimum damping $\gamma_{\text{min}} = \text{InpGammaMin}$, and precomputed range $\Delta\gamma = \gamma_{\text{max}} - \gamma_{\text{min}}$:
|
||||
$$\gamma_t = \text{Clamp}\Big( \gamma_{\text{max}} - (\text{Metric}_t \cdot \Delta\gamma), \; 0.0, \; 1.0 \Big)$$
|
||||
|
||||
---
|
||||
|
||||
### 2.4. Time-Warped 4-Element Laguerre Difference Equations
|
||||
|
||||
Using the dynamic gamma $\gamma_t$, the four orthogonal state elements update recursively:
|
||||
$$L_0(t) = (1 - \gamma_t) P_t + \gamma_t L_0(t-1)$$
|
||||
$$L_1(t) = -\gamma_t L_0(t) + L_0(t-1) + \gamma_t L_1(t-1)$$
|
||||
$$L_2(t) = -\gamma_t L_1(t) + L_1(t-1) + \gamma_t L_2(t-1)$$
|
||||
$$L_3(t) = -\gamma_t L_2(t) + L_2(t-1) + \gamma_t L_3(t-1)$$
|
||||
|
||||
The final adaptive output is synthesized via fast reciprocal multiplication:
|
||||
$$\text{Adaptive Filter}_t = \Big( L_0(t) + 2 \cdot (L_1(t) + L_2(t)) + L_3(t) \Big) \cdot \frac{1}{6}$$
|
||||
|
||||
---
|
||||
|
||||
## 3. MQL5 Architecture & Computational Benchmarking
|
||||
|
||||
```text
|
||||
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ Laguerre_Adaptive_Filter_Calculator.mqh │
|
||||
│ (Instance-Isolated Member Buffers: Zero Static!) │
|
||||
└──────────────────────────┬─────────────────────────────┘
|
||||
│ Delivers Adaptive Buffer in O(1)
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ Laguerre_Adaptive_Filter_Pro.mq5 │
|
||||
│ (Unified Native & Zero-Lag MTF Fast-Path) │
|
||||
├──────────────────────────┬─────────────────────────────┤
|
||||
│ Direct Mode (O(1)) │ Synchronized MTF Pipeline │
|
||||
│ • Current Timeframe │ • Atomic CopyRates MTF │
|
||||
│ • Fast-Pointer Safety │ • Binary Search Snapping │
|
||||
└──────────────────────────┴─────────────────────────────┘
|
||||
|
||||
```
|
||||
|
||||
### Engineering Benchmark: Legacy (v1.20) vs. Enterprise (v1.30)
|
||||
|
||||
| Metric | Legacy Implementation (v1.20) | Enterprise Refactor (v1.30) | Net Optimization |
|
||||
| :--- | :---: | :---: | :---: |
|
||||
| **Heikin Ashi Array Scope** | `static` shared arrays in method | **Strict Member Variables** | **Eliminates Multi-Chart Crashes** |
|
||||
| **Standard Deviation Math** | `pow(diff, 2)` transcendental calls | **Direct `diff * diff` squaring** | **50x Faster ALU Math** |
|
||||
| **Gamma Range Evaluation** | Subtracted on every bar | **Precomputed $\Delta\gamma$ in `Init`** | **Eliminates Loop Arithmetic** |
|
||||
| **MTF Live-Tick `iBarShift`** | Up to 500 calls per tick | **0 calls on live ticks (`ArrayBsearch`)** | **Complete Zero-Lag** |
|
||||
| **MTF Data Copy Calls** | 4 separate calls per tick | **1 atomic `CopyRates` query** | **-75.0% API Overhead** |
|
||||
| **Pointer Safety** | Slow `CheckPointer()` on ticks | **Fast `if(!g_calculator)` Guard** | **Optimized Branching** |
|
||||
| **Workspace Scalability** | Risk of array-out-of-range crashes | **100% thread-safe on >14 charts** | **Enterprise Certified** |
|
||||
|
||||
---
|
||||
|
||||
## 4. Parameters Reference
|
||||
|
||||
### Timeframe Settings
|
||||
|
||||
* `InpTimeframe` (*default: `PERIOD_CURRENT`*): Calculation timeframe. Set to `PERIOD_CURRENT` for native zero-lag execution, or choose a higher timeframe (e.g., `PERIOD_H1`, `PERIOD_H4`) to activate the synchronized MTF engine.
|
||||
|
||||
### Adaptive Baseline Settings
|
||||
|
||||
* `InpAdaptiveMethod` (*default: `METHOD_EFFICIENCY_RATIO`*): The underlying market kinematics engine:
|
||||
* `METHOD_EFFICIENCY_RATIO`: Kaufman's ER (Optimal for trend efficiency and whipsaw filtering).
|
||||
* `METHOD_ATR`: Average True Range volatility (Optimal for breakout expansion tracking).
|
||||
* `METHOD_STAND_DEV`: Standard Deviation dispersion (Optimal for statistical cycle tracking).
|
||||
* `InpAdaptivePeriod` (*default: `10`*): Lookback period for calculating the adaptive metric.
|
||||
* `InpGammaMin` (*default: `0.1`*): Minimum gamma boundary applied during peak efficiency/volatility (fastest tracking, near-zero lag).
|
||||
* `InpGammaMax` (*default: `0.9`*): Maximum gamma boundary applied during low efficiency/noise (maximum smoothing, horizontal brick wall).
|
||||
* `InpSourcePrice` (*default: `PRICE_CLOSE_STD`*): Applied price series source (Supports all 7 Standard and 7 Heikin Ashi modes).
|
||||
|
||||
### Visual Settings
|
||||
|
||||
* `InpColorFilter` (*default: `clrMidnightBlue`*): Color of the adaptive indicator line plot.
|
||||
* `InpStyleFilter` (*default: `STYLE_SOLID`*): Plot line style (Solid, Dash, Dot).
|
||||
* `InpWidthFilter` (*default: `1`*): Visual line width.
|
||||
|
||||
---
|
||||
|
||||
## 5. Quantitative Trading Playbooks
|
||||
|
||||
```text
|
||||
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ ADAPTIVE LAGUERRE TRADING PLAYBOOKS │
|
||||
├────────────────────────────────────────────────────────────────────────┤
|
||||
│ 1. Efficiency Breakout Drive: Enter momentum expansion when price │
|
||||
│ breaks away and curve snaps to price. │
|
||||
│ 2. Horizontal Consolidation: Pause all trend systems when curve │
|
||||
│ freezes horizontally (γ → γ_max). │
|
||||
│ 3. Low-Lag Dynamic S/R Bounce: Buy pullbacks to rising adaptive curve │
|
||||
│ during confirmed markup regimes. │
|
||||
└────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
```
|
||||
|
||||
### 5.1. Efficiency Breakout Acceleration (The ER Drive)
|
||||
|
||||
* **Premise:** During quiet market consolidation, $\text{ER} \to 0.0$ forces $\gamma \to \gamma_{\text{max}} = 0.90$. The Adaptive Laguerre freezes into a perfectly flat horizontal baseline. When an institutional breakout occurs, $\text{ER}$ spikes toward $1.0$, rapidly forcing $\gamma \to 0.10$.
|
||||
* **Execution Rules:**
|
||||
* **Bullish Breakout:** Price consolidates around a flat Adaptive Laguerre line, then prints a strong expansion candle closing clearly above the line. The curve instantly bends upward $\rightarrow$ **Enter Long**.
|
||||
* **Bearish Breakdown:** Price breaks down from a flat line with an expanding bearish candle, bending the curve downward $\rightarrow$ **Enter Short**.
|
||||
|
||||
### 5.2. Horizontal Consolidation Whipsaw Elimination
|
||||
|
||||
* **Premise:** Standard moving averages oscillate up and down during range-bound chop, triggering catastrophic false breakout losses.
|
||||
* **Filter Rule:**
|
||||
* If the absolute slope of Adaptive Laguerre over the last 3 bars is less than $0.5 \cdot \text{Point}$: **Disable all breakout algorithms**. The market is in random-walk equilibrium; wait for dynamic gamma compression before re-engaging.
|
||||
|
||||
### 5.3. Multi-Timeframe Alignment (H1 MTF Adaptive Laguerre on M5 Execution)
|
||||
|
||||
* Load `Laguerre_Adaptive_Filter_Pro` with `InpTimeframe = PERIOD_H1` and `InpAdaptiveMethod = METHOD_EFFICIENCY_RATIO` onto an **M5 execution chart**.
|
||||
* The non-warping flat staircase steps represent the hourly adaptive institutional trend:
|
||||
* When M5 price is above the H1 step and the step is rising: Execute **Long pullbacks only**.
|
||||
* When M5 price is below the H1 step and the step is falling: Execute **Short breakdowns only**.
|
||||
|
||||
---
|
||||
|
||||
## 6. Indicator Buffer Map (For Developers & EA Integration)
|
||||
|
||||
### Buffer Allocation
|
||||
|
||||
| Buffer Index | Name | Type | Visual Plot | Description |
|
||||
| :---: | :---: | :---: | :--- | :--- |
|
||||
| **0** | `BufferFilter` | `INDICATOR_DATA` | Plot 1 (`DRAW_LINE`) | Dynamic Adaptive Laguerre Filter curve. |
|
||||
|
||||
*The buffer strictly maintains non-series chronological order (`ArraySetAsSeries = false`), ensuring direct compatibility with automated Expert Advisors via `iCustom()`.*
|
||||
|
||||
---
|
||||
|
||||
### MQL5 EA Integration Interface Template
|
||||
|
||||
```mql5
|
||||
//+------------------------------------------------------------------+
|
||||
//| EA_Laguerre_Adaptive_Interface.mq5|
|
||||
//| Copyright 2026, xxxxxxxx|
|
||||
//+------------------------------------------------------------------+
|
||||
#property copyright "Copyright 2026, xxxxxxxx"
|
||||
#property version "1.00"
|
||||
#property strict
|
||||
|
||||
//--- Include Calculator Definitions
|
||||
#include <MyIncludes\Laguerre_Adaptive_Filter_Calculator.mqh>
|
||||
|
||||
//--- EA Inputs
|
||||
input group "=== Adaptive Laguerre Parameters ==="
|
||||
input ENUM_TIMEFRAMES InpLaguerreTF = PERIOD_CURRENT; // Timeframe
|
||||
input ENUM_ADAPTIVE_METHOD InpAdaptiveMethod = METHOD_EFFICIENCY_RATIO;// Adaptive Method
|
||||
input int InpAdaptivePeriod = 10; // Period
|
||||
input double InpGammaMin = 0.10; // Min Gamma
|
||||
input double InpGammaMax = 0.90; // Max Gamma
|
||||
input ENUM_APPLIED_PRICE_HA_ALL InpPriceSource = PRICE_CLOSE_STD; // Price Source
|
||||
|
||||
//--- Global Indicator Handle
|
||||
int g_laguerre_handle = INVALID_HANDLE;
|
||||
|
||||
//+------------------------------------------------------------------+
|
||||
//| Expert initialization function |
|
||||
//+------------------------------------------------------------------+
|
||||
int OnInit()
|
||||
{
|
||||
if(g_laguerre_handle != INVALID_HANDLE)
|
||||
IndicatorRelease(g_laguerre_handle);
|
||||
|
||||
// Instantiate handle to Laguerre_Adaptive_Filter_Pro via iCustom
|
||||
g_laguerre_handle = iCustom(_Symbol,
|
||||
InpLaguerreTF,
|
||||
"Laguerre_Adaptive_Filter_Pro",
|
||||
InpLaguerreTF,
|
||||
InpAdaptiveMethod,
|
||||
InpAdaptivePeriod,
|
||||
InpGammaMin,
|
||||
InpGammaMax,
|
||||
InpPriceSource);
|
||||
|
||||
if(g_laguerre_handle == INVALID_HANDLE)
|
||||
{
|
||||
PrintFormat("EA Error: Failed to create handle for Laguerre_Adaptive_Filter_Pro. Error: %d", GetLastError());
|
||||
return INIT_FAILED;
|
||||
}
|
||||
|
||||
Print("EA Success: Laguerre_Adaptive_Filter_Pro handle initialized successfully.");
|
||||
return INIT_SUCCEEDED;
|
||||
}
|
||||
|
||||
//+------------------------------------------------------------------+
|
||||
//| Expert deinitialization function |
|
||||
//+------------------------------------------------------------------+
|
||||
void OnDeinit(const int reason)
|
||||
{
|
||||
if(g_laguerre_handle != INVALID_HANDLE)
|
||||
{
|
||||
IndicatorRelease(g_laguerre_handle);
|
||||
g_laguerre_handle = INVALID_HANDLE;
|
||||
}
|
||||
}
|
||||
|
||||
//+------------------------------------------------------------------+
|
||||
//| Expert tick function |
|
||||
//+------------------------------------------------------------------+
|
||||
void OnTick()
|
||||
{
|
||||
// Query completed closed candle (Shift = 1) and previous candle (Shift = 2) for slope evaluation
|
||||
double filter_vals[2];
|
||||
ArraySetAsSeries(filter_vals, true); // Index 0 = Shift 1, Index 1 = Shift 2
|
||||
|
||||
if(CopyBuffer(g_laguerre_handle, 0, 1, 2, filter_vals) < 2)
|
||||
return; // Data synchronizing
|
||||
|
||||
double filter_bar1 = filter_vals[0];
|
||||
double filter_bar2 = filter_vals[1];
|
||||
|
||||
// Query corresponding closed price
|
||||
double close_prices[1];
|
||||
ArraySetAsSeries(close_prices, true);
|
||||
if(CopyClose(_Symbol, _Period, 1, 1, close_prices) < 1)
|
||||
return;
|
||||
|
||||
double close_bar1 = close_prices[0];
|
||||
|
||||
// Quantitative Slope & Regime Analysis
|
||||
double slope_points = (filter_bar1 - filter_bar2) / _Point;
|
||||
bool is_rising = (slope_points > 1.0);
|
||||
bool is_falling = (slope_points < -1.0);
|
||||
bool is_flat = (MathAbs(slope_points) <= 1.0);
|
||||
bool is_above_curve = (close_bar1 > filter_bar1);
|
||||
|
||||
// Telemetry Output
|
||||
Comment(StringFormat("Adaptive Laguerre Telemetry [Bar 1]:\n"
|
||||
"Filter: %.*f | Close: %.*f\n"
|
||||
"Slope: %.1f pts | Regime: %s | Position: %s",
|
||||
_Digits, filter_bar1,
|
||||
_Digits, close_bar1,
|
||||
slope_points,
|
||||
is_flat ? "FLAT (Consolidation Filter Active)" : (is_rising ? "RISING (Bullish Momentum)" : "FALLING (Bearish Momentum)"),
|
||||
is_above_curve ? "ABOVE FILTER (Bullish Bias)" : "BELOW FILTER (Bearish Bias)"));
|
||||
}
|
||||
//+------------------------------------------------------------------+
|
||||
```
|
||||
Reference in New Issue
Block a user