# ``gp_simulation_animation_tkbo.py`` ドキュメント

## 1. ファイル概要 (``gp_simulation_animation_tkbo.py``)

### 目的

このPythonスクリプトは、 ``tkbo`` ライブラリを使用して1次元のBayesian Optimizationシミュレーションをアニメーションとして視覚化することを目的としています。真の目的関数 ``f_true`` を定義し、様々なモデル（ガウス過程回帰、PhysBO、ランダムなど）とAcquisition関数（UCB、EI、PI、Steinなど）を試すことができます。シミュレーションの進行状況は ``matplotlib`` を用いてアニメーションとして描画され、GIFファイルとして保存したり、リアルタイムで表示したりできます。

### 主な機能

*   **真の目的関数の定義**: シミュレーションで使用される1次元の目的関数 ``f_true()`` を定義します。
*   **カスタムAcquisition関数の実装**: ポステリア平均の最大化を行う ``MeanAcquisition`` クラスを実装し、 ``tkbo`` に登録します。
*   **コマンドライン引数処理**: ``argparse`` を使用して、シミュレーションモード、モデル、最大イテレーション数、出力ファイル名などの詳細な設定をコマンドラインから指定できるようにします。
*   **``tkbo`` による最適化**: 指定されたモデルとAcquisition関数に基づき、 ``tkbo.create_optimizer()`` を用いてBayesian Optimizationのオプティマイザを構築・実行します。
*   **アニメーション生成**: ``matplotlib.animation.FuncAnimation`` を使用して、各評価ステップでのGP予測、Acquisitionスコア、観測点、次の評価点を視覚的に更新するアニメーションを生成します。
*   **GIF保存と表示**: 生成されたアニメーションをGIFファイルとして保存したり、ウィンドウに表示したりする機能を提供します。

### 非標準ライブラリ

このスクリプトは以下の非標準ライブラリに依存しています。

*   ``numpy``
*   ``matplotlib``
*   ``scikit-learn`` (``sklearn.exceptions.ConvergenceWarning``)
*   ``tkbo``

### 実行例

以下は、このスクリプトの典型的な実行例です。

```bash
python gp_simulation_animation_tkbo.py --mode ucb --model sklearn_gpr --nmaxiter 120 --save 0 --show 1
python gp_simulation_animation_tkbo.py --mode ei --model sklearn_gpr --nmaxiter 120 --save 0 --show 1
python gp_simulation_animation_tkbo.py --mode stein --model physbo_gp --nmaxiter 120 --save 0 --show 1
python gp_simulation_animation_tkbo.py --model physbo --acquisition EI --nmaxiter 120 --save 0 --show 1
python gp_simulation_animation_tkbo.py --model random --nmaxiter 120 --save 0 --show 1
python gp_simulation_animation_tkbo.py --model random --nmaxiter 20 --outfile random.gif

2. クラス

MeanAcquisition

ポステリア平均を最大化する候補点を選択するためのカスタムAcquisition関数です。 tkbo.base.BaseAcquisition を継承しています。

  • 継承元: tkbo.base.BaseAcquisition

  • 登録名: "mean" および "max"

属性

  • name: "mean" （Acquisition関数の識別名）

メソッド

  • __call__(self, X, mean, std, y_observed=None, observed_mask=None, maximize=True, **kwargs)

    • 目的: 予測平均に基づいてスコアを計算します。

    • 引数:

      • X: 候補点の入力データ（コードからは具体的な使用箇所は確認できません）。

      • mean: 各候補点の予測平均 (np.ndarray)。

      • std: 各候補点の予測標準偏差（コードからは具体的な使用箇所は確認できません）。

      • y_observed: 観測された目標値（コードからは具体的な使用箇所は確認できません）。

      • observed_mask: 観測された点のマスク（コードからは具体的な使用箇所は確認できません）。

      • maximize: ブール値。 True の場合、予測平均をそのままスコアとして返します。 False の場合、予測平均の負の値を返します。デフォルトは True です。

      • **kwargs: その他のキーワード引数。

    • 戻り値: 各候補点のスコア (np.ndarray)。 maximize が True なら mean と同じ値、False なら -mean と同じ値。

3. 関数

f_true

シミュレーションの真の目的関数を定義します。

  • 目的: np.sin(2 * np.pi * x) + 0.3 * np.cos(4 * np.pi * x) の関数値を計算します。

  • 引数:

    • x: 入力値 (np.ndarray または float)。

  • 戻り値: 計算された関数値 (np.ndarray または float)。

build_parser

コマンドライン引数を定義するための argparse.ArgumentParser オブジェクトを構築します。

  • 目的: スクリプトが受け入れるコマンドライン引数の定義とヘルプメッセージの設定を行います。

  • 引数: なし。

  • 戻り値: 設定済みの argparse.ArgumentParser オブジェクト。

normalize_args

解析されたコマンドライン引数を正規化します。

  • 目的: 後方互換性のために位置引数をキーワード引数にマッピングし、特定の文字列引数を小文字に変換します。

  • 引数:

    • args: argparse.Namespace オブジェクト。 build_parser() によって解析された引数が格納されています。

  • 戻り値: 正規化された argparse.Namespace オブジェクト。

infer_acquisition_from_mode

--mode 引数に基づいて、 tkbo が認識するAcquisition関数名を推測します。

  • 目的: ユーザーが指定した --mode 文字列を、内部で利用されるAcquisition関数名に変換します。

  • 引数:

    • mode: str。コマンドライン引数 --mode の値。

  • 戻り値: 推測されたAcquisition関数名 (str)。

  • 例外:

    • ValueError: 未知の mode が指定された場合。

effective_model

実効的なモデル名を決定します。

  • 目的: --mode が "random" または "grid" の場合、モデル選択がこれらのモードに上書きされるため、その実効的なモデル名を返します。それ以外の場合は --model 引数の値を返します。

  • 引数:

    • args: argparse.Namespace オブジェクト。

  • 戻り値: 実効的なモデル名 (str)。

acquisition_kwargs

特定のAcquisition関数が必要とする追加のパラメータを辞書として返します。

  • 目的: --mode または --acquisition で指定されたAcquisition関数に応じて、必要なキーワード引数を構築します。例えば、UCB や LCB は kappa パラメータを使用します。

  • 引数:

    • acquisition: str。Acquisition関数名。

    • args: argparse.Namespace オブジェクト。

  • 戻り値: Acquisition関数に渡されるキーワード引数の辞書 (dict)。

make_optimizer

Bayesian Optimizationのオプティマイザを構築し、初期化します。

  • 目的: コマンドライン引数と現在の観測データに基づいて、 tkbo.create_optimizer() を呼び出し、適切なオプティマイザインスタンスを生成・初期化します。プロット用の特別な設定（ for_plot=True ）も考慮します。

  • 引数:

    • X_candidates: 候補点の入力データ (np.ndarray)。

    • y_all: 全候補点に対する観測値。未観測の点は np.nan (np.ndarray)。

    • args: argparse.Namespace オブジェクト。

    • for_plot: ブール値。 True の場合、プロット目的でモデルが変更される可能性があります。デフォルトは False です。

  • 戻り値: 初期化された tkbo のオプティマイザオブジェクト。

  • 例外:

    • ValueError: --model physbo が acquisition=mean をサポートしない場合、またはサポートされていないAcquisition関数が指定された場合。

    • ValueError: 未知の --model が指定された場合。

choose_next_index

次に評価すべき候補点のインデックスを選択します。

  • 目的: 現在の観測データとオプティマイザの戦略に基づいて、次に評価すべき候補点のインデックスを決定します。最初の点はランダムに選択されます。

  • 引数:

    • X_candidates: 候補点の入力データ (np.ndarray)。

    • y_all: 全候補点に対する観測値。未観測の点は np.nan (np.ndarray)。

    • rng: 乱数生成器 (np.random.Generator)。

    • args: argparse.Namespace オブジェクト。

  • 戻り値: 選択された候補点のインデックス (int)。

  • 例外:

    • RuntimeError: 未観測の候補点が残っていない場合。

    • RuntimeError: tkbo が候補点を返さなかった場合。

normalize_score_for_color

スコアをプロットの色付け用に0から1の範囲に正規化します。

  • 目的: Acquisitionスコアを、プロットのカラーマップに適した0から1の浮動小数点値に変換します。 NaN や無限大の値、スコアの範囲がゼロの場合を適切に処理します。

  • 引数:

    • score: 正規化するスコア (np.ndarray)。

  • 戻り値: 正規化されたスコア (np.ndarray)。

safe_score_for_plot

観測済みの点のスコアを NaN に設定し、プロットに適した形に調整します。

  • 目的: プロット時に観測済みの点にAcquisitionスコアが表示されないように、それらの点のスコアを NaN に設定します。

  • 引数:

    • score: Acquisitionスコア (np.ndarray)。

    • observed_mask: 観測済みであるかを示すブールマスク (np.ndarray)。

  • 戻り値: 観測済み点のスコアが NaN に設定されたスコア (np.ndarray)。

compute_plot_posterior_and_score

プロット用にGPの予測平均、標準偏差、Acquisitionスコアを計算します。

  • 目的: 現在の観測データに基づいて、Bayesian Optimizationモデルから予測平均、標準偏差、そしてAcquisitionスコアを計算します。これらの値はアニメーションのプロットに使用されます。

  • 引数:

    • X_candidates: 候補点の入力データ (np.ndarray)。

    • y_all: 全候補点に対する観測値。未観測の点は np.nan (np.ndarray)。

    • args: argparse.Namespace オブジェクト。

  • 戻り値: 予測平均、予測標準偏差、Acquisitionスコアのタプル (tuple[np.ndarray, np.ndarray, np.ndarray])。Acquisitionスコアの計算でエラーが発生した場合は、全ての値が NaN の配列が返されます。

run

メインのシミュレーションとアニメーション生成ロジックです。

  • 目的: シミュレーションの初期設定、 matplotlib を用いたプロット要素の描画、 FuncAnimation を使ったアニメーションの生成、そしてその保存または表示を行います。

  • 引数:

    • args: argparse.Namespace オブジェクト。コマンドライン引数で指定された設定を保持します。

  • 戻り値: なし。

main

スクリプトのエントリポイントです。

  • 目的: コマンドラインパーサーを構築し、引数を解析・正規化した後、 run() 関数を呼び出してメインの処理を実行します。エラーが発生した場合はトレースバックを出力し、例外を再発生させます。

  • 引数: なし。

  • 戻り値: なし。

4. コマンドライン引数

引数名

型

デフォルト値

説明

mode_pos

str

None

(位置引数) シミュレーションモードを指定します（後方互換性のため）。

nmaxiter_pos

int

None

(位置引数) 最大イテレーション数を指定します（後方互換性のため）。

outfile_pos

str

None

(位置引数) アニメーションの出力ファイル名を指定します（後方互換性のため）。

--mode

str

"ucb"

シミュレーションモード。選択肢: "random", "std", "max", "ucb", "ei", "pi", "lcb", "stein", "entropy", "grid".

--model

str

"sklearn_gpr"

Bayesian Optimizationに使用するモデル。選択肢: "sklearn_gpr", "physbo_gp", "physbo", "random", "grid", "custom".

--surrogate

str

"sklearn_gpr"

--model custom が指定されたときに使用するサロゲートモデル。

--acquisition

str

""

Acquisition関数を明示的に上書きします。空の場合、 --mode から推測されます。

--nmaxiter

int

20

最大評価点数 (イテレーション数)。

--outfile

str

""

アニメーションを保存するファイル名。空の場合、自動生成されます。

--n-grid

int

200

候補点のグリッド数。

--noise-sigma

float

0.15

観測ノイズの標準偏差。

--random-seed

int

1

乱数シード。

--kappa

float

2.0

UCB/LCB Acquisition関数のパラメータ。

--length-scale

float

0.2

ガウス過程カーネルの長さスケール。

--n-restarts-optimizer

int

5

ガウス過程ハイパーパラメータ最適化のリスタート回数。

--num-rand-basis

int

200

physbo モデルの乱数基底数。

--interval

int

0

physbo モデルのパラメータ（コードからは具体的な意味は確認できません）。

--save

int

1

アニメーションをGIFファイルとして保存するかどうか。選択肢: 0 (保存しない), 1 (保存する)。

--show

int

1

アニメーションをウィンドウに表示するかどうか。選択肢: 0 (表示しない), 1 (表示する)。

--maximize

int

1

最大化問題としてBayesian Optimizationを実行するかどうか。選択肢: 0 (最小化), 1 (最大化)。

--show-score

int

1

下部パネルにAcquisitionスコアのプロットを表示するかどうか。選択肢: 0 (表示しない), 1 (表示する)。

--score-color

int

1

上部パネルで候補点をAcquisitionスコアに基づいて色付けするかどうか。選択肢: 0 (色付けしない), 1 (色付けする)。

--fps

int

2

GIF保存時のフレームレート (Frames Per Second)。

5. 入出力

入力

  • コマンドライン引数:

    • スクリプトの動作を制御する様々なパラメータ（シミュレーションモード、モデル、イテレーション数、保存オプションなど）は、上記の「コマンドライン引数」セクションで詳述されています。

出力

  • 標準出力 (stdout):

    • スクリプトの実行開始時に、設定されたパラメータ（モード、モデル、Acquisition関数、イテレーション数など）が列挙されます。

    • 各シミュレーションステップ（イテレーション）の進行状況（ステップ番号、選択されたインデックス、x の値、y の値）が出力されます。

  • グラフィカル出力:

    • アニメーションウィンドウ:

      • --show 1 オプションが指定された場合、 matplotlib のウィンドウが開かれ、Bayesian Optimizationの進行状況がリアルタイムでアニメーションとして表示されます。

      • 表示される内容には、真の関数、GPの予測平均と95%信頼区間、観測されたデータ点、次の評価点、および（ --show-score 1 の場合）Acquisitionスコアのプロットが含まれます。

      • --score-color 1 の場合、上部パネルの x 軸の下部に、候補点がAcquisitionスコアに応じて色付けされて表示されます。

    • GIFファイル:

      • --save 1 オプションが指定された場合、生成されたアニメーションはGIFファイルとして保存されます。

      • 出力ファイル名は --outfile オプションで指定できます。指定がない場合、デフォルトで gp_animation_{mode}_{effective_model}_{nmaxiter}.gif という形式でファイルが生成されます。

      • 保存後、保存先のファイルパスが標準出力に表示されます。