API stability policy¶

This page is the user-facing stability contract for ecabc. A copy also lives at the repository root as API_STABILITY.md for contributors who browse the source tree without building the docs.

ECabc implements the Artificial Bee Colony (ABC) metaheuristic for tuning parameters of user-supplied objective functions. Background literature:

Karaboğa D. Artificial bee colony algorithm. Scholarpedia, 5(3):6915, 2010. https://www.scholarpedia.org/article/Artificial_bee_colony_algorithm
Package paper (JOSS): DOI 10.21105/joss.01420 https://doi.org/10.21105/joss.01420

Frozen public surface¶

The following imports are the supported surface and must remain drop-in compatible within the 3.0.x / 3.1.x compatibility series:

from ecabc import ABC, Bee, Parameter
import ecabc.utils
from ecabc import __version__

ecabc.ABC is the primary documented entry point. Parameter names and defaults for its public methods are frozen. Additive optional keyword arguments may be introduced when they do not change existing call sites. Renaming methods, making new arguments required, changing primary return container types, or changing documented exception types for existing failure modes requires an explicit, versioned compatibility decision.

Primary workflow (`ABC`)¶

Signatures and defaults to preserve (keyword names and defaults must remain compatible):

ABC(
    num_employers: int,
    objective_fn,                 # callable
    obj_fn_args: dict = {},
    num_processes: int = 1,
)

abc.add_param(
    min_val,                      # int or float
    max_val,                      # same type as min_val
    restrict: bool = True,
    name: str | None = None,
)

abc.initialize()
abc.search()

abc.best_fitness                  # float
abc.best_ret_val                  # numeric or None
abc.best_params                   # dict
abc.average_fitness               # float or None
abc.average_ret_val               # float or None

Objective-function contract¶

Rule	Contract
Input	A `list` of parameter values (`int` and/or `float`)
Output	Numeric objective value
Sense	Lower return values are better
Extra args	Via `obj_fn_args` kwargs passed through to the objective

Exception and warning contracts¶

Condition	Type
Non-callable objective	`ReferenceError`
`add_param` after `initialize`	`RuntimeError`
`search` before `initialize`	`RuntimeError`
Second `initialize`	`RuntimeWarning`
Parameter min/max type mismatch	`ValueError`

Behavioral invariants¶

The following must not change without a major-version plan:

After initialize, colony size is 2 × num_employers (employers + onlookers).
Stay limit is num_employers × num_parameters.
Default keys in best_params are P0, P1, … when name is omitted.
Fitness transform follows Bee.calc_fitness: 1/(1+ofv) if ofv >= 0, else 1 + abs(ofv).

Secondary exports¶

ecabc.Bee, ecabc.Parameter, and ecabc.utils (apply_mutation, call_obj_fn, choose_bee, determine_best_bee) remain importable. They are secondary relative to the ABC workflow but are part of the frozen 3.x surface and must not be removed without a major-version plan. Prefer ecabc.ABC for new application code.

Version export¶

ecabc.__version__ is part of the public surface. Callers may rely on it resolving to the installed package version string.

Versioning¶

Patch (``3.0.x``): bugfixes, tooling, packaging, documentation, and internal hardening that preserve the frozen API. The API-stable modernization program ships as ``3.0.2``.
Minor (``3.1.0`` and later): reserved for future additive, still API-compatible work after 3.0.2.
Major (``4.0.0`` or higher): only after an explicit stability or migration plan (for example an intentional algorithm-semantics change or API redesign).

Runtime dependencies¶

The default install is stdlib-only (no required third-party runtime packages). Optional developer or documentation extras may exist for contributors and do not change the runtime contract for pip install ecabc.