Bgolearn

Bgolearn is a Bayesian global optimization package for accelerating materials discovery. It provides practical optimization workflows for costly experiments, including regression-based candidate recommendation, classification boundary exploration, cross-validation diagnostics, and several acquisition functions.

Author and maintainer: Dr.Bin Cao (https://bin-cao.github.io/)

Documentation: https://bgolearn.netlify.app/

Repository: https://github.com/Bin-Cao/Bgolearn

Features

• Bayesian global optimization for materials design and discovery.
• Single-objective minimization and maximization workflows.
• Classification-mode active learning for decision-boundary exploration.
• Acquisition functions including EI, EI with plugin, augmented EI, EQI, UCB, PoI, PES, and Knowledge Gradient.
• Built-in surrogate choices for SVM, Random Forest, AdaBoost, and MLP models.
• Gaussian process modeling with homogeneous or heterogeneous noise support.
• Optional cross-validation reports and virtual-sample prediction exports.

Installation

pip install Bgolearn

For local development from this repository:

pip install -e .

Quick Start

import pandas as pd

from Bgolearn.BGOsampling import Bgolearn

data = pd.read_csv("data.csv")
virtual_samples = pd.read_csv("virtual_data.csv")

X = data.iloc[:, :-1]
y = data.iloc[:, -1]

optimizer = Bgolearn()
model = optimizer.fit(
    data_matrix=X,
    Measured_response=y,
    virtual_samples=virtual_samples,
    Mission="Regression",
    min_search=True,
)

scores, candidates = model.EI()
print(candidates)

HTML Experiment Report

Fit the optimizer, then generate a self-contained report after selecting an acquisition function:

model = optimizer.fit(
    data_matrix=X,
    Measured_response=y,
    virtual_samples=virtual_samples,
    CV_test=5,
)

report_path = model.HTML_report("EI")
print(report_path)

HTML_report writes an offline HTML file in Bgolearn/Reports/. It includes the model summary, cross-validation diagnostics, the embedded prediction plot, recommended experiments, and the full utility ranking. Reports are generated automatically whenever a regression utility such as model.EI() or model.UCB() is called. Set Generate_HTML_report=False to disable this behavior.

Main API

Bgolearn.fit

Fits a Bayesian optimization workflow and returns an acquisition-function model.

Common parameters:

• data_matrix: measured feature matrix.
• Measured_response: measured target values.
• virtual_samples: candidate samples to rank.
• Mission: "Regression" or "Classification".
• Kriging_model: None, a built-in model name, or a custom model class with a fit_pre method.
• opt_num: number of candidates to recommend.
• min_search: True for minimization and False for maximization.
• CV_test: False, "LOOCV", or an integer for k-fold cross-validation.

Custom Surrogate Model

from sklearn.gaussian_process import GaussianProcessRegressor
from sklearn.gaussian_process.kernels import RBF


class CustomKrigingModel:
    def fit_pre(self, xtrain, ytrain, xtest):
        model = GaussianProcessRegressor(kernel=RBF(), normalize_y=True)
        model.fit(xtrain, ytrain)
        mean, std = model.predict(xtest, return_std=True)
        return mean, std

Use it with:

model = optimizer.fit(
    data_matrix=X,
    Measured_response=y,
    virtual_samples=virtual_samples,
    Kriging_model=CustomKrigingModel,
)

Classification Mode

model = optimizer.fit(
    data_matrix=X,
    Measured_response=labels,
    virtual_samples=virtual_samples,
    Mission="Classification",
    Classifier="RandomForest",
)

scores, candidates = model.Entropy()

Available classifiers include GaussianProcess, LogisticRegression, NaiveBayes, SVM, and RandomForest.

Citation

If Bgolearn supports your research, please cite:

Cao B. et al., "Bgolearn: A Unified Bayesian Optimization Framework for Accelerating Materials Discovery", npj Computational Materials. https://doi.org/10.1038/s41524-026-02226-3

Support

Questions, issues, pull requests, and research collaborations are welcome.

Contact: bcao686@connect.hkust-gz.edu.cn