Chips-n-Salsa - A Java library of customizable, hybridizable, iterative, parallel, stochastic, and self-adaptive local search algorithms
Copyright (C) 2002-2022 Vincent A. Cicirello.
Website: https://chips-n-salsa.cicirello.org/
API documentation: https://chips-n-salsa.cicirello.org/api/
| Publications About the Library |  |
|---|---|
| Packages and Releases |   |
| Build Status |    |
| JaCoCo Test Coverage |   |
| Security |   |
| DOI |  |
| License |  |
If you use this library in your research, please cite the following paper:
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 .
Chips-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) library.
Chips-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.
Beginning with version 3.0.0, the library supports Java 11+. Our development process utilizes OpenJDK 11, and all jar files released to Maven Central, GitHub Packages, and GitHub Releases are built for a Java 11 target.
Chips-n-Salsa uses Semantic Versioning with version numbers of the form: MAJOR.MINOR.PATCH, where differences in MAJOR correspond to incompatible API changes, differences in MINOR correspond to introduction of backwards compatible new functionality, and PATCH corresponds to backwards compatible bug fixes.
The Chips-n-Salsa library is built using Maven. The root of the
repository contains a Maven pom.xml. To build the library,
execute mvn package at the root of the repository, which
will compile all classes, run all tests, run javadoc, and generate
jar files of the library, the sources, and the javadocs. In addition
to the jar of the library itself, this will also generate a
jar of the library that includes all dependencies. The file names
make this distinction explicit. All build outputs will then
be found in the directory target.
To include generation of a code coverage report during the build,
execute mvn package -Pcoverage at the root of the repository to
enable a Maven profile that executes JaCoCo during the test phase.
There are several example programs available in a separate repository: cicirello/chips-n-salsa-examples. The examples repository contains example usage of several of the classes of the library. Each of the examples contains detailed comments within the source code explaining the example. Running the examples without reading the source comments is not advised.
This library provides a Java module, org.cicirello.chips_n_salsa. If your Java 11+
project utilizes modules, then add the following to your module-info.java:
module your.module.name.here {
requires org.cicirello.chips_n_salsa;
}The org.cicirello.chips_n_salsa module, in turn, transitively requires
the org.cicirello.jpt module because the functionality for optimizing
permutational problems uses the Permutation class as both parameters and
return types of methods, so if you need the functionality of that dependency
in your application, the Chips-n-Salsa dependencies, including the module
requirements will handle this for you.
Add this to the dependencies section of your pom.xml, replacing the version number with the version that you want to use.
<dependency>
<groupId>org.cicirello</groupId>
<artifactId>chips-n-salsa</artifactId>
<version>3.0.0</version>
</dependency>If you'd prefer to import from GitHub Packages, rather than Maven Central, then: (1) add the dependency as indicated in previous section above, and (2) add the following to the repositories section of your pom.xml:
<repository>
<id>github</id>
<name>GitHub cicirello Apache Maven Packages</name>
<url>https://maven.pkg.github.com/cicirello/Chips-n-Salsa</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>If you don't use a dependency manager that supports importing from Maven Central, or if you simply prefer to download manually, prebuilt jars are also attached to each GitHub Release.
In addition to the regular jar of the library, we also regularly publish
a jar-with-dependencies. The jar-with-dependencies is built for a Java 11 target,
but does not contain any module declarations (unlike the regular jar file). Therefore, the
jar-with-dependencies should only be used on the classpath.
The Chips-n-Salsa library is licensed under the GNU General Public License 3.0.
If you would like to contribute to Chips-n-Salsa in any way, such as reporting bugs, suggesting new functionality, or code contributions such as bug fixes or implementations of new functionality, then start by reading the contribution guidelines. This project has adopted the Contributor Covenant Code of Conduct.