ecabc 3.0.1__tar.gz → 3.0.2__tar.gz

{ecabc-3.0.1 → ecabc-3.0.2}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Sanskriti Sharma, Hernan Gelaf-Romer
+Copyright (c) 2018-2026 Sanskriti Sharma, Hernan Gelaf-Romer, Travis Kessler
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{ecabc-3.0.1 → ecabc-3.0.2}/PKG-INFO

@@ -1,23 +1,41 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: ecabc
-Version: 3.0.1
+Version: 3.0.2
 Summary: Artificial bee colony for function parameter optimization
 Author-email: Sanskriti Sharma <Sanskriti_Sharma@student.uml.edu>, Hernan Gelaf-Romer <Hernan_Gelafromer@student.uml.edu>, Travis Kessler <travis.j.kessler@gmail.com>
+License: MIT
 Project-URL: Homepage, https://github.com/ecrl/ecabc
 Project-URL: Bug Tracker, https://github.com/ecrl/ecabc/issues
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: pre-commit>=4; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: furo>=2024.1; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=2; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Dynamic: license-file
 
 [![UML Energy & Combustion Research Laboratory](https://sites.uml.edu/hunter-mack/files/2021/11/ECRL_final.png)](http://faculty.uml.edu/Hunter_Mack/)
 
-# ECabc: optimization algorithm for tuning user-defined parametric functions 
+# ECabc: optimization algorithm for tuning user-defined parametric functions
 [![GitHub version](https://badge.fury.io/gh/ECRL%2FECabc.svg)](https://badge.fury.io/gh/ECRL%2FECabc)
 [![PyPI version](https://badge.fury.io/py/ecabc.svg)](https://badge.fury.io/py/ecabc)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ECRL/ecabc/blob/master/LICENSE)
+[![CI](https://github.com/ecrl/ecabc/actions/workflows/run_tests.yml/badge.svg?branch=master)](https://github.com/ecrl/ecabc/actions/workflows/run_tests.yml)
 [![DOI](http://joss.theoj.org/papers/10.21105/joss.01420/status.svg)](https://doi.org/10.21105/joss.01420)
 
 **ECabc** is an open source Python package used to tune parameters for user-supplied functions based on the [Artificial Bee Colony by D. Karaboğa](http://scholarpedia.org/article/Artificial_bee_colony_algorithm). ECabc optimizes user supplied functions, or **fitness function**s, using a set of variables that exist within a search space. The bee colony consists of three types of bees: employers, onlookers and scouts. An **employer bee** exploits a solution comprised of a permutation of the variables in the search space, and evaluates the viability of the solution. An **onlooker bee** chooses an employer bee with an optimal solution and searches for new solutions near them. The **scout bee**, a variant of the employer bee, will search for a new solution if it has stayed too long at its current solution.
@@ -31,38 +49,35 @@ While it has several applications, ECabc has been successfully used by the Energ
 
 # Installation
 
-### Prerequisites:
-- Have python 3.X installed
-- Have the ability to install python packages
+**Requires Python 3.10 or newer.** ECabc has no runtime third-party dependencies
+(stdlib only). A virtual environment is recommended.
 
 ### Method 1: pip
-If you are working in a Linux/Mac environment:
-```
-sudo pip install ecabc
-```
 
-Alternatively, in a Windows or virtualenv environment:
 ```
 pip install ecabc
 ```
 
-To update your version of ECabc to the latest release version, use
+To upgrade to the latest release:
+
 ```
 pip install --upgrade ecabc
 ```
 
-Note: if multiple Python releases are installed on your system (e.g. 2.7 and 3.7), you may need to execute the correct version of pip. For Python 3.X, change **"pip install ecabc"** to **"pip3 install ecabc"**.
-
 ### Method 2: From source
-- Download the ECabc repository, navigate to the download location on the command line/terminal, and execute:
+
+Clone or download this repository, then from the repository root:
+
 ```
 pip install .
 ```
 
-There are currently no additional dependencies for ECabc.
-
 # Usage
 
+API stability for the public surface is documented in
+[API_STABILITY.md](API_STABILITY.md) (also the Sphinx *API stability policy*
+page under `docs/source/stability.rst`).
+
 To start using ECabc, you need a couple items:
 - a fitness function (cost function) to optimize
 - parameters used by the fitness function

{ecabc-3.0.1 → ecabc-3.0.2}/README.md

@@ -1,9 +1,10 @@
 [![UML Energy & Combustion Research Laboratory](https://sites.uml.edu/hunter-mack/files/2021/11/ECRL_final.png)](http://faculty.uml.edu/Hunter_Mack/)
 
-# ECabc: optimization algorithm for tuning user-defined parametric functions 
+# ECabc: optimization algorithm for tuning user-defined parametric functions
 [![GitHub version](https://badge.fury.io/gh/ECRL%2FECabc.svg)](https://badge.fury.io/gh/ECRL%2FECabc)
 [![PyPI version](https://badge.fury.io/py/ecabc.svg)](https://badge.fury.io/py/ecabc)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ECRL/ecabc/blob/master/LICENSE)
+[![CI](https://github.com/ecrl/ecabc/actions/workflows/run_tests.yml/badge.svg?branch=master)](https://github.com/ecrl/ecabc/actions/workflows/run_tests.yml)
 [![DOI](http://joss.theoj.org/papers/10.21105/joss.01420/status.svg)](https://doi.org/10.21105/joss.01420)
 
 **ECabc** is an open source Python package used to tune parameters for user-supplied functions based on the [Artificial Bee Colony by D. Karaboğa](http://scholarpedia.org/article/Artificial_bee_colony_algorithm). ECabc optimizes user supplied functions, or **fitness function**s, using a set of variables that exist within a search space. The bee colony consists of three types of bees: employers, onlookers and scouts. An **employer bee** exploits a solution comprised of a permutation of the variables in the search space, and evaluates the viability of the solution. An **onlooker bee** chooses an employer bee with an optimal solution and searches for new solutions near them. The **scout bee**, a variant of the employer bee, will search for a new solution if it has stayed too long at its current solution.
@@ -17,38 +18,35 @@ While it has several applications, ECabc has been successfully used by the Energ
 
 # Installation
 
-### Prerequisites:
-- Have python 3.X installed
-- Have the ability to install python packages
+**Requires Python 3.10 or newer.** ECabc has no runtime third-party dependencies
+(stdlib only). A virtual environment is recommended.
 
 ### Method 1: pip
-If you are working in a Linux/Mac environment:
-```
-sudo pip install ecabc
-```
 
-Alternatively, in a Windows or virtualenv environment:
 ```
 pip install ecabc
 ```
 
-To update your version of ECabc to the latest release version, use
+To upgrade to the latest release:
+
 ```
 pip install --upgrade ecabc
 ```
 
-Note: if multiple Python releases are installed on your system (e.g. 2.7 and 3.7), you may need to execute the correct version of pip. For Python 3.X, change **"pip install ecabc"** to **"pip3 install ecabc"**.
-
 ### Method 2: From source
-- Download the ECabc repository, navigate to the download location on the command line/terminal, and execute:
+
+Clone or download this repository, then from the repository root:
+
 ```
 pip install .
 ```
 
-There are currently no additional dependencies for ECabc.
-
 # Usage
 
+API stability for the public surface is documented in
+[API_STABILITY.md](API_STABILITY.md) (also the Sphinx *API stability policy*
+page under `docs/source/stability.rst`).
+
 To start using ECabc, you need a couple items:
 - a fitness function (cost function) to optimize
 - parameters used by the fitness function

ecabc-3.0.2/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["paper*"]
+
+[project]
+name = "ecabc"
+version = "3.0.2"
+authors = [
+    { name="Sanskriti Sharma", email="Sanskriti_Sharma@student.uml.edu" },
+    { name="Hernan Gelaf-Romer", email="Hernan_Gelafromer@student.uml.edu" },
+    { name="Travis Kessler", email="travis.j.kessler@gmail.com" },
+]
+description = "Artificial bee colony for function parameter optimization"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/ecrl/ecabc"
+"Bug Tracker" = "https://github.com/ecrl/ecabc/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.8",
+    "mypy>=1.8",
+    "pre-commit>=4",
+    "build>=1.2",
+]
+docs = [
+    "sphinx>=7",
+    "furo>=2024.1",
+    "sphinx-autodoc-typehints>=2",
+    "sphinx-copybutton>=0.5",
+]
+
+[tool.ruff]
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=ecabc --cov-report=term-missing --cov-fail-under=95"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["ecabc"]
+branch = false
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src/ecabc"]
+warn_return_any = true
+warn_unused_configs = true
+check_untyped_defs = true
+disallow_untyped_defs = false

ecabc-3.0.2/src/ecabc/__init__.py

@@ -0,0 +1,19 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from ecabc.abc import ABC
+from ecabc.bee import Bee
+from ecabc.parameter import Parameter
+
+from . import utils as utils
+
+__all__ = ["ABC", "Bee", "Parameter", "__version__", "utils"]
+
+
+def _resolve_version() -> str:
+    try:
+        return version("ecabc")
+    except PackageNotFoundError:
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()

ecabc-3.0.2/src/ecabc/abc.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python
+#
+#  ecabc/abc.py
+#  v.3.0.0
+#
+#  Developed in 2019 by Sanskriti Sharma <sanskriti_sharma@student.uml.edu>,
+#  Hernan Gelaf-Romer <hernan_gelafromer@student.uml.edu>, and Travis Kessler
+#  <Travis_Kessler@student.uml.edu>
+#
+#  abc.py: contains ABC object, handling the initialization and runtime of the
+#  artificial bee colony
+#
+
+# Stdlib. imports
+from collections.abc import Callable
+from multiprocessing import Pool
+from typing import Any
+from warnings import warn
+
+# ECabc imports
+from ecabc.bee import Bee
+from ecabc.parameter import Parameter
+from ecabc.utils import apply_mutation, call_obj_fn, choose_bee, determine_best_bee
+
+
+class ABC:
+    def __init__(
+        self,
+        num_employers: int,
+        objective_fn: Callable[[list], float],
+        obj_fn_args: dict = {},
+        num_processes: int = 1,
+    ):
+        """ABC object: optimizes parameters for user-supplied function
+
+        Args:
+            num_employers (int): number of employer bees in the colony
+            objective_fn (callable): function to optimize; accepts list of
+                ints/floats, returns float (fitness)
+            obj_fn_args (dict): non-tunable kwargs to pass to objective_fn
+            num_processes (int): number of concurrent processes to utilize
+        """
+
+        if not callable(objective_fn):
+            raise ReferenceError("Supplied objective function not callable")
+        self._obj_fn = objective_fn
+        # Copy so the shared mutable default (and caller-owned dicts) are not aliased.
+        self._obj_fn_args = dict(obj_fn_args)
+        self._num_employers = num_employers
+        self._num_processes = num_processes
+        self._params: list[Parameter] = []
+        self._bees: list[Bee] = []
+
+    @property
+    def best_fitness(self) -> float:
+        """Returns fitness score from best-performing bee"""
+
+        return determine_best_bee(self._bees)[0]
+
+    @property
+    def best_ret_val(self) -> int | float | None:
+        """Returns objective_fn return value from best-performing bee"""
+
+        return determine_best_bee(self._bees)[1]
+
+    @property
+    def best_params(self) -> dict:
+        """Returns parameters from best-performing bee"""
+
+        vals = determine_best_bee(self._bees)[2]
+        ret_val: dict[str, int | float] = {}
+        if vals is None:
+            return ret_val
+        for idx, param in enumerate(self._params):
+            if param._name is None:
+                ret_val[f"P{idx}"] = vals[idx]
+            else:
+                ret_val[param._name] = vals[idx]
+        return ret_val
+
+    @property
+    def average_fitness(self) -> float | None:
+        """Returns average fitness score for bee population"""
+
+        if len(self._bees) == 0:
+            return None
+        return sum(b._fitness_score for b in self._bees) / len(self._bees)
+
+    @property
+    def average_ret_val(self) -> int | float | None:
+        """Returns average objective_fn return value for bee population"""
+
+        if len(self._bees) == 0:
+            return None
+        return sum(b._obj_fn_val for b in self._bees) / len(self._bees)
+
+    def add_param(
+        self,
+        min_val: int | float,
+        max_val: int | float,
+        restrict: bool = True,
+        name: str | None = None,
+    ):
+        """ABC.add_param: adds a parameter to be processed by the user-
+        supplied objective function
+
+        Args:
+            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): name of parameter, optional
+        """
+
+        if len(self._bees) > 0:
+            raise RuntimeError("Cannot add another parameter after bee initialization")
+        self._params.append(Parameter(min_val, max_val, restrict, name))
+
+    def initialize(self):
+        """ABC.initialize: creates `num_employers` employer bees and
+        `num_employers` onlooker bees
+        """
+
+        if len(self._bees) > 0:
+            warn(
+                "initialize() called again: overwriting bee population", RuntimeWarning
+            )
+
+        self._bees = []
+
+        if self._num_processes > 1:
+            employer_pool = Pool(processes=self._num_processes)
+        employer_results: list[Any] = []
+
+        for _ in range(self._num_employers):
+            params = [p.rand_val for p in self._params]
+            if self._num_processes > 1:
+                employer_results.append(
+                    employer_pool.apply_async(
+                        call_obj_fn, [params, self._obj_fn, self._obj_fn_args]
+                    )
+                )
+            else:
+                employer_results.append(
+                    call_obj_fn(params, self._obj_fn, self._obj_fn_args)
+                )
+
+        if self._num_processes > 1:
+            employer_pool.close()
+            employer_pool.join()
+            employer_results = [r.get() for r in employer_results]
+
+        for result in employer_results:
+            self._bees.append(
+                Bee(result[0], result[1], len(self._params) * self._num_employers, True)
+            )
+
+        if self._num_processes > 1:
+            onlooker_pool = Pool(processes=self._num_processes)
+        onlooker_results: list[Any] = []
+
+        for _ in range(self._num_employers):
+            chosen_employer = choose_bee(self._bees)
+            neighbor_food = apply_mutation(chosen_employer._params, self._params)
+
+            if self._num_processes > 1:
+                onlooker_results.append(
+                    onlooker_pool.apply_async(
+                        call_obj_fn, [neighbor_food, self._obj_fn, self._obj_fn_args]
+                    )
+                )
+            else:
+                onlooker_results.append(
+                    call_obj_fn(neighbor_food, self._obj_fn, self._obj_fn_args)
+                )
+
+        if self._num_processes > 1:
+            onlooker_pool.close()
+            onlooker_pool.join()
+            onlooker_results = [r.get() for r in onlooker_results]
+
+        for result in onlooker_results:
+            self._bees.append(
+                Bee(
+                    result[0],
+                    result[1],
+                    len(self._params) * self._num_employers,
+                )
+            )
+
+    def search(self):
+        """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.
+        """
+
+        if len(self._bees) == 0:
+            raise RuntimeError("search() cannot be called before initialize()")
+
+        if self._num_processes > 1:
+            bee_pool = Pool(processes=self._num_processes)
+        new_employer_results: list[Any] = []
+        new_onlooker_results: list[Any] = []
+        new_position_results: list[Any] = []
+        current_positions: list[Bee] = []
+
+        for bee in self._bees:
+            if bee.abandon:
+                if bee._is_employer:
+                    new_params = [p.rand_val for p in self._params]
+                    if self._num_processes > 1:
+                        new_employer_results.append(
+                            bee_pool.apply_async(
+                                call_obj_fn,
+                                [new_params, self._obj_fn, self._obj_fn_args],
+                            )
+                        )
+                    else:
+                        new_employer_results.append(
+                            call_obj_fn(new_params, self._obj_fn, self._obj_fn_args)
+                        )
+
+                else:
+                    chosen_bee = choose_bee(self._bees)
+                    neighbor_food = apply_mutation(chosen_bee._params, self._params)
+                    if self._num_processes > 1:
+                        new_onlooker_results.append(
+                            bee_pool.apply_async(
+                                call_obj_fn,
+                                [neighbor_food, self._obj_fn, self._obj_fn_args],
+                            )
+                        )
+                    else:
+                        new_onlooker_results.append(
+                            call_obj_fn(neighbor_food, self._obj_fn, self._obj_fn_args)
+                        )
+
+            else:
+                current_positions.append(bee)
+                neighbor_food = apply_mutation(bee._params, self._params)
+                if self._num_processes > 1:
+                    new_position_results.append(
+                        bee_pool.apply_async(
+                            call_obj_fn,
+                            [neighbor_food, self._obj_fn, self._obj_fn_args],
+                        )
+                    )
+                else:
+                    new_position_results.append(
+                        call_obj_fn(neighbor_food, self._obj_fn, self._obj_fn_args)
+                    )
+
+        if self._num_processes > 1:
+            bee_pool.close()
+            bee_pool.join()
+            new_employer_results = [r.get() for r in new_employer_results]
+            new_onlooker_results = [r.get() for r in new_onlooker_results]
+            new_position_results = [r.get() for r in new_position_results]
+
+        next_bee_generation = []
+
+        for result in new_employer_results:
+            next_bee_generation.append(
+                Bee(result[0], result[1], len(self._params) * self._num_employers, True)
+            )
+
+        for result in new_onlooker_results:
+            next_bee_generation.append(
+                Bee(result[0], result[1], len(self._params) * self._num_employers)
+            )
+
+        for idx, result in enumerate(new_position_results):
+            bee_to_compare = current_positions[idx]
+            if bee_to_compare.is_better_food(result[1]):
+                if bee_to_compare._is_employer:
+                    next_bee_generation.append(
+                        Bee(
+                            result[0],
+                            result[1],
+                            len(self._params) * self._num_employers,
+                            True,
+                        )
+                    )
+                else:
+                    next_bee_generation.append(
+                        Bee(
+                            result[0],
+                            result[1],
+                            len(self._params) * self._num_employers,
+                        )
+                    )
+            else:
+                next_bee_generation.append(bee_to_compare)
+
+        self._bees = next_bee_generation

{ecabc-3.0.1 → ecabc-3.0.2/src}/ecabc/bee.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
 #
 #  ecabc/bee.py
 #  v.3.0.0
@@ -13,14 +12,17 @@
 #
 
 # Stdlib. imports
-from typing import Union
 
 
 class Bee:
-
-    def __init__(self, params: list, obj_fn_val: Union[int, float],
-                 stay_limit: int, is_employer: bool = False):
-        ''' Bee object: houses bee-specific information such as its current
+    def __init__(
+        self,
+        params: list,
+        obj_fn_val: int | float,
+        stay_limit: int,
+        is_employer: bool = False,
+    ):
+        """Bee object: houses bee-specific information such as its current
         set of parameters, the objective function value resulting from its,
         current parameters, maximum number of cycles it can stay at its
         current food source, and whether it is an employer bee or not
@@ -32,7 +34,7 @@ class Bee:
             stay_limit (int): maximum number of cycles the bee can stay at its
                 current food source
             is_employer (bool): `True` if employer, `False` if onlooker
-        '''
+        """
 
         self._params = params
         self._obj_fn_val = obj_fn_val
@@ -43,9 +45,9 @@ class Bee:
 
     @property
     def abandon(self) -> bool:
-        ''' When called, increment how many times the bee has stayed at its
+        """When called, increment how many times the bee has stayed at its
         current food source; if reached stay limit, return `True` else `False`
-        '''
+        """
 
         self._stay_count += 1
         if self._stay_count >= self._stay_limit:
@@ -54,8 +56,8 @@ class Bee:
             return False
 
     @staticmethod
-    def calc_fitness(obj_fn_val: Union[int, float]) -> float:
-        ''' Static method: Bee.calc_fitness: Calculates fitness score based on
+    def calc_fitness(obj_fn_val: int | float) -> float:
+        """Static method: Bee.calc_fitness: Calculates fitness score based on
         objective function value, using the equation:
 
         fitness = 1 / (1 + ofv)     if ofv >= 0
@@ -69,15 +71,15 @@ class Bee:
 
         Returns:
             float: resulting fitness score
-        '''
+        """
 
         if obj_fn_val >= 0:
             return 1 / (obj_fn_val + 1)
         else:
             return 1 + abs(obj_fn_val)
 
-    def is_better_food(self, obj_fn_val: Union[int, float]) -> bool:
-        ''' Bee.is_better_food: determines if objective function value
+    def is_better_food(self, obj_fn_val: int | float) -> bool:
+        """Bee.is_better_food: determines if objective function value
         resulting from a new food source is better than the bee's current food
         source
 
@@ -87,7 +89,7 @@ class Bee:
 
         Returns:
             bool: `True` if better food source else `False`
-        '''
+        """
 
         if self.calc_fitness(obj_fn_val) > self._fitness_score:
             return True