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]

with:

• <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:
  • a single elementary value: -data=<number>, as in -data=8
  • a list of elementary values, between square (or round) brackets and with comma used as a separator: -data=[number, ...], as in -data=[8,10,3]
  • a JSON file (possibly, given by an URL): -data=<datafile.json>
  • a text file: -data=<datafile.txt> (while specifying the option -parser)

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

• -parser=<file> (or -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.

• -export (or -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 Queens.py -data=4 

whereas it is ‘myname.xml’ when executing:

python Queens.py -data=4 -output=myname

This option can be also given the name of a directory. See examples given for Problem BIBD in the guide.

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 ‘TestVariant.py’):

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 TestVariant.py                 // no variant
python TestVariant.py -variant=v1     // variant v1
python TestVariant.py -variant=v2     // variant v2 
python testVariant.py -variant=v2-a   // variant v2  subvariant a 
python testVariant.py -variant=v2-b   // variant v2  subvariant b

Solving

The following options concern the solving process.

  -solve
  -solver

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 Queens.py -data=4 -solve
python Queens.py -data=4 -solver=choco
python Queens.py -data=4 -solver=ace
python Queens.py -data=4 -solver=[choco,v]
python Queens.py -data=4 -solver=[ace,vv]
python Queens.py -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
• -keepHybrid keeps compressed forms of hybrid tables
• -restrictTablesWrtDomains removes useless tuples (because invalid) in ordinary/starred tables
• -dontRunCompactor prevents from compacting the representation of constraints and objectives
• -dontCompactValues prevents from compressing lists of integers (with character ‘x’ as in 0x20)
• -groupSumCoeffs gathers coefficients that are associated with the same variables (e.g., in a constraint Sum)
• -mini attempts to generate instances in the perimeter of the mini-tracks of XCSP competitions
• -uncurse prevents from redefining some operators (with module ‘forbiddenfruit’)