Orrery Cycle Toolkit

Библиотека MQL5, которая измеряет доминирующий рыночный цикл любого символа и таймфрейма: период в барах, фазу, пару синус / опережающий синус, пересечения которых отмечают развороты цикла, режим цикла или тренда, амплитуду, линию тренда, спектр, адаптивные длины индикаторов и проекцию текущего цикла. Она только читает историю цен: никогда не торгует, ничего не рисует и не пишет файлы. Вы получаете скомпилированный Orrery_Cycle_Toolkit.ex5; эта страница - полный справочник API.

Быстрый старт

1. Скопируйте Orrery_Cycle_Toolkit.ex5 в MQL5/Libraries (Файл > Открыть каталог данных).
2. Вставьте блок #import ниже в ваш советник, индикатор или скрипт.
3. OnInit: h = OCT_Create(_Symbol, PERIOD_CURRENT, OCT_HOMODYNE, 8, 48, 2000).
4. OnTick или OnTimer: если OCT_Update(h) вернула true, читайте OCT_Value(h, поле, 1). Решения принимайте по shift 1, последнему закрытому бару.
5. OnDeinit: OCT_Release(h).
6. Проверка: запустите пример ниже на EURUSD H1 в тестере стратегий; после прогрева (3 x max_period баров) журнал выводит значения на каждом баре.

Объявление импорта (готово к копированию)

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

Как это работает

• Фильтр roofing: 2-полюсный фильтр высоких частот на max_period и super smoother на min_period оставляют только циклы между этими длинами (поле FILTER).
• Период по методу: 0 Homodyne discriminator (преобразование Гильберта, самый быстрый), 1 Autocorrelation periodogram (самый устойчивый), 2 DFT spectrum. Методы 1 и 2 берут центр тяжести, по частоте, полос с мощностью не ниже половины. Затем период = s x сырой + (1 - s) x прежний (s = сглаживание, 0.33).
• Фаза: корреляция фильтра с одним циклом синуса и косинуса, с поправкой на точную фазовую характеристику фильтра на измеренном периоде. 0-360 градусов: 90 = вершина цикла, 270 = дно. SINE = sin(фаза), LEADSINE = sin(фаза + 45).
• Разворот: LEADSINE пересекает SINE снизу вверх (+1, близко дно цикла) или сверху вниз (-1, близка вершина).
• Режим: цикл (0), если разворот был в последнем полуцикле или фаза продвинулась на 0.67-1.5 x 360/период за бар; иначе тренд: +1 вверх или -1 вниз по положению цены относительно TRENDLINE. Всегда тренд, если цена удалена от TRENDLINE минимум на полосу тренда x AMPLITUDE.
• Прогрев: первые 3 x max_period баров возвращают EMPTY_VALUE.

Поля

0 PERIOD: сглаженный доминирующий цикл в барах (от min_period до max_period). 1 RAW_PERIOD: несглаженное измерение. 2 PHASE: градусы, 0-360. 3 SINE и 4 LEADSINE: от -1 до +1. 5 FILTER: фильтр roofing, в единицах цены. 6 TRENDLINE: средняя цена за цикл, сглаженная 4-3-2-1. 7 AMPLITUDE: RMS фильтра за цикл x 1.414, в единицах цены. 8 STRENGTH: AMPLITUDE / средний диапазон бара за цикл. 9 MODE: 0 цикл, 1 тренд вверх, -1 тренд вниз. 10 PHASE_STEP: приращение фазы за бар, от -180 до 180 градусов (360/период в чистом цикле).

Справочник API

Shift 0 = формирующийся бар (меняется до закрытия), 1 = последний закрытый бар; закрытые бары не меняются. Каждый вызов обновляет OCT_LastError.

OCT_Create

Открывает трекер. symbol: "" или NULL = символ графика. timeframe: допускается PERIOD_CURRENT. method: 0-2. min_period: 4-50 (0 = 8). max_period: от min_period + 4 до 120 (0 = 48). lookback: хранимые бары, 0 = 2000, повышается до 4 x max_period (не менее 200), не более 50000. Возвращает хэндл 0-31 или -1 с кодом -1 (неверный параметр, неизвестный символ) или -2 (заняты все 32 хэндла). Данные пока не загружает.

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

OCT_SetParam

param 0 цена: 0 close, 1 медианная, 2 типичная, 3 взвешенная (по умолчанию 0). 1 полоса тренда, x AMPLITUDE: 0.1-10 (1.5). 2 сглаживание: 0.05-1 (0.33; 1 = нет). 3 длина усреднения автокорреляции: 0-50 (3; 0 = длина лага). Другие значения: false и -1. Изменённое значение перестраивает трекер при следующем OCT_Update; до этого OCT_Bars возвращает 0.

OCT_Update

Первый вызов загружает историю, следующие добавляют новые бары и пересчитывают формирующийся бар; вызывайте на каждом тике или таймере. true, если значения есть; false с -3 (неверный хэндл), -4 NO DATA (история ещё грузится: вызовите снова) или -5 NOT ENOUGH BARS (менее 3 x max_period + 1 баров). Пропуски или изменённая история вызывают перестройку. Сверх lookback + 500 баров самые старые удаляются; значения не меняются.

OCT_Release

Освобождает хэндл; -1 освобождает все. Вызывайте в OnDeinit.

OCT_Bars

Число баров со значениями (shift от 0 до OCT_Bars - 1); 0 до первого успешного обновления; -1 для неверного хэндла.

OCT_Value

Значение поля на shift. EMPTY_VALUE с -1 (поле вне 0-10), -3 или -6 (отрицательный shift, shift больше OCT_Bars - 1, обновления ещё не было).

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

OCT_TurnSignal

+1, если на этом баре LEADSINE пересекла SINE снизу вверх, -1 сверху вниз, 0 нет разворота или неверный shift. Развороты предназначены для режима цикла: проверяйте MODE. На shift 0 разворот может появиться и исчезнуть внутри бара.

OCT_Spectrum

Заполняет power[] значениями в количестве max_period - min_period + 1 (power[0] = min_period баров), шкала 0-1. Методы 0 и 2: DFT фильтра за max_period баров, сильнейшая полоса = 1. Метод 1: сглаженная автокорреляционная периодограмма относительно её медленно затухающего максимума. Возвращает количество или -1.

OCT_Project

Продолжает текущий цикл от shift 0 на bars баров (1-500): path[k] = TRENDLINE + наклон x (k + 1) + AMPLITUDE x sin(PHASE + 360 x (k + 1) / PERIOD), где наклон = изменение TRENDLINE за бар на последней четверти цикла; path[0] = следующий бар. Возвращает bars или -1 с -1 (bars вне диапазона) или -5 (не готово). Геометрическое продолжение, а не прогноз.

OCT_AdaptiveLength

round(PERIOD x fraction) в пределах min_len..max_len; fraction больше 0 и до 10, 1 <= min_len <= max_len. -1 при ошибке. RSI на полцикла:

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

Функции для массивов

Без хэндла, между вызовами ничего не хранится. src[] может быть хронологическим или индексированным как таймсерия; dst[i] относится к src[i], а dst сохраняет собственную индексацию. Динамический dst меняет размер; индикаторному буферу нужен размер src. Возвращают число значений или -1 с -1 (неверный параметр, dst слишком мал) или -5 (пусто или слишком коротко). Фиксированные настройки: сглаживание 0.33, усреднение 3, полоса тренда 1.5; STRENGTH использует среднее абсолютное изменение src.

• OCT_SuperSmoother: 2-полюсный super smoother, период 2-1000; первые 2 значения копируют src.
• OCT_HighPass: 2-полюсный фильтр высоких частот, период 2-1000; первые 2 значения равны 0.
• OCT_Roofing: фильтр высоких частот на max_period, затем super smoother на min_period (равен FILTER).
• OCT_CycleSeries: весь движок по src; dst = поле 0-10 на каждом баре, EMPTY_VALUE в прогреве. Нужно 3 x max_period + 1 значений.
• OCT_DFTSpectrum: мощность в src[index] (собственная индексация src), шкала как у OCT_Spectrum; нужно max_period - 1 более старых значений. Возвращает max_period - min_period + 1 или -1 с -6 (индекс вне диапазона) или -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 и OCT_ErrorText

Код последнего вызова и его текст заглавными буквами: 0 OK, -1 INVALID PARAMETER, -2 NO FREE HANDLE, -3 INVALID HANDLE, -4 NO DATA, -5 NOT ENOUGH BARS, -6 SHIFT OUT OF RANGE, иначе UNKNOWN.

Рабочий пример интеграции

Советник: сначала вставьте блок импорта и три строки enum выше.

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

Архитектура и примечания

• Каждый хэндл хранит свою историю и результаты; у каждой программы, импортирующей библиотеку, свои 32 хэндла.
• Тик пересчитывает только формирующийся бар (в тестах намного меньше 1 мс); первое обновление 2,000 баров занимает от нескольких до примерно 100 мс в зависимости от метода и max_period.
• MetaTrader 5, любой символ и таймфрейм; советники, индикаторы, скрипты. Безопасна в тестере стратегий, при оптимизации и в MQL5 Cloud Network: без DLL, файлов, веб-запросов, графических объектов, таймеров и глобальных переменных. OCT_Create добавляет символ в Обзор рынка, чтобы загрузить его историю.
• Ограничения: 32 хэндла на программу, периоды 4-120 баров, проекция до 500 баров, lookback до 50000 баров.
• Типовые настройки. Адаптивные длины: метод 0, периоды 8-48, длина RSI OCT_AdaptiveLength(h, 0.5, 2, 100, 1). Колебания цикла: метод 1, периоды 10-40, действуйте по OCT_TurnSignal(h, 1) только при MODE на shift 1, равном 0. Фильтр тренда: MODE не 0 = тренд; полоса тренда 2.5 даёт меньше трендовых баров. Индикаторы: OCT_CycleSeries в OnCalculate.
• Скриншоты и видео показывают демонстрационный советник на основе этой библиотеки; он не входит в покупку.

Предупреждение о рисках

Значения цикла описывают прошлые цены. Рынки меняют режим, проекция не является прогнозом, и никакое значение не гарантирует прибыль. Сначала проверяйте на демо-счёте.