ml-bayesian-optimization

Files (30)

• SKILL.md
• README.md · examples/branin-function/
• campaign_state.json · examples/branin-function/
• candidates_round_0.csv · examples/branin-function/
• candidates_round_1.csv · examples/branin-function/
• candidates_round_2.csv · examples/branin-function/
• candidates_round_3.csv · examples/branin-function/
• candidates_round_4.csv · examples/branin-function/
• candidates_round_5.csv · examples/branin-function/
• candidates_round_6.csv · examples/branin-function/
• candidates_round_7.csv · examples/branin-function/
• convergence_curve.png · examples/branin-function/
• evaluated.csv · examples/branin-function/
• gp_model_2d.png · examples/branin-function/
• parameter_importance.png · examples/branin-function/
• search_space.yaml · examples/branin-function/
• README.md · examples/li-ag-phases/
• campaign_state.json · examples/li-ag-phases/
• candidates_round_0.csv · examples/li-ag-phases/
• candidates_round_1.csv · examples/li-ag-phases/
• candidates_round_2.csv · examples/li-ag-phases/
• convergence_curve.png · examples/li-ag-phases/
• evaluated.csv · examples/li-ag-phases/
• gp_model_1d.png · examples/li-ag-phases/
• li_ag_phases.csv · examples/li-ag-phases/
• parameter_importance.png · examples/li-ag-phases/
• search_space.yaml · examples/li-ag-phases/
• search_space_template.yaml · resources/
• plot_bo_results.py · scripts/
• suggest_candidates.py · scripts/

SKILL.md (first lines)

# Bayesian Optimization

<!-- mcp-tools-note -->
> [!NOTE]
> Steps written `server.tool` are MCP tool calls: `mace.relax_structure` is the `relax_structure`
> tool of the `mace` server (`mcp__mace__relax_structure`, or
> `mcp__plugin_atomistic-skills_mace__relax_structure` when installed as a plugin).
> Without a connected server, run the same tools from the shell. Tools named in
> one command share a process, so a model loaded by `load_model` stays loaded:
>
> ```bash
> ${CLAUDE_SKILL_DIR}/../../venv/run mlip python -m src.mcp_server.cli mace relax_structure key=value predict_structure key=value
> ${CLAUDE_SKILL_DIR}/../../venv/run mlip python -m src.mcp_server.cli matgl relax_structure key=value predict_structure key=value
> ${CLAUDE_SKILL_DIR}/../../venv/run cpu python -m src.mcp_server.cli atomate2 run_atomate2_vasp_calculation key=value
> ${CLAUDE_SKILL_DIR}/../../venv/run cpu python -m src.mcp_server.cli base visualize_structure key=value
> ```

## Goal
Efficiently find the optimal input parameters (e.g., alloy composition, simulation hyperparameters, process conditions) that minimize or maximize one or more expensive black-box objectives (e.g., formation energy, bandgap, elastic modulus) using Bayesian Optimization (BO). BO builds a probabilistic surrogate model (Gaussian Process) over the objective landscape and uses an acquisition function to intelligently select the next most informative experiments, minimizing the number of expensive evaluations required.

- **Single-objective**: Expected Improvement (EI) maximized via multi-start L-BFGS-B.
- **Multi-objective**: ParEGO — random Chebyshev scalarization with independent GPs, one weight vector per batch element, naturally steering candidates toward different Pareto-front regions.

---

## Instructions

### Step 1: Define the Search Space

Create a `search_space.yaml` in the research directory. Use the template at `resources/search_space_template.yaml` as a starting point:

```yaml
# research_dir/search_space.yaml

parameters:
  # Continuous range parameter
  - name: x_Fe
    type: range
    bounds: [0.0, 1.0]
    value_type: float

  # Integer range parameter
  - name: supercell_size
    type: range
    bounds: [2, 6]
    value_type: int

objectives:
  # Single-objective: minimize formation energy
  - name: formation_energy_eV_atom
    minimize: true

  # Multi-objective: additionally maximize bandgap (uncomment to enable)
  # - name: bandgap_eV
  #   minimize: false
```

**Guidelines:**
- Use `type: range` for continuous or integer parameters with known bounds. Only `range` parameters are passed to the GP surrogate.
- `choice` and `fixed` types are recorded in output CSVs but not optimized. Run separate campaigns per discrete choice.
- Choose bounds informed by domain knowledge; avoid unnecessarily wide ranges.

### Step 2: Initialize with Quasi-Random Sobol Samples

Generate an initial space-filling design using Sobol sequences. Use a power-of-2 `batch_size` (4, 8, 16, …) for optimal Sobol balance:

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/suggest_candidates.py \
    --config research_dir/search_space.yaml \
    --batch_size 8 \
    --output research_dir/candidates_round_0.csv \
    --output_dir research_dir/
```

With no `--results` provided (or fewer than `2 × N_range_params` evaluated points), the script automatically uses Sobol initialization. The output CSV lists candidate parameter values only — it does **not** evaluate the objective.

### Step 3: Evaluate Candidates Using MCP Tools

For each row in `candidates_round_0.csv`, call the appropriate MCP tool to evaluate the objective and record results. The script plays no role in this step.

| Objective type | Recommended MCP tool |
|---|---|
| Energy / formation energy | `mace.relax_structure` or `matgl.relax_structure` |
| Bandgap | No MLIP tool: matgl withdrew its bandgap model and publishes no replacement — evaluate with `atomate2.run_atomate2_vasp_calculation` instead |
| Arbitrary property | `mace.predict_structure` |
| DFT reference | `atomate2.run_atomate2_vasp_calculation` |

Save all results to `evaluated.csv` — one row per candidate, parameter columns plus objective column(s):

```
x_Fe,formation_energy_eV_atom
0.12,-0.087
0.45,-0.143
0.73,-0.091
```

### Step 4: BO Loop — Suggest Next Candidates

With evaluated results, fit the GP surrogate and suggest the next batch:

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/suggest_candidates.py \
    --config research_dir/search_space.yaml \
    --results research_dir/evaluated.csv \
    --batch_size 4 \
    --output research_dir/candidates_round_1.csv \
    --output_dir research_dir/
```

The script will:
1. Normalize all inputs to [0, 1] per dimension.
2. Fit a GP with Matern-5/2 kernel (scikit-learn, `normalize_y=True`).
3. Single-objective: maximize EI via multi-start L-BFGS-B with diversity enforcement.
4. Multi-objective: fit one GP per batch element with a random Chebyshev weight vector (ParEGO).
5. Write the next `batch_size` candidates to the output CSV.
6. Append round metadata to `campaign_state.json` in `--output_dir`.

**Repeat Steps 3–4** until the budget is exhausted or convergence is observed.

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills