.. -*- coding: utf-8 -*-

コールバック関数
================

コールバックとは最適化計算が定期的に呼び出すユーザ関数のことです．
ユーザが最適化の状態を問い合わせ，最適化計算の挙動を制御することができます．

分枝限定法のユーザ停止
----------------------

PySIMPLE では分枝限定法の停止を制御するコールバック関数を設定することができます．
ユーザは Problem インスタンスのメソッド `setCallback` の引数 ``mip_terminate`` に
ユーザの定義した関数（コールバック関数）を渡すと，その関数が分枝限定法の計算内で呼び出されます．

コールバック関数は一つの引数をとり，bool 型を返す関数を想定します．
以下はユーザが定義するコールバック関数の関数定義です．::

    def mip_terminate(solver: dict) -> bool:

True を返すと分枝限定法を停止し，False を返すと継続して実行されます．
コールバック関数の引数には，本関数が呼び出された時点の最適化計算の情報が辞書型に格納されています．
以下は，引数に渡ってくる辞書型に格納されている最適化計算の情報一覧です．

.. csv-table::
   :header: キー, 内容

   ElapsedTime, 経過時間
   RelativeGap, 相対ギャップ 
   AbsoluteGap, 絶対ギャップ
   Objective, 目的関数値
   SolutionCount, 実行可能解の数
   TotalMemory, メモリ消費量(MiB) 
   MemoryAvailable, 利用可能メモリ量 (MiB)
   PartialProblemCount, 部分問題の数(ノード数)

以下はコールバック関数の記述例です．::

    def func(solver):
        # 実行可能解の個数が 1 以上になったら分枝限定法を停止する
        if solver['SolutionCount'] >= 1:
            return True
        return False

上記で定義した関数 func を Problem インスタンス problem に設定します．::

    problem.setCallback(mip_terminate=func)

以下では停止条件を設定せず，最適化計算の経過情報をカスタマイズして出力しています．::

    def func(solver):
        print(solver['Objective'], solver['RelativeGap'], solver['AbsoluteGap'])
        return False

コールバック関数で停止した場合，ステータス番号 ``NUOPT 31`` あるいは ``NUOPT 32`` で最適化計算が終了します．
例えば，ステータス番号が ``NUOPT 31`` の場合は以下のように出力されます．::

    [Result]
    STATUS                                            NON_OPTIMAL
    ERROR_TYPE  (NUOPT 31) B&B terminated by user (with feas.sol.).

以下は注意事項です．

- 実行可能解が得られていない場合，``AbsoluteGap`` / ``RelativeGap`` は +inf の値になっています．
- 実行可能解が得られていない場合，``Objective`` は最大化問題の場合 -inf，最小化問題の場合 +inf の値になっています．
- 最適化計算情報の内，``MemoryAvailable`` は Windows 版のみ有効です．