🐝 abcopt

Canonical Artificial Bee Colony (ABC) optimization in pure Python, with a scikit-learn compatible hyperparameter search.

abcopt implements the Artificial Bee Colony algorithm proposed by Derviş Karaboğa (2005) at Erciyes University, step for step as in the reference implementation published by the ABC research group. It is useful for two things:

1. Black-box optimization: minimize any objective function within box constraints, with no gradients required.
2. Hyperparameter tuning: a drop-in alternative to GridSearchCV / RandomizedSearchCV for any scikit-learn compatible estimator (scikit-learn, LightGBM, XGBoost, …).

✨ Features

• Canonical algorithm, verified: employed, onlooker and scout bee phases exactly as in the Erciyes University reference code. A test runs both implementations on the same random-number stream and checks that they evaluate identical points and return identical results.
• scikit-learn API: ABCSearchCV exposes fit, predict, score, best_params_, best_score_ and best_estimator_.
• Mixed search spaces: float (optionally log-scaled), int and categorical hyperparameters.
• Reproducible: pass random_state and every run is identical.
• Evaluation budget: you set max_evals, so the run cost is predictable.
• Robust: failing candidates raise a warning instead of being hidden (or stop the search with error_score="raise"), and invalid inputs fail fast with clear messages.
• Convergence history: every run returns its best-so-far curve for plotting and comparison.
• Tested: 48 tests, including the reference-equivalence test, run on every push via GitHub Actions.
• Lightweight: depends only on numpy and scikit-learn.

📦 Installation

pip install abcopt

from abcopt import ABCSearchCV, CanonicalABCSolver

For development:

git clone https://github.com/yusufkorkmazyigit/abc-optimizer-lib.git
cd abc-optimizer-lib
pip install -e ".[test]"

🚀 Quick Start

1. Hyperparameter tuning with ABCSearchCV

import lightgbm as lgb
from sklearn.datasets import load_breast_cancer
from abcopt import ABCSearchCV

X, y = load_breast_cancer(return_X_y=True)

param_space = {
    "learning_rate": {"type": "float", "range": (0.01, 0.3), "log": True},
    "n_estimators":  {"type": "int",   "range": (50, 500)},
    "num_leaves":    {"type": "int",   "range": (20, 100)},
    "boosting_type": {"type": "categorical", "choices": ["gbdt", "dart"]},
}

search = ABCSearchCV(
    estimator=lgb.LGBMClassifier(verbosity=-1),
    param_space=param_space,
    cv=3,
    scoring="accuracy",
    pop_size=20,     # number of food sources
    max_evals=100,   # total objective evaluations (each one = one CV run)
    random_state=42, # reproducible search
)
search.fit(X, y)

print("Best CV score:", search.best_score_)
print("Best params:  ", search.best_params_)
y_pred = search.predict(X)   # uses best_estimator_, refit on the full data

2. Function minimization with CanonicalABCSolver

import numpy as np
from abcopt import CanonicalABCSolver

def sphere(x):
    return np.sum(x ** 2)    # global minimum: 0 at x = 0

solver = CanonicalABCSolver(
    objective_func=sphere,
    n_params=3,
    lb=[-10, -10, -10],
    ub=[10, 10, 10],
    max_evals=2000,
    random_state=0,
)
best_x, best_cost, history = solver.solve()
print(f"x* = {best_x}, f(x*) = {best_cost:.5f}")

3. Plotting convergence

import matplotlib.pyplot as plt

evals, costs = zip(*history)          # solver: best cost so far
# evals, scores = zip(*search.history_) # ABCSearchCV: best CV score so far
plt.plot(evals, costs)
plt.xlabel("Function evaluations")
plt.ylabel("Best cost")
plt.title("ABC convergence")
plt.show()

📖 API Reference

CanonicalABCSolver

CanonicalABCSolver(objective_func, n_params, lb, ub,
                   pop_size=20, max_evals=1000, limit=None, random_state=None)

NaN objective values are treated as the worst possible cost.

solve() returns (best_params, best_cost, history), where history is a list of (eval_count, best_cost) tuples.

ABCSearchCV

ABCSearchCV(estimator, param_space, cv=3, scoring="accuracy",
            pop_size=20, max_evals=200, limit=None, random_state=None,
            n_jobs=None, error_score=np.nan, refit=True, verbose=False)

param_space: one entry per hyperparameter:

• scoring: any scikit-learn scorer; higher is better, exactly like GridSearchCV (use neg_* scorers for errors).
• error_score: score given to candidates that fail to fit (a RuntimeWarning is issued); "raise" stops the search instead.
• n_jobs: parallel jobs inside each cross-validation.
• After fit: best_params_, best_score_, best_estimator_ (when refit=True), history_, results_ (every candidate with its score), n_evals_.
• Methods: predict, predict_proba, score.

🧠 How ABC Works

ABC models the foraging behaviour of a honey bee colony. Each food source is a candidate solution, and its nectar amount is the solution's fitness.

Fitness is derived from cost as 1 / (1 + f) for f ≥ 0 and 1 + |f| otherwise.

🔬 Case Study: Federated Learning on MedMNIST

The library was used to tune a federated learning setup on PathMNIST (colon pathology images, 9 classes). The data is split across 5 simulated hospitals with a Dirichlet distribution (α = 0.5), a non-IID setting where FedAvg with default hyperparameters struggles.

CanonicalABCSolver searched the clients' learning rate (0.001–0.1) and SGD momentum (0.0–0.9), scoring each candidate with a short 3-round FL simulation as a proxy task. The best configuration was then trained for 15 rounds:

For reference, centralized training with the default hyperparameters reached 80.29%. (This case study was run with abcopt 0.1, before the reference-alignment changes of 0.2.1.)

📓 Full notebook and analysis · Related repo: fedLearningwithABC

📊 Benchmark

abcopt was compared with Random Search and Optuna TPE under identical evaluation budgets, using abcopt 0.2.1 (full notebook).

Black-box functions (D = 10, 10 seeds), best value found (lower is better):

Takeaways

• With a short budget, TPE is usually ahead; ABC beats Random Search everywhere and wins on the highly multimodal Rastrigin.
• With a larger budget, ABC converges to near the global optimum on all four functions while TPE stalls.
• ABC's own overhead is tiny: about 0.02 s vs 24 s for TPE over 2,000 evaluations.
• For hyperparameter tuning with only 50 candidates, the three methods are within noise on test accuracy, and TPE finds the best CV score. For very small budgets of expensive evaluations, TPE is the better choice.

🗺️ Roadmap

• Categorical and log-scaled hyperparameters
• random_state for reproducibility
• Unit tests and continuous integration
• Parallel cross-validation (n_jobs)
• Benchmark against Random Search and Optuna TPE
• Parallel evaluation of candidates within a colony
• PyPI release

Contributions and issues are welcome.

🧪 Development

pip install -e ".[test]"
pytest

See CHANGELOG.md for release notes.

📚 Reference

Karaboğa, D. (2005). An Idea Based on Honey Bee Swarm for Numerical Optimization. Technical Report TR06, Erciyes University, Engineering Faculty, Computer Engineering Department.

If you use this library in your research, please cite the original paper above and link to this repository.

📝 License

Released under the MIT License.

_{Developed by Yusuf Korkmazyiğit, Computer Engineering, Erciyes University.}