pymzn: merge branch develop

README.rst

@@ -3,9 +3,9 @@ PyMzn
 
 PyMzn is a Python library that wraps and enhances the `MiniZinc
 <http://minzinc.org>`__ tools for CSP modelling and solving.  It is built on top
-of the libminizinc library and provides a number of off-the-shelf functions to
-readily solve problems encoded in MiniZinc and parse the solutions into Python
-objects.
+of the `minizinc <https://github.com/MiniZinc/MiniZincIDE>`__ toolkit and
+provides a number of off-the-shelf functions to readily solve problems encoded
+in MiniZinc and parse the solutions into Python objects.
 
 Usage
 -----
@@ -30,18 +30,19 @@ Here is a simple 0-1 knapsack problem encoded with MiniZinc:::
     profit = [10, 3, 9, 4, 8];
     size = [14, 4, 10, 6, 9];
 
-You can solve the above problem using the ``pymzn.minizinc`` function:::
+You can solve the above problem using the ``pymzn.minizinc`` function::
 
     import pymzn
     pymzn.minizinc('test.mzn', 'test.dzn', data={'capacity': 20})
 
-The result will be:::
+The result will be::
 
-    [{'x': {3, 5}}]
+    SolnStream(solns=[{'x': {3, 5}}], complete=True)
 
-The ``minizinc`` function automatically flattens the MiniZinc model, using the
-provided mzn and dzn files, and the inline data provided. It executes the
-solver on the flattened model and parses the solution stream to get the
+The returned object represent a solution stream, which can be directly
+referenced and iterated as a list. The ``minizinc`` function automatically
+flattens the MiniZinc model, using the provided mzn and dzn files. It executes
+the solver on the flattened model and parses the solution stream to get the
 solutions as Python dictionaries.
 
 PyMzn is also able to:
@@ -62,36 +63,38 @@ For more information on the PyMzn functions read the
 Install
 -------
 
-PyMzn can be installed via Pip:::
+PyMzn can be installed via Pip::
 
     pip3 install pymzn
 
 or from the source code available
-on `GitHub <https://github.com/paolodragone/pymzn>`__:::
+on `GitHub <https://github.com/paolodragone/pymzn>`__::
 
     python3 setup.py install
 
 Currently, PyMzn is developed and maintained in Python v3.5 with a
-porting to Python v2.7 at every release (the python2 branch does not contain
-the most recent changes).
+porting to Python v2.7 at every release (the python2 branch does not always
+contain the most recent changes).
 
 
 Requirements
 ------------
 PyMzn requires some additional software to be installed on your system
 before you can use it properly, namely:
 
-* The `libminizinc library <https://github.com/MiniZinc/libminizinc>`__;
+* The `MiniZinc toolkit <https://github.com/MiniZinc/MiniZincIDE>`__;
 * A CSP solver compatible with the FlatZinc encoding, e.g. `Gecode <http://www.gecode.org>`__.
 
-You can use any solver you like, but the default one for PyMzn is
-`Gecode <http://www.gecode.org>`__. If you use the Gecode solver, PyMzn will
-work out-of-the-box, otherwise it will need some little configuration (see the
+You can use any solver you like, but the default one for PyMzn is `Gecode
+<http://www.gecode.org>`__. If you use the Gecode solver, PyMzn will work
+out-of-the-box. PyMzn also supports most of the solvers included in the MiniZinc
+toolkit. If the solver you are looking for is not supported by PyMzn you can
+implement your own interface and use it with little configuration (see the
 `Solvers section <reference/solvers/>`__).
 
-Detailed instructions on how to install *libminizinc* and *Gecode* can be
-found in the `Install section <http://paolodragone.com/pymzn/install.html>`__
-of the documentation.
+Detailed instructions on how to install *MiniZinc* and *Gecode* can be found in
+the `Install section <http://paolodragone.com/pymzn/install.html>`__ of the
+documentation.
 
 
 Contribute

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 8a66488725c672d3165d3f3dff3b91a4
+config: dbb8a4c6be933715e77ae65145b0ff0a
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_sources/install.txt → docs/_sources/install.rst.txt

@@ -1,45 +1,47 @@
 Install
 =======
 
-PyMzn can be installed via Pip:::
+PyMzn can be installed via Pip::
 
     pip3 install pymzn
 
-or from the source code:::
+or from the source code::
 
     python3 setup.py install
 
 Currently, PyMzn is developed and maintained in Python v3.5 with a
-porting to Python v2.7 at every release (the python2 branch does not contain
-the most recent changes).
+porting to Python v2.7 at every release (the python2 branch does not always
+contain the most recent changes).
 
 PyMzn requires some additional software to be installed on your system
 before you can use it properly, namely:
 
-* The `libminizinc library <https://github.com/MiniZinc/libminizinc>`__;
+* The `MiniZinc toolkit <https://github.com/MiniZinc/MiniZincIDE>`__;
 * A CSP solver compatible with the FlatZinc encoding, e.g. `Gecode <http://www.gecode.org>`__.
 
 
 Install libminizinc
 -------------------
 
-The latest release of libminizinc can be found here:
+The latest release of the MiniZinc toolkit can be found here:
 
-    `<https://github.com/MiniZinc/libminizinc/releases/latest>`__
+    `<https://github.com/MiniZinc/MiniZincIDE/releases/latest>`__
 
 Download and install the package on your system. After that you should insert
-the libminizinc binary path into the PATH environment variable, or alternatively
-you can tell PyMzn's where to find the MiniZinc binaries
+the MiniZinc binary path into the PATH environment variable, or alternatively
+you can configure PyMzn to find the MiniZinc binaries
 (see `Configuration <config.html>`__).
 
 Install Gecode
 --------------
 
-The next step is to install a CSP solver compatible with FlatZinc. You
-can use any solver you like, but the default one for PyMzn is
-`Gecode <http://www.gecode.org>`__. If you use the Gecode solver, PyMzn will
-work out-of-the-box, otherwise it will need some little configuration (see the
-`Solvers <reference/solvers/>`__ section).
+The next step is to install a CSP solver compatible with FlatZinc. You can use
+any solver you like, but the default one for PyMzn is `Gecode
+<http://www.gecode.org>`__. If you use the Gecode solver, PyMzn will work
+out-of-the-box. PyMzn also supports most of the solvers included in the MiniZinc
+toolkit. If the solver you are looking for is not supported by PyMzn you can
+implement your own interface and use it with little configuration (see the
+`Solvers section <reference/solvers/>`__).
 
 To install Gecode, we recommend you to download and compile the source code,
 since binary packages are usually less frequently updated.

docs/_sources/quick_start.txt → docs/_sources/quick_start.rst.txt

@@ -1,7 +1,7 @@
 Quick Start
 ===========
 First, you need a MiniZinc model encoding the problem you want to solve.
-Here is a simple 0-1 knapsack problem encoded with MiniZinc:::
+Here is a simple 0-1 knapsack problem encoded with MiniZinc::
 
     %% test.mzn %%
     int: n;                     % number of objects
@@ -21,71 +21,63 @@ Here is a simple 0-1 knapsack problem encoded with MiniZinc:::
     profit = [10, 3, 9, 4, 8];
     size = [14, 4, 10, 6, 9];
 
-You can solve the above problem using the ``pymzn.minizinc`` function:::
+You can solve the above problem using the ``pymzn.minizinc`` function::
 
     import pymzn
     pymzn.minizinc('test.mzn', 'test.dzn', data={'capacity': 20})
 
-The result will be:::
+The result will be::
 
-    [{'x': {3, 5}}]
+    SolnStream(solns=[{'x': {3, 5}}], complete=True)
 
-The ``minizinc`` function returns a list of solutions. The default
-behavior is to evaluate the solutions into python objects. Solutions are
-dictionaries containing variable assignments. The returned variables
-are, by default, the 'free' variables, i.e. those that do not depend on
-other variables. If you are interested in the value of other variables
-for each solution you can specify the ``output_vars`` argument:::
+The returned object represent a solution stream, which can be directly
+referenced and iterated as a list. The default behavior is to evaluate the
+solutions into python objects. Solutions are dictionaries containing variable
+assignments. The solution evaluation by PyMzn uses either json (when available)
+or dzn as intermediate format from the solver. More details on how PyMzn works
+internally are available in the `Implementation details <reference/internal>`__
+section).
 
-    pymzn.minizinc('test.mzn', output_vars=['x', 'obj'])
+If you wish to override the default behavior and get a different output format
+you can specify the ``output_mode`` argument. Possible formats are: ``dict``,
+``item``, ``dzn`` and ``json``. The first is the default one. The ``item``
+format will return strings formatted according to the output statement in the
+input model. The ``dzn`` and ``json`` formats return strings formatted in dzn or
+json respectively. The latter two formats are only available if the solver used
+supports them. ::
 
-This will override the default behavior so, if you are still interested
-in the default set of variables, you need to specify them as well.
+    pymzn.minizinc('test.mzn', output_mode='dzn')
 
-The evaluation of the solutions by PyMzn uses an internal output representation
-(actually dzn format) specified as an output statement that overrides the one
-specified in the model if any (though the original output statement in your
-model is left untouched, more details on how PyMzn works internally are
-available in the `Implementation details <reference/internal>`__ section).
-
-If you wish to override the default behavior and get as output strings
-formatted with your original output statement you can use the
-``eval_output=False`` argument:::
-
-    pymzn.minizinc('test.mzn', eval_output=False)
-
-This will disable the automatic parsing, so the ``output_vars`` will be ignored
-if specified.
 
 Data
 ----
 
 It is possible to specify data (.dzn) files to the ``minizinc`` function as
-additional positional arguments:::
+additional positional arguments::
 
     pymzn.minizinc('test.mzn', 'data1.dzn', 'data2.dzn')
 
 It is also possible to specify additional data inline with the ``minizinc``
-function:::
+function::
 
     pymzn.minizinc('test.mzn', 'data1.dzn', 'data2.dzn', data={'n': 10, 'm': [1,3,5]})
 
 With the ``data`` argument you can specify an assignment of variables that will
-be automatically converted to dzn format with the ``pymzn.dzn`` function (more
-details in the `Dzn files <reference/dzn/>`__ section).
+be automatically converted to dzn format with the ``pymzn.dict2dzn`` function
+(more details in the `Dzn files <reference/dzn/>`__ section).
 
 Solver's arguments
 ------------------
 
 Usually, solvers provide arguments that can be used to modify their behavior.
 You can specify arguments to pass to the solver as additional keyword arguments
 in the ``minizinc`` function. For instance, using the argument ``timeout`` for
-Gecode, it will set a time cut-off (in seconds) for the problem solving:::
+Gecode, it will set a time cut-off (in seconds) for the problem solving::
 
     pymzn.minizinc('test.mzn', timeout=30)  # 30 seconds cut-off
 
 Adding the ``parallel`` argument, you can specify how many threads
-should Gecode use for the problem solving:::
+should Gecode use for the problem solving::
 
     pymzn.minizinc('test.mzn', timeout=30, parallel=4)
 

docs/_sources/reference/dzn/generated/pymzn.dzn_value.txt → docs/_sources/reference/dzn/generated/pymzn.dict2dzn.rst.txt

@@ -1,6 +1,6 @@
-pymzn.dzn_value
+pymzn\.dict2dzn
 ===============
 
 .. currentmodule:: pymzn
 
-.. autofunction:: dzn_value
+.. autofunction:: dict2dzn

docs/_sources/reference/dzn/generated/pymzn.dzn2dict.rst.txt

@@ -0,0 +1,6 @@
+pymzn\.dzn2dict
+===============
+
+.. currentmodule:: pymzn
+
+.. autofunction:: dzn2dict

docs/_sources/reference/dzn/generated/pymzn.rebase_array.txt → docs/_sources/reference/dzn/generated/pymzn.rebase_array.rst.txt

@@ -1,5 +1,5 @@
-pymzn.rebase_array
-==================
+pymzn\.rebase\_array
+====================
 
 .. currentmodule:: pymzn
 

docs/_sources/reference/dzn/generated/pymzn.stmt2dzn.rst.txt

@@ -0,0 +1,6 @@
+pymzn\.stmt2dzn
+===============
+
+.. currentmodule:: pymzn
+
+.. autofunction:: stmt2dzn

docs/_sources/reference/dzn/generated/pymzn.dzn_eval.txt → docs/_sources/reference/dzn/generated/pymzn.val2dzn.rst.txt

@@ -1,6 +1,6 @@
-pymzn.dzn_eval
+pymzn\.val2dzn
 ==============
 
 .. currentmodule:: pymzn
 
-.. autofunction:: dzn_eval
+.. autofunction:: val2dzn

docs/_sources/reference/dzn/index.txt → docs/_sources/reference/dzn/index.rst.txt

@@ -6,9 +6,10 @@ Dzn files
 .. autosummary::
    :toctree: generated/
 
-   dzn
-   dzn_value
-   dzn_eval
+   dict2dzn
+   dzn2dict
+   stmt2dzn
+   val2dzn
    rebase_array
 
-.. automodule:: pymzn._dzn
+.. automodule:: pymzn.dzn

docs/_sources/reference/generated/pymzn.config.dump.txt → docs/_sources/reference/generated/pymzn.config.dump.rst.txt

@@ -1,5 +1,5 @@
-pymzn.config.dump
-=================
+pymzn\.config\.dump
+===================
 
 .. currentmodule:: pymzn.config
 

docs/_sources/reference/generated/pymzn.config.get.txt → docs/_sources/reference/generated/pymzn.config.get.rst.txt

@@ -1,5 +1,5 @@
-pymzn.config.get
-================
+pymzn\.config\.get
+==================
 
 .. currentmodule:: pymzn.config
 

docs/_sources/reference/generated/pymzn.config.set.txt → docs/_sources/reference/generated/pymzn.config.set.rst.txt

@@ -1,5 +1,5 @@
-pymzn.config.set
-================
+pymzn\.config\.set
+==================
 
 .. currentmodule:: pymzn.config