{"id":15645352,"url":"https://github.com/cicirello/chips-n-salsa","last_synced_at":"2025-04-05T18:06:36.004Z","repository":{"id":38268826,"uuid":"273074441","full_name":"cicirello/Chips-n-Salsa","owner":"cicirello","description":"A Java library of Customizable, Hybridizable, Iterative, Parallel, Stochastic, and Self-Adaptive Local Search Algorithms","archived":false,"fork":false,"pushed_at":"2025-03-17T19:55:58.000Z","size":17015,"stargazers_count":64,"open_issues_count":0,"forks_count":40,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T17:08:28.310Z","etag":null,"topics":["adaptive","discrete-optimization","evolutionary-computation","genetic-algorithm","hbss","hill-climbing","java","local-search","metaheuristics","multithreading","mutation","optimization","parallel-computing","permutations","randomized-heuristics","scheduling","search-algorithm","simulated-annealing","stochastic-sampling","vbss"],"latest_commit_sha":null,"homepage":"https://chips-n-salsa.cicirello.org/","language":"Java","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/cicirello.png","metadata":{"funding":{"github":"cicirello","patreon":null,"open_collective":null,"ko_fi":"cicirello","tidelift":null,"community_bridge":null,"liberapay":"cicirello","issuehunt":null,"otechie":null,"custom":null},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-17T20:43:20.000Z","updated_at":"2025-03-21T05:04:37.000Z","dependencies_parsed_at":"2023-11-20T22:24:18.521Z","dependency_job_id":"55eb3a20-35bd-4017-b5eb-31e8389a49dd","html_url":"https://github.com/cicirello/Chips-n-Salsa","commit_stats":{"total_commits":1940,"total_committers":4,"mean_commits":485.0,"dds":"0.10876288659793809","last_synced_commit":"b88fdac49cfefe9dc46e70a93273e27332641ee0"},"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2FChips-n-Salsa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2FChips-n-Salsa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2FChips-n-Salsa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2FChips-n-Salsa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cicirello","download_url":"https://codeload.github.com/cicirello/Chips-n-Salsa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378141,"owners_count":20929296,"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":["adaptive","discrete-optimization","evolutionary-computation","genetic-algorithm","hbss","hill-climbing","java","local-search","metaheuristics","multithreading","mutation","optimization","parallel-computing","permutations","randomized-heuristics","scheduling","search-algorithm","simulated-annealing","stochastic-sampling","vbss"],"created_at":"2024-10-03T12:06:44.704Z","updated_at":"2025-04-05T18:06:35.977Z","avatar_url":"https://github.com/cicirello.png","language":"Java","funding_links":["https://github.com/sponsors/cicirello","https://ko-fi.com/cicirello","https://liberapay.com/cicirello"],"categories":[],"sub_categories":[],"readme":"[![Chips-n-Salsa - A Java library of customizable, hybridizable, iterative, parallel, stochastic, and self-adaptive local search algorithms](https://chips-n-salsa.cicirello.org/images/chips-n-salsa640.png)](#chips-n-salsa---a-java-library-of-customizable-hybridizable-iterative-parallel-stochastic-and-self-adaptive-local-search-algorithms)\n\n# Chips-n-Salsa [![Mentioned in Awesome Machine Learning](https://awesome.re/mentioned-badge.svg)](https://github.com/josephmisiti/awesome-machine-learning)\n\nCopyright (C) 2002-2024 [Vincent A. Cicirello](https://www.cicirello.org/).\n\nWebsite: https://chips-n-salsa.cicirello.org/\n\nAPI documentation: https://chips-n-salsa.cicirello.org/api/\n\n| __Publications About the Library__ | [![doi:10.21105/joss.02448](https://joss.theoj.org/papers/10.21105/joss.02448/status.svg)](https://doi.org/10.21105/joss.02448) [![doi:10.5220/0013040600003837](doi-evo.svg)](https://doi.org/10.5220/0013040600003837) |\n| :--- | :--- |\n| __Packages and Releases__ | [![Maven Central](https://img.shields.io/maven-central/v/org.cicirello/chips-n-salsa.svg?label=Maven%20Central\u0026logo=apachemaven)](https://central.sonatype.com/artifact/org.cicirello/chips-n-salsa/) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/cicirello/Chips-n-Salsa?logo=GitHub)](https://github.com/cicirello/Chips-n-Salsa/releases) |\n| __Build Status__ | [![build](https://github.com/cicirello/Chips-n-Salsa/workflows/build/badge.svg)](https://github.com/cicirello/Chips-n-Salsa/actions/workflows/build.yml) [![docs](https://github.com/cicirello/Chips-n-Salsa/workflows/docs/badge.svg)](https://chips-n-salsa.cicirello.org/api/) [![CodeQL](https://github.com/cicirello/Chips-n-Salsa/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/cicirello/Chips-n-Salsa/actions/workflows/codeql-analysis.yml) |\n| __JaCoCo Test Coverage__ | [![coverage](https://raw.githubusercontent.com/cicirello/Chips-n-Salsa/badges/jacoco.svg)](https://github.com/cicirello/Chips-n-Salsa/actions/workflows/build.yml) [![branches coverage](https://raw.githubusercontent.com/cicirello/Chips-n-Salsa/badges/branches.svg)](https://github.com/cicirello/Chips-n-Salsa/actions/workflows/build.yml) |\n| __Security__ | [![Snyk security score](https://snyk-widget.herokuapp.com/badge/mvn/org.cicirello/chips-n-salsa/badge.svg)](https://snyk.io/vuln/maven%3Aorg.cicirello%3Achips-n-salsa) [![Snyk Known Vulnerabilities](https://snyk.io/test/github/cicirello/Chips-n-Salsa/badge.svg)](https://snyk.io/test/github/cicirello/Chips-n-Salsa) |\n| __DOI__ | [![DOI](https://zenodo.org/badge/273074441.svg)](https://zenodo.org/badge/latestdoi/273074441) |\n| __Other Information__ | [![GitHub](https://img.shields.io/github/license/cicirello/Chips-n-Salsa)](https://github.com/cicirello/Chips-n-Salsa/blob/master/LICENSE) [![style](https://img.shields.io/badge/style-Google%20Java%20Style-informational)](https://google.github.io/styleguide/javaguide.html) |\n| __Support__ | [![GitHub Sponsors](https://img.shields.io/badge/sponsor-30363D?logo=GitHub-Sponsors\u0026logoColor=#EA4AAA)](https://github.com/sponsors/cicirello) [![Liberapay](https://img.shields.io/badge/Liberapay-F6C915?logo=liberapay\u0026logoColor=black)](https://liberapay.com/cicirello) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/cicirello) | \n\n## How to Cite\n\nIf you use this library in your research, please cite one or both of the following papers, whichever is relevant. Chips-n-Salsa was introduced in this first article:\n\n\u003e Cicirello, V. A., (2020). Chips-n-Salsa: A Java Library of Customizable, Hybridizable, Iterative, Parallel, Stochastic, and Self-Adaptive Local Search Algorithms. *Journal of Open Source Software*, 5(52), 2448, https://doi.org/10.21105/joss.02448\n\nThe following paper covers the evolutionary algorithms of Chips-n-Salsa:\n\n\u003e Cicirello, V.A. (2024). [Open Source Evolutionary Computation with Chips-n-Salsa](https://www.cicirello.org/publications/cicirello2024ecta-chips-n-salsa.pdf).  *Proceedings of the 16th International Joint Conference on Computational Intelligence (IJCCI 2024)*, pages 330-337, https://doi.org/10.5220/0013040600003837\n\n## Overview\n\nChips-n-Salsa is a Java library of customizable, hybridizable, iterative, parallel, stochastic, and self-adaptive local search algorithms. The library includes implementations of several stochastic local search algorithms, including simulated annealing, hill climbers, as well as constructive search algorithms such as stochastic sampling. Chips-n-Salsa now also includes genetic algorithms as well as evolutionary algorithms more generally. The library very extensively supports simulated annealing. It includes several classes for representing solutions to a variety of optimization problems. For example, the library includes a BitVector class that implements vectors of bits, as well as classes for representing solutions to problems where we are searching for an optimal vector of integers or reals. For each of the built-in representations, the library provides the most common mutation operators for generating random neighbors of candidate solutions, as well as common crossover operators for use with evolutionary algorithms. Additionally, the library provides extensive support for permutation optimization problems, including implementations of many different mutation operators for permutations, and utilizing the efficiently implemented Permutation class of the [JavaPermutationTools (JPT)](https://jpt.cicirello.org/) library.\n\nChips-n-Salsa is customizable, making extensive use of Java's generic types, enabling using the library to optimize other types of representations beyond what is provided in the library. It is hybridizable, providing support for integrating multiple forms of local search (e.g., using a hill climber on a solution generated by simulated annealing), creating hybrid mutation operators (e.g., local search using multiple mutation operators), as well as support for running more than one type of search for the same problem concurrently using multiple threads as a form of algorithm portfolio. Chips-n-Salsa is iterative, with support for multistart metaheuristics, including implementations of several restart schedules for varying the run lengths across the restarts. It also supports parallel execution of multiple instances of the same, or different, stochastic local search algorithms for an instance of a problem to accelerate the search process. The library supports self-adaptive search in a variety of ways, such as including implementations of adaptive annealing schedules for simulated annealing, such as the Modified Lam schedule, implementations of the simpler annealing schedules but which self-tune the initial temperature and other parameters, and restart schedules that adapt to run length.\n\n### Table of Contents\n\nThe rest of this README is organized as follows:\n* [Java Requirements](#java-requirements): Minimum supported Java version information\n* [Versioning Scheme](#versioning-scheme): Explanation of the library's version numbers\n* [Building the Library (with Maven)](#building-the-library-with-maven)\n* [Example Programs](#example-programs): Information on example library usage\n* [Java Modules](#java-modules): Information for those whose projects use Java modules\n* [Importing from Package Repositories](#importing-from-package-repositories)\n  * [Importing the Library from Maven Central](#importing-the-library-from-maven-central)\n  * [Importing the Library from GitHub Packages](#importing-the-library-from-gitHub-packages)\n* [Downloading Jar Files](#downloading-jar-files): Information on where you can download pre-compiled jars\n* [License](#license): Licensing information\n* [Contribute](#contribute): Information for those who wish to contribute\n\n## Java Requirements\n\nChips-n-Salsa currently supports Java 17+. Our development process utilizes OpenJDK 17, and\nall jar files released to Maven Central, GitHub Packages, and GitHub Releases are built for a Java 17 target.\nSee the following table for a mapping between library version and minimum supported Java version.\n\n| version | Java requirements |\n| --- | --- |\n| 5.w.x to 7.y.z | Java 17+ |\n| 3.w.x to 4.y.z | Java 11+ |\n| 1.w.x to 2.y.z | Java 8+ |\n\n## Versioning Scheme\n\nChips-n-Salsa uses [Semantic Versioning](https://semver.org/) with \nversion numbers of the form: MAJOR.MINOR.PATCH, where differences \nin MAJOR correspond to incompatible API changes, differences in MINOR \ncorrespond to introduction of backwards compatible new functionality, \nand PATCH corresponds to backwards compatible bug fixes.\n\n## Building the Library (with Maven)\n\nThe Chips-n-Salsa library is built using Maven. The root of the\nrepository contains a Maven `pom.xml`.  To build the library, \nexecute `mvn package` at the root of the repository, which\nwill compile all classes, run all tests, run javadoc, and generate \njar files of the library, the sources, and the javadocs.  In addition\nto the jar of the library itself, this will also generate a\njar of the library that includes all dependencies.  The file names\nmake this distinction explicit.  All build outputs will then\nbe found in the directory `target`.\n\nTo include generation of a code coverage report during the build,\nexecute `mvn package -Pcoverage` at the root of the repository to \nenable a Maven profile that executes JaCoCo during the test phase.\n\nTo run all static analysis tools (i.e., SpotBugs, Find Security Bugs, \nrefactor-first), execute `mvn package -Panalysis` to enable a Maven \nprofile that executes the various static analysis tools that we are \nusing. The SpotBugs html report will be found in the `target` directory, \nor you can use the SpotBugs GUI with: `mvn spotbugs:gui -Panalysis`. The \nrefactor-first report will be found in the `target/site` directory.\n\nTo run all of the above: `mvn package -P \"analysis,coverage\"`.\n\n## Example Programs\n\nThere are several example programs available in a separate repository:\n[cicirello/chips-n-salsa-examples](https://github.com/cicirello/chips-n-salsa-examples).\nThe examples repository contains example usage of several of the \nclasses of the library. Each of the examples contains detailed\ncomments within the source code explaining the example. Running the \nexamples without reading the source comments is not advised.   \n\n## Java Modules\n\nThis library provides a Java module, `org.cicirello.chips_n_salsa`. If your Java\nproject utilizes modules, then add the following to your `module-info.java`:\n\n```Java\nmodule your.module.name.here {\n\trequires org.cicirello.chips_n_salsa;\n}\n```\n\nThe `org.cicirello.chips_n_salsa` module, in turn, transitively requires\nthe `org.cicirello.jpt` module because the functionality for optimizing\npermutational problems uses the Permutation class as both parameters and\nreturn types of methods. \n\nIf you are directly utilizing the functionality of the dependencies, then \nyou may instead need some combination of the following:\n\n```Java\nmodule your.module.name.here {\n\trequires org.cicirello.chips_n_salsa;\n\trequires org.cicirello.jpt;\n\trequires org.cicirello.rho_mu;\n\trequires org.cicirello.core;\n}\n```\n\n## Importing from Package Repositories\n\nPrebuilt artifacts are regularly published to Maven Central and GitHub Packages. In \nmost cases, you'll want to use Maven Central. Releases are published to GitHub Packages \nmainly as a fall-back in the unlikely scenario that Maven Central is unavailable.\n\n### Importing the Library from Maven Central\n\nAdd this to the dependencies section of your pom.xml, replacing \nthe version number with the version that you want to use.\n\n```XML\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.cicirello\u003c/groupId\u003e\n  \u003cartifactId\u003echips-n-salsa\u003c/artifactId\u003e\n  \u003cversion\u003e7.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Importing the Library from GitHub Packages\n\nIf you'd prefer to import from GitHub Packages, rather than Maven Central, \nthen: (1) add the dependency as indicated in previous section above, and (2) add \nthe following to the repositories section of your pom.xml:\n\n```XML\n\u003crepository\u003e\n  \u003cid\u003egithub\u003c/id\u003e\n  \u003cname\u003eGitHub cicirello Apache Maven Packages\u003c/name\u003e\n  \u003curl\u003ehttps://maven.pkg.github.com/cicirello/Chips-n-Salsa\u003c/url\u003e\n\u003c/repository\u003e\n```\n\nNote that GitHub Packages requires authenticating to GitHub (even for public \nartifacts). Thus, it is likely less convenient than importing from Maven \nCentral. We mainly provide this option as a backup source of artifacts.\n\n## Downloading Jar Files\n\nIf you don't use a dependency manager that supports importing from Maven Central,\nor if you simply prefer to download manually, prebuilt jars are also attached to \neach [GitHub Release](https://github.com/cicirello/Chips-n-Salsa/releases). If you\nmanually download the library jar file, make sure that you also download the jars\nof the relevant versions of the dependencies. The easiest way to get this right is\nto use a dependency manager rather than manually downloading jars.\n\n## License\n\nThe Chips-n-Salsa library is licensed under the [GNU General Public License 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).\n\n## Contribute\n\nIf you would like to contribute to Chips-n-Salsa in any way, such \nas reporting bugs, suggesting new functionality, or code contributions \nsuch as bug fixes or implementations of new functionality, then start \nby reading \nthe [contribution guidelines](https://github.com/cicirello/.github/blob/main/CONTRIBUTING.md).\nThis project has adopted \nthe [Contributor Covenant Code of Conduct](https://github.com/cicirello/.github/blob/main/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Fchips-n-salsa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcicirello%2Fchips-n-salsa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Fchips-n-salsa/lists"}