Link Search Menu Expand Document
Documentation Data GitHub XCSP3 About
download ipynb

Module Interface

In this section, we briefly review all components (constants, variables, functions) that are available from the main module of the library PyCSP$^3$. This is what you get when executing:

from pycsp3 import *

In the next sub-sections, we introduce the different categories of such components.

Building Models

The main functions for building CSP and COP models are about:

  • declaring stand-alone variables, and arrays of variables
    • Var()
    • VarArray()
  • posting constraints
    • satisfy()
  • specifying an objective
    • minimize()
    • maximize()
  • managing several model variants
    • variant()
    • subvariant()

How to declare variables is discussed here. How to post constraints is discussed here. How to specify an objective is discussed here. How to manage variants and subvariants is illustrated here.

Building Expressions

When building expressions of intensional constraints, one can use constants, variables, and arithmetic, relational, and logic operators (which are redefined to this particular purpose). In addition to the Python functions:

  • abs()
  • min()
  • max()

which are also extended (redefined), one can use the following specific functions:

  • xor()
  • iff()
  • imply()
  • ift()
  • expr()
  • conjunction()
  • disjunction()

For example, the 8 constraints of this demonstration model:

x = VarArray(size=6, dom=range(6))

    xor(x[0] == 0, x[1] == 1, x[2] == 2),
    iff(x[0] < 3, x[1] != 2),
    iff(x[i] != i for i in range(6)),
    imply(x[0] > 2, x[1] == 4),
    ift(x[0] == 1, x[1] == 2, x[2] == 3),
    expr("<", x[0], 4),
    conjunction(x[i] != i for i in range(6)),
    disjunction(x[i] != i for i in range(6)),

correspond to constraints Intension whose expressions in prefix notation are visible when calling posted():


Although a little bit technical, we can see the correspondances. Note that ‘eq’, ‘ne’, ‘lt’, ‘gt’ stands for ‘equal to’, ‘not equal to’, ‘strictly less than’, ‘strictly greater than’, respectively.

A related function is:

  • protect()

that allows us to execute some piece of code while all redefined operators are temporarily deactivated. To be effective, one must chain the call to protect() with a call to execute() with the piece of code to be executed in protected mode. As an illustration, if we execute:


x = Var(0,1)
y = Var(0,1)

print(x == y)
print(protect().execute(x == x))
print(protect().execute(x == y))

Building Global Constraints

Some constraints can be built by simply using the (redefined) operators (and functions) of Python. This is mainly the case for constraints Intension, Extension and also Element. For the other global constraints, here is the list of functions to be called:

  • Automaton() and MDD()
  • AllDifferent(), AllDifferentList(), AllEqual()
  • Increasing(), Decreasing(), LexIncreasing(), LexDecreasing()
  • Sum(), Count(), NValues(), Cardinality()
  • Maximum(), Minimum(), Channel()
  • NoOverlap(), Cumulative(), BinPacking()
  • Circuit(), Clause()

Details about these functions can be found in the docstrings and in other webpages of this site.

Loading (Default) JSON Data

Two useful functions to load some JSON data by default, or independently of the main object data are:

  • default_data()
  • loading_json_data()

These functions are described in XXX.

Handling Lists (Matrices)

Rather often, we need to handle matrices (i.e., two-dimensional lists) of integers or variables. The following functions can be helpful:

  • columns()
  • diagonal_down()
  • diagonals_down()
  • diagonal_up()
  • diagonals_up()

The function columns() actually computes a transpose matrix. Let us illustrate it with:


x = VarArray(size=[3,4], dom={0,1})

  [x[0][0], x[0][1], x[0][2], x[0][3]]
  [x[1][0], x[1][1], x[1][2], x[1][3]]
  [x[2][0], x[2][1], x[2][2], x[2][3]]
  [x[0][0], x[1][0], x[2][0]]
  [x[0][1], x[1][1], x[2][1]]
  [x[0][2], x[1][2], x[2][2]]
  [x[0][3], x[1][3], x[2][3]]

As an illustration of functions that are useful for extracting diagonals, let us execute:

y = VarArray(size=[4,4], dom={0,1})

print(diagonals_down(y, broken=True))
[y[0][0], y[1][1], y[2][2], y[3][3]]
  [y[2][0], y[3][1]]
  [y[1][0], y[2][1], y[3][2]]
  [y[0][0], y[1][1], y[2][2], y[3][3]]
  [y[0][1], y[1][2], y[2][3]]
  [y[0][2], y[1][3]]
  [y[0][0], y[1][1], y[2][2], y[3][3]]
  [y[0][3], y[1][0], y[2][1], y[3][2]]
  [y[0][2], y[1][3], y[2][0], y[3][1]]
  [y[0][1], y[1][2], y[2][3], y[3][0]]

Finally, the function cp_array() allows us to transform any list (of any dimension) of integers into a more specific type called ‘ListInt’ that inherits from list. Similarly, it allows us to transform any list (of any dimension) of variables into a more specific type called ‘ListVar’ that inherits from list. It is important to have such specific types of lists when using the constraint Element. Importantly, when the data are loaded from a file (the usual case), all lists of integers have the specific type of list returned by cp_array(), and so, it is very rare to need to call this function explicitly.

Here is an illustration:

t = [3, 4, 5]
t = cp_array(t)
<class 'list'>
<class ''>

Another illustration is:

z = VarArray(size=5, dom={0,1})

zz = [z[0], z[2], z[4]]
zz = cp_array(zz)
<class ''>
<class 'list'>
<class ''>

Let us reacll that when a list is from type ‘ListVar’ or ‘ListInt’, it can be used in the expression of a constraint Element.

Handling Tuples

From package itertools, the following functions are directly available:

  • product()
  • permutations()
  • combinations()

Note that the function combinations() is slightly extended so as to permit the first argument to be an integer. In that case, this value is converted into a range. For example, if we execute:

print([tuple for tuple in combinations(5,2)])
[(0, 1), (0, 2), (0, 3), (0, 4), (1, 2), (1, 3), (1, 4), (2, 3), (2, 4), (3, 4)]

Utility Computations

Some utility functions are:

  • different_values()
  • flatten()
  • alphabet_positions()
  • all_primes()
  • integer_scaling()

The function different_values() just checks that all specified arguments are different. The function flatten() builds a one-dimensional list with all elements that can be encountered when looking into the specified arguments (typically, this is a list of possibly any dimension). None values are discarded except if the optional named parameter keep_none is set to True. For example, if we execute:


x = VarArray(size=[3,3], dom=lambda i,j: {0,1} if i >= j else None)
print("x: ", x)
print("x flattened: ", flatten(x))
x:  [
  [x[0][0], None, None]
  [x[1][0], x[1][1], None]
  [x[2][0], x[2][1], x[2][2]]
x flattened:  [x[0][0], x[1][0], x[1][1], x[2][0], x[2][1], x[2][2]]

The function alphabet_positions() returns a list with the indexes of the letters (with respect to the 26 letters of the Latin alphabet) of a specified string. The function all_primes() returns a list with all prime numbers that are strictly less than the specified limit. The function integer_scaling() returns a list with all specified values after possibly converting them (when decimal) into integers by means of automatic scaling. For example, if we execute:

t = [3, 2.11, 0.0141]
print("t scaled: ", integer_scaling(t))
t scaled:  [30000, 21100, 141]

Building Compressed Forms of Tables

On the one hand, it is rather easy to build starred tuples, which are tuples involving ‘*’, denoted by the constant ANY in PySCP$^3$. Illustrations are given by the models of problems TravelingTournament and Layout.

On the other hand, when creating tables to be used with extensional constraints, one can use some auxiliary functions that capture some patterns (conditions) that can be put at some places inside tuples. Tables are then said to be hybrid. The interest is that it is easier (quicker) to build tables (and besides, in the near future, we shall be able to generate such tables when compiling). These functions are:

  • lt(), meaning ‘strictly less than’
  • le(), meaning ‘less than or equal to’
  • gt(), meaning ‘strictly greater than’
  • ge(), meaning ‘greater than or equal to’
  • eq(), meaning ‘equal to’
  • ne(), meaning ‘not equal to’
  • complement(), meaning ‘not present in’

For example, assuming that the possible values to work with are {0,1,2,3,4}, the hybrid tuple (0,lt(3),2) represents the set of tuples {(0,0,2),(0,1,2),(0,2,2)} since lt(3) means any value that is strictly less than 3. As a more concrete illustration, let us consider the following demonstration model:


table = [(0, ANY, gt(1)), (ne(0),(2,3),complement(2,3))]

x = VarArray(size=3, dom=range(4))

    x in table

The constraint expresses the fact that x[0] can be 0 if x[2] > 1, or different from 0 if x[1] in {2,3} and x[2] in {0,1} (the complement of {2,3}). When looking at the outcome of compilation (the XCSP$^3$ file), one can see that a starred table has been generated.

Although the transformation from hybrid tables to ordinary/starred tables is automatic when compiling, one may want, for some reasons, to apply explicitly the transformation with the function to_ordinary_table(). This function converts a specified table that may contain hybrid restrictions and stars into an ordinary table (or a starred table). The first argument of the function is a table that contains r-tuples. For converting, the domain to be considered are any index i of these tuples is given by domains[i] where domains is the second argument of the function. In case, domains[i] is an integer, it is automatically transformed into a range. An optional named parameter starred allows us to choose between an ordinary and a starred table. For example:

table = [(0, ANY, gt(1)), (ne(0),(2,3),complement(2,3))]
print("Hybrid table: ", table)
print("Starred Table: ", sorted(to_ordinary_table(table,[4,4,4], starred=True)))
print("Ordinary Table: ", sorted(to_ordinary_table(table,[4,4,4])))
Hybrid table:  [(0, *, ≥2), (≠0, (2, 3), ∁{2,3})]
Starred Table:  [(0, *, 2), (0, *, 3), (1, 2, 0), (1, 2, 1), (1, 3, 0), (1, 3, 1), (2, 2, 0), (2, 2, 1), (2, 3, 0), (2, 3, 1), (3, 2, 0), (3, 2, 1), (3, 3, 0), (3, 3, 1)]
Ordinary Table:  [(0, 0, 2), (0, 0, 3), (0, 1, 2), (0, 1, 3), (0, 2, 2), (0, 2, 3), (0, 3, 2), (0, 3, 3), (1, 2, 0), (1, 2, 1), (1, 3, 0), (1, 3, 1), (2, 2, 0), (2, 2, 1), (2, 3, 0), (2, 3, 1), (3, 2, 0), (3, 2, 1), (3, 3, 0), (3, 3, 1)]

Building Meta-constraints

It is possible to build meta-constraints by using the following functions:

  • And()
  • Or()
  • Not()
  • Xor()
  • IfThen()
  • IfThenElse()
  • Iff()

It is important to note that the first letter of these function names is uppercase. Some illustrations and details are given in this part. For the moment, note that meta-constraints should be avoided as they are not in the perimeter of XCSP$^3$-core.


Some constants are available. Some concern the result of a solving process, when solve() is called.

  • UNSAT, unsatisfiable (means that no solution is found by the solver)
  • SAT, satisfiable (means that at least one solution is found by the solver)
  • OPTIMUM, optimum (means that an optimal solution is found by the solver)
  • UNKNOWN, unknown (means that the solver is unable to solve the problem instance)
  • CORE, core (means that an unsatisfiable core has been extracted by the solver)

Some concern the choice of a solver:

  • ACE, Solver ACE (AbsCon Essence)
  • CHOCO, Solver Choco

A last constant is

  • ALL, meaning that all solutions must be sought, when used with the parameter sols of solve().

The functions that directly concern the solving process are:

  • solve(): runs the solver on the current instance
  • solver(): returns the current solver, when no argument is given, or sets the current solver with an argument set to the constant ACE or the constant CHOCO
  • status(): returns the result of the last solving process (last call to \nn{solve()})
  • solution(): returns an object with various information (fields) concerning the last found solution
  • value(): returns the value assigned to the variable specified as parameter
  • values(): returns the list of values assigned to the (list of) variables specified as parameter
  • n_solutions(): returns the number of found solutions
  • bound(): returns the value of the objective function corresponding to the last found solution
  • core(): returns the core identified by the last extraction operation

These functions are described and/or illustrated in this part.

Finally, some functions allow us to display the posted constraints (or objective), to remove some posted constraints and to clear everything (variables, constraints, objective):

  • posted(): displays the posted constraints
  • objective(): displays the current objective
  • unpost(): removes the constraints posted by the last call to satisfy().
  • clear(): clears everything (variables, constraints, objective)

These functions are described and/or illustrated in this part.