Metadata-Version: 2.4
Name: BgoKit
Version: 0.1.1
Summary: A lightweight multi-objective tool package for Bgolearn
Home-page: https://github.com/Bin-Cao/Bgolearn
Author: Dr.Bin Cao
Author-email: binjacobcao@gmail.com
Maintainer: Dr.Bin Cao
Maintainer-email: binjacobcao@gmail.com
License: MIT
Project-URL: Homepage, https://bin-cao.github.io/
Project-URL: Documentation, https://bgolearn.netlify.app/
Project-URL: Source, https://github.com/Bin-Cao/Bgolearn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: MultiBgolearn
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# BgoKit

BgoKit is a lightweight utility package for multi-objective candidate selection with
Bgolearn. It provides tools for two-objective Pareto-front search, hypervolume-based
selection, and score-distribution visualization.

Author: Dr.Bin Cao  
Website: <https://bin-cao.github.io/>  
Documentation: <https://bgolearn.netlify.app/>  
Repository: <https://github.com/Bin-Cao/Bgolearn>

## Installation

Install the package from PyPI:

```bash
pip install BgoKit
```

Install or upgrade from a local source tree:

```bash
pip install -U .
```

## Requirements

BgoKit requires Python 3.7 or later and depends on:

- `numpy`
- `matplotlib`
- `MultiBgolearn`

## Quick Start

The following example shows how to combine two Bgolearn score arrays and recommend
a candidate from the Pareto front.

```python
import pandas as pd
import Bgolearn.BGOsampling as BGOS
from BgoKit import ToolKit

# Load measured data and virtual samples.
data = pd.read_csv("./data/data.csv")
vs = pd.read_csv("./data/Visual_samples.csv")

# Use the first columns as input features and the final two columns as targets.
x = data.iloc[:, :-2]
y_t = data.iloc[:, -2]
y_e = data.iloc[:, -1]

# Run Bgolearn for two target properties.
bgolearn = BGOS.Bgolearn()

model_t = bgolearn.fit(
    data_matrix=x,
    Measured_response=y_t,
    virtual_samples=vs,
    min_search=False,
)
score_t, rec_t = model_t.UCB()

model_e = bgolearn.fit(
    data_matrix=x,
    Measured_response=y_e,
    virtual_samples=vs,
    min_search=False,
)
score_e, rec_e = model_e.UCB()

# Run BgoKit for multi-objective candidate selection.
model = ToolKit.MultiOpt(vs, [score_t, score_e], names=["Strength", "Elongation"])
candidate = model.BiSearch()
model.plot_distribution()
```

## Main API

### `ToolKit.MultiOpt(vs, scores, names=None)`

Create a multi-objective optimization helper.

- `vs`: virtual samples or candidate feature matrix.
- `scores`: list of score arrays, typically `[score_1, score_2]`.
- `names`: optional objective names used in plot labels.

### `MultiOpt.BiSearch()`

Normalize two score arrays, identify the Pareto front, save Pareto data to
`./Bgolearn/Paretodata.txt`, generate Pareto-front figures, and return the selected
candidate.

### `MultiOpt.HVSearch(y)`

Perform hypervolume-improvement candidate selection for the UCB workflow.

### `MultiOpt.HVSearch_user(y)`

Perform the educational hypervolume-improvement workflow designed for expected
improvement and probability improvement examples.

### `MultiOpt.plot_distribution()`

Plot normalized score distributions for each objective.

## Generated Files

Depending on the selected workflow, BgoKit may create:

- `./Bgolearn/Paretodata.txt`
- `ParetoF.png` and `ParetoF.svg`
- `HV_UCB.png` and `HV_UCB.svg`
- `HV_UCB_NOcandidates.png` and `HV_UCB_NOcandidates.svg`
- `HV_EIorPi.png` and `HV_EIorPi.svg`
- `HV_EIorPi_NOcandidates.png` and `HV_EIorPi_NOcandidates.svg`
- `distribution.png` and `distribution.svg`

## Citation

If BgoKit or Bgolearn supports your research, please cite the related publication:

npj Computational Materials: <https://doi.org/10.1038/s41524-026-02226-3>

## License

This project is released under the MIT License.
