Orrery Cycle Toolkit

あらゆる銘柄・時間足の支配的な市場サイクルを測定する MQL5 ライブラリです：バー単位の周期、位相、交差でサイクルの転換を示すサイン / 先行サインのペア、サイクルまたはトレンドのモード、振幅、トレンドライン、スペクトル、インジケーター用の適応期間、現在のサイクルの投影を提供します。価格履歴を読むだけで、取引も描画もファイル書き込みも一切行いません。お届けするのはコンパイル済みの 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 で行ってください。
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 }; 

仕組み

• ルーフィングフィルター：max_period の 2 極ハイパスと min_period の super smoother により、2 つの長さの間のサイクルだけを残します（フィールド FILTER）。
• 方式別の周期：0 Homodyne discriminator（ヒルベルト変換、最速）、1 Autocorrelation periodogram（最も安定）、2 DFT spectrum。方式 1 と 2 は、パワーが半分以上の帯域の周波数上の重心を使います。その後 周期 = s x 生の値 + (1 - s) x 前回値（s = スムージング、0.33）。
• 位相：フィルターを 1 周期分のサインとコサインと相関させ、測定周期におけるフィルターの正確な位相応答で補正します。0-360 度：90 = サイクルの山、270 = 谷。SINE = sin(位相)、LEADSINE = sin(位相 + 45)。
• 転換：LEADSINE が SINE を上抜け（+1、サイクルの安値が近い）または下抜け（-1、高値が近い）。
• モード：直近の半周期内に転換があった場合、またはそのバーで位相が 0.67-1.5 x 360/周期 進んだ場合はサイクル（0）。それ以外はトレンドで、TRENDLINE に対する価格の位置により +1 上昇または -1 下降。価格が 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：ルーフィングフィルター、価格単位。6 TRENDLINE：1 周期の平均価格を 4-3-2-1 で平滑化。7 AMPLITUDE：1 周期のフィルターの RMS x 1.414、価格単位。8 STRENGTH：AMPLITUDE / 1 周期の平均バー幅。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 終値、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 つ解放します。-1 ですべて解放します。OnDeinit で呼び出してください。

OCT_Bars

値のあるバー数（shift 0 から OCT_Bars - 1）。最初の更新成功前は 0、ハンドル不正なら -1。

OCT_Value

shift 位置のフィールド値。EMPTY_VALUE を返し、-1（フィールドが 0-10 の範囲外）、-3、または -6（負の shift、OCT_Bars - 1 を超える shift、未更新）を設定します。

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

OCT_TurnSignal

そのバーで LEADSINE が SINE を上抜けたら +1、下抜けたら -1、転換なしまたは shift 不正なら 0。転換はサイクルモード向けです：MODE を確認してください。shift 0 の転換はバーの途中で現れて消えることがあります。

OCT_Spectrum

power[] に max_period - min_period + 1 個の値を格納します（power[0] = min_period 本）、0-1 のスケール。方式 0 と 2：max_period 本にわたるフィルターの DFT、最も強い帯域 = 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)。傾き = 直近 4 分の 1 周期における 1 バーあたりの 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 でハイパス、続いて min_period で super smoother（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。

動作する統合例

エキスパートアドバイザーです。先に上のインポートブロックと 3 行の 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 ティックで再計算するのは形成中のバーだけです（テストでは 1 ミリ秒を大きく下回りました）。2,000 本の初回更新は方式と max_period により数ミリ秒から約 100 ミリ秒かかります。
• MetaTrader 5、あらゆる銘柄と時間足。EA、インジケーター、スクリプトで使用可能。ストラテジーテスター、最適化、MQL5 Cloud Network で安全：DLL、ファイル、Web リクエスト、チャートオブジェクト、タイマー、グローバル変数を使いません。OCT_Create は履歴を読み込むため銘柄を気配値表示に追加します。
• 制限：1 プログラムあたり 32 ハンドル、周期 4-120 本、投影は最大 500 本、lookback は最大 50000 本。
• 代表的な設定。適応期間：方式 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。インジケーター：OnCalculate 内で OCT_CycleSeries。
• スクリーンショットと動画は、このライブラリで作ったデモ EA を示しています。購入内容には含まれません。

リスクに関する注意

サイクルの値は過去の価格を表したものです。市場は局面が変わり、投影は予測ではなく、どの値も利益を保証しません。まずデモ口座でテストしてください。