Metadata-Version: 2.4
Name: MultiBgolearn
Version: 0.1.1
Summary: Python package designed for multi-objective Bayesian global optimization (MOBO)
Home-page: https://github.com/Bin-Cao/MultiBgolearn
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: scikit-learn
Requires-Dist: openpyxl
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

# MultiBgolearn

MultiBgolearn is a Python package for multi-objective Bayesian global optimization
(MOBO), with a focus on materials design tasks where several properties must be
optimized at the same time.

The package extends the idea of Bgolearn from single-objective optimization to
multi-objective optimization. It is suitable for candidate recommendation
problems that require balancing competing objectives, such as maximizing one
material property while minimizing or constraining another.

## Features

- Multi-objective Bayesian global optimization workflow.
- Support for common acquisition strategies, including `EHVI`, `PI`, `UCB`, and
  `qNEHVI`.
- Automatic model comparison using leave-one-out cross-validation.
- Surrogate models based on scikit-learn regressors.
- Candidate recommendation from a virtual search space.
- Prediction result export and model-performance visualization.

## Basic Usage

```python
from MultiBgolearn.bgo import fit

recommended_data, improvements, index = fit(
    dataset="./data/dataset.csv",
    VSdataset="./data/virtual_space.csv",
    object_num=3,
    max_search=True,
    method="EHVI",
    bootstrap=5,
)
```

## Input Data

`dataset` should be a `.csv`, `.xlsx`, or `.xls` file. Feature columns should
come first, followed by the objective columns. The number of objective columns is
specified by `object_num`.

`VSdataset` should contain the candidate virtual search space. If the candidate
space contains more than 20,000 rows, MultiBgolearn samples 20,000 candidates
with a fixed random seed before recommendation.

## Main Parameters

- `dataset`: path to the observed training dataset.
- `VSdataset`: path to the virtual search-space dataset.
- `object_num`: number of objective columns in `dataset`.
- `max_search`: `True` for maximization and `False` for minimization.
- `method`: acquisition method, such as `EHVI`, `PI`, `UCB`, or `qNEHVI`.
- `assign_model`: optional model name. If not provided, MultiBgolearn evaluates
  available models and recommends the best one.
- `bootstrap`: number of bootstrap rounds for uncertainty estimation.
- `batch_size`: number of candidates selected for batch acquisition methods.
- `noise_std`: observation-noise standard deviation for `qNEHVI`.

## Author

Dr. Bin Cao  
Personal homepage: <https://bin-cao.github.io/>  
GitHub: <https://github.com/Bin-Cao/MultiBgolearn>  
Email: [bcao686@connect.hkust-gz.edu.cn](mailto:bcao686@connect.hkust-gz.edu.cn)

For questions, issues, or suggestions, please open an issue on GitHub or contact
the author by email.
