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:

pip install BgoKit

Install or upgrade from a local source tree:

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.

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.