!DOCTYPE html> clp2zinc Documentation

clp2zinc Documentation

Table Of Contents

Getting Started with clp2zinc

clp2zinc is a front-end to compile CLP specifications of search strategies into Zinc models. Zinc is a well-established language to describe CSP: MiniZinc should be installed to run the generated models. Moreover, dynamic search strategies (with indexicals) should be run with a patched solver.

clp2zinc command-line usage

clp2zinc is a command-line tool. The basic usage is clp2zinc file.plz, which compiles the ClpZinc model file.plz and generates the MiniZinc model file.mzn. clp2zinc recognizes a few options:

Several files can be compiled together: e.g. clp2zinc file1.plz file2.plz..., the result is identical as if the files were concatenated in a single file in the same order. If the output file name is not specified with the -o option, then the base name file1 is used, with the proper .mzn or .inc suffix.

Using the patched Choco solver

Either use our build: choco-3.1.1-clpzinc.jar, or recompile it yourself:

To solve a .mzn model:

Using the patched JaCoP solver

Either use our build: jacop-4.0.0-clpzinc.jar, or recompile it yourself:

To solve a .mzn model:

Using the patched Gecode solver

Recompile it yourself:

To solve a .mzn model:

Using the patched SICStus solver

Install it with the patch:

To solve a .mzn model:

Using the patched or-tools solver

Recompile it yourself:

To solve a .mzn model:

The ClpZinc Language

The Goal Item

ClpZinc extends the Zinc programming language by allowing the solve item to be replaced by a CLP goal :- goal.. There can be at most one goal item in a ClpZinc model, as there can be only one solve item in a Zinc model.

A ClpZinc goal is either:

Terms are either:

where f1, ..., and fn are field names (any valid identifiers) t1, ..., and tn are terms. Model variables are a special case of compound terms, either atomic (a, b, ...) or array accessors (x[I,J]).

Lists are denoted [X1,...,Xn] ([] for the empty list) and partial lists are denoted [X1,...,Xn | T]. Zinc arrays have been unified with Prolog-like lists to ease their enumeration in search strategies. CLP lists are mapped to Zinc arrays in code generation. Zinc two-dimensional arrays have been unified with lists of lists.

Basic constraints are:

The following constraints are only defined when X and Y are numbers (or arithmetic expressions, or model variables, but not terms).

The following pseudo-constraints are only tests, they do not change the current store.

Goals without pending constraints can be negated with the negation-by-failure \+. Note that MiniZinc pending constraints never fail at compile time when they are not fully instantiated, therefore their negation will never succeed.

A comprehensive list of constraints is given in the MiniZinc specification. Every unknown predicate is assumed to be a constraint and is passed to MiniZinc, therefore all the constraints can be accessed, even solver-specific constraints.

CLP Clause Items

CLP predicates can be defined with clauses: a ClpZinc clause is an item of the form p(t1,...,tn) :- goal. where t1 and tn are terms and goal is a ClpZinc goal. The goal part can be omitted: p(t1,...,tn). is a shorthand for p(t1,...,tn) :- true..

include Items

Every include "file.plz"; item is evaluated by ClpZinc by expanding it with the contents of the file file.plz. include items that include files with any other suffix than .plz (typically, .mzn) are left to MiniZinc.

Files are searched in the current directory and in the list of include directories, in their order of appearance. This list contains all the directories listed in the CLP2ZINCPATH environment variable if it exists (separated by :), and ends with the lib/ sub-directory in the directory where the clp2zinc executable is located. Search paths can be added on the top of this list with the -I path option.

Moreover, for every directory in this list, prefixes can be added with the -O prefix. By default, only the . prefix is tried (the directory itself), but sub-directories can be added as prefix, for example to look in a sub-directory specific to a particular solver.


In CLP(X + H), arithmetic differs from Prolog. Indeed, in accordance with the theory of CLP and unlike most Prolog systems, arithmetic is supposed to be contained in X and is distinguished from H terms, e.g., 1 + 1 is undistinguishable from 2 and is not a H term. In ClpZinc, the different forms of unification, equality, and evaluation predicates that are encountered in Prolog systems (=, #=, is, ...) are thus all unified in a unique notion of equality, which is accessible either explicitly with the predicate =, or implicitly when predicate arguments in either X of H are unified.

A comprehensive list of arithmetic operators is given in the MiniZinc specification. Every unknown term is treated as an Herbrand term and is printed as is in the MiniZinc generated model, therefore every MiniZinc function symbol can be used.


Arithmetic expressions are also extended for accessing the indexicals of the model variables. For instance, the goal M = min(X) assumes that X is a model variable and unifies M with the currently known lower-bound of X. The available indexicals are:

Some search strategies require to iterate a search tree several times with some kind of memory passed from one branch to another. That is typically the case for optimization methods like branch-and-bound where the best score reached up to now is remembered from one iteration to another of the underlying search strategy, or for shaving, where one step of propagation is performed and undone in order to select the best one. In languages like Prolog, such methods are implemented with the help of some kind of global state, most commonly stored within the fact database (with assert and retract). The two additional annotations can be used in ClpZinc to handle global state.

The search annotations of MiniZinc are accessible in goals in order to allow the composition of user-defined strategies with built-in ones. MiniZinc search annotations (except indexicals and accesses to global states) cannot appear under an unsolved choice-point.

The three following pseudo-search annotations can appear at most once in the goal.

The Standard Library

The standard library is in the lib/ directory. It contains the following ClpZinc files: