Basic Usage

Import

First, we will import NIMS-OS.

import nimsos

Definition of parameters

ObjectivesNum: Specify the number of objective functions.
ProposalsNum: Specify the number of experimental conditions proposed by the AI in one cycle. This corresponds to the number of parallel experiments in a robotic experiments.
CyclesNum: Specify the number of cycles.

For example, if the number of objective functions is two, the number of parallel experiments is two, and the optimization is performed in three cycles, the following settings are used.

ObjectivesNum = 2
ProposalsNum = 2
CyclesNum = 3

Preparation of candidates file

candidates_file is a file listing the conditions of the experiment.

The candidates file is prepared in advance as follows. The example is that there is a \(d\) dimensional descriptor and \(l\) objective functions are considered. Enter all the candidate descriptors in the first \(d\) column. This is the search space for the materials, and there should be no empty space in this part. In the subsequent \(l\) column, enter the value of the objective functions. If there is no experimental data in the initial stage, the all part of objective functions will be left blank.

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

For example, if the name of the candidates file is “candidates.csv” and the file is stored in the same folder as the main script, set as follows.

candidates_file = "./candidates.csv"

If you have some experimental data, enter all \(l\) objective functions as follows

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

Proposals file by AI

Specify a file in proposals_file that describes the experimental conditions proposed by the AI. This file is automatically created by the NIMS-OS, and you do not need to create the file in advance. You only need to specify the name of the file.

For example, if you want to store the file named “proposals.csv” in the same folder as the main script, set as follows.

proposals_file = "./proposals.csv"

Storage of data for robotic experiments

input_folder: Specify the folder to store the input files for the robotic experiments.
output_folder: Specify the folder where the output files from the robotic experiments will be stored.

For example, when the input folder is “./EXPInput” and the output folder is “./EXPOutput”, set as follows.

input_folder = "./EXPInput"
output_folder = "./EXPOutput"

Execution of AI

Using nimsos.selection , computes suggestions for experimental conditions by AI.

Arguments

method: Specify the AI method.” PHYSBO”: Bayesian Optimization by PHYSBO, “BLOX”: Boundless objective-free exploration by BLOX, “PDC”: Phase diagram construction by PDC, “RE”: Random exploration can be used.
input_file: Specify the file stored experimental conditions, that is, “candidates_file”.
output_file: Specify the file stored proposal conditions by AI, that is “proposals_file”.
num_objectives: Specify “ObjectivesNum”, the number of objective functions. Of course, you can also directly specify a numerical value.
num_proposals: Specify “ProposalsNum”, the number of conditions proposed by the AI in one cycle. Of course, you can also directly specify a numerical value.

For example, to compute proposals by Bayesian optimization, set as follows.

nimsos.selection(method = "PHYSBO",
                 input_file = candidates_file,
                 output_file = proposals_file,
                 num_objectives = ObjectivesNum,
                 num_proposals = ProposalsNum)

Creation of input files for robotic experiments and execution of robotic experiments

Using nimsos.preparation_input, create input files for the robotic experiments and execute the robotic experiments.

This part must be revised depending on the robot to be used.

Arguments

machine: Specify the robot to be used. “STAN”: Standard format module, “NAREE”: NIMS automated robotic electrochemical experiments can be used.
input_file: Specify “proposals_file”, which is a file of proposals from the AI.
input_folder: Specify the folder “input_folder” to store the input files for the robotic experiments.

For example, to use a standard format module, set as follows.

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

Analysis of results by robotic experiments and update of candidates files

Using nimsos.analysis_output , analyze the results by the robotic experiments and update the candidates file.

This part must be revised depending on the robot to be used.

Arguments

machine: Specify the robot to be used. “STAN”: Standard format module, “NAREE”: NIMS automated robotic electrochemical experiments can be used.
input_file: Specify “proposals_file”, which is a file of proposals from the AI.
output_file: Specify the file stored experimental conditions, that is, “candidates_file”.
num_objectives: Specify “ObjectivesNum”, the number of objective functions. Of course, you can also directly specify a numerical value.
output_folder: Specify the folder “output_folder” to store the results by the robotic experiments.
objectives_info: If “NAREE” is specified, we set which properties of the experimental results are used as the objective functios. It must be specified as dictionary.

For example, to use a standard format module, set as follows.

nimsos.analysis_output(machine = "STAN",
                       input_file = proposals_file,
                       output_file = candidates_file,
                       num_objectives = ObjectivesNum,
                       output_folder = output_folder)

Storing and updating results history

Using nimsos.history , save a history of optimization results.

Arguments

input_file: Specify the file stored experimental conditions, that is, “candidates_file”.
num_objectives: Specify “ObjectivesNum”, the number of objective functions. Of course, you can also directly specify a numerical value.
itt: Enter the current number of cycles. If not specified, a new list will be created to store the history.
history_file: If a history_file has already been created, this will update the file. If not specified, a new history list is created.

When storing optimization results for the first time, set as follows.

res_history = nimsos.history(input_file = candidates_file,
                             num_objectives = ObjectivesNum)

If you want to update res_history in cycle K, set as follows.

res_history = nimsos.history(input_file = candidates_file,
                             num_objectives = ObjectivesNum,
                             itt = K,
                             history_file = res_history)

Visualization of results

Using nimsos.visualization, figures of the results are obtained. First, create a folder named fig in the same folder as the main script. The output will be stored in this folder.

Visualization of history

Using nimsos.visualization.plot_history , figures for history are obtained.

nimsos.visualization.plot_history.cycle: The cycle dependence of all data can be plotted.
nimsos.visualization.plot_history.best: The maximum value in each cycle can be plotted.

Arguments

input_file: Specify the file “res_history” that contains the history.
num_cycles: Specify the number of cycles “CyclesNum”. Of course, you can also directly specify a numerical value.

Specifically, set as follows.

nimsos.visualization.plot_history.cycle(input_file = res_history,
                                        num_cycles = CyclesNum)

nimsos.visualization.plot_history.best(input_file = res_history,
                                       num_cycles = CyclesNum)

Distributions of objective functions

Using nimsos.visualization.plot_distribution.plot , the distributions of objective functions are obtained. If the objective function is one dimensional, it is output as a histogram. If the objective function is two or three dimensional, it is output as a scatter plot. For four or more dimensions, no plot is output.

Arguments

input_file: Specify the file “res_history” that contains the history.
num_objectives: Specify the number of objective functions “ObjectivesNum”. Of course, you can also directly specify a numerical value.

Specifically, set as follows.

nimsos.visualization.plot_distribution.plot(input_file = candidates_file,
                                            num_objectives = ObjectivesNum)

Predicted phase diagram

Using nimsos.visualization.plot_phase_diagram.plot , the predicted phase diagrams are obtained.

This can be used when “PDC” is used as the AI method. If the descriptor has one dimension or four or more dimensions, no plot is output.

Arguments

input_file: Specify the file stored experimental conditions, that is, “candidates_file”.

Specifically, set as follows.

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

Usage of original module

Preparation of `ai_tool_original.py`

If we want to use original AI method, create a ai_tool_original.py and put it in the same folder containing the main script. To create it, the most basic module ai_tool_re.py should be rewritten appropriately. If ORIGINAL is used as the class name, this module can also be used in the GUI version.

class ORIGINAL():

Specifically, set as follows.

import ai_tool_original
ai_tool_original.ORIGINAL(input_file = candidates_file,
                          output_file = proposals_file,
                          num_objectives = ObjectivesNum,
                          num_proposals = ProposalsNum).select()

Preparation of `preparation_input_original.py`

If we want to use original robotic system, create a preparation_input_original.py and put it in the same folder containing the main script. To create it, the most basic module preparation_input_standard.py should be rewritten appropriately. If ORIGINAL is used as the class name, this module can also be used in the GUI version.

class ORIGINAL():

Specifically, set as follows.

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

Preparation of `analysis_output_original.py`

If we want to use original robotic system, create a analysis_output_original.py and put it in the same folder containing the main script. To create it, the most basic module analysis_output_standard.py should be rewritten appropriately. If ORIGINAL is used as the class name, this module can also be used in the GUI version.

class ORIGINAL():

Specifically, set as follows.

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

Basic Usage

Import

Definition of parameters

Preparation of candidates file

Proposals file by AI

Storage of data for robotic experiments

Execution of AI

Arguments

Creation of input files for robotic experiments and execution of robotic experiments

Arguments

Analysis of results by robotic experiments and update of candidates files

Arguments

Storing and updating results history

Arguments

Visualization of results

Visualization of history

Arguments

Distributions of objective functions

Arguments

Predicted phase diagram

Arguments

Usage of original module

Preparation of ai_tool_original.py

Preparation of preparation_input_original.py

Preparation of analysis_output_original.py

Preparation of `ai_tool_original.py`

Preparation of `preparation_input_original.py`

Preparation of `analysis_output_original.py`