{"id":15765416,"url":"https://github.com/cicirello/chips-n-salsa-examples","last_synced_at":"2025-04-21T03:32:32.748Z","repository":{"id":37974880,"uuid":"304046570","full_name":"cicirello/chips-n-salsa-examples","owner":"cicirello","description":"Example programs for usage of the Chips-n-Salsa library","archived":false,"fork":false,"pushed_at":"2024-10-03T23:58:36.000Z","size":337,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-05T12:41:43.057Z","etag":null,"topics":["combinatorial-optimization","evolutionary-algorithms","genetic-algorithms","hill-climbing","metaheuristics","simulated-annealing","stochastic-sampling"],"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":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-14T14:48:44.000Z","updated_at":"2024-10-03T23:58:33.000Z","dependencies_parsed_at":"2023-12-25T20:32:38.454Z","dependency_job_id":"a28dc522-ab05-476c-bec3-972b7b7e3281","html_url":"https://github.com/cicirello/chips-n-salsa-examples","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fchips-n-salsa-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fchips-n-salsa-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fchips-n-salsa-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fchips-n-salsa-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cicirello","download_url":"https://codeload.github.com/cicirello/chips-n-salsa-examples/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249991166,"owners_count":21357214,"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":["combinatorial-optimization","evolutionary-algorithms","genetic-algorithms","hill-climbing","metaheuristics","simulated-annealing","stochastic-sampling"],"created_at":"2024-10-04T12:41:39.627Z","updated_at":"2025-04-21T03:32:32.482Z","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":"# Example Programs for Usage of the Chips-n-Salsa Library\n\nCopyright (C) 2020-2023 Vincent A. Cicirello. https://www.cicirello.org/\n\n| __Packages and Releases__ | [![Maven Central](https://img.shields.io/maven-central/v/org.cicirello/chips-n-salsa-examples.svg?label=Maven%20Central\u0026logo=apachemaven)](https://central.sonatype.com/artifact/org.cicirello/chips-n-salsa-examples/) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/cicirello/chips-n-salsa-examples?logo=GitHub)](https://github.com/cicirello/chips-n-salsa-examples/releases) |\n| :--- | :--- |\n| __Build Status__ | [![build](https://github.com/cicirello/chips-n-salsa-examples/workflows/build/badge.svg)](https://github.com/cicirello/chips-n-salsa-examples/actions/workflows/build.yml) [![CodeQL](https://github.com/cicirello/chips-n-salsa-examples/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/cicirello/chips-n-salsa-examples/actions/workflows/codeql-analysis.yml) |\n| __Security__ | [![Snyk security score](https://snyk-widget.herokuapp.com/badge/mvn/org.cicirello/chips-n-salsa-examples/badge.svg)](https://snyk.io/vuln/maven%3Aorg.cicirello%3Achips-n-salsa-examples) [![Snyk Known Vulnerabilities](https://snyk.io/test/github/cicirello/chips-n-salsa-examples/badge.svg)](https://snyk.io/test/github/cicirello/chips-n-salsa-examples) |\n| __Other Information__ | [![GitHub](https://img.shields.io/github/license/cicirello/chips-n-salsa-examples)](https://github.com/cicirello/chips-n-salsa-examples/blob/main/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\nThis repository contains several example programs of the usage of the [Chips-n-Salsa](https://chips-n-salsa.cicirello.org) \nlibrary. Chips-n-Salsa is a Java library of customizable, hybridizable, iterative, parallel, stochastic, and self-adaptive \nlocal search algorithms. [Chips-n-Salsa's source code](https://github.com/cicirello/Chips-n-Salsa) is maintained on GitHub,\nand the prebuilt jars of the library can be imported from [Maven Central](https://central.sonatype.com/artifact/org.cicirello/chips-n-salsa/) \nusing maven or other build tools. The purpose of this repository is to demonstrate usage of the major functionality of the\nChips-n-Salsa library.\n\n## The Example Programs\n\nThe source for several example programs is contained in this repository.\nRead the comments in the source code of the example programs \nfor a description of what they demonstrate, etc. Running the \nexamples without reading the source code, and comments, \nis not advised, since the output of the example programs \nrequires the context of the code samples to be meaningful.\n\n__Basic Examples__: The following \nexamples are of basic usage using simulated annealing or genetic algorithms to optimize\nfunctions over different structure types: bit vectors, integer vectors,\npermutations, and a real-value function optimization example, the root finding \nexample:\n* org.cicirello.examples.chipsnsalsa.BitVectorExample\n* org.cicirello.examples.chipsnsalsa.GeneticAlgorithmExamples\n* org.cicirello.examples.chipsnsalsa.IntegerVectorExample\n* org.cicirello.examples.chipsnsalsa.RootFindingExample\n* org.cicirello.examples.chipsnsalsa.PermutationExample\n\n__Configuring the Random Number Generator__: If you either need to specify a particular\npseudorabdom number generator (PRNG) to be used by the library, or if you want to seed its \ndefault PRNG in order to exactly repeat a run of your program, or if you want to do both,\nthen you can use the `Configurator` class. Here are examples of using the `Configurator` class.\n* org.cicirello.examples.chipsnsalsa.ConfigureRandomness\n\n__Parallel Examples__: The next couple examples are of parallel search:\n* org.cicirello.examples.chipsnsalsa.ParallelPermutationExample\n* org.cicirello.examples.chipsnsalsa.TimedParallelExample\n\n__Custom Problem Examples__: The following examples demonstrate defining a custom optimization\nproblem (whereas the above examples mostly use benchmark problems\nincluded in the library):\n* org.cicirello.examples.chipsnsalsa.CustomProblemExample\n* org.cicirello.examples.chipsnsalsa.CustomIntegerCostProblemExample\n\n__Hybrid Search Examples__: The following examples show how multiple search algorithms can be\nintegrated (e.g., combining hill climbing with simulated annealing):\n* org.cicirello.examples.chipsnsalsa.PostHillclimbExample\n* org.cicirello.examples.chipsnsalsa.PreHillclimbExample\n\n__Industrial Scheduling Problem Examples__: The following examples use scheduling \nproblems, and are also a bit more complex than some of the other example programs.\n* org.cicirello.examples.chipsnsalsa.SchedulingExample\n* org.cicirello.examples.chipsnsalsa.SchedulingWithVBSS\n\n\n## Versioning Scheme\n\nThe version numbers for the example programs mirror the versions of\nChips-n-Salsa. The version may or may not be incremented upon every new release\nof the Chips-n-Salsa library. The version number of the examples corresponds\nto the version of the Chips-n-Salsa library used in that release.\nThe examples should run against newer versions of the Chips-n-Salsa library\nprovided the MAJOR portion of the version number is the same.  \n\nThe Chips-n-Salsa library 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## Prebuilt Jars of the Examples\n\nSince the purpose of the example programs is to demonstrate usage of the\nChips-n-Salsa library, you will most likely want to build the examples\ndirectly from the source (see the sections that follow).  However, we\nalso provide jars of the compiled examples, as well as of the source and javadocs, \nin a variety of ways:\n* [GitHub releases](https://github.com/cicirello/chips-n-salsa-examples/releases)\n* [Maven Central](https://central.sonatype.com/artifact/org.cicirello/chips-n-salsa-examples/)\n* [GitHub Packages](https://github.com/cicirello?tab=packages\u0026repo_name=chips-n-salsa-examples)\n\nIf you use the example programs in precompiled form, you will also need\na compatible version of the Chips-n-Salsa library, and its dependencies. If you\nbuild the examples from the source, the build process will take care of downloading these\nfor you. But if you choose to use the prebuilt jars, you can find the jars\nof the [Chips-n-Salsa library](https://github.com/cicirello/Chips-n-Salsa) \nlikewise in Maven Central, GitHub Releases, and GitHub Packages.  In particular,\nyou will find a jarred version of Chips-n-Salsa that includes all of its dependencies.\n\n## Requirements to Build and Run the Example Programs from the Source\n\nTo build and run the examples on your own machine, you will need the following:\n* __JDK 17__: Beginning with Chips-n-Salsa, v5.0.0, the minimum supported version of Java is\n  Java 17, so you will need Java 17+ for the example programs. \n* __Apache Maven__: In the root of the repository, there is a pom.xml for building the example programs. Using this pom.xml, Maven will take care of downloading the most recent version of the [Chips-n-Salsa](https://chips-n-salsa.cicirello.org/) library for which the examples have been tested, as well as Chips-n-Salsa's dependencies. The examples should also work with more recent versions of the library.\n* __Make__ (optional): The repository also contains a Makefile to simplify running the build, and running the example programs. If you are familiar with using the Maven build tool, then you can just run these directly, although the Makefile may be useful to see the specific commands needed, such as the main classes to execute for the example programs.\n\n## Building the Example Programs with Maven\n\nThe source code of the example programs are\nin the [src/main/java](src/main/java) directory.  You can build the example \nprograms in one of the following ways:\n* Execute `mvn package` at the root of the repository (`mvn compile` should also be sufficient, but only generates `class` files, while `mvn package` generates `jar` files as well as the javadocs).\n* Execute `make` or `make build` at the root of the repository (which simply executes a `mvn package`). \n\nThis build process follows the usual Maven directory structure, so \nthe `.class` files, `.jar` files, etc will be found in a `target` \ndirectory that is created by the build process.\n\nTo run various static analysis tools (e.g., SpotBugs, FindSecBugs, refactor-first, \netc) during the build, run: `mvn clean package -Panalysis`.\n\n## Running the Example Programs with Maven\n\nOnce you have successfully executed the build above, you can run the \nexamples by executing `make examples` at the root of the \nrepository. This will run each of the example programs in sequence.\nBe aware that the examples are intended to illustrate how to use\nthe Chips-n-Salsa library, so will be most meaningful if you read the\nsource code, which includes comments explaining what they are doing.\n\nIf you would rather run them one at a time, see the `examples` target\nin the `Makefile` for the main classes to execute.\n\n## License\n\nThe example programs in this repository are licensed under \nthe [GNU General Public License 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Fchips-n-salsa-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcicirello%2Fchips-n-salsa-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Fchips-n-salsa-examples/lists"}