Bgolearn Documentation

Note

Welcome to the comprehensive documentation for Bgolearn - a powerful Bayesian Global Optimization package designed specifically for materials discovery and scientific research.

🎯 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

Acknowledgment

The Bgolearn project received funding from the Shanghai Artificial Intelligence Open Source Award Project Support Plan (上海市人工智能开源奖励项目支持计划, 2025), with special thanks to Prof. Jie Xiong and Prof. Tong-Yi Zhang from Shanghai University for their support and guidance.

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{cao2024active,
  title={Active learning accelerates the discovery of high strength and high ductility lead-free solder alloys},
  author={Cao, Bin and Su, Tianhao and Yu, Shuting and Li, Tianyuan and Zhang, Taolue and Zhang, Jincang and Dong, Ziqiang and Zhang, Tong-Yi},
  journal={Materials \& Design},
  volume={241},
  pages={112921},
  year={2024},
  publisher={Elsevier}
}

📜 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! 🚀