SUNNY-CP: a Parallel CP Portfolio Solver
sunny-cp  is a parallel parallel portfolio solver that allows to solve a Constraint (Satisfaction/Optimization) Problem defined in the MiniZinc language. It essentially implements the SUNNY algorithm described in  and extends its sequential version  that attended the MiniZinc Challenge 2014 . sunny-cp is built on top of state-of-the-art constraint solvers, including: Choco, Chuffed, CPX, G12/LazyFD, G12/FD, G12/Gurobi, G12/MIP, Gecode, HaifaCSP, JaCoP, iZplus, MinisatID, Mistral, Opturion, OR-Tools, Picat. These solvers are not included by default in sunny-cp, except for those already included in the MiniZinc bundle (i.e., Chuffed, G12/FD, G12/LazyFD, G12/MIP, and Gecode). However, sunny-cp provides utilities for adding new solvers to the portfolio and for customizing their settings. Moreover, sunny-cp enables to use more solvers via Docker (see below).
In a nutshell, sunny-cp relies on two sequential steps:
PRE-SOLVING: consists in the parallel execution of a (maybe empty) static schedule and the neighborhood computation of underlying k-NN algorithm;
SOLVING: consists in the parallel and cooperative execution of a number of the predicted solvers, selected by means of SUNNY algorithm.
sunny-cp won the gold medal in the open track of MiniZinc Challenges 2015, 2016, and 2017 .
Contents of this git repository
- bin contains the executables of sunny-cp
- kb contains the utilities for the knowledge base of sunny-cp
- src contains the sources of sunny-cp
- solvers contains the utilities for the constituent solvers of sunny-cp
- test contains some MiniZinc examples for testing sunny-cp
- tmp is aimed at containing the temporary files produced by sunny-cp
- docker contains the dockerfile used to generate the image in the dockerhub
Installation & Usage by HTTP POST requests
To install sunny-cp it is possible to use Docker available for the majority of the operating systems. It can then be used by simply sending a post request to the server deployed by using docker (for a local installation of sunny-cp please see the Manual Installation section below).
The Docker image is availabe in Docker Hub. To install it please run the following commands.
sudo docker pull jacopomauro/sunny-cp sudo docker run -d -p <PORT>:9001 --name sunny_cp_container jacopomauro/sunny-cp
<PORT> is the port used to use the functionalities of the service.
<MZN> is the path of the mzn file to solve,
to run the solver on it is possible to invoke it by a multipart post request as follows.
curl -F "mzn=@<MZN>" http://localhost:<PORT>/process
This will run sunny-cp with the default parameters on the minizinc instance.
<DZN> file is also needed, sunny-cp can be invoked as follows.
curl -F "mzn=@<MZN>" -F "dzn=@<DZN>" http://localhost:<PORT>/process
sunny-cp options can be passed by adding the string "option=value" as additional part of the request.
For instance to solve the
<MZN> using only the gecode solver (option
the post request to perform is the following one.
curl -F "-P=gecode" -F "mzn=@<MZN>" http://localhost:<PORT>/process
To see the options supported by sunny-cp please run the following command.
curl -F "--help=" http://localhost:<PORT>/process
To select sunny-cp flags (like
--help above) it is possible to add the string
"flag=". For example, the option
--mzn is set with -F "--mzn=".
Note that the post requests will return the output generate by sunny-cp at the end of its execution. In case partial solutions are need, it is possible to interact with sunny-cp from command line as specified in the remaining part of the section.
To understand what are the solvers installed you can use the following get request.
It is also possible to get the feature vector of an instance by using the following post request.
curl -F "mzn=@<MZN>" -F "dzn=@<DZN>" http://localhost:<PORT>/get_features
To clean up please lunch the following commands:
sudo docker stop sunny_cp_container sudo docker rm sunny_cp_container sudo docker rmi jacopomauro/sunny-cp
Interacting with SUNNY-CP from command line
To interact with SUNNY-CP, it is possible to run the docker container getting a direct access to the bash. This can be done by running the following command.
sudo docker run --entrypoint="/bin/bash" -i --rm -t jacopomauro/sunny-cp
This will give access to the bash and SUNNY-CP can be invoked by running the
sunny-cp command like a manual installation.
To move the mzn and dzn files within the container
scp command can be used or, alternatively, it is possible also to
start the container with some shared volume (see
for more information.)
sunny-cp is tested on 64-bit machines running Ubuntu 12.04, and not yet fully portable on other platforms. If you want to avoid the virtualization via Docker, you can manually install sunny-cp on Linux operating systems. Some of the main requirements for its installation are:
- Python (version >= 2)
- MiniZinc (version >= 2.7.1)
- mzn2feat (version >= 1.2.1)
- psutil (version >= 2)
- click (version >= 6)
To manually install sunny-cp, simply run the
install.sh script in the main
This is a minimal installation script that checks the prerequisites, compiles all the python sources of sunny-cp and builds the portfolio of sunny-cp (e.g., it creates file SUNNY_HOME/src/pfolio_solvers.py).
If the installation is successful, you will see the following message:
--- Everything went well! To complete sunny-cp installation you just have to add/modify the environment variables SUNNY_HOME and PATH: 1. SUNNY_HOME must point to: "$PWD"/sunny-cp 2. PATH must be extended to include: "$PWD"/bin
It is important to set such variables in order to use sunny-cp. Once the variables are set, check the installation by typing the command:
for printing the help page.
Note that installing SUNNY-CP is recommended only for expert linux users. More detail information of the commands and the additional requirents to install SUNNY-CP and its solvers can be found in the Dockerfile in the docker folder.
By default, sunny-cp uses the solvers contained in the MiniZinc bundle, that is:
It is however possible to use, via Docker, the following solvers:
- OR-Tools (version v6.4.4495)
- Choco (version 4.0.4)
- Picat CP (version 2.3)
- Picat SAT (version 2.3)
- JaCoP (version 4.4)
- MinisatID (version 3.11.0)
Once a solver is installed on your machine, it is easy to add it to the portfolio and to customize its settings. For more details, see the README file in the SUNNY_HOME/solvers folder and the sunny-cp usage.
Note that sunny-cp does not guarantee that its constituent solvers are bug free.
However, the user can check the soundness of a solution with the command line
In particular we recommend the usage of this option for haifacsp and minisatid
which installed version are bugged.
During the presolving phase (in parallel with the static schedule execution) sunny-cp extracts a feature vector of the problem in order to compute the solvers schedule possibly run in the solving phase. By default, the feature vector is extracted by mzn2feat tool available at https://github.com/CP-Unibo/mzn2feat.
When using docker this tool is already installed in the image. In case of local installation it needs otherwise to be installed manually following the instruction in the README file of mzn2feat.
Note that the user can define its own extractor by implementing a corresponding class in src/features.py
The SUNNY algorithm on which sunny-cp relies needs a knowledge base, that consists of a folder containing the information relevant for the schedule computation. For the time being the default knowlege base of SUNNY-CP is empty. However, the user has the possibility of defining its own knowledge bases.
The sunny-cp/kb/mznc1215 folder contains a knowledge base consisting of 76 CSP instances and 318 COP instances coming from the MiniZinc challenges 2012--2015. Moreover, the knowledge base mznc15 used in the MiniZinc Challenges 2016--2017 is also available. For more details, see the README file in sunny-cp/kb folder.
Although a full support for automatic testing is not yet implemented, in the sunny-cp/test/examples folder there is a number of simple MiniZinc models. The user can test all the models by running the following command:
The run_examples script also produces output.log and errors.log files in the test/examples folder, where the standard output/error of the tested models are respectively redirected.
Previous versions of SUNNY-CP supported solvers that are currently not included in the docker image due to compilation problems or the fact that are not publicly available/free. The old solvers that are not provided with the current default configuration are:
- Mistral (version does not compile)
- G12/Gurobi (not free)
- iZplus (not publicly available)
- Opturion (not free)
We invite the developers interested in adding their solver to the default image of sunny-cp to contact us.
sunny-cp is developed by Roberto Amadini (University of Melbourne) and Jacopo Mauro (University of Oslo). For any question or information, please contact us:
- roberto.amadini at unimelb.edu.au
- mauro.jacopo at gmail.com
We would like to thank the staff of the former Optimization Research Group of NICTA (National ICT of Australia) for granting us the computational resources needed for building and testing sunny-cp. We also thank all the developers of the constituent solvers without which sunny-cp scould not exists.
 R. Amadini, M. Gabbrielli, and J. Mauro. SUNNY: a Lazy Portfolio Approach for Constraint Solving 2013. In ICLP, 2014.
 R. Amadini, M. Gabbrielli, and J. Mauro. Portfolio Approaches for Constraint Optimization Problems. In LION, 2014.
 R. Amadini, and P.J. Stuckey. Sequential Time Splitting and Bounds Communication for a Portfolio of Optimization Solvers. In CP, 2014.
 R. Amadini, M. Gabbrielli, and J. Mauro. SUNNY-CP: a Sequential CP Portfolio Solver. In SAC, 2015.
 R. Amadini, M. Gabbrielli, and J. Mauro. A Multicore Tool for Constraint Solving. In IJCAI, 2015.
 MiniZinc Challenge webpage. http://www.minizinc.org/challenge.html