基本的な使用方法 ===================== インストール --------------------- 実行環境・必要なパッケージ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PHYSBOの実行環境および必要なパッケージは以下の通りです。 * Python >= 3.9 * numpy * scipy PHYSBO v3.0.0 から、（特にWindows環境での）インストールプロセスの簡略化のために、Cythonは使用されなくなりました。 しかし、Cythonを使用しないことで、PHYSBOの性能が旧バージョンと比べて若干低下します。 より高速な実行が必要な場合には、 ``physbo-core-cython`` を追加でインストールしてください。 このパッケージはPHYSBOの一部の関数をCythonを用いて高速化したものです。 ダウンロード・インストール ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``PyPI`` からのインストール（推奨） :: $ pip3 install physbo - NumPy などの依存パッケージも同時にインストールされます。 - ソースコードからのインストール（開発者向け） #. 本体のダウンロード ソースファイルをダウンロードするか、以下のように github レポジトリをクローンしてください。 :: $ git clone https://github.com/issp-center-dev/PHYSBO #. インストール :: $ cd PHYSBO $ pip3 install --user ./ - ``physbo-core-cython`` をインストールする場合 :: $ python3 -m pip install physbo-core-cython アンインストール ~~~~~~~~~~~~~~~~~~~~~~~~ #. 以下のコマンドを実行します。 :: $ python3 -m pip uninstall physbo PHYSBOの基本構造 -------------------------- PHYSBOのパッケージ構成は以下のようになっています。 :: physbo ├── blm │   ├── basis │   ├── core │   ├── inf │   ├── lik │   └── prior ├── gp │   ├── core │   ├── cov │   ├── inf │   ├── lik │   └── mean ├── misc ├── opt ├── predictor └── search ├── discrete ├── discrete_multi ├── optimize ├── range └── range_multi 各モジュールは以下のような構成で作成されています。 - ``blm`` : ベイズ線形回帰モデル - ``gp`` : ガウス過程回帰モデル - ``opt`` : ガウス過程のハイパーパラメータ最適化 - ``search`` : ベイズ最適化 - ``discrete`` : 離散的な探索空間に対する単目的最適化 - ``discrete_multi`` : 離散的な探索空間に対する多目的最適化 - ``range`` : 連続的な探索空間に対する単目的最適化 - ``range_multi`` : 連続的な探索空間に対する多目的最適化 - ``optimize`` : 獲得関数の最適化 - ``predictor`` :predictorの抽象クラス - ``misc`` : その他(探索空間を正規化するためのモジュールなど) 各モジュールの詳細については `APIリファレンス `_ を参考にしてください。 計算の流れ -------------------------- ベイズ最適化は、複雑なシミュレーションや、実世界における実験タスクなど、目的関数の評価に大きなコストがかかるような最適化問題に適しています。 PHYSBO では以下の手順により最適化を実行します(それぞれの詳細はチュートリアルおよびAPIリファレンスを参考にしてください)。 1. 探索空間の定義 N: 探索候補の数 , d: 入力パラメータの次元数 とした時、探索候補である各パラメータセット (d 次元のベクトル) を定義します。パラメータセットは全ての候補をリストアップしておく必要があります。 2. simulator の定義 上で定義した探索候補に対して、各探索候補の目的関数値（材料特性値など最適化したい値）を与えるsimulatorを定義します。PHYSBOでは、最適化の方向は「目的関数の最大化」になります。目的関数を最小化したい場合には、simulatorから返す値にマイナスをかけてください。 3. 最適化の実行 最初に、最適化の policy をセットします(探索空間はこの段階で引数としてpolicyに渡されます)。最適化方法は、以下の2種類から選択します。 - ``random_search`` - ``bayes_search`` ``random_search`` では、探索空間からランダムにパラメータを選び、その中で最大となる目的関数を探します。ベイズ最適化を行うための前処理として初期パラメータ群を用意するために使用します。 ``bayes_search`` は、ベイズ最適化を行います。ベイズ最適化でのscore: 獲得関数(acquisition function) の種類は、以下のいずれかから指定します。 - TS (Thompson Sampling): 学習されたガウス過程の事後確率分布から回帰関数を１つサンプリングし、それを用いた予測が最大となる点を候補として選択します。 - EI (Expected Improvement): ガウス過程による予測値と現状での最大値との差の期待値が最大となる点を候補として選択します。 - PI (Probability of Improvement): 現状での最大値を超える確率が最大となる点を候補として選択します。 ガウス過程に関する詳細については :ref:`chap_algorithm` に記載してあります。その他、各手法の詳細については、 `こちらの文献 `_ およびその参考文献を参照して下さい。 これらのメソッドに先ほど定義した simulator と探索ステップ数を指定すると、探索ステップ数だけ以下のループが回ります。 i). パラメータ候補の中から次に実行するパラメータを選択 ii). 選択されたパラメータで simulator を実行 i)で返されるパラメータはデフォルトでは1つですが、1ステップで複数のパラメータを返すことも可能です。詳しくはチュートリアルの `「複数候補を一度に探索する」 `_ の項目を参照してください。また、上記のループを PHYSBO の中で回すのではなく、i) と ii) を別個に外部から制御することも可能です。つまり、PHYSBO から次に実行するパラメータを提案し、その目的関数値をPHYSBOの外部で何らかの形で評価し（例えば、数値計算ではなく、実験による評価など）、それをPHYSBOの外部で何らかの形で提案し、評価値をPHYSBOに登録する、という手順が可能です。詳しくは、チュートリアルの `「インタラクティブに実行する」 `_ の項目を参照してください。 4. 結果の確認 探索結果 res は history クラスのオブジェクト (``physbo.search.discrete.results.History``) として返されます。以下より探索結果を参照します。 - ``res.fx`` : simulator (目的関数) の評価値の履歴。 - ``res.chosen_actions``: simulator を評価したときのaction ID(パラメータ)の履歴。 - ``fbest, best_action = res.export_all_sequence_best_fx()``: simulator を評価した全タイミングにおけるベスト値とそのaction ID(パラメータ)の履歴。 - ``res.total_num_search``: simulator のトータル評価数。 また、ベイズ最適化後の ``policy`` は ``save`` メソッドにより外部ファイルに保存でき、 ``load`` メソッドを用いてファイルからロード・再開することができます。使用方法の詳細はチュートリアルの `「インタラクティブに実行する」`_ をご覧ください。 PHYSBOではほかにも、多目的最適化や連続的な探索空間に対する最適化など、様々な最適化手法が実装されています。詳しくはチュートリアルの `「多目的最適化」 `_ および `「連続空間での最適化」 `_ の項目を参照してください。