Chapter 2: NIMO Architecture

Learning Objectives

• Understand NIMO's three-layer modular architecture
• Learn about the CSV-based data flow between components
• Master the core workflow functions: selection(), preparation_input(), analysis_output()
• Understand how AI, Robot, and Visualization modules interact

2.1 The Three-Layer Architecture

NIMO is designed with a clean separation of concerns into three main layers. This modular approach allows researchers to mix and match different AI algorithms with various robotic systems.

Layer 1: AI Optimization Module

This layer contains 11 different algorithms for selecting the next experiment candidates:

Layer 2: Robot Interface Module

This layer handles communication with physical robotic systems:

• STAN: Standard interface for general-purpose robots
• NAREE: Specialized for electrochemistry experiments at NIMS
• COMBAT: Custom interface for user-defined robot systems

Layer 3: Visualization Module

This layer provides tools for monitoring and analyzing optimization progress:

• plot_history: Track the best objective value over iterations
• plot_distribution: Visualize the distribution of sampled points
• plot_phase_diagram: Generate phase diagrams for multi-component systems

2.2 CSV-Based Data Flow

NIMO uses CSV files as the universal interface between all components. This design choice provides several benefits:

• Transparency: You can inspect and edit data at any step
• Portability: Works with any system that can read/write CSV
• Debugging: Easy to identify issues by examining intermediate files
• Flexibility: Supports both simulated and real experiments

CSV File Format

All CSV files in NIMO follow a consistent format:

x1,x2,x3,objective
0.1,0.5,0.4,NaN
0.2,0.4,0.4,NaN
0.3,0.3,0.4,1.25
0.4,0.2,0.4,NaN
0.5,0.1,0.4,2.31

2.3 Core Workflow Functions

NIMO provides four main functions that form the complete optimization loop:

1. selection() - Choose Next Experiments

This function uses an AI algorithm to select the most promising candidates from the untested pool.

import nimo

# Select candidates using Bayesian Optimization
nimo.selection(
    method="PHYSBO",           # AI algorithm to use
    input_file="candidates.csv",   # File with all candidates
    output_file="proposals.csv",   # Selected candidates output
    num_objectives=1,          # Number of objective functions
    num_proposals=3            # How many candidates to select
)

Parameters explained:

• method: Which AI algorithm to use (see table above)
• input_file: CSV containing all candidates with current results
• output_file: Where to write the selected candidates
• num_objectives: 1 for single-objective, 2+ for multi-objective
• num_proposals: Number of experiments to propose per cycle

2. preparation_input() - Prepare for Robot

This function converts the selected proposals into the format required by the robot system.

import nimo

# Prepare proposals for the STAN robot interface
nimo.preparation_input(
    machine="STAN",            # Robot system type
    input_file="proposals.csv",    # Selected candidates
    output_file="robot_input.csv"  # Robot-ready format
)

3. analysis_output() - Process Robot Results

After the robot executes experiments, this function processes the results back into NIMO format.

import nimo

# Process results from the robot
nimo.analysis_output(
    machine="STAN",            # Robot system type
    input_file="robot_output.csv", # Raw robot results
    output_file="results.csv"      # Processed results
)

4. history() - Track Progress

This function provides a record of the optimization history.

import nimo

# Get optimization history
history_data = nimo.history(
    input_file="candidates.csv",
    num_objectives=1
)

print("Best value found:", history_data['best_objective'])
print("Number of experiments:", history_data['num_experiments'])

2.4 Complete Workflow Example

Let's see how all the pieces fit together in a typical optimization cycle:

import nimo
import pandas as pd

# Configuration
NUM_CYCLES = 10
PROPOSALS_PER_CYCLE = 3

# Initialize: create candidates file with search space
candidates = pd.DataFrame({
    'x1': [i/10 for i in range(11)],
    'x2': [1 - i/10 for i in range(11)],
    'objective': [float('nan')] * 11
})
candidates.to_csv('candidates.csv', index=False)

# Main optimization loop
for cycle in range(NUM_CYCLES):
    print(f"\n=== Cycle {cycle + 1} ===")

    # Step 1: Select candidates
    if cycle == 0:
        # First cycle: use random selection
        method = "RE"
    else:
        # Later cycles: use Bayesian Optimization
        method = "PHYSBO"

    nimo.selection(
        method=method,
        input_file="candidates.csv",
        output_file="proposals.csv",
        num_objectives=1,
        num_proposals=PROPOSALS_PER_CYCLE
    )

    # Step 2: Prepare for robot
    nimo.preparation_input(
        machine="STAN",
        input_file="proposals.csv",
        output_file="robot_input.csv"
    )

    # Step 3: [Robot executes experiments here]
    # In simulation, we would calculate objective values
    # In real experiments, robot_output.csv is generated by the robot

    # Step 4: Process results
    nimo.analysis_output(
        machine="STAN",
        input_file="robot_output.csv",
        output_file="results.csv"
    )

    # Step 5: Update candidates file with new results
    # (NIMO handles this internally)

    print(f"Completed {PROPOSALS_PER_CYCLE} experiments")

Exercises

x1,x2,objective
0.2,0.8,NaN
0.5,0.5,1.5
0.8,0.2,NaN

Summary

• NIMO uses a three-layer architecture: AI, Robot, and Visualization
• CSV files serve as the universal data format between components
• Four core functions: selection(), preparation_input(), analysis_output(), history()
• The modular design allows mixing different AI algorithms with various robot systems
• Each cycle: Select → Prepare → Execute → Analyze → Repeat