{"id":20071304,"url":"https://github.com/cptanalatriste/isula","last_synced_at":"2025-05-05T19:34:02.687Z","repository":{"id":33864835,"uuid":"37572630","full_name":"cptanalatriste/isula","owner":"cptanalatriste","description":"A Java Framework for Ant Colony Optimization algorithms.","archived":false,"fork":false,"pushed_at":"2023-09-04T09:44:46.000Z","size":1231,"stargazers_count":38,"open_issues_count":5,"forks_count":18,"subscribers_count":7,"default_branch":"master","last_synced_at":"2023-10-20T19:02:49.027Z","etag":null,"topics":["ant-colony-optimization","java","optimization","travelling-salesman"],"latest_commit_sha":null,"homepage":"https://www.sciencedirect.com/science/article/pii/S2352711019300639","language":"HTML","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/cptanalatriste.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-06-17T04:32:31.000Z","updated_at":"2023-10-20T19:02:49.729Z","dependencies_parsed_at":"2023-01-15T03:02:36.195Z","dependency_job_id":"30b1236e-15bf-407d-9b17-cd7725046bf0","html_url":"https://github.com/cptanalatriste/isula","commit_stats":null,"previous_names":[],"tags_count":12,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cptanalatriste%2Fisula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cptanalatriste%2Fisula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cptanalatriste%2Fisula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cptanalatriste%2Fisula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cptanalatriste","download_url":"https://codeload.github.com/cptanalatriste/isula/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224464925,"owners_count":17315716,"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":["ant-colony-optimization","java","optimization","travelling-salesman"],"created_at":"2024-11-13T14:28:39.096Z","updated_at":"2024-11-13T14:28:40.051Z","avatar_url":"https://github.com/cptanalatriste.png","language":"HTML","funding_links":[],"categories":["人工智能"],"sub_categories":[],"readme":"# isula\n\n![example workflow](https://github.com/cptanalatriste/isula/actions/workflows/build.yml/badge.svg)\n[![packagecloud](https://img.shields.io/badge/java-packagecloud.io-844fec.svg)](https://packagecloud.io/cgavidia/isula)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=isula\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=isula)\n\n\u003cp style=\"text-align:center\"\u003e\n  \u003ca href=\"https://cptanalatriste.github.io/isula/\"\u003e\n    \u003cimg alt=\"Isula\" title=\"Isula\" src=\"img/Isulas_(8583611782).jpg\" width=\"672\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## About\n\nAnt Colony Optimisation (ACO) is an algorithmic framework for solving\ncombinatorial optimisation problems.\nAlgorithms in the framework imitate the foraging behaviour of ants.\nAnts in the wild traverse a terrain looking for food, while depositing\npheromones over the path they take.\nPheromone is a chemical substance attractive to ants.\nEfficient ants find shorter paths, making more trips from the food source to\nthe colony than fellow ants on longer routes.\nThis produces an accumulation of pheromone over short paths, getting the\nattention of the rest the colony.\nOver time, the whole colony converges towards the shortest path found.\n\nIn a similar fashion, artificial ants in ACO algorithms traverse the solution\nspace of an optimisation problem, depositing pheromone over the components\nof the solution they built.\nThe amount of pheromone is proportional to the quality of their\nsolution, so pheromone accumulates in the most valuable solution components.\nOver time, ants in the artificial colony converge to high-quality solutions\nfor a given optimisation problem.\nIsula allows an easy implementation of Ant-Colony Optimisation algorithms using the Java Programming Language.\nIt contains the common elements present in the meta-heuristic, to allow algorithm designers the reutilization of\nbehaviors.\nWith Isula, solving optimisation problems with Ant Colony can be done in few lines of code.\n\n## Usage\n\n### Setup\n\nThe code uploaded to this GitHub Repository corresponds to a Maven Java Project.\nAs such, it is strongly recommended that you have Maven installed before working with Isula.\n\nYou can use Isula as a dependency on your own Ant Colony Optimization project, by adding the following\nto your `pom.xml` file:\n\n```xml\n\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003eisula\u003c/id\u003e\n        \u003curl\u003ehttps://packagecloud.io/cgavidia/isula/maven2\n        \u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n\u003cdependencies\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eisula\u003c/groupId\u003e\n    \u003cartifactId\u003eisula\u003c/artifactId\u003e\n    \u003cversion\u003e2.1.6\u003c/version\u003e\n\u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n### Algorithm Configuration\n\nTo solve a problem with an Ant-Colony Optimization algorithm, you need a colony of agents (a.k.a. ants), a graph\nrepresenting the problem, and a pheromone data-structure to allow communication between these agents.\nIsula tries to emulate that pattern:\n\n```java\nTspProblemConfiguration configurationProvider=new TspProblemConfiguration(problemRepresentation);\n        AntColony\u003cInteger, TspEnvironment\u003e colony=getAntColony(configurationProvider);\n        TspEnvironment environment=new TspEnvironment(problemRepresentation);\n\n        AcoProblemSolver\u003cInteger, TspEnvironment\u003e solver=new AcoProblemSolver\u003c\u003e();\n        solver.initialize(environment,colony,configurationProvider);\n        solver.addDaemonActions(new StartPheromoneMatrix\u003cInteger, TspEnvironment\u003e(),\n        new PerformEvaporation\u003cInteger, TspEnvironment\u003e());\n\n        solver.addDaemonActions(getPheromoneUpdatePolicy());\n\n        solver.getAntColony().addAntPolicies(new RandomNodeSelection\u003cInteger, TspEnvironment\u003e());\n        solver.solveProblem();\n```\n\nThat's a snippet from [our Travelling Salesman Problem solution](https://github.com/cptanalatriste/aco-tsp).\nSome things to notice there:\n\n* Problem and algorithm configuration are provided by `ConfigurationProvider` instances.\n  Make your own with the values you need.\n* The class that does most of the job is `AcoProblemSolver`.\n  In this case, we're using the same one provided by the framework but you can extend it to suit your needs.\n* The `ProblemSolver` needs an `Environment` that manages the problem graph and the pheromone matrix.\n  You need to extend the `Environment` class provided by the framework to adjust it to your problem.\n* And we need an `AntColony`. The `AntColony` main responsibility is to create Ants, and make them built solutions\n  in iterations. The base `AntColony` class makes implementing this very easy.\n* The heart of the algorithm is the `Ant` class. You will need to define an `Ant` that suits your needs.\n* Isula supports daemon actions (global behaviors) and ant-level policies, such as the ones present in\n  multiple ACO Algorithms. You can add daemon actions to a solver via the `addDaemonActions` method and ant policies\n  to a colony via the `addAntPolicies` method.\n* Finally, you call the `solveProblem()` method and wait for the best solution to be obtained.\n\n### Isula Workflow\n\nHere is a sequence diagram of the `solveProblem()` method, for you to get an idea on how isula works:\n\n\n\u003cp style=\"text-align:center\"\u003e\n  \u003ca href=\"https://cptanalatriste.github.io/isula/\"\u003e\n    \u003cimg alt=\"Isula Workflow\" title=\"Isula Workflow\" src=\"img/ACO_metaheuristic.png\" width=\"1428\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nIsula will provide you the basic execution flow for an algorithm in the ACO metaheuristic. Usually, you\ncan rely on the implementations already available for `AcoProblemSolver` and `AntColony` but you are free to override\nand extend in case you need it. Take in mind that you will need to create your own `Ant` instance for\ncustom problems, however the base implementation already contains a lot of functionality available.\nIf you need some reference, please take a look to the projects on the \"Examples\" section.\n\nEvery ACO algorithm has a set of customized behaviours that are executed during the solution processes: this behaviours\ncan have global impact (`DaemonAction` instances, like pheromone update rules) or only affect an ant and its solution\n(like component selection rules: they are subclasses of `AntPolicy`). Isula already provides these behaviours for some\nrepresentative algorithms (take a look at the `isula.aco.algorithms` package) ,but you might need to define\nyour own policies or extend the ones already available.\n\n## Examples\n\nIf you are not familiar with the framework, a good place to start is the classic Travelling Salesman Problem:\n\n* [The Travelling Salesman Problem, using Ant System](https://github.com/cptanalatriste/aco-tsp).\n* [The Travelling Salesman Problem, using Ant Colony System](https://github.com/cptanalatriste/aco-acs-tsp).\n\nHere are some advanced examples of optimization problems solved with Isula-based algorithms:\n\n* [Flow-Shop Scheduling Problem, using Max-Min Ant System](https://github.com/cptanalatriste/aco-flowshop).\n* [Unicost Set Covering Problem, using a parallelization strategy](https://github.com/cptanalatriste/aco-set-covering)\n* [Binary Image Segmentation using Ant System](https://github.com/cptanalatriste/aco-image-thresholding).\n* [Image Clustering using Max-Min Ant System](https://github.com/cptanalatriste/aco-image-segmentation)\n\n## Resources\n\n* [The JavaDoc of every class on the framework](https://cptanalatriste.github.io/isula/apidocs/).\n* [Our paper in the SoftwareX journal](https://www.sciencedirect.com/science/article/pii/S2352711019300639), for an\n  in-depth discussion of the framework and its features.\n* [A video of our tutorial at GECCO 2022](https://www.youtube.com/watch?v=QLgHeVhYFS8), where we describe how\n  to use Isula to solve the Unicost Set Covering Problem.\n* [A Medium article](https://medium.com/@cgavidia/the-travelling-sales-ant-problem-6a4f5d046a2b), discussing\n  how to solve the Travelling Salesman Problem using brute-force and an Isula-based ACO algorithm.\n* [A CodeProject article](http://www.codeproject.com/Articles/1011148/A-Java-Primer-of-Ant-Colony-Algorithms),\n  where Ant Colony Optimization algorithms are discussed and Isula is used to implement them.\n\n## Support\n\nFeel free to contact me [via email](mailto:carlos.gavidia@pucp.edu.pe), or create a GitHub Issue here.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcptanalatriste%2Fisula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcptanalatriste%2Fisula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcptanalatriste%2Fisula/lists"}