Orrery Cycle Toolkit

Bibliothèque MQL5 qui mesure le cycle dominant du marché sur tout symbole et toute unité de temps : période en barres, phase, une paire sinus / sinus avancé dont les croisements marquent les retournements du cycle, mode cycle ou tendance, amplitude, ligne de tendance, spectre, longueurs adaptatives pour indicateurs et une projection du cycle en cours. Elle lit seulement l'historique des prix : elle ne trade jamais, ne dessine rien et n'écrit aucun fichier. Vous recevez le fichier compilé Orrery_Cycle_Toolkit.ex5 ; cette page est la référence complète de l'API.

Démarrage rapide

1. Copiez Orrery_Cycle_Toolkit.ex5 dans MQL5/Libraries (Fichier > Ouvrir le dossier des données).
2. Collez le bloc #import ci-dessous dans votre EA, indicateur ou script.
3. OnInit : h = OCT_Create(_Symbol, PERIOD_CURRENT, OCT_HOMODYNE, 8, 48, 2000).
4. OnTick ou OnTimer : si OCT_Update(h) renvoie true, lisez OCT_Value(h, champ, 1). Décidez sur le shift 1, la dernière barre clôturée.
5. OnDeinit : OCT_Release(h).
6. Vérification : lancez l'exemple ci-dessous sur EURUSD H1 dans le Testeur de stratégie ; après le préchauffage (3 x max_period barres) le journal affiche les mesures à chaque barre.

Déclaration d'import (prête à copier)

#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 }; 

Fonctionnement

• Filtre roofing : un passe-haut à 2 pôles sur max_period et un super smoother sur min_period ne gardent que les cycles entre ces deux longueurs (champ FILTER).
• Période, selon la méthode : 0 Homodyne discriminator (transformée de Hilbert, la plus rapide), 1 Autocorrelation periodogram (la plus stable), 2 DFT spectrum. Les méthodes 1 et 2 prennent le centre de gravité, en fréquence, des bandes à au moins la moitié de la puissance. Puis période = s x brute + (1 - s) x précédente (s = lissage, 0.33).
• Phase : le filtre corrélé avec un cycle de sinus et cosinus, corrigée de la réponse de phase exacte du filtre à la période mesurée. 0-360 degrés : 90 = sommet du cycle, 270 = creux. SINE = sin(phase), LEADSINE = sin(phase + 45).
• Retournement : LEADSINE croise SINE à la hausse (+1, creux du cycle proche) ou à la baisse (-1, sommet proche).
• Mode : cycle (0) si un retournement a eu lieu dans le dernier demi-cycle ou si la phase a avancé de 0.67-1.5 x 360/période sur la barre ; sinon tendance : +1 haussière ou -1 baissière selon le prix face à TRENDLINE. Toujours tendance quand le prix est à au moins bande de tendance x AMPLITUDE de TRENDLINE.
• Préchauffage : les 3 x max_period premières barres renvoient EMPTY_VALUE.

Champs

0 PERIOD : cycle dominant lissé en barres (de min_period à max_period). 1 RAW_PERIOD : mesure non lissée. 2 PHASE : degrés, 0-360. 3 SINE et 4 LEADSINE : de -1 à +1. 5 FILTER : filtre roofing, en unités de prix. 6 TRENDLINE : prix moyen sur un cycle, lissé 4-3-2-1. 7 AMPLITUDE : RMS du filtre sur un cycle x 1.414, en unités de prix. 8 STRENGTH : AMPLITUDE / étendue moyenne des barres sur un cycle. 9 MODE : 0 cycle, 1 tendance haussière, -1 tendance baissière. 10 PHASE_STEP : avance de phase sur la barre, de -180 à 180 degrés (360/période dans un cycle net).

Référence de l'API

Shift 0 = barre en formation (change jusqu'à sa clôture), 1 = dernière barre clôturée ; une barre clôturée ne change jamais. Chaque appel met à jour OCT_LastError.

OCT_Create

Ouvre un traceur. symbol : "" ou NULL = symbole du graphique. timeframe : PERIOD_CURRENT accepté. method : 0-2. min_period : 4-50 (0 = 8). max_period : de min_period + 4 à 120 (0 = 48). lookback : barres conservées, 0 = 2000, relevé à 4 x max_period (au moins 200), au plus 50000. Renvoie un handle 0-31, ou -1 avec -1 (paramètre invalide, symbole inconnu) ou -2 (32 handles utilisés). Ne charge encore aucune donnée.

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

OCT_SetParam

param 0 prix : 0 clôture, 1 médian, 2 typique, 3 pondéré (défaut 0). 1 bande de tendance, x AMPLITUDE : 0.1-10 (1.5). 2 lissage : 0.05-1 (0.33 ; 1 = aucun). 3 longueur de moyenne de l'autocorrélation : 0-50 (3 ; 0 = longueur du décalage). Autres valeurs : false et -1. Une valeur modifiée reconstruit le traceur au prochain OCT_Update ; d'ici là OCT_Bars renvoie 0.

OCT_Update

Charge l'historique au premier appel, puis ajoute les nouvelles barres et recalcule la barre en formation ; appelez-la à chaque tick ou timer. true s'il y a des valeurs ; false avec -3 (handle invalide), -4 NO DATA (historique en cours de chargement : rappelez) ou -5 NOT ENOUGH BARS (moins de 3 x max_period + 1 barres). Trous ou historique modifié déclenchent une reconstruction. Au-delà de lookback + 500 barres les plus anciennes sont supprimées ; aucune valeur ne change.

OCT_Release

Libère un handle ; -1 les libère tous. À appeler dans OnDeinit.

OCT_Bars

Barres disposant de valeurs (shift 0 à OCT_Bars - 1) ; 0 avant la première mise à jour réussie ; -1 pour un handle invalide.

OCT_Value

Valeur du champ au shift. EMPTY_VALUE avec -1 (champ hors de 0-10), -3 ou -6 (shift négatif, shift au-delà de OCT_Bars - 1, pas encore de mise à jour).

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

OCT_TurnSignal

+1 si LEADSINE a croisé SINE à la hausse sur cette barre, -1 à la baisse, 0 aucun ou shift invalide. Les retournements servent au mode cycle : vérifiez MODE. Au shift 0 un retournement peut apparaître puis disparaître dans la barre.

OCT_Spectrum

Remplit power[] avec max_period - min_period + 1 valeurs (power[0] = min_period barres), échelle 0-1. Méthodes 0 et 2 : DFT du filtre sur max_period barres, bande la plus forte = 1. Méthode 1 : le périodogramme d'autocorrélation lissé rapporté à son maximum à décroissance lente. Renvoie le nombre de valeurs ou -1.

OCT_Project

Prolonge le cycle en cours depuis le shift 0 sur bars (1-500) : path[k] = TRENDLINE + pente x (k + 1) + AMPLITUDE x sin(PHASE + 360 x (k + 1) / PERIOD), avec pente = variation de TRENDLINE par barre sur le dernier quart de cycle ; path[0] = barre suivante. Renvoie bars, ou -1 avec -1 (bars hors plage) ou -5 (pas prêt). Une continuation géométrique, pas une prévision.

OCT_AdaptiveLength

round(PERIOD x fraction) borné à min_len..max_len ; fraction supérieure à 0 et jusqu'à 10, 1 <= min_len <= max_len. -1 en cas d'erreur. RSI sur un demi-cycle :

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

Fonctions sur tableaux

Sans handle ; rien n'est conservé entre les appels. src[] peut être chronologique ou indexé en série ; dst[i] correspond à src[i] et dst garde sa propre indexation. Un dst dynamique est redimensionné ; un buffer d'indicateur doit avoir la taille de src. Renvoient le nombre de valeurs, ou -1 avec -1 (paramètre invalide, dst trop petit) ou -5 (vide ou trop court). Réglages fixes : lissage 0.33, moyenne 3, bande de tendance 1.5 ; STRENGTH utilise la variation absolue moyenne de src.

• OCT_SuperSmoother : super smoother à 2 pôles, période 2-1000 ; les 2 premières valeurs copient src.
• OCT_HighPass : passe-haut à 2 pôles, période 2-1000 ; les 2 premières valeurs valent 0.
• OCT_Roofing : passe-haut sur max_period puis super smoother sur min_period (égal à FILTER).
• OCT_CycleSeries : le moteur complet sur src ; dst = champ 0-10 par barre, EMPTY_VALUE pendant le préchauffage. Requiert 3 x max_period + 1 valeurs.
• OCT_DFTSpectrum : puissance en src[index] (indexation propre de src), à l'échelle de OCT_Spectrum ; requiert max_period - 1 valeurs antérieures. Renvoie max_period - min_period + 1, ou -1 avec -6 (index hors plage) ou -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 et OCT_ErrorText

Code du dernier appel et son texte en majuscules : 0 OK, -1 INVALID PARAMETER, -2 NO FREE HANDLE, -3 INVALID HANDLE, -4 NO DATA, -5 NOT ENOUGH BARS, -6 SHIFT OUT OF RANGE, sinon UNKNOWN.

Exemple d'intégration fonctionnel

Un Expert Advisor : collez d'abord le bloc d'import et les trois lignes enum ci-dessus.

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));
} 

Architecture et remarques

• Chaque handle garde son propre historique et ses résultats ; chaque programme qui importe la bibliothèque a ses propres 32 handles.
• Un tick ne recalcule que la barre en formation (bien moins de 1 ms lors des tests) ; la première mise à jour de 2,000 barres prend de quelques ms à environ 100 ms selon la méthode et max_period.
• MetaTrader 5, tout symbole et toute unité de temps ; EA, indicateurs, scripts. Sûre dans le Testeur de stratégie, l'optimisation et MQL5 Cloud Network : pas de DLL, fichiers, requêtes web, objets graphiques, timers ni variables globales. OCT_Create ajoute le symbole à l'Observation du marché pour charger son historique.
• Limites : 32 handles par programme, périodes de 4-120 barres, projection jusqu'à 500 barres, lookback jusqu'à 50000 barres.
• Réglages types. Longueurs adaptatives : méthode 0, périodes 8-48, longueur du RSI OCT_AdaptiveLength(h, 0.5, 2, 100, 1). Oscillations du cycle : méthode 1, périodes 10-40, agissez sur OCT_TurnSignal(h, 1) seulement quand MODE au shift 1 vaut 0. Filtre de tendance : MODE différent de 0 = tendance ; bande de tendance 2.5 pour moins de barres en tendance. Indicateurs : OCT_CycleSeries dans OnCalculate.
• Les captures et la vidéo montrent un EA de démonstration construit avec cette bibliothèque ; il ne fait pas partie de l'achat.

Avertissement sur les risques

Les mesures de cycle décrivent des prix passés. Les marchés changent de régime, une projection n'est pas une prévision et aucune mesure ne garantit un profit. Testez d'abord sur un compte démo.