Metadata-Version: 2.4
Name: Bgolearn
Version: 3.1.0
Summary: A Bayesian global optimization package for material design
Home-page: https://github.com/Bin-Cao/Bgolearn
Author: CaoBin
Author-email: bcao686@connect.hkust-gz.edu.cn
Maintainer: CaoBin
Maintainer-email: bcao686@connect.hkust-gz.edu.cn
License: MIT License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: multiprocess
Requires-Dist: art
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
pip install Bgolearn
```

For local development from this repository:

```bash
pip install -e .
```

## Quick Start

```python
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)
```

## 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

```python
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:

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

## Classification Mode

```python
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
