# PyCRO-SL
## About
This project is a Python implementation of the **Coral Reef Optimization with Substrate Layers** algorithm,
both in its original version (CRO-SL) and in its probabilistic versions (PCRO-SL and DPCRO-SL). The goal is to provide an
easy-to-use, versatile Python package that can be used **off-the-shelf** for a wide array of optimization problems.
Among its features, we highlight:
- *Operators included*: the package includes more than 30 solution operators, such as Gaussian noise addition, BLX Alpha, Multi-point crossover, etc.
- *Multiple conditions*: the algorithm can be configured to stop after a given number of evaluations, generations, or time, or after reaching a given fitness value. These stopping conditions can also be combined using any logical expression.
- *Parallelization*: the package allows for parallelization of the fitness function evaluations, which can significantly speed up optimization.
- *Automatic report*: the implementation produces a graphical report at the end of each simulation, summarizing the behavior of the most important metrics.
- *Dynamic variant*: the algorithm has a dynamic variant, which allows it to reward the operators that perform better in the current problem.
For an explanation of how the CRO-SL algorithm works, we refer to [the paper](https://www.mdpi.com/2227-7390/11/7/1666).
## How to install
We recommend installing the project as a package. To do so, use the following commands:
```
git clone https://github.com.jperezaracil/PyCROSL.git
cd PyCROSL
pip intall -r requirements.txt
pip install -e .
```
Then, you can import the algorithm as a package, for example
```
from PyCROSL.CRO_SL import CRO_SL
```
## How to use it
To use PyCRO-SL in your own optimization problems, take a look at our [tutorial](/Tutorials/guide.ipynb).
## Parameters
To configure the hyperparameters a dictionary will have to be given to the class CRO_SL.
This dictionary contains the following parameters:
- Basic hyperparameters:
- `popSize`: maximum number of corals in the reef
- `rho`: percentage of initial occupation of the reef
- `Fb`: broadcast spawning proportion
- `Fd`: depredation proportion
- `Pd`: depredation probability
- `k`: maximum attempts for larva setting
- `K`: maximum number of corals with duplicate solutions
- `group_subs`: if `True`, corals reproduce only within the same substrate, if `False` they reproduce within the whole population
- Dynamic variant hyperparameters:
- `dynamic`: boolean value that determines whether to use the dynamic variant of the algorithm
- `method`: string that determines how to determine the probability of choosing each substrate. Possible values:
- `"fitness"`: uses the fitness of the individuals of each substrate.
- `"diff"`: uses the difference between the fitness of the previous generation and the current one.
- `"success"`: uses the ratio of successful larvae in each generation.
- `dyn_metric`: string that determines how to aggregate the values of each substrate to get the metric of each. Possible values:
- `"best"`: takes the best fitness
- `"avg"`: takes the average fitness
- `"med"`: takes the median fitness
- `"worse"`: takes the worse fitness
- `dyn_steps`: specifies the number of times the substrates will be evaluated. If `dyn_steps = -1`, the substrates will be evaluated every generation.
- `prob_amp`: float that determines how the differences between substrate metrics affect the probability of each one. A lower value means more amplification
- Stopping conditions (you only need to include the ones that will be used!):
- `Neval`: number of evaluations of the fitness function
- `Ngen`: number of generations
- `time_limit`: execution time limit given in seconds (real time, not CPU time)
- `fit_target`: value of the fitness function we want to reach
- `stop_cond`: a string that determines the stopping condition. It can be simply the name of the criterion to be used (e.g. `Ngen`, `Neval`, etc), or also a logical expression that combines these different criteria (e.g. `Ngen or Neval`, `time_limit and fit_target`, etc). Must be included even if only a single criterion is used.
- Parallelization:
- `Njobs`: the number of jobs to run in parallel. If `Njobs = 1`, the algorithm will run in sequential mode.
- Display options:
- `verbose`: shows a periodic report of the algorithm's performance
- `v_timer`: amount of time between each report
For examples of how to fill the parameters dictionary, please take a look at [main.py](/PyCROSL/main.py).
# Cite
If you use this implementation, please cite it as:
```bibtex
@article{perez2023,
title={New Probabilistic, Dynamic Multi-Method Ensembles for Optimization Based on the CRO-SL},
author={P{\'e}rez-Aracil, Jorge and Camacho-G{\'o}mez, Carlos and Lorente-Ramos, Eugenio and Marina, Cosmin M and Cornejo-Bueno, Laura M and Salcedo-Sanz, Sancho},
journal={Mathematics},
volume={11},
number={7},
pages={1666},
year={2023},
publisher={MDPI}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jperezaracil/PyCROSL.git",
"name": "PyCROSL",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "GHEODE",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/2b/81/5f37d1070ce5738144af262ab28de03c554e606ad3848c6c780bc2bdde0f/PyCROSL-1.0.tar.gz",
"platform": null,
"description": "# PyCRO-SL\n\n## About\n\nThis project is a Python implementation of the **Coral Reef Optimization with Substrate Layers** algorithm, \nboth in its original version (CRO-SL) and in its probabilistic versions (PCRO-SL and DPCRO-SL). The goal is to provide an\neasy-to-use, versatile Python package that can be used **off-the-shelf** for a wide array of optimization problems. \nAmong its features, we highlight:\n\n- *Operators included*: the package includes more than 30 solution operators, such as Gaussian noise addition, BLX Alpha, Multi-point crossover, etc.\n- *Multiple conditions*: the algorithm can be configured to stop after a given number of evaluations, generations, or time, or after reaching a given fitness value. These stopping conditions can also be combined using any logical expression.\n- *Parallelization*: the package allows for parallelization of the fitness function evaluations, which can significantly speed up optimization.\n- *Automatic report*: the implementation produces a graphical report at the end of each simulation, summarizing the behavior of the most important metrics. \n- *Dynamic variant*: the algorithm has a dynamic variant, which allows it to reward the operators that perform better in the current problem.\n\nFor an explanation of how the CRO-SL algorithm works, we refer to [the paper](https://www.mdpi.com/2227-7390/11/7/1666).\n\n## How to install\n\nWe recommend installing the project as a package. To do so, use the following commands:\n\n```\ngit clone https://github.com.jperezaracil/PyCROSL.git\ncd PyCROSL\npip intall -r requirements.txt\npip install -e .\n```\n\nThen, you can import the algorithm as a package, for example\n\n```\nfrom PyCROSL.CRO_SL import CRO_SL\n```\n## How to use it\n\nTo use PyCRO-SL in your own optimization problems, take a look at our [tutorial](/Tutorials/guide.ipynb).\n\n## Parameters\n\nTo configure the hyperparameters a dictionary will have to be given to the class CRO_SL.\nThis dictionary contains the following parameters:\n\n- Basic hyperparameters:\n - `popSize`: maximum number of corals in the reef \n - `rho`: percentage of initial occupation of the reef \n - `Fb`: broadcast spawning proportion\n - `Fd`: depredation proportion\n - `Pd`: depredation probability\n - `k`: maximum attempts for larva setting \n - `K`: maximum number of corals with duplicate solutions\n - `group_subs`: if `True`, corals reproduce only within the same substrate, if `False` they reproduce within the whole population\n- Dynamic variant hyperparameters:\n - `dynamic`: boolean value that determines whether to use the dynamic variant of the algorithm\n - `method`: string that determines how to determine the probability of choosing each substrate. Possible values:\n - `\"fitness\"`: uses the fitness of the individuals of each substrate.\n - `\"diff\"`: uses the difference between the fitness of the previous generation and the current one.\n - `\"success\"`: uses the ratio of successful larvae in each generation.\n - `dyn_metric`: string that determines how to aggregate the values of each substrate to get the metric of each. Possible values:\n - `\"best\"`: takes the best fitness\n - `\"avg\"`: takes the average fitness\n - `\"med\"`: takes the median fitness\n - `\"worse\"`: takes the worse fitness\n - `dyn_steps`: specifies the number of times the substrates will be evaluated. If `dyn_steps = -1`, the substrates will be evaluated every generation. \n - `prob_amp`: float that determines how the differences between substrate metrics affect the probability of each one. A lower value means more amplification\n- Stopping conditions (you only need to include the ones that will be used!):\n - `Neval`: number of evaluations of the fitness function\n - `Ngen`: number of generations\n - `time_limit`: execution time limit given in seconds (real time, not CPU time)\n - `fit_target`: value of the fitness function we want to reach\n - `stop_cond`: a string that determines the stopping condition. It can be simply the name of the criterion to be used (e.g. `Ngen`, `Neval`, etc), or also a logical expression that combines these different criteria (e.g. `Ngen or Neval`, `time_limit and fit_target`, etc). Must be included even if only a single criterion is used.\n- Parallelization:\n - `Njobs`: the number of jobs to run in parallel. If `Njobs = 1`, the algorithm will run in sequential mode.\n- Display options:\n - `verbose`: shows a periodic report of the algorithm's performance\n - `v_timer`: amount of time between each report\n\nFor examples of how to fill the parameters dictionary, please take a look at [main.py](/PyCROSL/main.py).\n\n# Cite\n\nIf you use this implementation, please cite it as:\n\n```bibtex\n@article{perez2023,\n title={New Probabilistic, Dynamic Multi-Method Ensembles for Optimization Based on the CRO-SL},\n author={P{\\'e}rez-Aracil, Jorge and Camacho-G{\\'o}mez, Carlos and Lorente-Ramos, Eugenio and Marina, Cosmin M and Cornejo-Bueno, Laura M and Salcedo-Sanz, Sancho},\n journal={Mathematics},\n volume={11},\n number={7},\n pages={1666},\n year={2023},\n publisher={MDPI}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pyhton implementation of the \"Coral Reef Optimization with Substrate Layers\" algorithm",
"version": "1.0",
"project_urls": {
"Homepage": "https://github.com/jperezaracil/PyCROSL.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "829918aba564e0689ce61221f9ce2d350b08b1169800581e979f2f72f65c928b",
"md5": "482796645986af8e5738f2b7a1c03026",
"sha256": "a61b3042704385f400ab4c49cf4b19d86e5e8f623d23d31f68a584d853f672f8"
},
"downloads": -1,
"filename": "PyCROSL-1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "482796645986af8e5738f2b7a1c03026",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 24946,
"upload_time": "2023-10-07T13:55:35",
"upload_time_iso_8601": "2023-10-07T13:55:35.271979Z",
"url": "https://files.pythonhosted.org/packages/82/99/18aba564e0689ce61221f9ce2d350b08b1169800581e979f2f72f65c928b/PyCROSL-1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2b815f37d1070ce5738144af262ab28de03c554e606ad3848c6c780bc2bdde0f",
"md5": "4985a2f5206f3cd12a8fba99d73200f0",
"sha256": "a3cd74c828692e64ca100c71a81386e3fa3f5597a8bc2f812e9745752ca331b4"
},
"downloads": -1,
"filename": "PyCROSL-1.0.tar.gz",
"has_sig": false,
"md5_digest": "4985a2f5206f3cd12a8fba99d73200f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22867,
"upload_time": "2023-10-07T13:55:37",
"upload_time_iso_8601": "2023-10-07T13:55:37.155861Z",
"url": "https://files.pythonhosted.org/packages/2b/81/5f37d1070ce5738144af262ab28de03c554e606ad3848c6c780bc2bdde0f/PyCROSL-1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-07 13:55:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jperezaracil",
"github_project": "PyCROSL",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.1"
]
]
},
{
"name": "numba",
"specs": [
[
">=",
"0.56.2"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.22.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.5.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.10.1"
]
]
},
{
"name": "joblib",
"specs": [
[
">=",
"1.2.0"
]
]
},
{
"name": "pyparsing",
"specs": [
[
">=",
"3.1.0"
]
]
}
],
"lcname": "pycrosl"
}
JSON
