# **PyCSP**^{3}

^{3}

PyCSP^{3} is a Python library that allows us to write models of combinatorial constrained problems in a declarative manner. Currently, with PyCSP^{3}, you can write models of constraint satisfaction and optimization problems. More specifically, you can build models for:

In this website, you will find all that you need to know about Constraint Programming (CP) and PyCSP^{3}, with more than 60 Jupyter Notebooks:

- find the 25 popular constraints , with dedicated Jupyter Notebooks
- discover, step by step, more than 30 models of classical problems (Sport Scheduling, Social Golfers, Warehouse Location , ...), with dedicated Jupyter Notebooks

You can also:

- read this guide
- explore a GitHub repository containing more than 350 models at pycsp3-models

As an illustration, below, you can find two simple examples of PyCSP^{3} models:

#### AllInterval Problem

```
from pycsp3 import *
n = data or 8
# x[i] is the ith note of the series
x = VarArray(size=n, dom=range(n))
satisfy(
# notes must occur once, and so form a permutation
AllDifferent(x),
# intervals between neighbouring notes must form a permutation
AllDifferent(abs(x[i] - x[i + 1]) for i in range(n - 1)),
# tag(symmetry-breaking)
x[0] < x[n - 1]
)
```

#### Golomb Ruler Problem

```
from pycsp3 import *
n = data or 10
# x[i] is the position of the ith tick
x = VarArray(size=n, dom=range(n * n))
satisfy(
# all distances are different
AllDifferent(abs(x[i] - x[j]) for i, j in combinations(range(n), 2)),
# tag(symmetry-breaking)
[x[0] == 0, Increasing(x, strict=True)]
)
minimize(
# minimizing the position of the rightmost tick
x[-1]
)
```

## *Last News*

- December 10, 2023
- New GitHub repository for Models and Data; see pycsp3-models and this page.

- December 10, 2023
- PyCSP
^{3}2.2, with new (control) structures 'If' and 'Match', new derivated constraint forms (Hamming, Exist, NotExist, ExactlyOne, AtLeastOne, AtMostOne and AllHold), new functions 'both' and 'either', auto-adjustment of array indexing, and the predefined named tuple 'Task'. See other extensions in Changelog Chapter of the complete guide.

- August 30, 2023
- 2023 XCSP
^{3}Competition, held with CP 2023; see the results.

- November 10, 2022
- PyCSP
^{3}2.1, with new versions of embedded solvers (ACE and Choco) and additional constraints (Precedence, BinPacking, Knapsack, MinimumArg, MaximumArg).

- November 10, 2022
- Specifications of XCSP
^{3}, Version 3.1

- November 10, 2022
- ACE 2.1 , Version 2.1 of the generic constraint solver ACE (written in Java).

- August 3, 2022
- 2022 XCSP
^{3}Competition, held with FLoC 2022 (Olympic Games); see the results.

- December 15, 2021
- PyCSP
^{3}2.0 , Version 2 of the Python library PyCSP^{3}.

- December 15, 2021
- ACE 2.0 , Version 2 of the generic constraint solver ACE (written in Java).

- January 16, 2021
- Specifications of XCSP
^{3}, Version 3.0.7

## Requirements

- For building and compiling models, you need:
- Python 3.8 (at least) to be installed.
- Python package PyCSP
^{3}to be installed, for example from PyPi:`pip install pycsp3`

- For running the embedded solvers (ACE and Choco), you need Java 11 to be installed

Importantly, there is a complete separation between the modeling and solving phases: you write a model, you compile it (while providing some data) in order to generate an XCSP^{3} instance (file), and you solve that problem instance by means of a constraint solver. You can also directly pilot the solving procedure in PyCSP^{3} possibly conducting an incremental solving strategy.

In a nutshell, the main ingredients of the complete tool chain we propose for handling combinatorial constrained problems are:

- PyCSP
^{3}: a Python library for modelling constrained problems, which is described in this document - XCSP
^{3}: an intermediate format used to represent problem instances while preserving structure of models

A shown in the figure below, the user who wishes to solve a combinatorial constrained problem has to:

- write a model using the Python library PyCSP
^{3}(i.e., write a Python file) - provide a data file (in JSON format) for a specific problem instance to be solved
- compile both files (model and data) so as to generate an XCSP
^{3}instance (file) - solve the XCSP
^{3}file (problem instance under format XCSP^{3}) by using a constraint solver as, e.g., ACE, Choco, OscaR or PicatSAT

This approach has many advantages:

- Python, JSON, and XML are robust mainstream technologies
- using JSON for data permits to have a unified notation, easy to read for both humans and computers
- using Python 3 for modeling allows the user to avoid learning again a new programming language
- using a coarse-grained XML structure permits to have compact and readable problem instances

Note that using JSON instead of XML for representing instances would have been possible but has some drawbacks, as explained in an appendix of XCSP^{3} Specifications.