Bgolearn

Note

Welcome to the documentation of Bgolearn : a powerful Bayesian Global Optimization package specifically designed for materials discovery. This document is written and produced by Bin Cao to help new learners master the basics of Bayesian Optimization and use Bgolearn to solve real-world optimization problems.

What is Bgolearn?

Bgolearn is a Python package developed by Bin Cao at Hong Kong University of Science and Technology (Guangzhou) that implements state-of-the-art Bayesian optimization algorithms for both single-objective and multi-objective optimization. It’s particularly powerful for materials discovery, where experiments are costly and time-consuming.

Key Features:

• Single-objective optimization with multiple acquisition functions

• Multi-objective optimization via MultiBgolearn

• Materials-focused design and applications

• Flexible surrogate model selection

• Bootstrap uncertainty quantification

What makes Bgolearn special?

• Materials-focused: Built specifically for materials science workflows

• Parallel experiments: Batch optimization for efficient resource utilization

• Rich visualizations: Interactive plots and optimization dashboards

• Robust & reliable: Comprehensive error handling and data validation

• Easy to use: Simple API with sensible defaults

About

The Bgolearn project is supported by the Shanghai Artificial Intelligence Open Source Award Project Support Plan (上海市人工智能开源奖励项目支持计划, 2025), with a funding of 500,000 RMB. Special thanks to Prof. Jie Xiong and Prof. Tong-Yi Zhang from Shanghai University for their support in this project.

An updated survey of Bgolearn has been published on arXiv, 2026. We express our deep gratitude for the guidance and contributions of Prof. Tong-Yi Zhang (Shanghai University, HKUST(GZ)), Prof. Turab Lookman (Xi’an Jiaotong University), Prof. Dezhen Xue (Xi’an Jiaotong University), Prof. Jie Xiong (Shanghai University), and Prof. Jian Hui (Suzhou Laboratory).

Key Features

Materials Science Focus

Specialized workflows for composition optimization, processing parameter tuning, and multi-objective materials design.

Multiple Acquisition Functions

EI, UCB, PI, PES, KG, etc. for different optimization strategies and experimental constraints.

Batch Optimization

Select multiple experiments for parallel execution, dramatically reducing optimization time and cost.

Advanced Visualization

Interactive plots, optimization dashboards, and materials-specific visualizations for better insights.

Quick Start Example

from Bgolearn import BGOsampling
import pandas as pd
import numpy as np

# Load your materials data
X_train = pd.DataFrame(np.random.randn(20, 3), columns=['Temperature', 'Pressure', 'Composition'])
y_train = pd.Series(np.random.randn(20))  # Target property (e.g., strength)
X_candidates = pd.DataFrame(np.random.randn(100, 3), columns=['Temperature', 'Pressure', 'Composition'])

# Initialize and fit Bgolearn
optimizer = BGOsampling.Bgolearn()
model = optimizer.fit(
    data_matrix=X_train,  # Pass DataFrame directly
    Measured_response=y_train,  # Pass Series directly
    virtual_samples=X_candidates,  # Pass DataFrame directly
    opt_num=1
)

# Get recommendation using Expected Improvement
ei_values, recommended_points = model.EI()

# The recommended point(s)
next_experiment = recommended_points[0]  # First (best) recommendation
print(f"Next recommended experiment: {next_experiment}")

# Get prediction for all virtual samples
predicted_values = model.virtual_samples_mean
print(f"Number of predictions: {len(predicted_values)}")

# Basic visualization using matplotlib
import matplotlib.pyplot as plt

# Plot EI values
plt.figure(figsize=(10, 6))
plt.plot(ei_values)
plt.title('Expected Improvement Values')
plt.xlabel('Candidate Index')
plt.ylabel('EI Value')
plt.show()

Installation

Basic Installation

pip install bgolearn

Development Installation

git clone https://github.com/Bin-Cao/Bgolearn.git
cd Bgolearn
pip install -e .

With Optional Dependencies

# Complete installation with all features
pip install bgolearn[all]

# Or install specific components
pip install bgolearn plotly seaborn  # For advanced visualization
pip install bgolearn pymatgen matminer  # For materials science

Verify Installation

from Bgolearn import BGOsampling
print("Bgolearn imported successfully!")

# Test basic functionality
opt = BGOsampling.Bgolearn()
print("Bgolearn optimizer initialized successfully!")

Documentation Structure

This documentation is organized into several main sections:

Getting Started

Installation, basic concepts, and your first optimization

Perfect for newcomers to Bayesian optimization

Getting Started with Bgolearn

BgoFace GUI

Graphical user interface for visual optimization workflows

No coding required - perfect for materials scientists

BgoFace: Graphical User Interface for Bgolearn

Core Documentation

API reference, acquisition functions, and optimization strategies

Comprehensive guides for all features

API Reference

Applications

Materials discovery workflows and specialized applications

Real-world examples and best practices

Materials Discovery with Bgolearn

Detailed Navigation

Getting Started

• 1. Installation & Quick Start
• 2. Basic Concepts
• 3. Your First Optimization

Single-Objective Optimization

• 4. API Reference
• 5. Acquisition Functions
• 6. Surrogate Models
• 7. Optimization Strategies

Multi-Objective Optimization

• 8. MultiBgolearn Overview
• 9. Multi-Objective Concepts
• 10. MOBO Algorithms
• 11. Pareto Optimization

User Interfaces

• 12. BgoFace GUI

Applications

• 13. Materials Discovery

Examples & Tutorials

• 14. Single-Objective Examples
• 15. Multi-Objective Examples

Learning Paths

Choose your learning path based on your background and goals:

🔰 Beginner Path

New to Bayesian Optimization?

1. Getting Started with Bgolearn - Installation and basic concepts

2. Your First Optimization - Your first optimization tutorial

3. Acquisition Functions Guide - Understanding acquisition functions

4. Single-Objective Optimization Examples - Single-objective examples

🔬 Materials Scientist Path

Focused on materials discovery?

1. Materials Discovery with Bgolearn - Materials discovery overview

2. Single-Objective Optimization Examples - Alloy composition optimization

3. MultiBgolearn: Multi-Objective Bayesian Global Optimization - Multi-objective optimization

4. Multi-Objective Optimization Examples - Multi-property design examples

⚡ Advanced User Path

Ready for advanced features?

1. Optimization Strategies - Advanced optimization strategies

2. Surrogate Models in Bgolearn - Different surrogate models

3. BgoFace: Graphical User Interface for Bgolearn - GUI interface for visual workflows

4. MultiBgolearn: Multi-Objective Bayesian Global Optimization - Multi-objective optimization

Community & Support

Get Help & Connect

• GitHub Discussions: Ask questions and share experiences

• Issues: Report bugs and request features

• Email: binjacobcao@gmail.com

• Documentation: You’re reading it!

🔗 Links

• GitHub Repository

• PyPI Package

• Documentation

Contributing

• Contributing Guide

• Code of Conduct

• Development Setup

Citation

If you use Bgolearn in your research, please cite our work:

@article{cao2026bgolearn,
  title        = {Bgolearn: a Unified Bayesian Optimization Framework for Accelerating Materials Discovery},
  author       = {Cao, Bin and Xiong, Jie and Ma, Jiaxuan and Tian, Yuan and Hu, Yirui and He, Mengwei and Zhang, Longhan and Wang, Jiayu and Hui, Jian and Liu, Li and Xue, Dezhen and Lookman, Turab and Zhang, Tong-Yi},
  journal      = {arXiv preprint arXiv:2601.06820},
  year         = {2026},
  eprint       = {2601.06820},
  archivePrefix= {arXiv},
  primaryClass = {cond-mat.mtrl-sci},
  doi          = {https://doi.org/10.48550/arXiv.2601.06820},
  note         = {38 pages, 5 figures}
}

License

MIT License

Bgolearn is released under the MIT License, making it free for both academic and commercial use. See the full license for details.

---

Ready to accelerate your research? Start here or explore our examples to see Bgolearn in action!