基本的な使い方

インポート

はじめに，NIMOをインポートします．

import nimo

各種パラメータを定義

n_objectives: 目的関数の個数を指定します．
n_proposals: 一度のサイクルで探索アルゴリズムが提案する実験条件数を指定します．これはロボット実験における並列実験数に対応します．
n_cycles: サイクル数を指定します．

例えば，目的関数の個数が２つであり，並列実験数を２とする場合，３回サイクルを回し最適化を実施する場合は，以下のように設定する．

n_objectives = 2
n_proposals = 2
n_cycles = 3

実験条件ファイルを指定

candidates_file に実験条件をリスト化したファイルを指定します．

実験条件ファイルは，以下のようにあらかじめ用意します． \(d\) 次元のdescriptorがあり，\(l\) 個の目的関数を考える場合を例としています．初めの \(d\) 列にdescriptorの候補を全て入力します．これが材料の探索空間となり，この部分には空欄が無いようにします．続く \(l\) 列は，目的関数の値を入力します．初期段階で実験データが全くない場合，目的関数の部分は空欄となります．

descriptor 1	…	descriptor \(d\)
1	…	0
1	…	0.5
1	…	1
0.5	…	0
0.5	…	0.5
0.5	…	1
0	…	0
0	…	0.5
0	…	1

例えば，実験条件ファイルの名前をcandidates.csvとし，メインスクリプトと同じフォルダに格納する場合は，以下のように設定します．

candidates_file = "./candidates.csv"

もし，実験データがいくつか得られている場合は，以下のように \(l\) 個の全ての目的関数を入力します．

descriptor 1	…	descriptor \(d\)	objective 1	…	objective \(l\)
1	…	0
1	…	0.5	12	…	20
1	…	1
0.5	…	0
0.5	…	0.5
0.5	…	1	5	…	8
0	…	0
0	…	0.5
0	…	1	23	…	2

注意：目的関数のセルに，数字以外が記載された場合，そのセルは空欄としてNIMOでは扱われます．そのため，探索アルゴリズムによって，数字以外が記載されたセルの実験条件が提案される場合があります．

探索アルゴリズムによる提案ファイルを指定

proposals_file に探索アルゴリズムが提案する条件を記載するファイルを指定します．このファイルは，NIMOにより作成されるため，ファイルをあらかじめ作成する必要はなく，名前を指定するだけになります．

例えば，メインスクリプトと同じフォルダにproposals.csvという名前で格納する場合は，以下のように設定します．

proposals_file = "./proposals.csv"

探索アルゴリズムの実行

nimo.selection を利用し，探索アルゴリズムによる実験条件の提案を計算します．結果は，”proposals_file”に出力されます．このとき，”proposals_file”の最初の列には，”candidates_file”の順番で各実験条件のIDが記載されます．実験を実施する際には必要ない情報なため，最初の列は無視してください．

引数

method: 探索アルゴリズムの手法を指定します．”PHYSBO”: PHYSBOによるベイズ最適化，”BLOX”: BLOXによる無目的探索，”PDC”: PDCによる相図作成， “RE”: ランダム探索等が指定できます．
input_file: 実験条件ファイル”candidates_file”を指定します．
output_file: 探索アルゴリズムからの提案ファイル”proposals_file”を指定します．
num_objectives: 目的関数の個数”n_objectives”を指定します．もちろん，直接，値を指定することもできます．
num_proposals: 一度のサイクルで探索アルゴリズムが提案する条件数”n_proposals”を指定します．もちろん，直接，値を指定することもできます．
output_res: “True”を指定することで，”RE”以外の探索アルゴリズムを利用する場合，目的関数の予測値および獲得関数が格納されたoutput_res.csvを得ることができます．デフォルトでは”False”になっています．

例えば，ベイズ最適化による提案を計算する場合は以下のように指定します．

nimo.selection(method = "PHYSBO",
                 input_file = candidates_file,
                 output_file = proposals_file,
                 num_objectives = n_objectives,
                 num_proposals = n_proposals)

ロボット実験用インプットファイルの作成およびロボット実験の実行

nimo.preparation_input を利用し，ロボット実験用インプットファイルを作成し，ロボット実験を実行します．

この部分は， 扱うロボットに依存して書き換える必要 があります．

引数

machine: 使用するロボットを指定します．”STAN”: 標準形式のモジュール，”NAREE”: NIMS電気化学自動実験ロボット用のモジュールが指定できます．
input_file: 探索アルゴリズムからの提案ファイル”proposals_file”を指定します．
input_folder: ロボット実験における入力ファイルを格納するフォルダ”input_folder”を指定します．

例えば，標準形式のモジュールを使用する場合は以下のように指定します．

nimo.preparation_input(machine = "STAN",
                         input_file = proposals_file,
                         input_folder = input_folder)

ロボット実験結果の解析と実験条件ファイルの更新

nimo.analysis_output を利用し，ロボット実験の結果を解析し，実験条件ファイルを更新します．

この部分は， 扱うロボットに依存して書き換える必要 があります．

引数

machine: 使用するロボットを指定します．（”STAN”: 標準形式のモジュール，”NAREE”: NIMS電気化学自動実験ロボット用のモジュール）
input_file: 探索アルゴリズムからの提案ファイル”proposals_file”を指定します．
output_file: 実験条件ファイル”candidates_file”を指定します．
num_objectives: 目的関数の個数”n_objectives”を指定します．もちろん，直接，値を指定することもできます．
output_folder: ロボット実験からの出力ファイルを格納するフォルダ”output_folder”を指定します．
objectives_info: “NAREE”を指定した場合に，実験結果のうちどの特性を目的関数として利用するかを指定します．辞書形式で指定する必要があります．

例えば，標準形式のモジュールを使用する場合は以下のように指定します．

nimo.analysis_output(machine = "STAN",
                       input_file = proposals_file,
                       output_file = candidates_file,
                       num_objectives = n_objectives,
                       output_folder = output_folder)

結果履歴の格納・更新

nimo.history を利用することで，最適化結果の履歴を保存できます．

引数

input_file: 実験条件ファイル”candidates_file”を指定します．
num_objectives: 目的関数の個数”n_objectives”を指定します．もちろん，直接，値を指定することもできます．
itt: 現在のサイクル数を入力します．指定しない場合，新しく履歴を保存するリストが作成されます．
history_file: すでに history_file を作成済みな場合，ここで指定することで，ファイルが更新されます．指定しない場合，新しく履歴を保存するリストが作成されます．

具体的には，初めて最適化結果を格納する場合以下のように実行します．

res_history = nimo.history(input_file = candidates_file,
                             num_objectives = n_objectives)

res_history を更新する場合，

Kサイクル目に res_history を更新する場合，以下のように実行します．

res_history = nimo.history(input_file = candidates_file,
                             num_objectives = n_objectives,
                             itt = K,
                             history_file = res_history)

結果の可視化

nimo.visualization を利用することで，結果を可視化することができます．

履歴の可視化

nimo.visualization.plot_history を利用することで，履歴を可視化することができます．

nimo.visualization.plot_history.cycle: 全データのサイクル依存性をプロットすることができます．
nimo.visualization.plot_history.best: 各サイクルにおける最大値をプロットすることができます．

引数

input_file: 履歴を格納したファイル”res_history”を指定します．
num_cycles: サイクル数”n_cycles”を指定します．
fig_folder: 図を出力するフォルダを指定します．指定しない場合，メインスクリプトと同じフォルダに fig という名前のフォルダを作成してください．その中に図が保存されます．
dpi: 図の解像度を指定します．指定しない場合， dpi=72となります．

具体的には，以下のように実行します．

nimo.visualization.plot_history.cycle(input_file = res_history,
                                        num_cycles = n_cycles)

nimo.visualization.plot_history.best(input_file = res_history,
                                       num_cycles = n_cycles)

目的関数の分布の可視化

nimo.visualization.plot_distribution.plot を利用することで，目的関数値の分布を可視化することができます．目的関数が１次元の場合は，ヒストグラムとして，２次元，３次元の場合はscatter plotとして出力されます．４次元以上は指定しても図は出力されません．

引数

input_file: 実験条件ファイル”candidates_file”を指定します．
num_objectives: 目的関数の個数”n_objectives”を指定します．
fig_folder: 図を出力するフォルダを指定します．指定しない場合，メインスクリプトと同じフォルダに fig という名前のフォルダを作成してください．その中に図が保存されます．
dpi: 図の解像度を指定します．指定しない場合， dpi=72となります．

具体的には，以下のように実行します．

nimo.visualization.plot_distribution.plot(input_file = candidates_file,
                                            num_objectives = n_objectives)

相図の可視化

nimo.visualization.plot_phase_diagram.plot を利用することで，予測相図を出力することができます．探索アルゴリズムの方法としてPDCを利用する場合に利用できます． descriptorの次元が１次元の場合，４次元以上の場合は出力されません．

引数

input_file: 実験条件ファイル”candidates_file”を指定します．
fig_folder: 図を出力するフォルダを指定します．指定しない場合，メインスクリプトと同じフォルダに fig という名前のフォルダを作成してください．その中に図が保存されます．
pdc_estimation: 使用するアルゴリズムを選択します．”LC”，”LS”が指定できます．指定しない場合，”LC”が選択されます．
dpi: 図の解像度を指定します．指定しない場合， dpi=72となります．

具体的には，以下のように実行します．

nimo.visualization.plot_phase_diagram.plot(input_file = candidates_file)

自作モジュールを利用する場合

`ai_tool_original.py` の作成

自作のAIを利用する場合， ai_tool_original.py を作成しメインスクリプトと同じフォルダに格納してください．最も基本的な ai_tool_re.py を適切に書き換えて作成してください．クラス名は以下のように ORIGINAL とすることで，GUI版でも使用することができます．

class ORIGINAL():

以下のように実行します．

import ai_tool_original
ai_tool_original.ORIGINAL(input_file = candidates_file,
                          output_file = proposals_file,
                          num_objectives = n_objectives,
                          num_proposals = n_proposals).select()

`preparation_input_original.py` の作成

自作のロボット実験装置を利用する場合， preparation_input_original.py を作成しメインスクリプトと同じフォルダに格納してください．最も基本的な preparation_input_standard.py を適切に書き換えて作成してください．クラス名は以下のように ORIGINAL とすることで，GUI版でも使用することができます．

class ORIGINAL():

以下のように実行します．

import preparation_input_original
preparation_input_original.ORIGINAL(input_file = proposals_file,
                                    input_folder = input_folder).perform()

`analysis_output_original.py` の作成

自作のロボット実験装置を利用する場合， analysis_output_original.py を作成しメインスクリプトと同じフォルダに格納してください．最も基本的な analysis_output_standard.py を適切に書き換えて作成してください．クラス名は以下のように ORIGINAL とすることで，GUI版でも使用することができます．

class ORIGINAL():

以下のように実行します．

import analysis_output_original
analysis_output_original.ORIGINAL(input_file = proposals_file,
                                  output_file = candidates_file,
                                  num_objectives = n_objectives,
                                  output_folder = output_folder).perform()

目的関数を実験条件ファイルに書き込む

上記 nimo.analysis_output 関数では，実験条件ファイルの更新も関数内で実行するようになっています．一方で，実験操作を異なるプログラムで実施し，探索アルゴリズムだけを使用したい場合も想定し，実験により得られた目的関数を実験ファイルに書き込む関数 nimo.output_update を用意しています．

引数

input_file: 探索アルゴリズムからの提案ファイル”proposals_file”を指定します．
output_file: 実験条件ファイル”candidates_file”を指定します．
num_objectives: 目的関数の個数”n_objectives”を指定します．もちろん，直接，値を指定することもできます．
objective_values: 書き込む目的関数をリストとして指定します．順番は”proposals_file”に書かれた順番にしてください．例えば，単目的の場合，objs = [0.5, 1.0, …]，多目的の場合，objs = [[1.1, 3.2], [5, 8.2]…]とリストを準備してください．

nimo.output_update(input_file = proposals_file,
                     output_file = candidates_file,
                     num_objectives = n_objectives,
                     objective_values = objs)

提案された実験条件をPythonのリストとして格納する

上記 nimo.selection 関数では，proposals_fileとして指定したファイルに実験条件が記載されます．これをPython上でリストとして読み込む関数 nimo.proposed_conditions を用意しています． Python経由でロボット実験装置に実験条件を指定する場合に，実験条件をリストとして得ることができます．以下のように指定することで，”proposals.csv”の提案をconditionsというリストで読み込むことができます．

引数

input_file: 探索アルゴリズムからの提案ファイル”proposals_file”を指定します．

conditions = nimo.proposed_conditions(input_file = "proposals.csv")

基本的な使い方

インポート

各種パラメータを定義

実験条件ファイルを指定

探索アルゴリズムによる提案ファイルを指定

探索アルゴリズムの実行

引数

ロボット実験用インプットファイルの作成およびロボット実験の実行

引数

ロボット実験結果の解析と実験条件ファイルの更新

引数

結果履歴の格納・更新

引数

結果の可視化

履歴の可視化

引数

目的関数の分布の可視化

引数

相図の可視化

引数

自作モジュールを利用する場合

ai_tool_original.py の作成

preparation_input_original.py の作成

analysis_output_original.py の作成

目的関数を実験条件ファイルに書き込む

引数

提案された実験条件をPythonのリストとして格納する

引数

`ai_tool_original.py` の作成

`preparation_input_original.py` の作成

`analysis_output_original.py` の作成