Orrery Cycle Toolkit

一个 MQL5 函数库，可测量任意品种和周期的主导市场周期：以K线计的周期长度、相位、一对正弦 / 超前正弦（其交叉标记周期转折）、周期或趋势模式、振幅、趋势线、频谱、自适应指标长度以及当前周期的投影。它只读取价格历史：从不交易、不绘图、不写文件。您获得的是编译后的 Orrery_Cycle_Toolkit.ex5；本页即完整的 API 参考。

快速开始

1. 将 Orrery_Cycle_Toolkit.ex5 复制到 MQL5/Libraries（文件 > 打开数据文件夹）。
2. 把下面的 #import 代码块粘贴到您的 EA、指标或脚本中。
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（最后一根已收盘K线）做决策。
5. OnDeinit：OCT_Release(h)。
6. 验证：在策略测试器中于 EURUSD H1 运行下方示例；预热（3 x max_period 根K线）之后，日志会在每根K线输出读数。

导入声明（可直接复制）

#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 滤波器：max_period 上的 2 极高通滤波器加 min_period 上的 super smoother，只保留两种长度之间的周期（字段 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，高点临近）。
• 模式：若最近半个周期内出现过转折，或本K线相位推进了 0.67-1.5 x 360/周期，则为周期模式（0）；否则为趋势：按价格相对 TRENDLINE 的位置，+1 向上或 -1 向下。价格距 TRENDLINE 至少 趋势带 x AMPLITUDE 时始终为趋势。
• 预热：前 3 x max_period 根K线返回 EMPTY_VALUE。

字段

0 PERIOD：平滑后的主导周期，单位K线（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 / 一个周期内的平均K线波幅。9 MODE：0 周期，1 上升趋势，-1 下降趋势。10 PHASE_STEP：本K线的相位推进，-180 至 180 度（理想周期中为 360/周期）。

API 参考

Shift 0 = 正在形成的K线（收盘前会变化），1 = 最后一根已收盘K线；已收盘K线的数值永不改变。每次调用都会设置 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：保留的K线数，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 收盘价，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

首次调用加载历史，之后追加新K线并重新计算正在形成的K线；请在每个报价或定时器中调用。有数值时返回 true；否则返回 false 并设置 -3（句柄错误）、-4 NO DATA（历史仍在加载：请再次调用）或 -5 NOT ENOUGH BARS（少于 3 x max_period + 1 根K线）。数据缺口或历史被修改会触发重建。超过 lookback + 500 根K线时删除最旧的K线；数值不变。

OCT_Release

释放一个句柄；-1 释放全部。请在 OnDeinit 中调用。

OCT_Bars

有数值的K线数量（shift 0 至 OCT_Bars - 1）；首次成功更新前为 0；句柄错误时为 -1。

OCT_Value

指定 shift 处的字段值。返回 EMPTY_VALUE 并设置 -1（字段不在 0-10）、-3 或 -6（shift 为负、超出 OCT_Bars - 1、尚未更新）。

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

OCT_TurnSignal

该K线上 LEADSINE 向上穿越 SINE 时为 +1，向下为 -1，无转折或 shift 无效时为 0。转折适用于周期模式：请检查 MODE。shift 0 上的转折可能在K线内出现又消失。

OCT_Spectrum

向 power[] 填入 max_period - min_period + 1 个值（power[0] = min_period 根K线），范围 0-1。方法 0 和 2：滤波器在 max_period 根K线上的 DFT，最强频段 = 1。方法 1：平滑后的自相关周期图，相对于其缓慢衰减的最大值。返回数量或 -1。

OCT_Project

从 shift 0 起将当前周期延续 bars 根K线（1-500）：path[k] = TRENDLINE + 斜率 x (k + 1) + AMPLITUDE x sin(PHASE + 360 x (k + 1) / PERIOD)，其中斜率 = 最近四分之一周期内 TRENDLINE 每根K线的变化；path[0] = 下一根K线。返回 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 上高通，再在 min_period 上 super smoother（等于 FILTER）。
• OCT_CycleSeries：在 src 上运行完整引擎；dst = 每根K线的字段 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。

可运行的集成示例

一个智能交易系统（EA）：请先粘贴上方的导入代码块和三行 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 个句柄。
• 每个报价只重新计算正在形成的K线（测试中远低于 1 毫秒）；2,000 根K线的首次更新耗时从几毫秒到约 100 毫秒，取决于方法和 max_period。
• MetaTrader 5，任意品种和周期；EA、指标、脚本均可使用。在策略测试器、优化和 MQL5 Cloud Network 中安全：不使用 DLL、文件、网络请求、图表对象、定时器或全局变量。OCT_Create 会将品种加入市场报价窗口以加载其历史。
• 限制：每个程序 32 个句柄，周期 4-120 根K线，投影最多 500 根K线，lookback 最多 50000 根K线。
• 典型设置。自适应长度：方法 0，周期 8-48，RSI 长度 OCT_AdaptiveLength(h, 0.5, 2, 100, 1)。周期摆动：方法 1，周期 10-40，仅当 shift 1 上的 MODE 为 0 时依据 OCT_TurnSignal(h, 1) 操作。趋势过滤：MODE 不为 0 = 趋势；趋势带设为 2.5 可减少趋势K线。指标：在 OnCalculate 中使用 OCT_CycleSeries。
• 截图和视频展示的是基于本函数库构建的演示 EA；它不包含在购买内容中。

风险提示

周期读数描述的是过去的价格。市场会改变状态，投影不是预测，任何读数都不能保证盈利。请先在模拟账户上测试。