{"id":21292048,"url":"https://github.com/ecrl/ecabc","last_synced_at":"2025-07-11T16:31:11.869Z","repository":{"id":57425459,"uuid":"123346907","full_name":"ecrl/ecabc","owner":"ecrl","description":"Artificial Bee Colony for generic feature tuning","archived":false,"fork":false,"pushed_at":"2023-08-02T03:20:16.000Z","size":8296,"stargazers_count":12,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-27T02:08:35.588Z","etag":null,"topics":["artificial-bee-colony","feature-tuning","hyperparameter-optimization","neural-network"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ecrl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-02-28T21:52:57.000Z","updated_at":"2024-09-29T21:06:48.000Z","dependencies_parsed_at":"2025-04-14T17:17:11.179Z","dependency_job_id":"42433024-02eb-42cd-ae73-7cacba65e426","html_url":"https://github.com/ecrl/ecabc","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ecrl/ecabc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecrl%2Fecabc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecrl%2Fecabc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecrl%2Fecabc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecrl%2Fecabc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecrl","download_url":"https://codeload.github.com/ecrl/ecabc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecrl%2Fecabc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262175248,"owners_count":23270424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-bee-colony","feature-tuning","hyperparameter-optimization","neural-network"],"created_at":"2024-11-21T13:47:24.353Z","updated_at":"2025-07-11T16:31:10.344Z","avatar_url":"https://github.com/ecrl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![UML Energy \u0026 Combustion Research Laboratory](https://sites.uml.edu/hunter-mack/files/2021/11/ECRL_final.png)](http://faculty.uml.edu/Hunter_Mack/)\n\n# ECabc: optimization algorithm for tuning user-defined parametric functions \n[![GitHub version](https://badge.fury.io/gh/ECRL%2FECabc.svg)](https://badge.fury.io/gh/ECRL%2FECabc)\n[![PyPI version](https://badge.fury.io/py/ecabc.svg)](https://badge.fury.io/py/ecabc)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ECRL/ecabc/blob/master/LICENSE)\n[![DOI](http://joss.theoj.org/papers/10.21105/joss.01420/status.svg)](https://doi.org/10.21105/joss.01420)\n\n**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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg align=\"center\" src=\"docs/img/abc_visual_convergence.gif\" width=\"75%\" height=\"75%\"\u003e\n\u003c/p\u003e\n\n### Research applications\nWhile it has several applications, ECabc has been successfully used by the Energy and Combustion Research Laboratory (ECRL) at the University of Massachusetts Lowell to tune the hyperparameters of ECNet, an open source Python package tailored to predicting fuel properties. ECNet provides scientists an open source tool for predicting key fuel properties of potential next-generation biofuels, reducing the need for costly fuel synthesis and experimentation. By increasing the accuracy of ECNet and similar models efficiently, ECabc helps to provide a higher degree of confidence in discovering new, optimal fuels. A single run of ECabc on ECNet yielded a lower average root mean square error (RMSE) for cetane number (CN) and yield sooting index (YSI) when compared to the RMSE generated by a year of manual tuning. While the manual tuning generated an RMSE of 10.13, the ECabc was able to yield an RMSE of 8.06 in one run of 500 iterations.\n\n# Installation\n\n### Prerequisites:\n- Have python 3.X installed\n- Have the ability to install python packages\n\n### Method 1: pip\nIf you are working in a Linux/Mac environment:\n```\nsudo pip install ecabc\n```\n\nAlternatively, in a Windows or virtualenv environment:\n```\npip install ecabc\n```\n\nTo update your version of ECabc to the latest release version, use\n```\npip install --upgrade ecabc\n```\n\nNote: 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\"**.\n\n### Method 2: From source\n- Download the ECabc repository, navigate to the download location on the command line/terminal, and execute:\n```\npip install .\n```\n\nThere are currently no additional dependencies for ECabc.\n\n# Usage\n\nTo start using ECabc, you need a couple items:\n- a fitness function (cost function) to optimize\n- parameters used by the fitness function\n\nFor example, let's define a fitness function to minimize the sum of three integers:\n\n```python\ndef minimize_integers(integers):\n\n    return sum(integers)\n\n```\n\nYour fitness function must accept a **list** from ECabc. The list values represent the current \"food source\", i.e. parameter values, being exploited by a given bee.\n\nNow that we have our fitness function, let's import the ABC object from ECabc, initialize the artificial bee colony, and add our parameters:\n\n```python\nfrom ecabc import ABC\n\ndef minimize_integers(integers):\n\n    return sum(integers)\n\nabc = ABC(10, minimize_integers)\nabc.add_param(0, 10, name='Int_1')\nabc.add_param(0, 10, name='Int_2')\nabc.add_param(0, 10, name='Int_3')\n```\n\nHere we initialize the colony with 10 employer bees, supply our fitness function, and add our parameters. Parameters are added with minimum/maximum values for its search space and optionally a name. By default, parameter mutations (searching a neighboring food source) will not exceed the specified parameter bounds [min_val, max_val]; if this limitation is not desired, supply the \"restrict=False\" argument:\n\n```python\nabc.add_param(0, 10, restrict=False, name='Int_1')\n```\n\nOnce we have created our colony and added our parameters, we then need to \"initialize\" the colony's bees:\n\n```python\nfrom ecabc import ABC\n\ndef minimize_integers(integers):\n\n    return sum(integers)\n\nabc = ABC(10, minimize_integers)\nabc.add_param(0, 10, name='Int_1')\nabc.add_param(0, 10, name='Int_2')\nabc.add_param(0, 10, name='Int_3')\nabc.initialize()\n```\n\nInitializing the colony's bees deploys employer bees (in this example, 10 bees) to random food sources (random parameter values are generated), their fitness is evaluated (in this example, lowest sum is better), and onlooker bees (equal to the number of employers) are deployed proportionally to neighboring food sources of well-performing bees.\n\nWe then send the colony through a predetermined of \"search cycles\":\n\n```python\nfrom ecabc import ABC\n\ndef minimize_integers(integers):\n\n    return sum(integers)\n\nabc = ABC(10, minimize_integers)\nabc.add_param(0, 10, name='Int_1')\nabc.add_param(0, 10, name='Int_2')\nabc.add_param(0, 10, name='Int_3')\nabc.initialize()\nfor _ in range(10):\n    abc.search()\n```\n\nA search cycle consists of:\n- each bee searches a neighboring food source (performs a mutation on one parameter)\n- if the food source produces a better fitness than the bee's current food source, move there\n- otherwise, the bee stays at its current food source\n    - if the bee has stayed for (NE * D) cycles (NE = number of employers, D = dimension of the function, 3 in our example), abandon the food source\n        - if the bee is an employer, go to a new random food source\n        - if the bee is an onlooker, go to a food source neighboring a well-performing bee\n\nWe can access the colony's average fitness score, average fitness function return value, best fitness score, best fitness function return value and best parameters at any time:\n\n```python\nprint(abc.average_fitness)\nprint(abc.average_ret_val)\nprint(abc.best_fitness)\nprint(abc.best_ret_val)\nprint(abc.best_params)\n```\n\nECabc can utilize multiple CPU cores for concurrent processing:\n\n```python\nabc = ABC(10, minimize_integers, num_processes=8)\n```\n\nTying everything together, we have:\n\n```python\nfrom ecabc import ABC\n\ndef minimize_integers(integers):\n\n    return sum(integers)\n\nabc = ABC(10, minimize_integers)\nabc.add_param(0, 10, name='Int_1')\nabc.add_param(0, 10, name='Int_2')\nabc.add_param(0, 10, name='Int_3')\nabc.initialize()\nfor _ in range(10):\n    abc.search()\n    print('Average fitness: {}'.format(abc.average_fitness))\n    print('Average obj. fn. return value: {}'.format(abc.average_ret_val))\n    print('Best fitness score: {}'.format(abc.best_fitness))\n    print('Best obj. fn. return value: {}'.format(abc.best_ret_val))\n    print('Best parameters: {}\\n'.format(abc.best_params))\n```\n\nRunning this script produces:\n\n```\nAverage fitness: 0.08244866244866243\nAverage obj. fn. return value: 11.65\nBest fitness score: 0.125\nBest obj. fn. return value: 7\nBest parameters: {'Int_1': 4, 'Int_2': 3, 'Int_3': 0}\n\nAverage fitness: 0.0885855117105117\nAverage obj. fn. return value: 10.8\nBest fitness score: 0.125\nBest obj. fn. return value: 7\nBest parameters: {'Int_1': 4, 'Int_2': 3, 'Int_3': 0}\n\nAverage fitness: 0.10361832611832611\nAverage obj. fn. return value: 9.4\nBest fitness score: 0.16666666666666666\nBest obj. fn. return value: 5\nBest parameters: {'Int_1': 2, 'Int_2': 3, 'Int_3': 0}\n\nAverage fitness: 0.11173502151443326\nAverage obj. fn. return value: 8.8\nBest fitness score: 0.2\nBest obj. fn. return value: 4\nBest parameters: {'Int_1': 0, 'Int_2': 0, 'Int_3': 4}\n\nAverage fitness: 0.12448879551820731\nAverage obj. fn. return value: 7.95\nBest fitness score: 0.2\nBest obj. fn. return value: 4\nBest parameters: {'Int_1': 1, 'Int_2': 3, 'Int_3': 0}\n\nAverage fitness: 0.1767694805194805\nAverage obj. fn. return value: 6.7\nBest fitness score: 1.0\nBest obj. fn. return value: 0\nBest parameters: {'Int_1': 0, 'Int_2': 0, 'Int_3': 0}\n\nAverage fitness: 0.183255772005772\nAverage obj. fn. return value: 6.3\nBest fitness score: 1.0\nBest obj. fn. return value: 0\nBest parameters: {'Int_1': 0, 'Int_2': 0, 'Int_3': 0}\n\nAverage fitness: 0.20172799422799423\nAverage obj. fn. return value: 5.65\nBest fitness score: 1.0\nBest obj. fn. return value: 0\nBest parameters: {'Int_1': 0, 'Int_2': 0, 'Int_3': 0}\n\nAverage fitness: 0.23827561327561328\nAverage obj. fn. return value: 4.95\nBest fitness score: 1.0\nBest obj. fn. return value: 0\nBest parameters: {'Int_1': 0, 'Int_2': 0, 'Int_3': 0}\n\nAverage fitness: 0.28456349206349213\nAverage obj. fn. return value: 4.35\nBest fitness score: 1.0\nBest obj. fn. return value: 0\nBest parameters: {'Int_1': 0, 'Int_2': 0, 'Int_3': 0}\n```\n\nTo run this script yourself, head over to our [examples](https://github.com/ecrl/ecabc/tree/master/examples) directory.\n\n# Contributing, Reporting Issues and Other Support:\n\nTo contribute to ECabc, make a pull request. Contributions should include tests for new features added, as well as extensive documentation.\n\nTo report problems with the software or feature requests, file an issue. When reporting problems, include information such as error messages, your OS/environment and Python version.\n\nFor additional support/questions, contact Sanskriti Sharma (Sanskriti_Sharma@student.uml.edu), Hernan Gelaf-Romer (Hernan_Gelafromer@student.uml.edu), or Travis Kessler (Travis_Kessler@student.uml.edu).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecrl%2Fecabc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecrl%2Fecabc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecrl%2Fecabc/lists"}