【MQL5】SetReturnError関数について

SetReturnError関数の働き・役割
SetReturnError関数の引数について
SetReturnError関数の戻り値について
SetReturnError関数を使う際の注意点
SetReturnError関数を使ったサンプルコード
サンプルコード解説1
1. matrixについて
  1. 行列の作り方
2. 行列とは
サンプルコード解説2
サンプルコード解説3
1. matrix_a.LU(matrix_l, matrix_u) の詳細
2. 具体的な動作
サンプルコード解説4
1. 記述の詳細
2. 具体的な動作
サンプルコード解説5
1. 記述の詳細
2. 具体的な動作

SetReturnError関数の働き・役割

SetReturnError関数は、クライアント端末が操作を完了した際に返すコードを設定するために使用されます。
この関数は、プログラムの実行後に端末プロセスが返す終了コードを指定するもので、コマンドラインから端末を起動した場合などに、プログラムがどのような状態で完了したのかを分析する際に役立ちます。

SetReturnError関数自体は、端末操作を終了させるためのものではありません。あくまでも操作完了時に返される終了コードを設定するものであり、実際に端末を閉じる場合は別の関数（例えば、TerminalClose関数）を使用します。

SetReturnError関数の引数について

void  SetReturnError(
  int ret_code      // クライアント端末完了コード
  );

ret_code
クライアント端末（取引プラットフォームのユーザーインターフェースとなるプログラム）が操作完了時に返す終了コードを指定します。データ型はint型です。

SetReturnError関数の戻り値について

SetReturnError関数は、戻り値を返しません。この関数の目的は、クライアント端末（取引プラットフォームのユーザーインターフェースとなるプログラム）が操作完了時に返すコードを設定することです。

SetReturnError関数を使う際の注意点

SetReturnError関数は端末操作を終了するためのものではありません。終了コードを設定するだけで、端末を閉じる場合には別途、TerminalClose関数を使用する必要があります。

さらに、SetReturnError関数が複数回呼び出された場合、最後に設定されたコードが有効になります。また、異なるMQL5プログラムからこの関数が呼び出された場合でも、同様に最後の呼び出しが優先されます。

重大なエラーが発生した場合や、TerminalClose関数が実行されている場合は、SetReturnError関数で設定されたコードが無効になる可能性があります。

SetReturnError関数を使ったサンプルコード

//+------------------------------------------------------------------+
//| スクリプトプログラム開始関数                                              |
//+------------------------------------------------------------------+
void OnStart()
{
  // matrix_aに4x4の行列を設定します
  matrix matrix_a =
  {
     {-3.474589, 1.106384, -9.091977, -3.925227},  // 1行目
     {-5.522139, 2.366887,-15.162351, -6.357512},  // 2行目
     { 8.394926,-2.960067, 22.292115,  9.524129},  // 3行目
     { 7.803242,-2.080287, 19.217706,  8.186645}   // 4行目
  };

  // LU分解後にL行列とU行列を格納するための4x4の行列を初期化します
  matrix matrix_l(4,4);  // 下三角行列を保持するmatrix_l
  matrix matrix_u(4,4);  // 上三角行列を保持するmatrix_u

  //--- LU分解を行います（matrix_a = L * Uとなるように分解します）
  matrix_a.LU(matrix_l, matrix_u);

  //--- 分解した行列を掛け合わせて、元の行列と一致するか確認します
  matrix matrix_lu = matrix_l.MatMul(matrix_u);  // L行列とU行列を掛け算してLU行列を得る

  //--- matrix_aとmatrix_luを比較し、違いがあればその数をエラーとして返します
  int compare_errors = (int)matrix_a.Compare(matrix_lu, 1e-29);  
  Print("MatrixCompare errors=", compare_errors);  // 比較の結果をエキスパートログに出力します

  //--- 完了時に、比較結果のエラー数をクライアント端末に終了コードとして返します
  SetReturnError(compare_errors);
}

このサンプルコードは、4×4の数値行列に対してLU分解（行列を下三角行列と上三角行列に分解する方法）を行い、その結果として得られた下三角行列（対角成分より上がすべてゼロの行列）と上三角行列（対角成分より下がすべてゼロの行列）を掛け合わせた行列が、元の行列と一致するかを確認します。分解後の行列を掛け合わせた結果と元の行列を比較し、差異があればその数をエラー数として計算します。そして、計算されたエラー数をクライアント端末が返す終了コードとして設定します。

このプロセスにより、LU分解の精度や結果が正常かどうかを判定し、その結果を端末に報告するという動作を行います。

サンプルコード解説1

//+------------------------------------------------------------------+
//| スクリプトプログラム開始関数                                              |
//+------------------------------------------------------------------+
void OnStart()
{
  // matrix_aに4x4の行列を設定します
  matrix matrix_a =
  {
     {-3.474589, 1.106384, -9.091977, -3.925227},  // 1行目
     {-5.522139, 2.366887,-15.162351, -6.357512},  // 2行目
     { 8.394926,-2.960067, 22.292115,  9.524129},  // 3行目
     { 7.803242,-2.080287, 19.217706,  8.186645}   // 4行目
  };

この部分では、まず4×4の行列を変数matrix_aに代入しています。matrix_aは4行4列の数値データを持つ行列で、それぞれの数値はプログラム内でLU分解の計算に使用されます。LU分解（行列を下三角行列と上三角行列に分解する方法）は、行列の操作を通じて様々な数学的問題の解決に使われます。

コード内では、各行の値を個別に設定し、行列として扱っています。例えば、matrix_aの1行目には -3.474589, 1.106384, -9.091977, -3.925227 という数値が含まれており、この形式で4つの行を設定することで4×4の行列が作られています。

matrixについて

matrixはMQL5で行列を扱うためのデータ型で、数値の配列を二次元的に操作することができます。行列とは、縦の列と横の行からなる数値の表で、主に数学やプログラムの計算に利用されます。行列は、例えばデータを変換したり、物理シミュレーションのための数値計算に使われることがあります。

このサンプルコードでは、matrix_aという変数に4×4の数値行列が設定されており、プログラム内でLU分解という特定の数学的操作に利用されています。

行列の作り方

MQL5で行列を作成するためには、まずmatrix型を使用し、次に中括弧 {} を用いて数値を指定します。各行はさらに中括弧 {} で囲み、その中に対応する行の数値をカンマで区切って配置します。

例えば、このコードでの行列matrix_a の設定方法は次のようになっています。

matrix matrix_a =
{
   {-3.474589, 1.106384, -9.091977, -3.925227},  // 1行目
   {-5.522139, 2.366887, -15.162351, -6.357512}, // 2行目
   { 8.394926, -2.960067, 22.292115, 9.524129},  // 3行目
   { 7.803242, -2.080287, 19.217706, 8.186645}   // 4行目
};

このように、まずmatrix型の変数を宣言し、その後に{}で囲んだ行列データを定義します。行列の各行をさらに{}で囲み、カンマで要素を区切ります。このコードでは4×4の行列が定義されており、4行それぞれに4つの数値が含まれています。

行列とは

行列は、数値を縦横に並べたもので、端的に言えば次元配列です。

行列の中の一つ一つの値は「要素」と呼ばれ、行列のサイズは「行（横方向）」と「列（縦方向）」の数で表されます。このサンプルでは、4行4列なので「4×4行列」と呼ばれます。行列は数値データの操作に非常に有効で、シミュレーションやデータ分析など、多くの場面で用いられています。

サンプルコード解説2

  // LU分解後にL行列とU行列を格納するための4x4の行列を初期化します
  matrix matrix_l(4,4);  // 下三角行列を保持するmatrix_l
  matrix matrix_u(4,4);  // 上三角行列を保持するmatrix_u

この部分では、LU分解に必要な2つの行列、matrix_lとmatrix_uを初期化しています。これらは、それぞれ下三角行列と上三角行列を保持するための変数です。LU分解では、元の行列を2つの行列に分けて表現します。

まず、matrix_l(4,4)で4行4列の行列を初期化し、この行列にはLU分解の結果として得られる下三角行列が格納されます。下三角行列とは、対角線より上の要素がすべて0である行列です。同様に、matrix_u(4,4)も4行4列で初期化され、この行列にはLU分解によって得られる上三角行列が格納されます。上三角行列は、対角線より下の要素がすべて0である行列です。

このコードでは、LU分解を行う準備として、これらの行列を適切なサイズで初期化しています。

サンプルコード解説3

 //--- LU分解を行います（matrix_a = L * Uとなるように分解します）
  matrix_a.LU(matrix_l, matrix_u);

この部分では、matrix_aに対してLU分解を実行しています。ここで使用されているLUというメソッドは、行列のLU分解を行うためのもので、元の行列を2つの行列、下三角行列と上三角行列に分けます。これにより、行列を扱いやすくし、数値計算の効率を高めることができます。

matrix_a.LU(matrix_l, matrix_u) の詳細

matrix_a.LU
この部分は、matrix型の変数matrix_aが持つメソッドLUを呼び出しています。このメソッドは、matrix_aに格納されている行列に対してLU分解を行い、その結果を引数として渡された他の行列に格納します。
matrix_l, matrix_u
LUメソッドの引数として渡されているmatrix_lとmatrix_uは、LU分解の結果として得られる行列を格納するための変数です。
matrix_lは下三角行列（対角線より上の要素がすべて0の行列）を受け取ります。
matrix_uは上三角行列（対角線より下の要素がすべて0の行列）を受け取ります。

具体的な動作

matrix_a.LU(matrix_l, matrix_u) という記述は、次のように機能します。

matrix_aに対してLU分解を実行し、元の行列を下三角行列（matrix_l）と上三角行列（matrix_u）に分けます。
matrix_lとmatrix_uは、その結果をそれぞれ保持します。
LU分解の結果、元の行列matrix_aはmatrix_l（L行列）とmatrix_u（U行列）の積として表現される形になります。つまり、matrix_a = L * Uの関係が成り立つように分解されています。

この文法構造により、LU分解が実行され、結果として2つの行列にデータが分配されます。

サンプルコード解説4

  //--- 分解した行列を掛け合わせて、元の行列と一致するか確認します
  matrix matrix_lu = matrix_l.MatMul(matrix_u);  // L行列とU行列を掛け算してLU行列を得る

この部分では、LU分解で得られた下三角行列と上三角行列を掛け合わせ、その結果が元の行列と一致するかを確認しています。

記述の詳細

matrix_l.MatMul(matrix_u)
ここで使われているMatMulメソッドは、行列の掛け算（行列積）を行うメソッドです。具体的には、LU分解によって得られたmatrix_l（下三角行列）とmatrix_u（上三角行列）を掛け合わせて、新しい行列matrix_luを生成しています。この行列matrix_luが、LU分解前の元の行列matrix_aと一致するかどうかを後で比較します。

具体的な動作

matrix_lとmatrix_uをMatMulメソッドで掛け合わせて、新しい行列matrix_luを作成します。
matrix_luは、理論上、LU分解の結果として、元の行列matrix_aと一致するはずの行列です。
この後で行われる行列の比較で、LU分解が正しく行われたかどうかを検証することになります。

この操作によって、LU分解の結果を検証するための準備が整います。

サンプルコード解説5

  //--- matrix_aとmatrix_luを比較し、違いがあればその数をエラーとして返します
  int compare_errors = (int)matrix_a.Compare(matrix_lu, 1e-29);  
  Print("MatrixCompare errors=", compare_errors);  // 比較の結果をエキスパートログに出力します

  //--- 完了時に、比較結果のエラー数をクライアント端末に終了コードとして返します
  SetReturnError(compare_errors);
}

この部分では、LU分解前の元の行列と、LU分解の結果得られた行列を比較し、その違いがあればエラー数として記録しています。さらに、そのエラー数をクライアント端末に終了コードとして返す処理も行っています。

記述の詳細

matrix_a.Compare(matrix_lu, 1e-29)
このCompareメソッドは、元の行列matrix_aと、LU分解後に生成した行列matrix_luを比較します。ここで、2つの行列の要素がほぼ同じかどうかを確認し、違いがあればその数をエラーとしてカウントします。
第2引数「1e-29」について
第2引数に指定されている「1e-29」は、行列の要素の比較において許容される誤差の範囲を示しています。具体的には、「1e-29」は「1 × 10^-29」＝「0.1を29回掛け合わせたもの」を意味し、非常に小さな数値（0.00000000000000000000000000001）です。
この値を使うことで、計算上のわずかな誤差を許容しつつ、比較を行います。数値計算においては、浮動小数点演算によって非常に微小な誤差が生じることがあるため、完全に一致するかどうかではなく、一定の誤差範囲内で「ほぼ一致している」と判断するためにこのような誤差範囲を設定します。「1e-29」のような表記は、科学記法と呼ばれる形式で、非常に大きい数や非常に小さい数を扱う際に便利な表現方法です。この場合、「1e-29」は「1 × 10のマイナス29乗」を意味します。つまり、1の後に29個のゼロが続く非常に小さな数を表します。
compare_errors
比較の結果、エラーの数がcompare_errorsという変数に格納されます。この数値は、2つの行列がどの程度異なっていたかを示します。
SetReturnError(compare_errors)
比較が終わると、そのエラー数をSetReturnError関数を使ってクライアント端末に終了コードとして返します。これにより、プログラムがどのような結果で終了したのかを外部から確認できるようになります。