Orrery Cycle Toolkit

Biblioteca MQL5 que mede o ciclo dominante do mercado em qualquer símbolo e timeframe: período em barras, fase, um par seno / seno antecipado cujos cruzamentos marcam as viradas do ciclo, modo ciclo ou tendência, amplitude, linha de tendência, espectro, comprimentos adaptativos para indicadores e uma projeção do ciclo atual. Apenas lê o histórico de preços: nunca opera, não desenha e não grava arquivos. Você recebe o arquivo compilado Orrery_Cycle_Toolkit.ex5; esta página é a referência completa da API.

Início rápido

1. Copie Orrery_Cycle_Toolkit.ex5 para MQL5/Libraries (Arquivo > Abrir pasta de dados).
2. Cole o bloco #import abaixo no seu EA, indicador ou script.
3. OnInit: h = OCT_Create(_Symbol, PERIOD_CURRENT, OCT_HOMODYNE, 8, 48, 2000).
4. OnTick ou OnTimer: se OCT_Update(h) retornar true, leia OCT_Value(h, campo, 1). Decida no shift 1, a última barra fechada.
5. OnDeinit: OCT_Release(h).
6. Verificação: execute o exemplo abaixo em EURUSD H1 no Testador de estratégia; após o aquecimento (3 x max_period barras) o log mostra as leituras a cada barra.

Declaração de importação (pronta para copiar)

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

Como funciona

• Filtro roofing: um passa-alta de 2 polos em max_period e um super smoother em min_period mantêm apenas os ciclos entre os dois comprimentos (campo FILTER).
• Período, por método: 0 Homodyne discriminator (transformada de Hilbert, o mais rápido), 1 Autocorrelation periodogram (o mais estável), 2 DFT spectrum. Os métodos 1 e 2 usam o centro de gravidade, em frequência, das faixas com pelo menos metade da potência. Depois período = s x bruto + (1 - s) x anterior (s = suavização, 0.33).
• Fase: o filtro correlacionado com um ciclo de seno e cosseno, corrigida pela resposta de fase exata do filtro no período medido. 0-360 graus: 90 = topo do ciclo, 270 = fundo. SINE = sin(fase), LEADSINE = sin(fase + 45).
• Virada: LEADSINE cruza acima de SINE (+1, fundo do ciclo próximo) ou abaixo (-1, topo próximo).
• Modo: ciclo (0) se houve uma virada no último meio ciclo ou se a fase avançou 0.67-1.5 x 360/período na barra; caso contrário tendência: +1 alta ou -1 baixa conforme o preço frente a TRENDLINE. Sempre tendência quando o preço está a pelo menos banda de tendência x AMPLITUDE de TRENDLINE.
• Aquecimento: as primeiras 3 x max_period barras retornam EMPTY_VALUE.

Campos

0 PERIOD: ciclo dominante suavizado em barras (de min_period a max_period). 1 RAW_PERIOD: medição sem suavização. 2 PHASE: graus, 0-360. 3 SINE e 4 LEADSINE: de -1 a +1. 5 FILTER: filtro roofing, em unidades de preço. 6 TRENDLINE: preço médio de um ciclo, suavizado 4-3-2-1. 7 AMPLITUDE: RMS do filtro em um ciclo x 1.414, em unidades de preço. 8 STRENGTH: AMPLITUDE / amplitude média da barra em um ciclo. 9 MODE: 0 ciclo, 1 tendência de alta, -1 tendência de baixa. 10 PHASE_STEP: avanço de fase na barra, de -180 a 180 graus (360/período em um ciclo limpo).

Referência da API

Shift 0 = barra em formação (muda até fechar), 1 = última barra fechada; barras fechadas nunca mudam. Cada chamada atualiza OCT_LastError.

OCT_Create

Abre um rastreador. symbol: "" ou NULL = símbolo do gráfico. timeframe: PERIOD_CURRENT é aceito. method: 0-2. min_period: 4-50 (0 = 8). max_period: de min_period + 4 a 120 (0 = 48). lookback: barras mantidas, 0 = 2000, elevado a 4 x max_period (no mínimo 200), no máximo 50000. Retorna um handle 0-31, ou -1 com -1 (parâmetro inválido, símbolo desconhecido) ou -2 (32 handles em uso). Ainda não carrega dados.

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

OCT_SetParam

param 0 preço: 0 fechamento, 1 mediano, 2 típico, 3 ponderado (padrão 0). 1 banda de tendência, x AMPLITUDE: 0.1-10 (1.5). 2 suavização: 0.05-1 (0.33; 1 = nenhuma). 3 comprimento de média da autocorrelação: 0-50 (3; 0 = comprimento do atraso). Outros valores: false e -1. Um valor alterado reconstrói o rastreador no próximo OCT_Update; até lá OCT_Bars retorna 0.

OCT_Update

Carrega o histórico na primeira chamada; depois acrescenta as barras novas e recalcula a barra em formação. Chame a cada tick ou timer. true quando há valores; false com -3 (handle inválido), -4 NO DATA (histórico ainda carregando: chame de novo) ou -5 NOT ENOUGH BARS (menos de 3 x max_period + 1 barras). Lacunas ou histórico editado provocam uma reconstrução. Acima de lookback + 500 barras as mais antigas são descartadas; nenhum valor muda.

OCT_Release

Libera um handle; -1 libera todos. Chame em OnDeinit.

OCT_Bars

Barras com valores (shift 0 até OCT_Bars - 1); 0 antes da primeira atualização bem-sucedida; -1 para um handle inválido.

OCT_Value

Valor do campo no shift. EMPTY_VALUE com -1 (campo fora de 0-10), -3 ou -6 (shift negativo, shift além de OCT_Bars - 1, ainda sem atualização).

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

OCT_TurnSignal

+1 se LEADSINE cruzou acima de SINE naquela barra, -1 abaixo, 0 nenhum ou shift inválido. As viradas servem ao modo ciclo: verifique MODE. No shift 0 uma virada pode surgir e sumir dentro da barra.

OCT_Spectrum

Preenche power[] com max_period - min_period + 1 valores (power[0] = min_period barras), em escala 0-1. Métodos 0 e 2: DFT do filtro sobre max_period barras, faixa mais forte = 1. Método 1: o periodograma de autocorrelação suavizado em relação ao seu máximo, que decai lentamente. Retorna a quantidade ou -1.

OCT_Project

Prolonga o ciclo atual a partir do shift 0 por bars (1-500): path[k] = TRENDLINE + inclinação x (k + 1) + AMPLITUDE x sin(PHASE + 360 x (k + 1) / PERIOD), com inclinação = variação de TRENDLINE por barra no último quarto de ciclo; path[0] = próxima barra. Retorna bars, ou -1 com -1 (bars fora do intervalo) ou -5 (não pronto). Uma continuação geométrica, não uma previsão.

OCT_AdaptiveLength

round(PERIOD x fraction) limitado a min_len..max_len; fraction acima de 0 e até 10, 1 <= min_len <= max_len. -1 em caso de erro. RSI de meio ciclo:

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

Funções de arrays

Sem handle; nada é mantido entre chamadas. src[] pode ser cronológico ou indexado como série; dst[i] pertence a src[i] e dst mantém sua própria indexação. Um dst dinâmico é redimensionado; um buffer de indicador precisa do tamanho de src. Retornam a quantidade de valores, ou -1 com -1 (parâmetro inválido, dst pequeno demais) ou -5 (vazio ou curto demais). Ajustes fixos: suavização 0.33, média 3, banda de tendência 1.5; STRENGTH usa a variação absoluta média de src.

• OCT_SuperSmoother: super smoother de 2 polos, período 2-1000; os 2 primeiros valores copiam src.
• OCT_HighPass: passa-alta de 2 polos, período 2-1000; os 2 primeiros valores são 0.
• OCT_Roofing: passa-alta em max_period e depois super smoother em min_period (igual a FILTER).
• OCT_CycleSeries: o motor completo sobre src; dst = campo 0-10 por barra, EMPTY_VALUE no aquecimento. Precisa de 3 x max_period + 1 valores.
• OCT_DFTSpectrum: potência em src[index] (indexação própria de src), na escala de OCT_Spectrum; precisa de max_period - 1 valores anteriores. Retorna max_period - min_period + 1, ou -1 com -6 (índice fora do intervalo) 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 e OCT_ErrorText

Código da última chamada e seu texto em maiúsculas: 0 OK, -1 INVALID PARAMETER, -2 NO FREE HANDLE, -3 INVALID HANDLE, -4 NO DATA, -5 NOT ENOUGH BARS, -6 SHIFT OUT OF RANGE, caso contrário UNKNOWN.

Exemplo de integração funcional

Um Expert Advisor: cole antes o bloco de importação e as três linhas enum acima.

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

Arquitetura e notas

• Cada handle guarda seu próprio histórico e resultados; cada programa que importa a biblioteca tem seus próprios 32 handles.
• Um tick recalcula apenas a barra em formação (bem abaixo de 1 ms nos testes); a primeira atualização de 2,000 barras leva de poucos a cerca de 100 ms, conforme o método e max_period.
• MetaTrader 5, qualquer símbolo e timeframe; EAs, indicadores, scripts. Seguro no Testador de estratégia, na otimização e na MQL5 Cloud Network: sem DLLs, arquivos, requisições web, objetos gráficos, timers ou variáveis globais. OCT_Create adiciona o símbolo à Observação do mercado para carregar seu histórico.
• Limites: 32 handles por programa, períodos de 4-120 barras, projeção de até 500 barras, lookback de até 50000 barras.
• Configurações típicas. Comprimentos adaptativos: método 0, períodos 8-48, comprimento do RSI OCT_AdaptiveLength(h, 0.5, 2, 100, 1). Oscilações do ciclo: método 1, períodos 10-40, aja sobre OCT_TurnSignal(h, 1) apenas quando MODE no shift 1 for 0. Filtro de tendência: MODE diferente de 0 = tendência; banda de tendência 2.5 para menos barras de tendência. Indicadores: OCT_CycleSeries em OnCalculate.
• As capturas de tela e o vídeo mostram um EA de demonstração construído com esta biblioteca; ele não faz parte da compra.

Aviso de risco

As leituras de ciclo descrevem preços passados. Os mercados mudam de regime, uma projeção não é uma previsão e nenhuma leitura garante lucro. Teste primeiro em uma conta demo.