API reference

Primary entry point

ecabc.ABC is the supported workflow for application code. See API stability policy for the frozen contract.

class ecabc.ABC(num_employers, objective_fn, obj_fn_args={}, num_processes=1)

Bases: object

Parameters:

• num_employers (int)

• objective_fn (Callable[[list], float])

• obj_fn_args (dict)

• num_processes (int)

add_param(min_val, max_val, restrict=True, name=None)

ABC.add_param: adds a parameter to be processed by the user- supplied objective function

Parameters:

• min_val (int | float) – minimum value allowed for the parameter’s initialization

• max_val (int | float) – maximum value allowed for the parameter’s initialization

• restrict (bool) – if True, parameter mutations must be within [min_val, max_val], False allows out-of-bounds mutation

• name (str | None) – name of parameter, optional

property average_fitness: float | None

Returns average fitness score for bee population

property average_ret_val: int | float | None

Returns average objective_fn return value for bee population

property best_fitness: float

Returns fitness score from best-performing bee

property best_params: dict

Returns parameters from best-performing bee

property best_ret_val: int | float | None

Returns objective_fn return value from best-performing bee

initialize()

ABC.initialize: creates num_employers employer bees and num_employers onlooker bees

search()

Perform one search cycle for all bees in the colony.

For each bee: if it has exhausted its current food source, an employer finds a new random food source and an onlooker travels near a well-performing bee; otherwise one parameter is mutated and the bee moves only if the neighbor food is better. The colony is then replaced with the updated bee states.

Exhaustion is the maximum number of search cycles a bee may stay at its current food source, EX = NE * D, where NE is the number of employers and D is the number of parameters.

Secondary exports

ecabc.Bee, ecabc.Parameter, and ecabc.utils remain part of the frozen 3.x surface. Prefer the ABC workflow for new code; these types are useful for tests, extensions, and advanced inspection.

class ecabc.Bee(params, obj_fn_val, stay_limit, is_employer=False)

Bases: object

Parameters:

• params (list)

• obj_fn_val (int | float)

• stay_limit (int)

• is_employer (bool)

property abandon: bool

When called, increment how many times the bee has stayed at its current food source; if reached stay limit, return True else False

static calc_fitness(obj_fn_val)

Static method: Bee.calc_fitness: Calculates fitness score based on objective function value, using the equation:

fitness = 1 / (1 + ofv) if ofv >= 0 fitness = 1 + abs(ofv) if ofv < 0

Where ofv is the objective function value and fitness is the resulting fitness score

Parameters:

obj_fn_val (int | float) – value obtained from objective function

Returns:

resulting fitness score

Return type:

float

is_better_food(obj_fn_val)

Bee.is_better_food: determines if objective function value resulting from a new food source is better than the bee’s current food source

Parameters:

obj_fn_val (int | float) – value resulting from objective function with new food

Returns:

True if better food source else False

Return type:

bool

class ecabc.Parameter(min_val, max_val, restrict=True, name=None)

Bases: object

Parameters:

• min_val (int | float)

• max_val (int | float)

• restrict (bool)

• name (str | None)

mutate(curr_value)

Parameter.mutate: mutates current parameter value by using the equation:

V = X + rand(-1, 1) * (X - Xrand)

Where V is the new value, X is the current value and Xrand is a random parameter value

Parameters:

curr_value (int | float) – current parameter value

Returns:

mutated parameter value

Return type:

int | float

property rand_val: int | float

Returns a random value X in range [min_val, max_val] using the equation:

X = min_val + rand(0, 1) * (max_val - min_val)

Package version

ecabc.__version__ = '3.0.2'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

Utilities

Import helpers as import ecabc.utils. Public functions:

• apply_mutation

• call_obj_fn

• choose_bee

• determine_best_bee

ecabc.utils.apply_mutation(curr_params, all_params)

apply_mutation: alters the value of one parameter in supplied list of values

Parameters:

• curr_params (list) – current parameter values, ints or floats

• all_params (list) – list of Parameter objects

Returns:

parameter values with one value mutation

Return type:

list

ecabc.utils.call_obj_fn(params, obj_fn, obj_fn_args)

call_obj_fn: calls supplied objective function, evaluating using supplied parameters; callable in single- and multi-processed configurations

Parameters:

• params (list) – list of ints or floats corresponding to current bee parameter values

• obj_fn (Callable[..., float]) – function to accept list of paramters, returns a quantitative measurement of fitness

• obj_fn_args (dict) – non-tunable kwargs to pass to objective function

Returns:

(params, objective function return value)

Return type:

tuple

ecabc.utils.choose_bee(bees)

choose_bee: choose a bee based on probabilities a given bee will be chosen; probabilities based on fitness score (higher fitness score == higher probability of being chosen)

Parameters:

bees (list[Bee]) – list of Bee objects

Returns:

chosen Bee

Return type:

Bee

ecabc.utils.determine_best_bee(bees)

determine_best_bee: return highest fitness score w/ corresponding objective function return value and parameters given a list of bees

Parameters:

bees (list[Bee]) – list of Bee objects

Returns:

(best fitness score, best return value, best parameters)

Return type:

tuple[float, int | float | None, list | None]

ecabc.utils.random() → x in the interval [0, 1).