出力関数とプロット関数の構文

出力関数およびプロット関数とは

出力関数およびプロット関数の例については、Optimization Toolbox の出力関数とプロット関数を参照してください。

OutputFcn オプションは、最適化関数が各反復で呼び出す 1 つ以上の関数を指定します。通常、出力関数は各反復で点をプロットしたり、アルゴリズムからの最適化量を表示するために使用します。表示できる出力関数を使用しますが、最適化量は設定しません。設定した条件に基づいてソルバーの実行を停止することもできます。出力関数またはプロット関数の構造を参照してください。

同様に、PlotFcn オプションは、最適化関数が各反復で呼び出す 1 つ以上の関数を指定し、ソルバーを停止できます。プロット関数と出力関数の違いは次の 2 つです。

事前に定義されたプロット関数がほとんどのソルバーに存在するため、標準的なプロットを簡単に取得できます。
プロット関数は出力を [一時停止] ボタンと [停止] ボタンがあるウィンドウに送信するため、情報を失うことなくソルバーを早期に停止することができます。

注意

intlinprog の出力関数とプロット関数は、他のソルバーのものと異なります。詳細については、intlinprog の出力関数とプロット関数の構文を参照してください。

出力関数またはプロット関数を設定するには、以下を行います。

関数を関数ファイルまたはローカル関数として記述します。
optimoptions を使用して、OutputFcn または PlotFcn の値を関数ハンドル、つまり、@ 記号が先行する関数名になるように設定します。たとえば、出力関数が outfun.m の場合、コマンド
```
 options = optimoptions(@solvername,'OutputFcn',@outfun);
```
は、OutputFcn を outfun へのハンドルになるように指定します。複数の出力関数またはプロット関数を指定するには、次の構文を使用します。
```
 options = optimoptions('solvername','OutputFcn',{@outfun, @outfun2});
```
タブ補完を使用して組み込みプロット関数名の選択を容易にするには、関数ハンドルではなく、引用符を使用します。
入力引数に options を使用して最適化関数を呼び出します。

追加パラメーターの受け渡しに、必要に応じて、パラメーターまたはデータを出力関数またはプロット関数に渡す方法が記載されています。

出力関数またはプロット関数の構造

出力関数またはプロット関数の関数定義行は、次の形式になります。

stop = outfun(x,optimValues,state)

ここで、

x は、現在のアルゴリズムの反復処理で計算される点です。
optimValues は現在の反復からのデータを含む構造体です。optimValues のフィールドはこの構造体を詳しく説明します。
state はアルゴリズムの現在の状態です。アルゴリズムの状態は可能な値の表があります。
stop は、最適化ルーチンを終了するか (true) か継続するか (false) によって、true または false になるフラグです。詳細については、Stop フラグを参照してください。

最適化関数は、反復処理ごとに入力引数の値を outfun に渡します。

optimValues のフィールド

以下の表は optimValues 構造体のフィールドをリストします。特定の最適化関数は、これらのフィールドのいくつかのみに対して値を返します。各フィールドに対して、表の、関数による出力の欄は、フィールドを返す関数をリストします。

対応する出力引数

optimValues のフィールドのいくつかは、最適化関数の出力引数に対応します。最適化アルゴリズムの最終的な反復の後、そのようなフィールドの値は、対応する出力引数に等しくなります。たとえば、optimValues.fval は出力引数 fval に相当します。従って、出力関数とともに fmincon を呼び出し、fval を戻すと optimValues.fval の最終値は fval に等しくなります。次の表の詳細の列は、相当する出力引数をもつフィールドを示します。

コマンドラインの表示

optimValues のいくつかのフィールドの値は options の Display フィールドを 'iter' に設定して最適化関数を呼び出す場合、反復表示で説明されるようにコマンドラインに表示されます。たとえば、optimValues.fval は f(x) の列に表示されます。次の表のコマンドラインの表示の欄は、コマンドラインで表示できるフィールドを示します。

一部の optimValues フィールドは、特定のアルゴリズムにのみ適用されます。

AS — active-set
D — trust-region-dogleg
IP — interior-point
LM — levenberg-marquardt
Q — quasi-newton
SQP — sqp
TR — trust-region
TRR — trust-region-reflective

一部の optimValues フィールドは特定のソルバーまたはアルゴリズムに存在しますが、常に空またはゼロ値が含まれるため意味はありません。このようなフィールドには次のものがあります。

fminunc TR および fsolve TRR の constrviolation。
fmincon TRR および SQP、および fminunc の procedure。

optimValues フィールド

OptimValues フィールド (optimValues.field)	説明	関数による出力	コマンドラインの表示
`attainfactor`	多目的問題のための到達因子。詳細については、ゴール到達法を参照してください。	`fgoalattain`	なし
`cgiterations`	現在の最適化反復での共役勾配反復法の回数。	`fmincon` (IP, TRR), `fminunc` (TR), `fsolve` (TRR), `lsqcurvefit` (TRR), `lsqnonlin` (TRR)	`CG-iterations` 詳細については、反復表示を参照してください。
`constrviolation`	最大の制約違反。	`fgoalattain`, `fmincon`, `fminimax`, `fseminf` `fminunc` `TR` および `fsolve` `TRR` は空白のフィールド値を提供します。	`Max constraint` または `Feasibility` 詳細については、反復表示を参照してください。
`degenerate`	退化の尺度。以下を満たす点は "退化 (degenerate)" です。変数の 1 つについての偏導関数がその点で 0 その点でその変数に対する範囲制約がアクティブ詳細については、退化を参照してください。	`fmincon` (TRR), `lsqcurvefit` (TRR), `lsqnonlin` (TRR)	なし
`directionalderivative`	探索方向の方向導関数。	`fgoalattain`, `fmincon` (AS), `fminimax`, `fminunc` (Q), `fseminf`, `fsolve` (LM), `lsqcurvefit` (LM), `lsqnonlin` (LM)	`Directional derivative` 詳細については、反復表示を参照してください。
`firstorderopt`	1 次の最適性条件 (アルゴリズムに依存)。最終値は最適化関数の出力 `output.firstorderopt` に等しくなります。	`fgoalattain`, `fmincon`, `fminimax`, `fminunc`, `fseminf`, `fsolve`, `lsqcurvefit`, `lsqnonlin`	`First-order optimality` 詳細については、反復表示を参照してください。
`funccount`	関数評価の累積回数。最終値は最適化関数の出力 `output.funcCount` に等しくなります。	`fgoalattain`, `fminbnd`, `fmincon`, `fminimax`, `fminsearch`, `fminunc`, `fsolve`, `fzero`, `fseminf`, `lsqcurvefit`, `lsqnonlin`	`F-count` または `Func-count` 詳細については、反復表示を参照してください。
`fval`	現在の点の関数値。最終値は最適化関数の出力 `fval` に等しくなります。 `fsolve` では、`fval` はベクトル関数値、反復表示 `f(x)` はこのベクトルの 2 乗ノルムです。	`fgoalattain`, `fminbnd`, `fmincon`, `fminimax`, `fminsearch`, `fminunc`, `fseminf`, `fsolve`, `fzero`	`f(x)` 詳細については、反復表示を参照してください。
`gradient`	目的関数の現在の勾配。提供された解析勾配か、または有限差分近似のいずれかになります。最終値は最適化関数の出力 `grad` に等しくなります。	`fgoalattain`, `fmincon`, `fminimax`, `fminunc`, `fseminf`, `fsolve`, `lsqcurvefit`, `lsqnonlin`	なし
`iteration`	反復回数。`0` で開始します。最終値は最適化関数の出力 `output.iterations` に等しくなります。	`fgoalattain`, `fminbnd`, `fmincon`, `fminimax`, `fminsearch`, `fminunc`, `fsolve`, `fseminf`, `fzero`, `lsqcurvefit`, `lsqnonlin`	`Iteration` 詳細については、反復表示を参照してください。
`lambda`	現在の反復でのレーベンバーグ・マルカートパラメーター `lambda`。詳細については、レーベンバーグ・マルカート法を参照してください。	`fsolve` (LM), `lsqcurvefit` (LM), `lsqnonlin` (LM)	`Lambda`
`lssteplength`	初期予測ステップ長で除算された実際のステップ長	`fmincon` (AS、SQP)、`fminunc` (Q)	`Steplength` または `Line search steplength` または `Step-size` 詳細については、反復表示を参照してください。
`maxfval`	最大関数値	`fminimax`	なし
`positivedefinite`	アルゴリズムがニュートンステップを計算中に負の曲率を検出する場合は `0` です。それ以外の場合は `1` です。	`fmincon` (TRR), `fminunc` (TR), `fsolve` (TRR), `lsqcurvefit` (TRR), `lsqnonlin` (TRR)	なし
`procedure`	手順メッセージ。	`fgoalattain`, `fminbnd`, `fmincon` (AS), `fminimax`, `fminsearch`, `fseminf`, `fzero` `fmincon` `TRR` および `SQP` と、`fminunc` は、空白のフィールド値を提供します。	`Procedure` 詳細については、反復表示を参照してください。
`ratio`	二次近似の変動に対する目的関数の変動比。	`fmincon` (TRR), `fminunc` (TR), `fsolve` (TRR), `lsqcurvefit` (TRR), `lsqnonlin` (TRR)	なし
`residual`	残差ベクトル。	`lsqcurvefit`, `lsqnonlin`,	`Residual` 詳細については、反復表示を参照してください。
`resnorm`	残差の二乗の 2 ノルム。	`lsqcurvefit`, `lsqnonlin`	`Resnorm` 詳細については、反復表示を参照してください。
`searchdirection`	探索方向。	`fgoalattain`, `fmincon` (AS, SQP), `fminimax`, `fminunc` (Q), `fseminf`, `fsolve` (LM), `lsqcurvefit` (LM), `lsqnonlin` (LM)	なし
`stepaccept`	現在の信頼領域法手順の状態です。現在の信頼領域法手順が満たされた場合 true を出力し、そうでない場合は false を出力します。	`fsolve` (D)	なし
`stepsize`	現在のステップサイズ (`x` の変動)。最終値は最適化関数の出力 `output.stepsize` に等しくなります。	`fgoalattain`, `fmincon`, `fminimax`, `fminunc`, `fseminf`, `fsolve`, `lsqcurvefit`, `lsqnonlin`	`Step-size` または `Norm of Step` 詳細については、反復表示を参照してください。
`trustregionradius`	信頼領域の半径。	`fmincon` (IP, TRR), `fminunc` (TR), `fsolve` (D, TRR), `lsqcurvefit` (TRR), `lsqnonlin` (TRR)	`Trust-region radius` 詳細については、反復表示を参照してください。

退化

現在の最適化の点 x の退化を測るフィールド degenerate の値は次のように定義されます。最初に、x と同じサイズをもつベクトル r を定義します。r(i) は x(i) から下限 lb と上限 ub の i 番目の要素までの最小の距離です。つまり、

r = min(abs(ub-x, x-lb))

すると degenerate の値はベクトル r + abs(grad) の最小の要素です。ここで、grad は目的関数の勾配です。次の両方が成立するインデックス i がある場合、degenerate の値は 0 です。

grad(i) = 0
x(i) は上限または下限のいずれかの i 番目の要素に等しくなります。

アルゴリズムの状態

次の表は、state の値を一覧表示したものです。

state	説明
`'init'`	アルゴリズムは、最初の反復の前の初期状態にあります。
`'interrupt'`	アルゴリズムは、反復の計算中です。この状態で、出力関数は、最適化の現在の反復を中断することができます。このとき、`x` と `optimValues` の値は `state=='iter'` であるような出力関数に対する最近の呼び出しと同じです。
`'iter'`	アルゴリズムは、反復の最後にあります。
`'done'`	アルゴリズムは、最後の反復の後の最終状態にあります。

'interrupt' 状態は、fmincon 'active-set' アルゴリズムと fgoalattain ソルバー、fminimax ソルバー、および fseminf ソルバーでのみ発生します。その場合、この状態は、二次計画法部分問題の求解または直線探索の前に発生することがあります。

以下のコードは現在の反復で、どのタスクを実行するかを決めるために出力関数が state の値を使用する方法を示します。

switch state
    case 'iter'
          % Make updates to plot or guis as needed
    case 'interrupt'
          % Probably no action here. Check conditions to see  
          % whether optimization should quit.
    case 'init'
          % Setup for plots or guis
    case 'done'
          % Cleanup of plots, guis, or final plot
otherwise
end

Stop フラグ

出力引数 stop は、true またはfalse を示すフラグです。フラグは、最適化を停止するのか (true) 継続するのか (false) を最適化関数に伝えます。次の例は、stop フラグの一般的な使用方法を示したものです。

optimValues のデータに基づき最適化を停止

出力関数またはプロット関数は、optimValues 内の現在のデータに基づいて、任意の反復で最適化を停止できます。たとえば、次のコードは、方向導関数のサイズが .01 より小さい場合に、stop を、最適化を停止する true に設定します。

function stop = outfun(x,optimValues,state)
stop = false;
% Check whether directional derivative norm is less than .01.
if norm(optimValues.directionalderivative) < .01
    stop = true;
end

GUI の入力に基づき最適化を停止

最適化を実行する GUI を設計すると、ユーザーが GUI の [停止] ボタンを押したときに、出力関数によって最適化を停止させることができます。次のコードはこれを行う方法を示します。[停止] ボタンコールバックが hObject と呼ばれる handles 構造体の optimstop フィールドに値 true を保存することを仮定します。

function stop = outfun(x,optimValues,state)
stop = false;
% Check if user has requested to stop the optimization.
stop = getappdata(hObject,'optimstop');