Docs improvement

cpmpy/expressions/core.py

@@ -11,7 +11,7 @@
 
     Here is a list of standard python operators and what object (with what expr.name) it creates:
 
-    Comparisons:
+    **Comparisons**:
 
     - x == y        Comparison("==", x, y)
     - x != y        Comparison("!=", x, y)
@@ -20,9 +20,9 @@
     - x > y         Comparison(">", x, y)
     - x >= y        Comparison(">=", x, y)
 
-    Mathematical operators:
+    **Mathematical operators**:
 
-    - -x            Operator("-", [x])
+    - −x            Operator("-", [x])
     - x + y         Operator("sum", [x,y])
     - sum([x,y,z])  Operator("sum", [x,y,z])
     - sum([c0*x, c1*y, c2*z])  Operator("wsum", [[c0,c1,c2],[x,y,z]])
@@ -32,7 +32,7 @@
     - x % y         Operator("mod", [x,y])
     - x ** y        Operator("pow", [x,y])
 
-    Logical operators:
+    **Logical operators**:
 
     - x & y         Operator("and", [x,y])
     - x | y         Operator("or", [x,y])
@@ -47,14 +47,16 @@
 
     Apart from operator overloading, expressions implement two important functions:
 
-    - `is_bool()`   which returns whether the __return type__ of the expression is Boolean.
-                    If it does, the expression can be used as top-level constraint
-                    or in logical operators.
+    - `is_bool()`   
+        which returns whether the return type of the expression is Boolean.
+        If it does, the expression can be used as top-level constraint
+        or in logical operators.
 
-    - `value()`     computes the value of this expression, by calling .value() on its
-                    subexpressions and doing the appropriate computation
-                    this is used to conveniently print variable values, objective values
-                    and any other expression value (e.g. during debugging).
+    - `value()`     
+        computes the value of this expression, by calling .value() on its
+        subexpressions and doing the appropriate computation
+        this is used to conveniently print variable values, objective values
+        and any other expression value (e.g. during debugging).
 
     ===============
     List of classes

cpmpy/expressions/globalfunctions.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python
-# -*- coding:utf-8 -*-
+#-*- coding:utf-8 -*-
 ##
 ## globalfunctions.py
 ##
 """
+    Global functions conveniently express numerical global constraints.
 
     Using global functions
     ------------------------

cpmpy/expressions/utils.py

@@ -12,14 +12,21 @@
     .. autosummary::
         :nosignatures:
 
+        is_bool
         is_int
         is_num
+        is_false_cst
+        is_true_cst
+        is_boolexpr
         is_pure_list
         is_any_list
+        is_transition
         flatlist
         all_pairs
         argval
+        argvals
         eval_comparison
+        get_bounds     
 """
 
 import numpy as np

cpmpy/expressions/variables.py

@@ -24,9 +24,18 @@
 
     Boolean and Integer decision variables are the key elements of a CP model.
 
-    All variables in CPMpy are n-dimensional array objects and have defined dimensions. Following the numpy library, the dimension sizes of an n-dimenionsal array is called its __shape__. In CPMpy all variables are considered an array with a given shape. For 'single' variables the shape is '1'. For an array of length `n` the shape is 'n'. An `n*m` matrix has shape (n,m), and tensors with more than 2 dimensions are all supported too. For the implementation of this, CPMpy builts on numpy's n-dimensional ndarray and inherits many of its benefits (vectorized operators and advanced indexing).
+    All variables in CPMpy are n-dimensional array objects and have defined dimensions. 
+    Following the numpy library, the dimension sizes of an n-dimenionsal array is called its __shape__. 
+    In CPMpy all variables are considered an array with a given shape. For 'single' variables the shape 
+    is '1'. For an array of length `n` the shape is 'n'. An `n*m` matrix has shape (n,m), and tensors 
+    with more than 2 dimensions are all supported too. For the implementation of this, 
+    CPMpy builts on numpy's n-dimensional ndarray and inherits many of its benefits 
+    (vectorized operators and advanced indexing).
 
-    This module contains the cornerstone `boolvar()` and `intvar()` functions, which create (numpy arrays of) variables. There is also a helper function `cpm_array` for wrapping standard numpy arrays so they can be indexed by a variable. Apart from these 3 functions, none of the classes in this module should be directly created; they are created by these 3 helper functions.
+    This module contains the cornerstone `boolvar()` and `intvar()` functions, which create (numpy arrays of) 
+    variables. There is also a helper function `cpm_array()` for wrapping standard numpy arrays so they can be 
+    indexed by a variable. Apart from these 3 functions, none of the classes in this module should be directly 
+    instantiated; they are created by these 3 helper functions.
 
 
     ===============
@@ -135,7 +144,7 @@ def IntVar(lb, ub, shape=1, name=None):
 
 def intvar(lb, ub, shape=1, name=None):
     """
-    Integer decision variables are constructed by specifying the lowest (lb)
+    Integer decision variables are constructed by specifying the lowest (lb) value
     the decision variable can take, as well as the highest value (ub).
 
     Arguments:

cpmpy/model.py

@@ -15,9 +15,9 @@
 
     See the examples for basic usage, which involves:
 
-    - creation, e.g. m = Model(cons, minimize=obj)
-    - solving, e.g. m.solve()
-    - optionally, checking status/runtime, e.g. m.status()
+    - creation, e.g. `m = Model(cons, minimize=obj)` 
+    - solving, e.g. `m.solve()` 
+    - optionally, checking status/runtime, e.g. `m.status()` 
 
     ===============
     List of classes

cpmpy/solvers/__init__.py

@@ -2,8 +2,8 @@
     CPMpy interfaces to (the Python API interface of) solvers
 
     Solvers typically use some of the generic transformations in
-    `transformations` as well as specific reformulations to map the
-    CPMpy expression to the solver's Python API
+    :mod:`cpmpy.transformations` as well as specific reformulations to map the
+    CPMpy expression to the solver's Python API.
 
     ==================
     List of submodules

cpmpy/solvers/choco.py

@@ -1,10 +1,15 @@
 #!/usr/bin/env python
+#-*- coding:utf-8 -*-
+##
 ## choco.py
 ##
 """
     Interface to Choco solver's Python API
 
-    ...
+    Requires that the 'pychoco' python package is installed:
+
+        $ pip install pychoco
+
 
     Documentation of the solver's own Python API:
     https://pypi.org/project/pychoco/
@@ -18,6 +23,10 @@
         :nosignatures:
 
         CPM_choco
+
+    ==============
+    Module details
+    ==============
 """
 import time
 

cpmpy/solvers/exact.py

@@ -6,8 +6,11 @@
 """
     Interface to Exact
 
-    Exact solves decision and optimization problems formulated as integer linear programs. Under the hood, it converts integer variables to binary (0-1) variables and applies highly efficient propagation routines and strong cutting-planes / pseudo-Boolean conflict analysis.
+    Exact solves decision and optimization problems formulated as integer linear programs. 
+    Under the hood, it converts integer variables to binary (0-1) variables and applies highly efficient 
+    propagation routines and strong cutting-planes / pseudo-Boolean conflict analysis.
 
+    The solver's git repository:
     https://gitlab.com/JoD/exact
 
     ===============
@@ -18,6 +21,10 @@
         :nosignatures:
 
         CPM_exact
+
+    ==============
+    Module details
+    ==============
 """
 import sys  # for stdout checking
 import time
@@ -84,7 +91,7 @@ def __init__(self, cpm_model=None, subsolver=None):
 
         Arguments:
         - cpm_model: Model(), a CPMpy Model() (optional)
-        - subsolver: None
+        - subsolver: None, not used
         """
         if not self.supported():
             raise Exception("Install 'exact' as a Python package to use this solver interface")

cpmpy/solvers/gurobi.py

@@ -1,17 +1,22 @@
 #!/usr/bin/env python
+#-*- coding:utf-8 -*-
+##
+## gurobi.py
+##
 """
     Interface to the python 'gurobi' package
 
     Requires that the 'gurobipy' python package is installed:
 
         $ pip install gurobipy
 
-    as well as the Gurobi bundled binary packages, downloadable from:
-    https://www.gurobi.com/
 
     In contrast to other solvers in this package, Gurobi is not free to use and requires an active licence
     You can read more about available licences at https://www.gurobi.com/downloads/
 
+    Documentation of the solver's own Python API:
+    https://www.gurobi.com/documentation/current/refman/py_python_api_details.html
+
     ===============
     List of classes
     ===============
@@ -83,6 +88,7 @@ def __init__(self, cpm_model=None, subsolver=None):
 
         Arguments:
         - cpm_model: a CPMpy Model()
+        - subsolver: None, not used
         """
         if not self.supported():
             raise Exception(

cpmpy/solvers/minizinc.py

@@ -1,8 +1,18 @@
 #!/usr/bin/env python
+#-*- coding:utf-8 -*-
+##
+## minizinc.py
+##
 """
     Interface to MiniZinc's Python API
 
-    CPMpy can translate CPMpy models to the (text-based) MiniZinc language.
+    Requires that the 'minizinc' python package is installed:
+
+        $ pip install minizinc
+
+    as well as the Minizinc bundled binary packages, downloadable from:
+    https://github.com/MiniZinc/MiniZincIDE/releases
+
 
     MiniZinc is a free and open-source constraint modeling language.
     MiniZinc is used to model constraint satisfaction and optimization problems in
@@ -14,6 +24,8 @@
     Documentation of the solver's own Python API:
     https://minizinc-python.readthedocs.io/
 
+    CPMpy can translate CPMpy models to the (text-based) MiniZinc language.
+
     ===============
     List of classes
     ===============
@@ -22,6 +34,10 @@
         :nosignatures:
 
         CPM_minizinc
+
+    ==============
+    Module details
+    ==============
 """
 import re
 import warnings
@@ -674,7 +690,7 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
                 - time_limit: stop after this many seconds (default: None)
                 - solution_limit: stop after this many solutions (default: None)
                 - call_from_model: whether the method is called from a CPMpy Model instance or not
-                - any other keyword argument
+                - kwargs:      any keyword argument, sets parameters of solver object, overwrites construction-time kwargs
 
             Returns: number of solutions found
         """

cpmpy/solvers/ortools.py

@@ -4,7 +4,12 @@
 ## ortools.py
 ##
 """
-    Interface to ortools' CP-SAT Python API
+    Interface to OR-Tools' CP-SAT Python API. 
+
+    The 'ortools' python package is bundled by default with CPMpy.
+    It can be installed through `pip`:
+
+        $ pip install ortools
 
     Google OR-Tools is open source software for combinatorial optimization, which seeks
     to find the best solution to a problem out of a very large set of possible solutions.
@@ -22,6 +27,10 @@
         :nosignatures:
 
         CPM_ortools
+
+    ==============
+    Module details
+    ==============
 """
 import sys  # for stdout checking
 import numpy as np
@@ -42,7 +51,7 @@
 
 class CPM_ortools(SolverInterface):
     """
-    Interface to the python 'ortools' CP-SAT API
+    Interface to the Python 'ortools' CP-SAT API
 
     Requires that the 'ortools' python package is installed:
     $ pip install ortools
@@ -79,7 +88,7 @@ def __init__(self, cpm_model=None, subsolver=None):
 
         Arguments:
         - cpm_model: Model(), a CPMpy Model() (optional)
-        - subsolver: None
+        - subsolver: None, not used
         """
         if not self.supported():
             raise Exception("Install the python 'ortools' package to use this solver interface")

cpmpy/solvers/pysat.py

@@ -6,6 +6,10 @@
 """
     Interface to PySAT's API
 
+    Requires that the 'python-sat' python package is installed:
+
+        $ pip install python-sat[aiger,approxmc,cryptosat,pblib]
+
     PySAT is a Python (2.7, 3.4+) toolkit, which aims at providing a simple and unified
     interface to a number of state-of-art Boolean satisfiability (SAT) solvers as well as
     to a variety of cardinality and pseudo-Boolean encodings.
@@ -28,6 +32,10 @@
         :nosignatures:
 
         CPM_pysat
+
+    ==============
+    Module details
+    ==============
 """
 from .solver_interface import SolverInterface, SolverStatus, ExitStatus
 from ..exceptions import NotSupportedError

cpmpy/solvers/pysdd.py

@@ -1,6 +1,15 @@
+#!/usr/bin/env python
+#-*- coding:utf-8 -*-
+##
+## pysdd.py
+##
 """
     Interface to PySDD's API
 
+    Requires that the 'PySDD' python package is installed:
+
+        $ pip install PySDD
+
     PySDD is a knowledge compilation package for Sentential Decision Diagrams (SDD)
     https://pysdd.readthedocs.io/en/latest/
 
@@ -19,6 +28,10 @@
         :nosignatures:
 
         CPM_pysdd
+
+    ==============
+    Module details
+    ==============
 """
 from functools import reduce
 from .solver_interface import SolverInterface, SolverStatus, ExitStatus

cpmpy/solvers/utils.py

@@ -6,9 +6,6 @@
 """
     Utilities for handling solvers
 
-    Contains a static variable `builtin_solvers` that lists
-    CPMpy solvers (first one is the default solver by default)
-
     =================
     List of functions
     =================
@@ -36,9 +33,10 @@ def param_combinations(all_params, remaining_keys=None, cur_params=None):
         Recursively yield all combinations of param values
 
         For example usage, see `examples/advanced/hyperparameter_search.py`
+        https://github.com/CPMpy/cpmpy/blob/master/examples/advanced/hyperparameter_search.py
 
         - all_params is a dict of {key: list} items, e.g.:
-            {'val': [1,2], 'opt': [True,False]}
+          {'val': [1,2], 'opt': [True,False]}
 
         - output is an generator over all {key:value} combinations
           of the keys and values. For the example above: