🐝 abcopt

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

abcopt implements the Artificial Bee Colony algorithm of Derviş Karaboğa (2005) step for step as in the reference implementation published by the ABC research group at Erciyes University, and wraps it in ABCSearchCV, a drop-in alternative to GridSearchCV and RandomizedSearchCV.

_{A real CanonicalABCSolver run on the 2-D Rastrigin function (many local minima, one global minimum ★).
Employed bees move one dimension at a time, onlookers revisit the best sources, and a scout restarts an exhausted source at a random spot.
Numbers are failed-trial counters. Generated by docs/make_animation.py.}

Highlights

• Verified canonical ABC. A test runs abcopt and the Erciyes University reference code on the same random-number stream and checks that both evaluate identical points and return identical results.
• scikit-learn native. ABCSearchCV provides fit, predict, predict_proba, score, best_params_, best_estimator_ and a cv_results_ table in the same format as GridSearchCV.
• Mixed search spaces. Continuous (optionally log-scaled), integer and categorical hyperparameters.
• No wasted runs. Configurations that ABC proposes twice are served from a cache, which roughly halves tuning time on discrete spaces without changing the search.
• Reproducible and predictable. Fixed evaluation budget (max_evals) and random_state for identical runs.
• Lightweight. Depends only on numpy and scikit-learn.

Contents: Installation · Quick start · How ABC works · Benchmark · API reference · Notes and limitations · Examples · Citation

Installation

pip install abcopt

Requires Python 3.9+, NumPy and scikit-learn.

Quick start

Tune a scikit-learn model

from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import HistGradientBoostingClassifier
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},
    "max_iter":         {"type": "int",   "range": (50, 300)},
    "max_leaf_nodes":   {"type": "int",   "range": (8, 64)},
    "l2_regularization": {"type": "float", "range": (1e-6, 1.0), "log": True},
}

search = ABCSearchCV(
    HistGradientBoostingClassifier(random_state=0),
    param_space,
    cv=5,
    scoring="accuracy",
    max_evals=60,       # candidates evaluated by ABC
    random_state=0,
)
search.fit(X, y)

print(search.best_score_, search.best_params_)
search.predict(X[:5])   # best_estimator_, refit on all data

Any scikit-learn compatible estimator works, including XGBoost and LightGBM.

Minimize a function

import numpy as np
from abcopt import CanonicalABCSolver

def rastrigin(x):
    return 10 * len(x) + np.sum(x**2 - 10 * np.cos(2 * np.pi * x))

solver = CanonicalABCSolver(rastrigin, n_params=5, lb=[-5.12] * 5, ub=[5.12] * 5,
                            max_evals=20_000, random_state=0)
best_x, best_f, history = solver.solve()

Inspect the search

import pandas as pd
import matplotlib.pyplot as plt

results = pd.DataFrame(search.cv_results_)          # one row per unique configuration
results.sort_values("rank_test_score").head()

evals, best = zip(*search.history_)                  # best CV score after each ABC cycle
plt.plot(evals, best); plt.xlabel("candidates evaluated"); plt.ylabel("best CV 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. Three kinds of bees share the work:

Fitness is derived from cost as 1 / (1 + f) for f ≥ 0 and 1 + |f| otherwise. The best solution found so far is always kept.

Benchmark

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

Black-box functions (D = 10, mean over 10 seeds, lower is better):

• 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 close to the global optimum on all four functions, while TPE stalls.
• ABC's own overhead is negligible: about 0.02 s versus 24 s for TPE over 2,000 evaluations.
• For hyperparameter tuning with about 50 candidates, the three methods end within noise of each other on test accuracy.

When to use which: TPE for very small budgets of expensive evaluations (for example deep-learning tuning); ABC when evaluations are cheap enough to afford thousands, when the landscape is rugged, or when you want a dependency-light scikit-learn drop-in.

API reference

CanonicalABCSolver

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

solve() returns (best_params, best_cost, history), where history lists (evaluations_used, best_cost_so_far) after initialization and after every cycle.

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, cache=True, verbose=False)

Search space (param_space), one entry per hyperparameter:

Parameters

fit(X, y=None, groups=None, **fit_params): groups is passed to group-aware splitters and fit_params (for example sample_weight) to the estimator.

Attributes after fit

Methods: predict, predict_proba, predict_log_proba, decision_function, transform, score and classes_, whenever the underlying estimator supports them.

Notes and limitations

• Budget semantics. As in the reference implementation, the budget is a number of objective evaluations, not of cycles. With ABCSearchCV, cached repeats still count towards max_evals.
• Integer and categorical parameters are searched as continuous values and rounded. Categorical choices become equal-width intervals of one dimension, so neighbouring choices are treated as "close"; this works well for a handful of choices.
• Sequential by design. Bees are evaluated one after another, exactly as in the reference algorithm; parallelism comes from n_jobs inside each cross-validation.
• Minimization. CanonicalABCSolver minimizes; to maximize, return the negative value.

Examples

Development

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

The test suite includes the reference-equivalence test (tests/test_reference_equivalence.py) and runs on Python 3.9, 3.11 and 3.12 for every push. Release notes are in CHANGELOG.md. Issues and pull requests are welcome.

Citation

If abcopt helps your work, please cite the original algorithm and this software:

@techreport{karaboga2005abc,
  author      = {Karaboğa, Derviş},
  title       = {An Idea Based on Honey Bee Swarm for Numerical Optimization},
  institution = {Erciyes University, Engineering Faculty, Computer Engineering Department},
  number      = {TR06},
  year        = {2005}
}

@software{korkmazyigit_abcopt,
  author  = {Korkmazyiğit, Yusuf},
  title   = {abcopt: Canonical Artificial Bee Colony optimization for Python},
  url     = {https://github.com/yusufkorkmazyigit/abc-optimizer-lib},
  version = {0.2.2},
  year    = {2026}
}

License

MIT. See LICENSE. The reference port used in the tests is MIT licensed by its authors.

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