Orrery Cycle Toolkit

Libreria MQL5 che misura il ciclo dominante del mercato su qualsiasi simbolo e timeframe: periodo in barre, fase, una coppia seno / seno anticipato i cui incroci segnano le svolte del ciclo, modalità ciclo o trend, ampiezza, linea di tendenza, spettro, lunghezze adattive per indicatori e una proiezione del ciclo in corso. Legge solo lo storico dei prezzi: non opera mai, non disegna e non scrive file. Ricevete il file compilato Orrery_Cycle_Toolkit.ex5; questa pagina è il riferimento completo dell'API.

Avvio rapido

1. Copiate Orrery_Cycle_Toolkit.ex5 in MQL5/Libraries (File > Apri cartella dati).
2. Incollate il blocco #import qui sotto nel vostro EA, indicatore o script.
3. OnInit: h = OCT_Create(_Symbol, PERIOD_CURRENT, OCT_HOMODYNE, 8, 48, 2000).
4. OnTick o OnTimer: se OCT_Update(h) restituisce true, leggete OCT_Value(h, campo, 1). Decidete sullo shift 1, l'ultima barra chiusa.
5. OnDeinit: OCT_Release(h).
6. Verifica: eseguite l'esempio qui sotto su EURUSD H1 nel Tester strategie; dopo il riscaldamento (3 x max_period barre) il log mostra le letture a ogni barra.

Dichiarazione di import (pronta da copiare)

#import "Orrery_Cycle_Toolkit.ex5"
   int    OCT_Create(string symbol, ENUM_TIMEFRAMES timeframe, int method, int min_period, int max_period, int lookback);
   bool   OCT_SetParam(int handle, int param, double value);
   bool   OCT_Update(int handle);
   void   OCT_Release(int handle);
   int    OCT_Bars(int handle);
   double OCT_Value(int handle, int field, int shift);
   int    OCT_TurnSignal(int handle, int shift);
   int    OCT_Spectrum(int handle, int shift, double &power[]);
   int    OCT_Project(int handle, int bars, double &path[]);
   int    OCT_AdaptiveLength(int handle, double fraction, int min_len, int max_len, int shift);
   int    OCT_SuperSmoother(const double &src[], double &dst[], double period);
   int    OCT_HighPass(const double &src[], double &dst[], double period);
   int    OCT_Roofing(const double &src[], double &dst[], int min_period, int max_period);
   int    OCT_CycleSeries(const double &src[], int method, int min_period, int max_period, int field, double &dst[]);
   int    OCT_DFTSpectrum(const double &src[], int index, int min_period, int max_period, double &power[]);
   int    OCT_LastError();
   string OCT_ErrorText(int code);
#import
enum OCT_METHOD { OCT_HOMODYNE, OCT_AUTOCORR, OCT_DFT };
enum OCT_FIELD  { OCT_PERIOD, OCT_RAW_PERIOD, OCT_PHASE, OCT_SINE, OCT_LEADSINE, OCT_FILTER, OCT_TRENDLINE,
                  OCT_AMPLITUDE, OCT_STRENGTH, OCT_MODE, OCT_PHASE_STEP };
enum OCT_PARAM  { OCT_PARAM_PRICE, OCT_PARAM_TREND_BAND, OCT_PARAM_SMOOTHING, OCT_PARAM_AVGLEN }; 

Come funziona

• Filtro roofing: un passa-alto a 2 poli su max_period e un super smoother su min_period conservano solo i cicli tra le due lunghezze (campo FILTER).
• Periodo, per metodo: 0 Homodyne discriminator (trasformata di Hilbert, il più veloce), 1 Autocorrelation periodogram (il più stabile), 2 DFT spectrum. I metodi 1 e 2 usano il baricentro, in frequenza, delle bande con almeno metà della potenza. Poi periodo = s x grezzo + (1 - s) x precedente (s = smussamento, 0.33).
• Fase: il filtro correlato con un ciclo di seno e coseno, corretta per la risposta di fase esatta del filtro al periodo misurato. 0-360 gradi: 90 = picco del ciclo, 270 = minimo. SINE = sin(fase), LEADSINE = sin(fase + 45).
• Svolta: LEADSINE incrocia SINE verso l'alto (+1, minimo del ciclo vicino) o verso il basso (-1, massimo vicino).
• Modalità: ciclo (0) se c'è stata una svolta nell'ultimo mezzo ciclo o se la fase è avanzata di 0.67-1.5 x 360/periodo sulla barra; altrimenti trend: +1 rialzista o -1 ribassista secondo il prezzo rispetto a TRENDLINE. Sempre trend quando il prezzo dista almeno banda di trend x AMPLITUDE da TRENDLINE.
• Riscaldamento: le prime 3 x max_period barre restituiscono EMPTY_VALUE.

Campi

0 PERIOD: ciclo dominante smussato in barre (da min_period a max_period). 1 RAW_PERIOD: misura non smussata. 2 PHASE: gradi, 0-360. 3 SINE e 4 LEADSINE: da -1 a +1. 5 FILTER: filtro roofing, in unità di prezzo. 6 TRENDLINE: prezzo medio su un ciclo, smussato 4-3-2-1. 7 AMPLITUDE: RMS del filtro su un ciclo x 1.414, in unità di prezzo. 8 STRENGTH: AMPLITUDE / escursione media delle barre su un ciclo. 9 MODE: 0 ciclo, 1 trend rialzista, -1 trend ribassista. 10 PHASE_STEP: avanzamento di fase sulla barra, da -180 a 180 gradi (360/periodo in un ciclo pulito).

Riferimento API

Shift 0 = barra in formazione (cambia fino alla chiusura), 1 = ultima barra chiusa; le barre chiuse non cambiano mai. Ogni chiamata aggiorna OCT_LastError.

OCT_Create

Apre un tracker. symbol: "" o NULL = simbolo del grafico. timeframe: PERIOD_CURRENT ammesso. method: 0-2. min_period: 4-50 (0 = 8). max_period: da min_period + 4 a 120 (0 = 48). lookback: barre conservate, 0 = 2000, alzato a 4 x max_period (almeno 200), al massimo 50000. Restituisce un handle 0-31, oppure -1 con -1 (parametro errato, simbolo sconosciuto) o -2 (32 handle in uso). Non carica ancora dati.

int h = OCT_Create("XAUUSD", PERIOD_M15, OCT_AUTOCORR, 10, 40, 3000); 

OCT_SetParam

param 0 prezzo: 0 chiusura, 1 mediano, 2 tipico, 3 ponderato (predefinito 0). 1 banda di trend, x AMPLITUDE: 0.1-10 (1.5). 2 smussamento: 0.05-1 (0.33; 1 = nessuno). 3 lunghezza di media dell'autocorrelazione: 0-50 (3; 0 = lunghezza del ritardo). Altri valori: false e -1. Un valore cambiato ricostruisce il tracker al prossimo OCT_Update; fino ad allora OCT_Bars restituisce 0.

OCT_Update

Carica lo storico alla prima chiamata, poi aggiunge le nuove barre e ricalcola la barra in formazione; chiamatela a ogni tick o timer. true se ci sono valori; false con -3 (handle errato), -4 NO DATA (storico ancora in caricamento: richiamate) o -5 NOT ENOUGH BARS (meno di 3 x max_period + 1 barre). Buchi o storico modificato provocano una ricostruzione. Oltre lookback + 500 barre le più vecchie vengono scartate; nessun valore cambia.

OCT_Release

Libera un handle; -1 li libera tutti. Chiamatela in OnDeinit.

OCT_Bars

Barre con valori (shift da 0 a OCT_Bars - 1); 0 prima del primo aggiornamento riuscito; -1 per un handle errato.

OCT_Value

Valore del campo allo shift. EMPTY_VALUE con -1 (campo fuori da 0-10), -3 o -6 (shift negativo, shift oltre OCT_Bars - 1, nessun aggiornamento).

if(OCT_Value(h, OCT_MODE, 1) == 0 && OCT_TurnSignal(h, 1) == 1) Print("cycle low turn"); 

OCT_TurnSignal

+1 se LEADSINE ha incrociato SINE verso l'alto su quella barra, -1 verso il basso, 0 nessuno o shift non valido. Le svolte servono alla modalità ciclo: controllate MODE. Allo shift 0 una svolta può comparire e sparire durante la barra.

OCT_Spectrum

Riempie power[] con max_period - min_period + 1 valori (power[0] = min_period barre), in scala 0-1. Metodi 0 e 2: DFT del filtro su max_period barre, banda più forte = 1. Metodo 1: il periodogramma di autocorrelazione smussato rispetto al suo massimo a lento decadimento. Restituisce il numero di valori o -1.

OCT_Project

Prolunga il ciclo corrente dallo shift 0 per bars (1-500): path[k] = TRENDLINE + pendenza x (k + 1) + AMPLITUDE x sin(PHASE + 360 x (k + 1) / PERIOD), con pendenza = variazione di TRENDLINE per barra nell'ultimo quarto di ciclo; path[0] = barra successiva. Restituisce bars, oppure -1 con -1 (bars fuori intervallo) o -5 (non pronto). Una continuazione geometrica, non una previsione.

OCT_AdaptiveLength

round(PERIOD x fraction) limitato a min_len..max_len; fraction maggiore di 0 e fino a 10, 1 <= min_len <= max_len. -1 in caso di errore. RSI su mezzo ciclo:

int len = OCT_AdaptiveLength(h, 0.5, 2, 100, 1); 

Funzioni su array

Nessun handle; nulla viene conservato tra le chiamate. src[] può essere cronologico o indicizzato come serie; dst[i] corrisponde a src[i] e dst mantiene la propria indicizzazione. Un dst dinamico viene ridimensionato; un buffer di indicatore deve avere la dimensione di src. Restituiscono il numero di valori, oppure -1 con -1 (parametro errato, dst troppo piccolo) o -5 (vuoto o troppo corto). Impostazioni fisse: smussamento 0.33, media 3, banda di trend 1.5; STRENGTH usa la variazione assoluta media di src.

• OCT_SuperSmoother: super smoother a 2 poli, periodo 2-1000; i primi 2 valori copiano src.
• OCT_HighPass: passa-alto a 2 poli, periodo 2-1000; i primi 2 valori sono 0.
• OCT_Roofing: passa-alto su max_period, poi super smoother su min_period (uguale a FILTER).
• OCT_CycleSeries: l'intero motore su src; dst = campo 0-10 per barra, EMPTY_VALUE nel riscaldamento. Richiede 3 x max_period + 1 valori.
• OCT_DFTSpectrum: potenza in src[index] (indicizzazione propria di src), in scala come OCT_Spectrum; richiede max_period - 1 valori precedenti. Restituisce max_period - min_period + 1, oppure -1 con -6 (indice fuori intervallo) o -5.

double c[], per[];
ArraySetAsSeries(c, true);
CopyClose(_Symbol, _Period, 0, 500, c);
OCT_CycleSeries(c, OCT_HOMODYNE, 8, 48, OCT_PERIOD, per);   // per[0] = forming bar 

OCT_LastError e OCT_ErrorText

Codice dell'ultima chiamata e il suo testo in maiuscolo: 0 OK, -1 INVALID PARAMETER, -2 NO FREE HANDLE, -3 INVALID HANDLE, -4 NO DATA, -5 NOT ENOUGH BARS, -6 SHIFT OUT OF RANGE, altrimenti UNKNOWN.

Esempio di integrazione funzionante

Un Expert Advisor: incollate prima il blocco di import e le tre righe enum qui sopra.

int      h    = -1;
datetime last = 0;

int OnInit()
{
   h = OCT_Create(_Symbol, PERIOD_CURRENT, OCT_HOMODYNE, 8, 48, 2000);
   return(h < 0 ? INIT_FAILED : INIT_SUCCEEDED);
}

void OnDeinit(const int reason) { OCT_Release(h); }

void OnTick()
{
   datetime bar = iTime(_Symbol, _Period, 0);
   if(bar == last)
      return;
   if(!OCT_Update(h)) { Print("orrery: ", OCT_ErrorText(OCT_LastError())); return; }
   last = bar;
   PrintFormat("period %.1f phase %.0f mode %.0f turn %d rsi length %d", OCT_Value(h, OCT_PERIOD, 1),
               OCT_Value(h, OCT_PHASE, 1), OCT_Value(h, OCT_MODE, 1), OCT_TurnSignal(h, 1), OCT_AdaptiveLength(h, 0.5, 2, 100, 1));
} 

Architettura e note

• Ogni handle conserva il proprio storico e i propri risultati; ogni programma che importa la libreria ha i propri 32 handle.
• Un tick ricalcola solo la barra in formazione (ben sotto 1 ms nei test); il primo aggiornamento di 2,000 barre richiede da pochi ms a circa 100 ms, secondo il metodo e max_period.
• MetaTrader 5, qualsiasi simbolo e timeframe; EA, indicatori, script. Sicura nel Tester strategie, nell'ottimizzazione e in MQL5 Cloud Network: niente DLL, file, richieste web, oggetti grafici, timer o variabili globali. OCT_Create aggiunge il simbolo al Market Watch per caricarne lo storico.
• Limiti: 32 handle per programma, periodi di 4-120 barre, proiezione fino a 500 barre, lookback fino a 50000 barre.
• Configurazioni tipiche. Lunghezze adattive: metodo 0, periodi 8-48, lunghezza RSI OCT_AdaptiveLength(h, 0.5, 2, 100, 1). Oscillazioni del ciclo: metodo 1, periodi 10-40, agite su OCT_TurnSignal(h, 1) solo quando MODE allo shift 1 vale 0. Filtro di trend: MODE diverso da 0 = trend; banda di trend 2.5 per meno barre di trend. Indicatori: OCT_CycleSeries in OnCalculate.
• Gli screenshot e il video mostrano un EA dimostrativo costruito con questa libreria; non fa parte dell'acquisto.

Avviso sui rischi

Le letture del ciclo descrivono prezzi passati. I mercati cambiano regime, una proiezione non è una previsione e nessuna lettura garantisce profitti. Provate prima su un conto demo.