# BeesAlgorithm - A Python Implementation
This repository contains a Bees Algorithm implementation in Python 3. For a more complete documentation please refer to the [project page](https://gitlab.com/bees-algorithm/bees_algorithm_python).
The aim is to make available to everyone an implementation, built with the minimal number of dependencies, which can be easily integrated in larger projects as well as used out-of-the-box to solve specific problems.
The Bees Algorithm is an intelligent optimization technique belonging to the swarm algorithms field.
Given a parametric objective function, the goal of the algorithm is to find the parameter values that maximise/minimise the output of the objective function.
Many real-world problems can be modeled as the optimisation of a parametric objective function, therefore effective algorithms to handle this kind of problems are of primary importance in many fields.
The Bees Algorithm performs simultaneus aggressive local searches around the most promising parameter settings of the objective function.
The algorithm is proven to outperform other intelligent optimisation techniques in many benchmark functions<sup>[3][4][5]</sup> as well as real world problems.
On top of this Python version, implmentations of the bees Algorithm in [C++](https://gitlab.com/bees-algorithm/bees_algorithm_cpp) and [Matlab](https://gitlab.com/bees-algorithm/bees_algorithm_matlab) are also available in the respective repositories.
The main steps of the Bees Algorithm will be described in the next section. For more information please refer to the [official Bees Algorithm website](http://beesalgorithmsite.altervista.org) and the [wikipedia page](https://en.wikipedia.org/wiki/Bees_algorithm). If you are interested in a detailed analysis of the algorithm, and the properties of its search strategy, please refer to this paper<sup>[1]</sup>:
- Luca Baronti, Marco Castellani, and Duc Truong Pham. "[An Analysis of the Search Mechanisms of the Bees Algorithm.](
https://doi.org/10.1016/j.swevo.2020.100746)" Swarm and Evolutionary Computation 59 (2020): 100746.
If you are using this implementation of the Bees Algorithm for your research, feel free to cite this work in your paper using the following BibTex entry:
```bibtex
@article{baronti2020analysis,
title={An Analysis of the Search Mechanisms of the Bees Algorithm},
author={Baronti, Luca and Castellani, Marco and Pham, Duc Truong},
journal={Swarm and Evolutionary Computation},
volume={59},
pages={100746},
year={2020},
publisher={Elsevier},
doi={10.1016/j.swevo.2020.100746},
url={https://doi.org/10.1016/j.swevo.2020.100746}
}
```
# Installation
This module is available on [pip](https://pypi.org/project/bees-algorithm) and can be installed as follows:
```sh
$ pip3 install bees_algorithm
```
# Introduction on the Bees Algorithm
<img src="https://images.pexels.com/photos/1043059/pexels-photo-1043059.jpeg"
align="left"
width="333" height="250" />
The Bees Algorithm is a nature-inspired search method that mimics the foraging behaviour of honey bees. It was created by [Prof. D.T. Pham](https://www.birmingham.ac.uk/staff/profiles/mechanical/pham-duc.aspx) and his co-workers in 2005<sup>[2]</sup>, and described in its standard formulation by Pham and Castellani<sup>[3]</sup>.
The algorithm uses a population of agents (artificial bees) to sample the solution space. A fraction of the population (scout bees) searches randomly for regions of high fitness (global search). The most successful scouts recruit a variable number of idle agents (forager bees) to search in the proximity of the fittest solutions (local search). Cycles of global and local search are repeated until an acceptable solution is discovered, or a given number of iterations have elapsed.
The standard version of the Bees Algorithm includes two heuristics: *neighbourhood shrinking* and *site abandonment*.
Using neighbourhood shrinking the size of the local search is progressively reduced when local search stops progressing on a given site.
The site abandonment procedure interrupts the search at one site after a given number of consecutive stagnation cycles, and restarts the local search at a randomly picked site.
<img src="https://gitlab.com/bees-algorithm/bees_algorithm_python/-/raw/master/pics/algorithm.png"
align="right"
width="300" height="300" />
The algorithm requires a number of parameters to be set, namely: the number of scout bees (*ns*), number of sites selected out of *ns* visited sites (*nb*), number of elite sites out of *nb* selected sites (*ne*), number of bees recruited for the best *ne* sites (*nre*), number of bees recruited for the other (*nb-ne*) selected sites (*nrb*).
The heuristics also require the set of the initial size of the patches (*ngh*) and the number of cycles after which a site is abandoned (*stlim*).
Finally, the stopping criterion must be defined.
The algorithm starts with the *ns* scout bees being placed randomly in the search space and the main algorithm steps can be summarised as follows:
1. Evaluate the fitness of the population according the objective function;
2. Select the best *nb* sites for neighbourhood (local) search;
3. Recruit *nrb* forager bees for the selected sites (*nre* bees for the best *ne* sites) and evaluate their fitnesses;
4. Select the fittest bee from each local site as the new site centre;
5. If a site fails to improve in a single local search, its neighbourhood size is reduced (neighbourhood shrinking);
6. If a site fails to improve for *stlim* cycles, the site is abandoned (site abandonment);
7. Assign the remaining bees to search uniformly the whole search space and evaluate their fitnesses;
8. If the stopping criterion is not met, return to step 2;
# Usage
This repository offers two kinds of libraries.
The library contained in *bees_algorithm.py* is a simple python implementation of the iterative Bees Algorithm.
The libraries contained in *bees_algorithm_parallel_algorithm.py* and *bees_algorithm_parallel_testing.py* offer parallel versions of the algorithm, which is implemented on two different levels of parallelisms.
### Guidelines
The implementations present here try to cover the following use cases:
- General use of the Bees Algorithm on a single test when only a limited number of iterations are expected: use *BeesAlgorithm* from *bees_algorithm.py*;
- Single test using a computationally expensive objective function, a large number of dimensions or iterations: use *ParallelBeesAlgorithm* from *bees_algorithm_parallel_algorithm.py*;
- Single test using an even more computationally expensive objective function, a larger number of dimensions or iterations: use *FullyParallelBeesAlgorithm* from *bees_algorithm_parallel_algorithm.py*;
- Multiple tests on the same objective function: use *BeesAlgorithmTester* from *bees_algorithm_parallel_testing.py*;
Please refer to the tests present in the following [test section](#tests) for the resons behind these guidelines.
## Iterative Version
To use the library just import it
```python
from bees_algorithm import BeesAlgorithm
```
then define your objective function (an hypesphere in this case)
```python
def hypersphere(x):
return -sum([pow(xi,2) for xi in x])
```
and the search boundaries (in this case we are assuming a 4-dimensional search)
```python
search_boundaries=([-5,-5,-5,-5], [5,5,5,5])
```
This implementation of the bees algorithm will always try to find the solution that **maximize** the objective function.
Therefore, if you have to find the minimum of your function $`g(x)`$ simply implement the objective function $`f(x)=-g(x)`$.
The next step is create an instance of the algoritm:
```python
alg = BeesAlgorithm(hypersphere,search_boundaries[0],search_boundaries[1])
```
This will create an instance of the bees algorithm with default parameters (ns=10,nb=5,ne=1,nrb=10,nre=15,stlim=10,shrink_factor=.2).
To use a different set of parameters, it's sufficient to pass the right values in the constructor like that:
```python
alg = BeesAlgorithm(hypersphere,search_boundaries[0],search_boundaries[1],ns=0,nb=14,ne=1,nrb=5,nre=30,stlim=10)
```
This implementation of the bees algorithm use a simplified parameters formulation for the scout bees.
Normally the parameter *ns* indicates the number of best sites **and** the number of scout bees used for the global search at each iteration.
In this simpler formulation the parameter *ns* is the number of scout bees that are exclusively used for the global search, instead.
Therefore setting *ns=0* means that no scout bees are used for the global search.
In any case, it's possible to use the traditional parameters notation setting *useSimplifiedParameters=True* in the constructor.
To perform the optimisation is possible to do it iteratively calling:
```python
alg.performSingleStep()
```
which perform a single iteration of the algoritm.
Alternatively it's possible to perform the search all at once with:
```python
alg.performFullOptimisation(max_iteration=5000)
```
In this case, two different stop criteria can be used: *max_iteration* wil interrupt the optimisation when a certain number of iterations are reached and *max_score* will interrupt it when a certain score is reached.
If this method is used, at least one stop criterion must be specified.
Finally, it is possible to use both the stop criteria, in which case the algorithm will stop when the first one is reached.
To assess the state of the algorithm, as well as the final result, the following variable can be accessed:
```python
best = alg.best_solution
best.score # is the score of the best solution (e.g. 0.0 in our case)
best.values # are the coordinates of the best solution (e.g. [0.0, 0.0, 0.0, 0.0] in our case)
```
It is also possible to asses the score and values of all the current *nb* best sites accessing to the list *alg.current_sites*.
The variable *best_solution* contains the best solution found so far by the algorithm, which may or may not be included in the current best sites list *current_sites*.
## Parallel Versions
The parallel version exposes the data structures and functions to run the Bees Algorithm in parallel on two different levels:
- At the testing level, where a certain number of instances of the iterative Bees Algorithm are run in parallel on the same objective function;
- At the algorithm level, where a single instance of a parallel version of the Bees Algorithm is run on a certain objective function;
Despite using a prallel version of the algorithm in a parallel may looks like a good idea, the eccessive prolification of processes that will result would most likely impact negatively on the performance.
For this reason other kind of *mixed* parallelisms are not implemented here.
### Parallel Version: Testing Level
Being a sthocastic algorithm, the final result of the Bees Algorithm is not deterministic.
Therefore, running multiple instances of the algorithm on the same problem is useful to assess the general quality of the Bees Algorithm, or of a certain selection of its parameters, on a given problem.
In this case (testing level) it is possible to import:
```python
from bees_algorithm import BeesAlgorithmTester
```
create an instance of the class *BeesAlgorithmTester* class similarly to how is done with the iterative version:
```python
tester = BeesAlgorithmTester(hypersphere,search_boundaries[0],search_boundaries[2])
```
and finally call the *run_tests* function:
```python
tester.run_tests(n_tests=50, max_iteration=5000)
```
which accepts the parameter *n_tests*, which defines how many test ought to be performed, the optional parameter *verbose*, useful to assess the completion of the single processes and the stop criteria used (similar to the *performFullOptimisation* function).
Optionallly, it is also possible to pass the argument *n_processes* to define the degree of parallelism (namely, how many processes are run at the same time).
If it is not present, the number of cores of the CPU will be used as degree of parallelism.
It is advisable to not use an high value for this argument, otherwise the performances may be *negatively* impacted.
Once the *run_tests* function is terminated the final results can be accessed using the *results* list of the instance, this way:
```python
res = tester.results
```
each element of the *results* list is a tuple *(iteration, best_solution)* representing the iteration reached and the best solution found for a run.
### Parallel Version: Algorithm Level
Some characteristics of the Bees Algorithm pose serious limitation on the design of an effective parallel version.
One of the most effective way to perform the algorithm in parallel is to run the sequence of sites local searches simultaneously.
However, mapping a site search search on a thread/process that perform the whole site search (up to the point the site is abandoned) can't be entirerly done due to some info that need to be shared between the sites.
For instance, at each iteration the algorithm must know:
- which *nb* sites are the best ones, to promote them to elite sites and give them more foragers;
- which *nb* sites need to be replaced by better solutions found in the global search (*ns*);
- how many local searches have been done so far, and what's the best solution, to assess the stop criteria;
To assess all these information, the parallel searches must stop-and-report to a central controller, reducing the parallelism performances greately.
Removing heuristics like the elite sites, the global scouts, and accepting some approximation on the stop criteria (i.e. updating the number of iterations and best score only when a site is abandoned) will remove this problem.
However these modifications will lead to a quite different algorithm than the standard one, so the two different approaches are implemented in this library.
#### Parallel Version: Algorithm Level - Partial
In this version, the Bees Algorithm works in parallel only in performing a single local search for all the sites.
That is, at each iteration, the *nb* sites perform a single local search in parallel.
In this way it's possible to control the other aspects of the algorithm keeping its original behaviour and, at the same time, have an improvment in the completion time to a certain extent.
To use this parallel version of the Bees Algorithm it is possible to import:
```python
from bees_algorithm import ParallelBeesAlgorithm
```
and create an instance of the class *ParallelBeesAlgorithm* class exactly how is done with the iterative version:
```python
alg = ParallelBeesAlgorithm(hypersphere,search_boundaries[0],search_boundaries[2])
```
where the constructors takes all the parameters of the iterative version, with the addition of the *n_processes* parameters, set as the number of cores of the current machine as default.
The algorithm instance can then be used exactly the same way as the iterative case.
#### Parallel Version: Algorithm Level - Full
In this version, *nb* sites perform separate searches in a higher degree of parallelism.
Under ideal circumnstances, *nb* threads are run in parallel, each one performing a search for a site.
When the site is abandoned, the associated thread will generate a new site and start a new search.
Threads communicate to eachothers only in assessing the stop criteria, mostly when a site is abandoned.
This will avoid overhead induced by accessing to shared resources with high frequency.
This version can potentially offers an higher performance Bees Algorithm, however it comes with the following limitations:
- No elite sites can be used;
- No global scouts can be used;
- The value of the final number of iterations may not be accurate (can be overestimed);
To use this parallel version of the Bees Algorithm it is possible to import the same file:
```python
from bees_algorithm import FullyParallelBeesAlgorithm
```
and create an instance of the class *FullyParallelBeesAlgorithm* class similarry as it is done with the iterative version:
```python
alg = FullyParallelBeesAlgorithm(hypersphere,search_boundaries[0],search_boundaries[2])
```
The key difference is that the constructor accept the following parameters: *score_function*, *range_min*, *range_max*, *nb*, *nrb*, *stlim*, *initial_ngh*, *shrink_factor*,*useSimplifiedParameters* and *n_processes*.
The number of threads used in this case will be:
```math
\min(nb, n\_processes)
```
The algorithm instance can then be used exactly the same way as the iterative case.
# Step-by-step Visualisation
A function that plot a visual rapresentation of the Bees Algorithm steps is included in this package.
The function *visualize_iteration_steps* can be called in lieu of *performFullOptimisation*. It accepts no parameters.
Here is an example using the *Schwefel* target function (see section below for details):
```python
import benchmark_functions as bf
b_func = bf.Schwefel(opposite=True)
suggested_lowerbound, suggested_upperbound = b_func.suggested_bounds()
schwefel_bees_parameters = {'ns':0, 'nb':14, 'ne':1, 'nrb':5, 'nre':30, 'stlim':10}
alg = BeesAlgorithm(b_func,
suggested_lowerbound, suggested_upperbound,
**schwefel_bees_parameters)
alg.visualize_iteration_steps()
```
# References
- [1]: Luca Baronti, Marco Castellani, and Duc Truong Pham. "[An Analysis of the Search Mechanisms of the Bees Algorithm.](
https://www.sciencedirect.com/science/article/abs/pii/S2210650220303990)" Swarm and Evolutionary Computation 59 (2020): 100746.
- [2]: Pham, Duc Truong, et al. "[The Bees Algorithm—A Novel Tool for Complex Optimisation Problems.](https://s3.amazonaws.com/academia.edu.documents/37269572/Pham06_-_The_Bee_Algorithm.pdf?AWSAccessKeyId=AKIAIWOWYYGZ2Y53UL3A&Expires=1550167392&Signature=%2BAoKD8QFeUIXvpEjojuAxWu2y0k%3D&response-content-disposition=inline%3B%20filename%3DThe_Bees_Algorithm_-_A_Novel_Tool_for_Co.pdf)" Intelligent production machines and systems. 2006. 454-459.
- [3]: Pham, Duc Truong, and Marco Castellani. "[The bees algorithm: modelling foraging behaviour to solve continuous optimization problems.](https://www.researchgate.net/profile/Marco_Castellani2/publication/229698041_The_Bees_Algorithm_Modelling_foraging_behaviour_to_solve_continuous_optimization_problems/links/0912f50107f349b7de000000/The-Bees-Algorithm-Modelling-foraging-behaviour-to-solve-continuous-optimization-problems.pdf)" Proceedings of the Institution of Mechanical Engineers, Part C: Journal of Mechanical Engineering Science 223.12 (2009): 2919-2938.
- [4]: Pham, Duc Truong, and Marco Castellani. "[Benchmarking and comparison of nature-inspired population-based continuous optimisation algorithms.](https://link.springer.com/article/10.1007/s00500-013-1104-9)" Soft Computing 18.5 (2014): 871-903.
- [5]: Pham, Duc Truong, and Marco Castellani. "[A comparative study of the Bees Algorithm as a tool for function optimisation.](https://www.tandfonline.com/doi/full/10.1080/23311916.2015.1091540)" Cogent Engineering 2.1 (2015): 1091540.
For more references please refer to the README file in the [C++ repository](https://gitlab.com/bees-algorithm/bees_algorithm_cpp).
# Author and License
This library is developed and mantained by Luca Baronti (**gmail** address: *lbaronti*) and released under [GPL v3 license](LICENSE).
# Versions History
## v1.0.2
- minor fixes
- minor code refactoring
- added numpy dependnency
- moved static method *visualize_steps* to instance method *visualize_iteration_steps*
## v1.0.1
- minor fixes in the README
## v1.0.0
- full stable release
- added unit tests
- made compliant with benchmark_functions v1.1.3
## v0.1.1
- initial beta release
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/bees-algorithm/bees_algorithm_python",
"name": "bees-algorithm",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Optimisation,Optimization,Bees Algorithm,Intelligent Optimisation",
"author": "Luca Baronti",
"author_email": "lbaronti@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/40/b9/e5b3c2c7499c86a968a22eb888c6219d8b2cb76ad1509eab9066b72fb1f0/bees_algorithm-1.0.2.tar.gz",
"platform": null,
"description": "# BeesAlgorithm - A Python Implementation\n\nThis repository contains a Bees Algorithm implementation in Python 3. For a more complete documentation please refer to the [project page](https://gitlab.com/bees-algorithm/bees_algorithm_python).\n\nThe aim is to make available to everyone an implementation, built with the minimal number of dependencies, which can be easily integrated in larger projects as well as used out-of-the-box to solve specific problems.\n\nThe Bees Algorithm is an intelligent optimization technique belonging to the swarm algorithms field.\nGiven a parametric objective function, the goal of the algorithm is to find the parameter values that maximise/minimise the output of the objective function.\n\nMany real-world problems can be modeled as the optimisation of a parametric objective function, therefore effective algorithms to handle this kind of problems are of primary importance in many fields.\nThe Bees Algorithm performs simultaneus aggressive local searches around the most promising parameter settings of the objective function.\nThe algorithm is proven to outperform other intelligent optimisation techniques in many benchmark functions<sup>[3][4][5]</sup> as well as real world problems.\n\nOn top of this Python version, implmentations of the bees Algorithm in [C++](https://gitlab.com/bees-algorithm/bees_algorithm_cpp) and [Matlab](https://gitlab.com/bees-algorithm/bees_algorithm_matlab) are also available in the respective repositories. \n\nThe main steps of the Bees Algorithm will be described in the next section. For more information please refer to the [official Bees Algorithm website](http://beesalgorithmsite.altervista.org) and the [wikipedia page](https://en.wikipedia.org/wiki/Bees_algorithm). If you are interested in a detailed analysis of the algorithm, and the properties of its search strategy, please refer to this paper<sup>[1]</sup>:\n\n- Luca Baronti, Marco Castellani, and Duc Truong Pham. \"[An Analysis of the Search Mechanisms of the Bees Algorithm.](\nhttps://doi.org/10.1016/j.swevo.2020.100746)\" Swarm and Evolutionary Computation 59 (2020): 100746.\n\nIf you are using this implementation of the Bees Algorithm for your research, feel free to cite this work in your paper using the following BibTex entry:\n```bibtex\n@article{baronti2020analysis,\n title={An Analysis of the Search Mechanisms of the Bees Algorithm},\n author={Baronti, Luca and Castellani, Marco and Pham, Duc Truong},\n journal={Swarm and Evolutionary Computation},\n volume={59},\n pages={100746},\n year={2020},\n publisher={Elsevier},\n doi={10.1016/j.swevo.2020.100746},\n url={https://doi.org/10.1016/j.swevo.2020.100746}\n}\n```\n\n# Installation\nThis module is available on [pip](https://pypi.org/project/bees-algorithm) and can be installed as follows:\n```sh\n$ pip3 install bees_algorithm\n```\n\n\n# Introduction on the Bees Algorithm\n<img src=\"https://images.pexels.com/photos/1043059/pexels-photo-1043059.jpeg\"\n align=\"left\"\n width=\"333\" height=\"250\" />\n\nThe Bees Algorithm is a nature-inspired search method that mimics the foraging behaviour of honey bees. It was created by [Prof. D.T. Pham](https://www.birmingham.ac.uk/staff/profiles/mechanical/pham-duc.aspx) and his co-workers in 2005<sup>[2]</sup>, and described in its standard formulation by Pham and Castellani<sup>[3]</sup>.\n\nThe algorithm uses a population of agents (artificial bees) to sample the solution space. A fraction of the population (scout bees) searches randomly for regions of high fitness (global search). The most successful scouts recruit a variable number of idle agents (forager bees) to search in the proximity of the fittest solutions (local search). Cycles of global and local search are repeated until an acceptable solution is discovered, or a given number of iterations have elapsed.\n\nThe standard version of the Bees Algorithm includes two heuristics: *neighbourhood shrinking* and *site abandonment*.\nUsing neighbourhood shrinking the size of the local search is progressively reduced when local search stops progressing on a given site.\nThe site abandonment procedure interrupts the search at one site after a given number of consecutive stagnation cycles, and restarts the local search at a randomly picked site.\n\n\n<img src=\"https://gitlab.com/bees-algorithm/bees_algorithm_python/-/raw/master/pics/algorithm.png\"\n align=\"right\"\n width=\"300\" height=\"300\" />\n\nThe algorithm requires a number of parameters to be set, namely: the number of scout bees (*ns*), number of sites selected out of *ns* visited sites (*nb*), number of elite sites out of *nb* selected sites (*ne*), number of bees recruited for the best *ne* sites (*nre*), number of bees recruited for the other (*nb-ne*) selected sites (*nrb*).\nThe heuristics also require the set of the initial size of the patches (*ngh*) and the number of cycles after which a site is abandoned (*stlim*).\nFinally, the stopping criterion must be defined. \n\nThe algorithm starts with the *ns* scout bees being placed randomly in the search space and the main algorithm steps can be summarised as follows:\n\n\n1. Evaluate the fitness of the population according the objective function;\n2. Select the best *nb* sites for neighbourhood (local) search;\n3. Recruit *nrb* forager bees for the selected sites (*nre* bees for the best *ne* sites) and evaluate their fitnesses;\n4. Select the fittest bee from each local site as the new site centre;\n5. If a site fails to improve in a single local search, its neighbourhood size is reduced (neighbourhood shrinking);\n6. If a site fails to improve for *stlim* cycles, the site is abandoned (site abandonment);\n7. Assign the remaining bees to search uniformly the whole search space and evaluate their fitnesses;\n8. If the stopping criterion is not met, return to step 2;\n\n# Usage\nThis repository offers two kinds of libraries. \nThe library contained in *bees_algorithm.py* is a simple python implementation of the iterative Bees Algorithm.\nThe libraries contained in *bees_algorithm_parallel_algorithm.py* and *bees_algorithm_parallel_testing.py* offer parallel versions of the algorithm, which is implemented on two different levels of parallelisms.\n\n### Guidelines\nThe implementations present here try to cover the following use cases:\n\n- General use of the Bees Algorithm on a single test when only a limited number of iterations are expected: use *BeesAlgorithm* from *bees_algorithm.py*;\n- Single test using a computationally expensive objective function, a large number of dimensions or iterations: use *ParallelBeesAlgorithm* from *bees_algorithm_parallel_algorithm.py*;\n- Single test using an even more computationally expensive objective function, a larger number of dimensions or iterations: use *FullyParallelBeesAlgorithm* from *bees_algorithm_parallel_algorithm.py*;\n- Multiple tests on the same objective function: use *BeesAlgorithmTester* from *bees_algorithm_parallel_testing.py*;\n\nPlease refer to the tests present in the following [test section](#tests) for the resons behind these guidelines.\n\n## Iterative Version\nTo use the library just import it\n```python\nfrom bees_algorithm import BeesAlgorithm\n```\nthen define your objective function (an hypesphere in this case)\n```python\ndef hypersphere(x):\n return -sum([pow(xi,2) for xi in x])\n```\nand the search boundaries (in this case we are assuming a 4-dimensional search)\n```python\nsearch_boundaries=([-5,-5,-5,-5], [5,5,5,5])\n```\nThis implementation of the bees algorithm will always try to find the solution that **maximize** the objective function.\nTherefore, if you have to find the minimum of your function $`g(x)`$ simply implement the objective function $`f(x)=-g(x)`$.\n\nThe next step is create an instance of the algoritm:\n```python\nalg = BeesAlgorithm(hypersphere,search_boundaries[0],search_boundaries[1])\n```\nThis will create an instance of the bees algorithm with default parameters (ns=10,nb=5,ne=1,nrb=10,nre=15,stlim=10,shrink_factor=.2).\nTo use a different set of parameters, it's sufficient to pass the right values in the constructor like that:\n```python\nalg = BeesAlgorithm(hypersphere,search_boundaries[0],search_boundaries[1],ns=0,nb=14,ne=1,nrb=5,nre=30,stlim=10)\n```\nThis implementation of the bees algorithm use a simplified parameters formulation for the scout bees.\nNormally the parameter *ns* indicates the number of best sites **and** the number of scout bees used for the global search at each iteration.\nIn this simpler formulation the parameter *ns* is the number of scout bees that are exclusively used for the global search, instead.\nTherefore setting *ns=0* means that no scout bees are used for the global search.\n\nIn any case, it's possible to use the traditional parameters notation setting *useSimplifiedParameters=True* in the constructor.\n\nTo perform the optimisation is possible to do it iteratively calling:\n```python\nalg.performSingleStep()\n```\nwhich perform a single iteration of the algoritm.\nAlternatively it's possible to perform the search all at once with:\n```python\nalg.performFullOptimisation(max_iteration=5000)\n```\nIn this case, two different stop criteria can be used: *max_iteration* wil interrupt the optimisation when a certain number of iterations are reached and *max_score* will interrupt it when a certain score is reached.\nIf this method is used, at least one stop criterion must be specified.\nFinally, it is possible to use both the stop criteria, in which case the algorithm will stop when the first one is reached.\n\nTo assess the state of the algorithm, as well as the final result, the following variable can be accessed:\n```python\nbest = alg.best_solution\nbest.score # is the score of the best solution (e.g. 0.0 in our case)\nbest.values # are the coordinates of the best solution (e.g. [0.0, 0.0, 0.0, 0.0] in our case)\n```\nIt is also possible to asses the score and values of all the current *nb* best sites accessing to the list *alg.current_sites*.\n\nThe variable *best_solution* contains the best solution found so far by the algorithm, which may or may not be included in the current best sites list *current_sites*.\n\n## Parallel Versions\nThe parallel version exposes the data structures and functions to run the Bees Algorithm in parallel on two different levels:\n\n- At the testing level, where a certain number of instances of the iterative Bees Algorithm are run in parallel on the same objective function;\n- At the algorithm level, where a single instance of a parallel version of the Bees Algorithm is run on a certain objective function;\n\nDespite using a prallel version of the algorithm in a parallel may looks like a good idea, the eccessive prolification of processes that will result would most likely impact negatively on the performance.\nFor this reason other kind of *mixed* parallelisms are not implemented here.\n### Parallel Version: Testing Level\nBeing a sthocastic algorithm, the final result of the Bees Algorithm is not deterministic. \nTherefore, running multiple instances of the algorithm on the same problem is useful to assess the general quality of the Bees Algorithm, or of a certain selection of its parameters, on a given problem.\n\nIn this case (testing level) it is possible to import:\n```python\nfrom bees_algorithm import BeesAlgorithmTester\n```\ncreate an instance of the class *BeesAlgorithmTester* class similarly to how is done with the iterative version:\n```python\ntester = BeesAlgorithmTester(hypersphere,search_boundaries[0],search_boundaries[2])\n```\nand finally call the *run_tests* function:\n```python\ntester.run_tests(n_tests=50, max_iteration=5000)\n```\nwhich accepts the parameter *n_tests*, which defines how many test ought to be performed, the optional parameter *verbose*, useful to assess the completion of the single processes and the stop criteria used (similar to the *performFullOptimisation* function).\n\nOptionallly, it is also possible to pass the argument *n_processes* to define the degree of parallelism (namely, how many processes are run at the same time).\nIf it is not present, the number of cores of the CPU will be used as degree of parallelism.\nIt is advisable to not use an high value for this argument, otherwise the performances may be *negatively* impacted.\n\nOnce the *run_tests* function is terminated the final results can be accessed using the *results* list of the instance, this way:\n```python\nres = tester.results\n```\neach element of the *results* list is a tuple *(iteration, best_solution)* representing the iteration reached and the best solution found for a run.\n\n### Parallel Version: Algorithm Level\nSome characteristics of the Bees Algorithm pose serious limitation on the design of an effective parallel version.\nOne of the most effective way to perform the algorithm in parallel is to run the sequence of sites local searches simultaneously.\nHowever, mapping a site search search on a thread/process that perform the whole site search (up to the point the site is abandoned) can't be entirerly done due to some info that need to be shared between the sites.\nFor instance, at each iteration the algorithm must know:\n\n- which *nb* sites are the best ones, to promote them to elite sites and give them more foragers;\n- which *nb* sites need to be replaced by better solutions found in the global search (*ns*);\n- how many local searches have been done so far, and what's the best solution, to assess the stop criteria;\n\nTo assess all these information, the parallel searches must stop-and-report to a central controller, reducing the parallelism performances greately.\nRemoving heuristics like the elite sites, the global scouts, and accepting some approximation on the stop criteria (i.e. updating the number of iterations and best score only when a site is abandoned) will remove this problem.\nHowever these modifications will lead to a quite different algorithm than the standard one, so the two different approaches are implemented in this library.\n\n#### Parallel Version: Algorithm Level - Partial\nIn this version, the Bees Algorithm works in parallel only in performing a single local search for all the sites.\n\nThat is, at each iteration, the *nb* sites perform a single local search in parallel.\nIn this way it's possible to control the other aspects of the algorithm keeping its original behaviour and, at the same time, have an improvment in the completion time to a certain extent.\n\nTo use this parallel version of the Bees Algorithm it is possible to import:\n```python\nfrom bees_algorithm import ParallelBeesAlgorithm\n```\nand create an instance of the class *ParallelBeesAlgorithm* class exactly how is done with the iterative version:\n```python\nalg = ParallelBeesAlgorithm(hypersphere,search_boundaries[0],search_boundaries[2])\n```\nwhere the constructors takes all the parameters of the iterative version, with the addition of the *n_processes* parameters, set as the number of cores of the current machine as default.\nThe algorithm instance can then be used exactly the same way as the iterative case.\n\n#### Parallel Version: Algorithm Level - Full\nIn this version, *nb* sites perform separate searches in a higher degree of parallelism.\n\nUnder ideal circumnstances, *nb* threads are run in parallel, each one performing a search for a site.\nWhen the site is abandoned, the associated thread will generate a new site and start a new search.\nThreads communicate to eachothers only in assessing the stop criteria, mostly when a site is abandoned.\nThis will avoid overhead induced by accessing to shared resources with high frequency.\n\nThis version can potentially offers an higher performance Bees Algorithm, however it comes with the following limitations:\n\n- No elite sites can be used;\n- No global scouts can be used;\n- The value of the final number of iterations may not be accurate (can be overestimed);\n\nTo use this parallel version of the Bees Algorithm it is possible to import the same file:\n```python\nfrom bees_algorithm import FullyParallelBeesAlgorithm\n```\nand create an instance of the class *FullyParallelBeesAlgorithm* class similarry as it is done with the iterative version:\n```python\nalg = FullyParallelBeesAlgorithm(hypersphere,search_boundaries[0],search_boundaries[2])\n```\nThe key difference is that the constructor accept the following parameters: *score_function*, *range_min*, *range_max*, *nb*, *nrb*, *stlim*, *initial_ngh*, *shrink_factor*,*useSimplifiedParameters* and *n_processes*.\n\nThe number of threads used in this case will be:\n```math\n\\min(nb, n\\_processes)\n```\nThe algorithm instance can then be used exactly the same way as the iterative case.\n\n# Step-by-step Visualisation\nA function that plot a visual rapresentation of the Bees Algorithm steps is included in this package.\nThe function *visualize_iteration_steps* can be called in lieu of *performFullOptimisation*. It accepts no parameters.\n\nHere is an example using the *Schwefel* target function (see section below for details):\n```python\nimport benchmark_functions as bf\n\nb_func = bf.Schwefel(opposite=True)\nsuggested_lowerbound, suggested_upperbound = b_func.suggested_bounds()\nschwefel_bees_parameters = {'ns':0, 'nb':14, 'ne':1, 'nrb':5, 'nre':30, 'stlim':10}\n\nalg = BeesAlgorithm(b_func,\n suggested_lowerbound, suggested_upperbound,\n **schwefel_bees_parameters)\n\nalg.visualize_iteration_steps()\n```\n\n# References\n\n- [1]: Luca Baronti, Marco Castellani, and Duc Truong Pham. \"[An Analysis of the Search Mechanisms of the Bees Algorithm.](\nhttps://www.sciencedirect.com/science/article/abs/pii/S2210650220303990)\" Swarm and Evolutionary Computation 59 (2020): 100746.\n- [2]: Pham, Duc Truong, et al. \"[The Bees Algorithm\u2014A Novel Tool for Complex Optimisation Problems.](https://s3.amazonaws.com/academia.edu.documents/37269572/Pham06_-_The_Bee_Algorithm.pdf?AWSAccessKeyId=AKIAIWOWYYGZ2Y53UL3A&Expires=1550167392&Signature=%2BAoKD8QFeUIXvpEjojuAxWu2y0k%3D&response-content-disposition=inline%3B%20filename%3DThe_Bees_Algorithm_-_A_Novel_Tool_for_Co.pdf)\" Intelligent production machines and systems. 2006. 454-459.\n- [3]: Pham, Duc Truong, and Marco Castellani. \"[The bees algorithm: modelling foraging behaviour to solve continuous optimization problems.](https://www.researchgate.net/profile/Marco_Castellani2/publication/229698041_The_Bees_Algorithm_Modelling_foraging_behaviour_to_solve_continuous_optimization_problems/links/0912f50107f349b7de000000/The-Bees-Algorithm-Modelling-foraging-behaviour-to-solve-continuous-optimization-problems.pdf)\" Proceedings of the Institution of Mechanical Engineers, Part C: Journal of Mechanical Engineering Science 223.12 (2009): 2919-2938.\n- [4]: Pham, Duc Truong, and Marco Castellani. \"[Benchmarking and comparison of nature-inspired population-based continuous optimisation algorithms.](https://link.springer.com/article/10.1007/s00500-013-1104-9)\" Soft Computing 18.5 (2014): 871-903.\n- [5]: Pham, Duc Truong, and Marco Castellani. \"[A comparative study of the Bees Algorithm as a tool for function optimisation.](https://www.tandfonline.com/doi/full/10.1080/23311916.2015.1091540)\" Cogent Engineering 2.1 (2015): 1091540.\n\nFor more references please refer to the README file in the [C++ repository](https://gitlab.com/bees-algorithm/bees_algorithm_cpp).\n\n# Author and License\n\nThis library is developed and mantained by Luca Baronti (**gmail** address: *lbaronti*) and released under [GPL v3 license](LICENSE).\n\n\n# Versions History\n\n## v1.0.2\n\n- minor fixes\n- minor code refactoring\n- added numpy dependnency\n- moved static method *visualize_steps* to instance method *visualize_iteration_steps*\n\n## v1.0.1\n\n- minor fixes in the README\n\n## v1.0.0\n\n- full stable release\n- added unit tests\n- made compliant with benchmark_functions v1.1.3\n\n## v0.1.1\n\n- initial beta release\n\n\n",
"bugtrack_url": null,
"license": "GNUv3",
"summary": "A Python implementation of the Bees Algorithm. This library allows an out-of-the-box use of the optimisation algorithm on an user-defined target function. The algorithm can be configured to find either the minimum or the maximum of the target function with an iterative process.",
"version": "1.0.2",
"split_keywords": [
"optimisation",
"optimization",
"bees algorithm",
"intelligent optimisation"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "eeb6720ba28da0019010661c53b3b246",
"sha256": "a0570ca90d7f44076a4152c893d54f833ec86c97220cb50c96a636034e098a98"
},
"downloads": -1,
"filename": "bees_algorithm-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eeb6720ba28da0019010661c53b3b246",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 27066,
"upload_time": "2022-12-27T16:17:09",
"upload_time_iso_8601": "2022-12-27T16:17:09.658447Z",
"url": "https://files.pythonhosted.org/packages/d2/b8/9595307e7542ff9dbdb6423bf81f49b6e9e4fd67fb7456abbb970a5bc413/bees_algorithm-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "fc24e0f51b0b58dcbaf179d36b84b2fd",
"sha256": "4e1813899eb74c119a9ffbb993b6e0ba5e830ba0115a51ae4376b90d16e0f95b"
},
"downloads": -1,
"filename": "bees_algorithm-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "fc24e0f51b0b58dcbaf179d36b84b2fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 35084,
"upload_time": "2022-12-27T16:17:11",
"upload_time_iso_8601": "2022-12-27T16:17:11.804220Z",
"url": "https://files.pythonhosted.org/packages/40/b9/e5b3c2c7499c86a968a22eb888c6219d8b2cb76ad1509eab9066b72fb1f0/bees_algorithm-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-27 16:17:11",
"github": false,
"gitlab": true,
"bitbucket": false,
"gitlab_user": "bees-algorithm",
"gitlab_project": "bees_algorithm_python",
"lcname": "bees-algorithm"
}
JSON