{"id":28557290,"url":"https://github.com/giovcandido/swarming","last_synced_at":"2025-06-30T05:03:28.511Z","repository":{"id":57472629,"uuid":"382442305","full_name":"giovcandido/swarming","owner":"giovcandido","description":"Swarming is a Python3 library that features both parallel and serial implementation of the Particle Swarm Optimization (PSO) algorithm.","archived":false,"fork":false,"pushed_at":"2021-10-26T20:26:49.000Z","size":460,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-10T07:09:34.651Z","etag":null,"topics":["distributed-computing","library","metaheuristic","optimization","optimizer","parallel","particle-swarm-optimization","pso","python3","swarm-optimization-algorithm"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giovcandido.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}},"created_at":"2021-07-02T19:20:50.000Z","updated_at":"2024-12-25T04:24:02.000Z","dependencies_parsed_at":"2022-09-19T05:21:22.110Z","dependency_job_id":null,"html_url":"https://github.com/giovcandido/swarming","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/giovcandido/swarming","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giovcandido%2Fswarming","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giovcandido%2Fswarming/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giovcandido%2Fswarming/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giovcandido%2Fswarming/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giovcandido","download_url":"https://codeload.github.com/giovcandido/swarming/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giovcandido%2Fswarming/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262714471,"owners_count":23352462,"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":["distributed-computing","library","metaheuristic","optimization","optimizer","parallel","particle-swarm-optimization","pso","python3","swarm-optimization-algorithm"],"created_at":"2025-06-10T07:09:31.514Z","updated_at":"2025-06-30T05:03:28.502Z","avatar_url":"https://github.com/giovcandido.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swarming - PSO and ParallelPSO Python3 library\n\n[![PyPI][pypi-badge]][pypi-link]\n[![PyPI - Downloads][install-badge]][install-link]\n[![PyPI - Status][status-badge]][status-link]\n[![PyPI - License][license-badge]][license-link]\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/giovcandido/swarming/blob/master/demo.gif?raw=true\" alt=\"Swarming in action\"\u003e\n\u003c/p\u003e\n\nOptimize as much as you want with this easy-to-use library.\n\n## Contents\n\n- [About](#about)\n- [Usage](#usage)\n    - [Constructors](#constructors)\n    - [Working](#working)\n    - [Illustration](#illustration)\n    - [Parser](#parser)\n    - [Output](#output)\n- [Examples](#examples)\n- [Installation](#installation)\n- [Acknowledgement](#acknowledgement)\n- [Contribute](#contribute)\n\n## About\n\nSwarming is a Python3 library that features both parallel and serial\nimplementation of the Particle Swarm Optimization (PSO) algorithm.\n\nIt's made with Python3 and tested on Linux.\n\n## Usage\n\nIn order to use Swarming for an optimization task, you need to choose\nbetween PSO and ParallelPSO. It's important to note that the further one\nworks better for long calculations.\n\n### Constructors\n\nAfter making your choice, you're ready to go. Both PSO and ParallelPSO\nconstructors take 5 arguments. The arguments are:\n\n- swarm_size - the number of particles in the swarm;\n- dimension - the number of function variables;\n- function - the function you wish to optimize;\n- lower_bounds - the lower bounds of the function variables;\n- upper_bounds - the upper bounds of the function variables.\n\n### Working\n\nBear in mind that for this library optimizing a function means finding a\npoint of minimum function value. In the PSO algorithm, the particles\nrepresent candidate solutions to the optimization problem.\n\nThe particles are randomly placed within the search space boundaries and move\nin the direction that is more convenient for a certain number of iterations. By\nthe end of the task, it's expected that the swarm gets to an optimum position.\n\nIt is essential to discuss the algorithm metric for measuring \"convenience\".\nThe algorithm not only keeps track of the position of the particles, but of\nthe best particle position and of the best position of the whole swarm.\n\nIn short, the particle position, its best position and the best swarm position\nare taken into consideration when calculating the \"direction\" a particular\nparticle should go to in the search space.\n\nThe best particle position and the best swarm position are both determined by\nthe function value in the particle position, that is the particle score. Since\nthe algorithm tries finding a minimum value, the lower the score, the better.\n\nHaving said all that, the function to be optimized must receive a single\nargument, that is a point or position in the space. Additionally, it needs\nto return one single value, that is the function value on the passed point.\n\n### Illustration\n\nBelow, we have a working example. In this example, we want to optimize a\npolynomial function. For this task, let's consider 20 particles moving in a\nrestricted search space, that is bounded by [-100, 100] and [100, 100], for\na total of 1000 iterations.\n\n```python\nfrom swarming.core.pso import PSO\n\ndef polynomial(x):\n    return x[0] ** 2 + ((x[1] ** 2) / 16 - 5) ** 2 + 2 * x[0] + 6\n\nswarm_size = 20\ndimension = 2\nlower_bounds = [-100, -100]\nupper_bounds = [100, 100]\n\npso = PSO(swarm_size, dimension, polynomial, lower_bounds, upper_bounds)\n\npso.optimize(iterations=1000)\n```\n\nNotice that optimizing a polynomial function doesn't require long computations,\nso we chose to use The PSO class instead of the ParallelPSO. But, in case you\nwant to test the above example with the ParallelPSO class, you just need to\nreplace the PSO with ParallelPSO in the code.\n\nMaking it easier for you, the example with ParallelPSO would be as follows:\n\n```python\nfrom swarming.core.pso import ParallelPSO\n\ndef polynomial(x):\n    return x[0] ** 2 + ((x[1] ** 2) / 16 - 5) ** 2 + 2 * x[0] + 6\n\nswarm_size = 20\ndimension = 2\nlower_bounds = [-100, -100]\nupper_bounds = [100, 100]\n\npso = ParallelPSO(swarm_size, dimension, polynomial, lower_bounds, upper_bounds)\n\npso.optimize(iterations=1000)\n```\n\n### Parser\n\nIntending to facilitate the execution of a certain task, Swarming also provides\nan argument parser. The parser is supposed to help you experiment with the same\nfunction to be optimized. You can quickly try different settings.\n\nThe parser has four predefined arguments:\n- (P) if it should run in parallel;\n- (S) the number particles in the swarm;\n- (I) the number of iterations in the task;\n- (E) the number of executions of the task.\n\nUsing the parser, you could execute a certain task by running:\n```bash\npython3 example.py --parallel --swarm-size S --iterations I --executions E\n```\n\nYou can also run:\n```bash\npython3 example.py -p -s S -i I -e E\n```\n\nNote that you should __replace__ example.py with the desired script and the\nuppercase letters with the values you wish.\n\nMoreover, it's also important to note that 'parallel' and 'executions' are\noptional arguments. If you don't include them when executing a script, the\ndefault values are considered. For parallel, the default is 'False', which\nmeans no parallel execution. As for executions, the default is one execution.\n\nIf you are wondering how an optimization script would be with the parser,\nhere goes an example for you:\n\n```python\nfrom swarming.utils.argument_parser import parse_arguments\n\nfrom swarming.core.pso import PSO, ParallelPSO\n\ndef polynomial(x):\n    return x[0] ** 2 + ((x[1] ** 2) / 16 - 5) ** 2 + 2 * x[0] + 6\n\nargs = parse_arguments()\n\nparallel = args.parallel\nswarm_size = args.swarm_size\niterations = args.iterations\nexecutions = args.executions\n\ndimension = 2\nlower_bounds = [-100, -100]\nupper_bounds = [100, 100]\n\nif not parallel:\n    PSOClass = PSO\nelse:\n    PSOClass = ParallelPSO\n\npso = PSOClass(swarm_size, dimension, polynomial, lower_bounds, upper_bounds)\n\npso.optimize(iterations=iterations, executions=executions)\n```\n\n### Output\n\nEvery execution generates one unique __.log__ file that describes step-by-step what happens in the optimization task.\n\nAdditionally, one unique __.npy__ is also saved. This file contains the best task position, that is the solution to the optimization problem.\n\nIn order to load the solution, all you have to do is:\n```python3\nimport numpy as np\n\nsol = np.load('file.npy')\n```\n\n## Examples\n\nIn the examples directory, there are currently three scripts:\n- polynomial.py;\n- exponential.py;\n- neural_net.py.\n\nYou can pick any script to test. Moreover, you can change them as you want.\n\nIn order to test Swarming for the first time, keep the scripts unchanged\nand execute them.\n\nThe first two scripts don't not use the parser, while the latter does.\n\nSo, the first script can be executed as follows:\n```bash\npython3 polynomial.py\n```\n\nThe third script can be executed this way:\n```bash\npython3 neural_net.py --swarm-size 10 --iterations 100\n```\n\n## Installation\n\nThere are two ways you can install Swarming: you can install it from source or\nyou can get it using the pip3 command.\n\nIf you want to get it from source, download the latest release on GitHub or\nclone the repository. Then, extract the source code and run:\n\n```bash\npip3 install -e .\n```\n\nIf you want to install Swarming with pip, you just need to run:\n```bash\npip3 install swarming\n```\n\nYou can also run:\n```bash\nsudo pip3 install swarming\n```\n\n## Acknowledgement\n\nThe idea of Particle Swarm Optimization can be found in\n[Kennedy's paper](https://ieeexplore.ieee.org/document/488968).\n\nIt's worth mentioning that my colleague\n[gugarosa](https://github.com/gugarosa) made sure I was on the right path.\n\n## Contribute\n\nFeel free to reach out and contribute. We can add more features to Swarming.\n\nFurthermore, if you have any problem or suggestion, open an issue.\n\nIf you want to talk to us, send a message to giovcandido@outlook.com.\n\n[pypi-badge]: https://img.shields.io/pypi/v/swarming.svg\n[pypi-link]: https://pypi.org/project/swarming\n[install-badge]: https://img.shields.io/pypi/dm/swarming?label=pypi%20installs\n[install-link]: https://pypistats.org/packages/swarming\n[license-badge]: https://img.shields.io/pypi/l/swarming.svg\n[license-link]: https://pypi.python.org/pypi/swarming/\n[status-badge]: https://img.shields.io/pypi/status/swarming.svg\n[status-link]: https://pypi.python.org/pypi/swarming/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiovcandido%2Fswarming","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiovcandido%2Fswarming","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiovcandido%2Fswarming/lists"}