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

Command-Line Interface

When a command is executed from a console (terminal) of the operating system, it is usually for generating an XCSP$^3$ instance from a PyCSP$^3$ model. You execute something like:

python <file> [options]


  • <file>: a Python file to be executed, describing a model in PyCSP$^3$

Among the options, we find:

  • -data=<data_value>: allows us to specify the data to be used by the model. It can be:
    • elementary: -data=5
    • a simple list: -data=[9,0,0,3,9]
    • a JSON file: -data=Bibd-3-4-6.json

    Data can then be directly used in the PyCSP$^3$ model by means of a predefined variable data.

  • -dataparser=<file>: a Python file for reading/parsing data given under any arbitrary form (e.g., by a text file). See Example Nonogram for an illustration.

  • -dataexport: exports (saves) the data in JSON format. See Example Nonogram for an illustration.

  • -dataformat: formats numbers in the filename of the generated XCSP$^3$ instance.

By default, a file containing the XCSP$^3$ instance is generated, unless you use the option:

  • -display: displays the XCSP$^3$ instance in the system standard output, instead of generating an XCSP$^3$ file

Setting the Filename

The option -output allows us to indicate what must be the name of the generated filename (instead of the one that is automatically chosen).

For example, the name of the generated XCSP$^3$ file is ‘Queens-4.xml’ when executing:

python -data=4 

whereas it is ‘myname.xml’ when executing:

python -data=4 -output=myname

Variants and Subvariants

The option -variant allows us to choose between several possible variants of a model. Actually, it is possible to reason with both a variant name and a subvariant name. It is the case when the name contains the character ‘-‘ separating the variant name from the subvariant name. In PySCP$^3$, we then use the functions variant() and subvariant(). Let us consider the following example (piece of code in a file called ‘’):

from pycsp3 import *

x = Var(0,1)

if not variant():
    print("no variant")
elif variant("v1"):
    print("variant v1")
elif variant("v2"):
    print("variant v2")
    if not subvariant():
        print("no subvariant")
    elif subvariant("a"):
        print("subvariant a")
    elif subvariant("b"):
        print("subvariant b")

Here are the results we obtain for various command lines:

python                 // no variant
python -variant=v1     // variant v1
python -variant=v2     // variant v2 
python -variant=v2-a   // variant v2  subvariant a 
python -variant=v2-b   // variant v2  subvariant b


The following options concern the solving process.


When using -solve, the default solver, ACE, is called. When using -solver, one must indicate the name of the solver (ace or choco, case insensitive), and possibly other solver options, in which case, square brackets are required. Among the solver options, one can use v (for verbose) or vv (for very verbose), and args that must then be followed by the symbol ‘=’ and a string corresponding to some specific solver options. Here are a few examples:

python -data=4 -solve
python -data=4 -solver=choco
python -data=4 -solver=ace
python -data=4 -solver=[choco,v]
python -data=4 -solver=[ace,vv]
python -data=4 -solver=[ace,v,args="-s=2"]

Other Options

Finally, there are some other options, used as flags, i.e., requiring no argument:

  • -display displays the XCSP$^3$ instance in the system standard output, instead of generating an XCSP$^3$ file (not compatible with -solve and -solver)
  • -verbose displays some additional information when compiling
  • -sober does not include side notes in the XCSP$^3$ file
  • -ev may display additional information when an error occurs
  • -lzma compresses the XCSP$^3$ file with lzma (requires lzma to be installed)
  • -safe performs some operations (possibly based on parallelism) in a safer manner