{ "cells": [ { "cell_type": "markdown", "id": "50f59844", "metadata": {}, "source": [ "# Command-Line Interface" ] }, { "cell_type": "markdown", "id": "b467c7b5", "metadata": {}, "source": [ "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:" ] }, { "cell_type": "raw", "id": "8ac93d46", "metadata": {}, "source": [ "python [options]" ] }, { "cell_type": "markdown", "id": "ebbf103b", "metadata": {}, "source": [ "with:\n", "- <file>: a Python file to be executed, describing a model in PyCSP$^3$\n", "- [options]: possible options to be used when compiling\n" ] }, { "cell_type": "markdown", "id": "e739f7d5", "metadata": {}, "source": [ "Among the options, we find:\n", "\n", "* ```-data=```: allows us to specify the data to be used by the model. It can be:\n", " + elementary: -data=5\n", " + a simple list: -data=[9,0,0,3,9]\n", " + a JSON file: -data=Bibd-3-4-6.json\n", "\n", " Data can then be directly used in the PyCSP$^3$ model by means of a predefined variable `data`.\n", " \n", "\n", "* ```-dataparser=```: a Python file for reading/parsing data given under any arbitrary form (e.g., by a text file).\n", " See Example Nonogram for an illustration.\n", " \n", "\n", "* ```-dataexport```: exports (saves) the data in JSON format.\n", " See Example Nonogram for an illustration.\n", " \n", "\n", "* ```-dataformat```: formats numbers in the filename of the generated XCSP$^3$ instance.\n", "\n", "\n", "By default, a file containing the XCSP$^3$ instance is generated, unless you use the option:\n", "\n", "* ```-display```: displays the XCSP$^3$ instance in the system standard output, instead of generating an XCSP$^3$ file \n" ] }, { "cell_type": "markdown", "id": "6dda7e83", "metadata": {}, "source": [ "## Setting the Filename " ] }, { "cell_type": "markdown", "id": "ac8bf540", "metadata": {}, "source": [ "The option ```-output``` allows us to indicate what must be the name of the generated filename (instead of the one that is automatically chosen)." ] }, { "cell_type": "markdown", "id": "8ed6aa55", "metadata": {}, "source": [ "For example, the name of the generated XCSP$^3$ file is 'Queens-4.xml' when executing:\n", "\n", "```\n", "python Queens.py -data=4 \n", "```\n", "\n", "whereas it is 'myname.xml' when executing:\n", "```\n", "python Queens.py -data=4 -output=myname\n", "```" ] }, { "cell_type": "markdown", "id": "20f350f6", "metadata": {}, "source": [ "This option can be also given the name of a directory.\n", "See examples given for Problem *BIBD* in the guide." ] }, { "cell_type": "markdown", "id": "6b67f760", "metadata": {}, "source": [ "## Variants and Subvariants" ] }, { "cell_type": "markdown", "id": "f4b693e3", "metadata": {}, "source": [ "The option ```-variant``` allows us to choose between several possible variants of a model.\n", "Actually, it is possible to reason with both a variant name and a subvariant name.\n", "It is the case when the name contains the character '-' separating the variant name from the subvariant name.\n", "In PySCP$^3$, we then use the functions *variant()* and *subvariant()*.\n", "Let us consider the following example (piece of code in a file called 'TestVariant.py'):" ] }, { "cell_type": "raw", "id": "62c5f6ee", "metadata": {}, "source": [ "from pycsp3 import *\n", "\n", "x = Var(0,1)\n", "\n", "if not variant():\n", " print(\"no variant\")\n", "elif variant(\"v1\"):\n", " print(\"variant v1\")\n", "elif variant(\"v2\"):\n", " print(\"variant v2\")\n", " if not subvariant():\n", " print(\"no subvariant\")\n", " elif subvariant(\"a\"):\n", " print(\"subvariant a\")\n", " elif subvariant(\"b\"):\n", " print(\"subvariant b\")" ] }, { "cell_type": "markdown", "id": "0ab176bf", "metadata": {}, "source": [ "Here are the results we obtain for various command lines:\n", "```\n", "python TestVariant.py // no variant\n", "python TestVariant.py -variant=v1 // variant v1\n", "python TestVariant.py -variant=v2 // variant v2 \n", "python testVariant.py -variant=v2-a // variant v2 subvariant a \n", "python testVariant.py -variant=v2-b // variant v2 subvariant b\n", "```" ] }, { "cell_type": "markdown", "id": "d024f792", "metadata": {}, "source": [ "## Solving" ] }, { "cell_type": "markdown", "id": "1d0101a3", "metadata": {}, "source": [ "The following options concern the solving process.\n", "\n", "```\n", " -solve\n", " -solver\n", "```" ] }, { "cell_type": "markdown", "id": "92d18786", "metadata": {}, "source": [ "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:" ] }, { "cell_type": "markdown", "id": "69ca2794", "metadata": {}, "source": [ "```\n", "python Queens.py -data=4 -solve\n", "python Queens.py -data=4 -solver=choco\n", "python Queens.py -data=4 -solver=ace\n", "python Queens.py -data=4 -solver=[choco,v]\n", "python Queens.py -data=4 -solver=[ace,vv]\n", "python Queens.py -data=4 -solver=[ace,v,args=\"-s=2\"]\n", "```" ] }, { "cell_type": "markdown", "id": "7704f258", "metadata": {}, "source": [ "## Other Options" ] }, { "cell_type": "markdown", "id": "5737a0a9", "metadata": {}, "source": [ "Finally, there are some other options, used as flags, i.e., requiring no argument:\n", "- `-display` displays the XCSP$^3$ instance in the system standard output, instead of generating an\n", "XCSP$^3$ file (not compatible with -solve and -solver)\n", "- `-verbose` displays some additional information when compiling\n", "- `-sober` does not include side notes in the XCSP$^3$ file\n", "- `-ev` may display additional information when an error occurs\n", "- `-lzma` compresses the XCSP$^3$ file with lzma (requires lzma to be installed)\n", "- `-safe` performs some operations (possibly based on parallelism) in a safer manner\n", "- `-keepHybrid` keeps compressed forms of hybrid tables\n", "- `-restrictTablesWrtDomains` removes useless tuples (because invalid) in ordinary/starred tables\n", "- `-dontRunCompactor` prevents from compacting the representation of constraints and objectives \n", "- `-dontCompactValues` prevents from compressing lists of integers (with character 'x' as in 0x20)\n", "- `-groupSumCoeffs` gathers coefficients that are associated with the same variables (e.g., in a constraint *Sum*) \n", "- `-mini` attempts to generate instances in the perimeter of the mini-tracks of XCSP competitions\n", "- `-uncurse` prevents from redefining some operators (with module 'forbiddenfruit')" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.12" } }, "nbformat": 4, "nbformat_minor": 5 }