AI Tool Modules

This page lists the search algorithm modules available in NIMO. Each module can be specified via the method argument of the nimo.selection function, or imported and used directly.

BLOX: Boundless Objective-Free Exploration 

Overview

ai_tool_blox.py implements the BLOX algorithm. Rather than maximizing an objective function, it efficiently explores uncharted regions using Stein Novelty as a measure of diversity in the objective function space. It is suited for “objective-free exploration,” where no objective function is defined in advance.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives
`num_proposals`	int	Number of proposals per cycle
`output_res`	bool	If `True` , outputs predicted values and acquisition function values to `output_res.csv`

License and Citation

License: MIT

If you use BLOX, please cite the following paper.

Kei Terayama, Masato Sumita, Ryo Tamura, Daniel T. Payne, Mandeep K. Chahal, Shinsuke Ishihara, and Koji Tsuda, Pushing property limits in materials discovery via boundless objective-free exploration, Chemical Science 11, 5959-5968 (2020). Available from https://pubs.rsc.org/en/content/articlelanding/2020/SC/d0sc00982b.

Example

import ai_tool_blox
ai_tool_blox.BLOX(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 2,
    num_proposals = 2,
    output_res = False
).select()

BOMP: Bayesian Optimization with Material Process 

Overview

ai_tool_bomp.py implements BOMP (Bayesian Optimization with Material Process). In addition to standard Bayesian optimization using PHYSBO, it performs process-constrained Bayesian optimization by fixing the process parameters specified by process_X and optimizing the remaining parameter space.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives
`num_proposals`	int	Number of proposals per cycle
`physbo_score`	str	Acquisition function. Choose from `'TS'` , `'EI'` , `'PI'` . If `None` , `'EI'` is used for single-objective and `'TS'` for multi-objective
`minimization`	bool	If `True` , treats as a minimization problem. If `None` , defaults to `False`
`process_X`	list	Index list of process parameters to fix
`output_res`	bool	If `True` , outputs prediction results to `output_res.csv`
`training_res`	bool	If `True` , outputs prediction results for training data to `training_res.csv`

Example

import ai_tool_bomp
ai_tool_bomp.BOMP(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 1,
    num_proposals = 2,
    physbo_score = "EI",
    minimization = False,
    process_X = [0, 1],
    output_res = False,
    training_res = False
).select()

COMBI: Composition-Spread Exploration 

Overview

ai_tool_combi.py implements the COMBI (Combinatorial) method. It first determines the best composition point using Bayesian optimization, then proposes a set of candidates (composition spread) by continuously varying the composition between specified element pairs starting from that point, and also proposes the element pair with the highest potential among them. This method is suited for combinatorial experiments.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives
`num_proposals`	int	Number of proposals per cycle (number of divisions in the composition spread)
`physbo_score`	str	Acquisition function. Choose from `'TS'` , `'EI'` , `'PI'` , `'RE'`
`minimization`	bool	If `True` , treats as a minimization problem. If `None` , defaults to `False`
`combi_ranges`	list	Composition range for each element `[[min, max], ...]`
`spread_elements`	list	Index list of element pairs for composition spread `[[i, j], ...]`

License and Citation

If you use COMBI, please cite the following paper.

Ryo Toyama, Ryo Tamura, Shoichi Matsuda, Yuma Iwasaki, and Yuya Sakuraba, Autonomous closed-loop exploration of composition-spread films for the anomalous Hall effect, npj Computational Materials 11, 329 (2025). Available from https://www.nature.com/articles/s41524-025-01828-7.

Example

import ai_tool_combi
ai_tool_combi.COMBI(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 1,
    num_proposals = 5,
    physbo_score = "EI",
    minimization = False,
    combi_ranges = [[0, 100], [0, 100], [0, 100]],
    spread_elements = [[0, 1], [1, 2], [0, 2]]
).select()

DOE: Design of Experiments 

Overview

ai_tool_doe.py is a module based on Design of Experiments (DOE). It selects experimental conditions that uniformly cover the search space, using criteria such as distance from existing observations or matrix determinants. Four modes are available: greedy , distance , d_optimal , and lhs.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives
`num_proposals`	int	Number of proposals per cycle
`mode`	str	Sampling mode. Choose from `'greedy'` , `'distance'` , `'d_optimal'` , `'lhs'` . If `None` , defaults to `'distance'`
`max_iter`	int	Number of iterations for the Exchange Algorithm. If `None` , defaults to `1000`

Example

import ai_tool_doe
ai_tool_doe.DOE(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 1,
    num_proposals = 2,
    mode = "distance",
    max_iter = 1000
).select()

ES: Exhaustive Search 

Overview

ai_tool_es.py implements Exhaustive Search. It proposes num_proposals candidates in order from the top of the candidates file. Useful when you want to experiment on all candidates in sequence, or when the number of candidates is small.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives
`num_proposals`	int	Number of proposals per cycle

Example

import ai_tool_es
ai_tool_es.ES(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 1,
    num_proposals = 2
).select()

LLMEP: LLM-based Experimental Planner 

Overview

ai_tool_llmep.py is a module for experimental proposal using a Large Language Model (LLM-based Experimental Planner).

The user provides a candidate list and experimental context via Markdown prompt files. The LLM performs multiple independent selection runs with diverse exploration strategies and determines the final proposals through majority voting. Objective values are not limited to numerical data — phase names, crystal structures, and other categorical or text-based values are also supported. This makes the module applicable to a wide range of problems including phase diagram construction, property optimization, and process exploration.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidate file (CSV format; the rightmost `num_objectives` columns are treated as objective values)
`output_file`	str	Path to the proposals output file
`num_objectives`	int	Number of objective columns
`num_proposals`	int	Number of proposals per cycle
`prompt_file`	str	Path to the Markdown file describing the experimental background and objectives
`system_prompt_file`	str	Path to the Markdown file defining the LLM’s expert role
`model`	str	Anthropic model ID to use
`num_runs`	int	Number of independent selection runs for majority voting (default: `10`)
`log_file`	str	Path to the Markdown log file for saving the selection process (optional)
`api_key`	str	Anthropic API key
`max_tokens`	int	Maximum number of tokens in the LLM response (default: `8192`)

Input File Format

The rightmost num_objectives columns of the CSV file are treated as objective values; all other columns are treated as descriptors. Both descriptors and objective values accept numeric, categorical, and free-text data. Rows that have not yet been measured should have empty objective columns.

Co,Al,Ge,phase
5,0.25,0.25,B2 CoAl(Ge)
5,0.0,0.5,
8,0.0,0.2,

Dependencies

pip install anthropic numpy

Prompt Files

prompt_file is a free-form Markdown file describing the experimental background, objectives, and constraints. The candidate table is automatically injected by the module and does not need to be included in the prompt.

Example for phase diagram construction (prompt.md)

We want to construct a ternary phase diagram of the Co-Al-Ge system at 900 degC.
Select 8 compositions for the next round of experiments.

Example for property optimization (prompt.md)

We are searching for superconducting materials with high critical temperature (Tc).
The `Tc` column shows the measured critical temperature in Kelvin. Higher Tc is better.
Select 8 candidates likely to have high Tc, balancing exploitation and exploration.

system_prompt_file defines the expert role of the LLM.

Example for phase diagram construction (system.md)

You are an expert materials scientist specializing in alloy phase diagram construction.
Your task is to select the most informative experimental compositions from a candidate list
to efficiently map an unknown phase diagram.

Usage

import ai_tool_llmep
ai_tool_llmep.LLMEP(
    input_file         = "candidates.csv",
    output_file        = "proposals.csv",
    num_objectives     = 1,
    num_proposals      = 8,
    prompt_file        = "prompt.md",
    system_prompt_file = "system.md",
    model              = "claude-opus-4-6",
    num_runs           = 10,
    log_file           = "log.md",
    api_key            = "your-api-key-here",
).select()

NTS: Nested Thompson Sampling 

Overview

ai_tool_nts.py implements NTS (Nested Thompson Sampling). It sets a threshold based on the maximum value of observed objectives and preferentially selects candidates with a high probability of exceeding that threshold. The strictness of the threshold can be adjusted via sample_mode.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives (currently only `1` is supported)
`num_proposals`	int	Number of proposals per cycle
`sample_mode`	str	Threshold scale mode. Choose from `'aggressive'` (0.99), `'moderate'` (0.95), `'conservative'` (0.9)
`minimization`	bool	If `True` , treats as a minimization problem. If `None` , defaults to `False` (maximization)
`use_dpp`	bool	If `True` , uses DPP to account for diversity within a batch
`re_seed`	int	Random seed
`output_res`	bool	If `True` , outputs predicted values, variance, and acquisition function values to `output_res.csv`

Example

import ai_tool_nts
ai_tool_nts.NTS(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 1,
    num_proposals = 2,
    sample_mode = "moderate",
    minimization = False,
    use_dpp = False,
    re_seed = 0,
    output_res = False
).select()

PDC: Phase Diagram Construction 

Overview

ai_tool_pdc.py is a module for efficient Phase Diagram Construction. It predicts the phase of each experimental condition using label propagation (Label Propagation / Label Spreading) and prioritizes exploration of high-uncertainty regions to construct phase diagrams efficiently.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives (number of phase label columns). Only `1` is supported for PDC
`num_proposals`	int	Number of proposals per cycle
`pdc_estimation`	str	Phase estimation algorithm. `'LP'` (Label Propagation) or `'LS'` (Label Spreading). If `None` , defaults to `'LP'`
`pdc_sampling`	str	Sampling strategy. Choose from `'LC'` (Least Confidence), `'MS'` (Margin Sampling), `'EA'` (Entropy). If `None` , defaults to `'LC'`
`output_res`	bool	If `True` , outputs predicted probabilities for each phase to `output_res.csv`

License and Citation

License: MIT

If you use PDC, please cite the following papers.

Kei Terayama, Ryo Tamura, Yoshitaro Nose, Hidenori Hiramatsu, Hideo Hosono, Yasushi Okuno, and Koji Tsuda, Efficient construction method for phase diagrams using uncertainty sampling, Physical Review Materials 3, 033802 (2019). Available from https://journals.aps.org/prmaterials/abstract/10.1103/PhysRevMaterials.3.033802.

Ryo Tamura, Guillaume Deffrennes, Kwangsik Han, Taichi Abe, Haruhiko Morito, Yasuyuki Nakamura, Masanobu Naito, Ryoji Katsube, Yoshitaro Nose, and Kei Terayama, Machine-learning-based phase diagram construction for high-throughput batch experiments, Science and Technology of Advanced Materials: Methods 2, 153-161 (2022). Available from https://www.tandfonline.com/doi/full/10.1080/27660400.2022.2076548.

Example

import ai_tool_pdc
ai_tool_pdc.PDC(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 1,
    num_proposals = 2,
    pdc_estimation = "LP",
    pdc_sampling = "LC",
    output_res = False
).select()

PHYSBO: Bayesian Optimization 

Overview

ai_tool_physbo.py is a Bayesian optimization module using the PHYSBO package. It supports both single-objective and multi-objective optimization. Acquisition functions TS (Thompson Sampling), EI (Expected Improvement), and PI (Probability of Improvement) are available.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives
`num_proposals`	int	Number of proposals per cycle
`physbo_score`	str	Acquisition function. For single-objective, choose from `'TS'` , `'EI'` , `'PI'` . For multi-objective, choose from `'TS'` , `'HVPI'` , `'EHVI'` . If `None` , `'EI'` is used for single-objective and `'TS'` for multi-objective
`minimization`	bool	If `True` , treats as a minimization problem. If `None` , defaults to `False` (maximization)
`output_res`	bool	If `True` , outputs predicted values, variance, and acquisition function values to `output_res.csv`
`training_res`	bool	If `True` , outputs prediction results for training data to `training_res.csv`

License and Citation

License: Mozilla Public License version 2.0 (MPL v2)

If you use PHYSBO, please cite the following paper.

Yuichi Motoyama, Ryo Tamura, Kazuyoshi Yoshimi, Kei Terayama, Tsuyoshi Ueno, and Koji Tsuda, Bayesian optimization package: PHYSBO, Computer Physics Communications 278, 108405 (2022). Available from https://www.sciencedirect.com/science/article/pii/S0010465522001242?via%3Dihub.

Example

import ai_tool_physbo
ai_tool_physbo.PHYSBO(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 1,
    num_proposals = 2,
    physbo_score = "EI",
    minimization = False,
    output_res = False,
    training_res = False
).select()

PTR: Probability of Target Range 

Overview

ai_tool_ptr.py implements PTR (Probability of Target Range). It predicts each objective function using Gaussian process regression and proposes the experimental condition that maximizes the probability of falling within a user-specified target range. Different target ranges can be set for each objective function in multi-objective optimization.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives
`num_proposals`	int	Number of proposals per cycle
`ptr_ranges`	list	Target range for each objective in the format `[[lower1, upper1], [lower2, upper2], ...]`. Specifying `'max'` or `'min'` uses the observed maximum or minimum value
`output_res`	bool	If `True` , outputs predicted values and acquisition function values to `output_res.csv`

License and Citation

If you use PTR, please cite the following paper.

Akira Takahashi, Kei Terayama, Yu Kumagai, Ryo Tamura, and Fumiyasu Oba, Fully autonomous materials screening methodology combining first-principles calculations, machine learning and high-performance computing system, Science and Technology of Advanced Materials: Methods 3, 1, 2261834 (2023). Available from https://www.tandfonline.com/doi/full/10.1080/27660400.2023.2261834.

Example

import ai_tool_ptr
ai_tool_ptr.PTR(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 2,
    num_proposals = 2,
    ptr_ranges = [[10.0, 20.0], [0.5, 1.0]],
    output_res = False
).select()

RE: Random Exploration 

Overview

ai_tool_re.py implements Random Exploration. It randomly selects experimental conditions from untested candidates. Useful as an initial search or as a baseline for comparison with other methods.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives
`num_proposals`	int	Number of proposals per cycle
`process_X`	list	Index list of process parameters. If `None` , not used
`re_seed`	int	Random seed. If `None` , seed is not fixed

Example

import ai_tool_re
ai_tool_re.RE(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 1,
    num_proposals = 2,
    process_X = None,
    re_seed = 0
).select()

RSVM: Ranking Support Vector Machine 

Overview

ai_tool_rsvm.py implements RSVM (Ranking Support Vector Machine). Rather than the absolute values of objective functions, it learns the ordinal relationships (ranking information) of observed data and predicts scores for unobserved data to select experimental conditions. By adding external datasets via other_datasets , ranking information from other material systems can be leveraged in a transfer learning fashion.

Arguments

Argument	Type	Description
`input_file`	str	Path to the candidates file
`output_file`	str	Path to the proposals file
`num_objectives`	int	Number of objectives
`num_proposals`	int	Number of proposals per cycle
`other_datasets`	list	List of paths to external datasets for transfer learning. Use an empty list `[]` if not used
`minimization`	bool	If `True` , treats as a minimization problem. If `None` , defaults to `False`
`output_res`	bool	If `True` , outputs predicted scores to `output_res.csv`

License and Citation

If you use RSVM, please cite the following paper.

Weilin Yuan, Yusuke Hibi, Ryo Tamura, Masato Sumita, Yasuyuki Nakamura, Masanobu Naito, and Koji Tsuda, Revealing factors influencing polymer degradation with rank-based machine learning, Patterns 4, 100846 (2023). Available from https://linkinghub.elsevier.com/retrieve/pii/S2666389923002258.

Example

import ai_tool_rsvm
ai_tool_rsvm.RSVM(
    input_file = "candidates.csv",
    output_file = "proposals.csv",
    num_objectives = 1,
    num_proposals = 2,
    other_datasets = [],
    minimization = False,
    output_res = False
).select()