Preliminaries

About Choco Solver

Choco is a Free and Open-Source Software dedicated to Constraint Programming. It is written in Java, under BSD license. It aims at describing real combinatorial problems in the form of Constraint Satisfaction Problems and solving them with Constraint Programming techniques. Choco is used for:

  • teaching : easy to use
  • research : easy to extend
  • real-life applications : easy to integrate

Choco is among the fastest CP solvers on the market. In 2013 and 2014, Choco has been awarded two silver medals and three bronze medals at the MiniZinc challenge that is the world-wide competition of constraint-programming solvers. In addition to these performance results, Choco benefits from academic contributors, who provide support and long term improvements, and the consulting company COSLING, which provides services ranging from training to the development and the integration of CP models into larger applications.

Choco official website is: http://www.choco-solver.org

Technical overview

Choco Solver 4 is a Java 8 library including:

  • various type of variables (integer, boolean, set and real),
  • many constraints (alldifferent, count, nvalues, etc.),
  • a configurable search (custom search, activity-based search, large neighborhood search, etc.),
  • conflict explanations (conflict-based back jumping, dynamic backtracking, path repair, etc.).

It also includes facilities to interact with the search process, factories to help modeling, many samples, an interface to Ibex, etc. Choco Solver has also many extensions, including a FlatZinc parser to solve minizinc instances and a graph module to better solve graph problems such as the TSP. An overview of the features of Choco 4 may also be found in the presentation made in the “CP Solvers: Modeling, Applications, Integration, and Standardization” workshop of CP2013. The source code of choco-solver-4 is hosted on GitHub.

History

The first version of Choco dates from the early 2000s. A few years later, Choco 2 has encountered a great success in both the academic and the industrial world. For maintenance issue, Choco has been completely rewritten in 2011, leading to Choco 3. The first beta version of Choco 3 has been released in 2012 and it has shown significant performance improvement. Choco 4 comes with a simpler modeling API. The latest version is Choco 4.0.5.

Main contributors

Core developers Charles Prud’homme and Jean-Guillaume Fages
   
Main contributors Xavier Lorca, Narendra Jussien, Fabien Hermenier, Jimmy Liang.
   
Previous versions contributors François Laburthe, Hadrien Cambazard, Guillaume Rochart, Arnaud Malapert, Sophie Demassey, Nicolas Beldiceanu, Julien Menana, Guillaume Richaud, Thierry Petit, Julien Vion, Stéphane Zampelli.

If you want to contribute, let us know.

Choco is developed with Intellij IDEA and JProfiler, that are kindly provided for free.

How to get Support ?

The company COSLING can provide you with professional support and specific software development related to Choco Solver. Feel free to contact them at contact@cosling.com to discuss your upcoming projects.

A forum is also available on the website of Choco. It is dedicated to technical questions about the Choco solver and basic modeling helps. If you encounter any bug or would like some features to be added, please feel free to open a discussion on the forum.

How to cite Choco ?

A reference to this manual, or more generally to Choco 4, is made like this:

@manual{chocoSolver,
  author        = {Charles Prud'homme and Jean-Guillaume Fages and Xavier Lorca},
  title         = {Choco Solver Documentation},
  year          = {2016},
  organization  = {TASC, INRIA Rennes, LINA CNRS UMR 6241, COSLING S.A.S.},
  timestamp     = {Tue, 9 Feb 2016},
  url           = {http://www.choco-solver.org },
}

Using Choco Solver

Structure of the main package

You can download Choco Solver on the website of Choco Solver. You will get a zip file which contains the following files:

choco-solver-4.0.5-with-dependencies.jar
A ready-to-use jar file including dependencies; it provides tools to declare a Model, the variables, the constraints, the search strategies, etc. In a few words, it enables modeling and solving CP problems.
choco-solver-4.0.5.jar
A jar file excluding all dependencies and configuration file; Enable using choco-solver as a dependency of an application. Otherwise, it provides the same code as the jar with dependencies.
choco-solver-4.0.5-sources.jar
The source of the core library, to be loaded in your favourite IDE to benefit from the javadoc while coding.
choco-samples-4.0.5-sources.jar
The source of the artifact choco-samples made of problems modeled with Choco. It is a good start point to see what it is possible to do with Choco.
apidocs-4.0.5.zip
Javadoc of Choco-4.0.5
logback.xml
The logback configuration file; may be needed when choco-solver is used as a library.

Please, refer to README.md for more details.

Adding Choco Solver to your project

Directly

Simply add choco-solver-4.0.5-with-dependencies.jar to the classpath of your project (in a terminal or in your favorite IDE).

With Maven

Choco Solver is available on the Maven Central Repository. To declare Choco as a dependency of your project, simply update the pom.xml of your project by adding the following instruction:

<dependency>
 <groupId>org.choco-solver</groupId>
 <artifactId>choco-solver</artifactId>
 <version>X.Y.Z</version>
</dependency>

where X.Y.Z is replaced by 4.0.5. Note that the artifact does not include any dependencies or logback.xml. Please, refer to README.md for the list of required dependencies.

With SBT

To declare Choco as a dependency of your project, simply update the build.sbt of your project by adding the following instruction:

libraryDependencies ++= Seq(
  "org.choco-solver" % "choco-solver" % "X.Y.Z",
)

where X.Y.Z is replaced by 4.0.5.

Compiling sources

As a Maven-based project, Choco Solver can be installed in a few instructions. Once you have downloaded the source (from the zip file or GitHub, simply run the following command:

mvn clean install -DskipTests

This instruction downloads the dependencies required for Choco Solver (such as the trove4j and logback) then compiles the sources. The instruction -DskipTests avoids running the tests after compilation (and saves you a couple of hours). Regression tests are run on a private continuous integration server.

Maven provides commands to generate files needed for an IDE project setup. For example, to create the project files for your favorite IDE:

IntelliJ Idea
mvn idea:idea
Eclipse
mvn eclipse:configure-workspace eclipse:eclipse

Example

Simple example showing how to use Choco Solver

import org.chocosolver.solver.Model;
import org.chocosolver.solver.variables.IntVar;

/**
 * Trivial example showing how to use Choco Solver
 * to solve the equation system
 * x + y < 5
 * x * y = 4
 * with x in [0,5] and y in {2, 3, 8}
 *
 * @author Charles Prud'homme, Jean-Guillaume Fages
 * @since 9/02/2016
 */
public class Overview {

    public static void main(String[] args) {
        // 1. Create a Model
        Model model = new Model("my first problem");
        // 2. Create variables
        IntVar x = model.intVar("X", 0, 5);                 // x in [0,5]
        IntVar y = model.intVar("Y", new int[]{2, 3, 8});   // y in {2, 3, 8}
        // 3. Post constraints
        model.arithm(x, "+", y, "<", 5).post(); // x + y < 5
        model.times(x,y,4).post();              // x * y = 4
        // 4. Solve the problem
        model.getSolver().solve();
        // 5. Print the solution
        System.out.println(x); // Prints X = 2
        System.out.println(y); // Prints Y = 2
    }
}

Change history

Changes to the library are logged into the CHANGES.md file.