From 659f18a5b6935176a2d8391407d2c44eb11ff8e8 Mon Sep 17 00:00:00 2001
From: Ignace Bleukx <ignace.bleukx@kuleuven.be>
Date: Wed, 16 Apr 2025 11:48:51 +0200
Subject: [PATCH 01/39] Parameters to exact (#616)

* add proper warnings for setting parameters at solve time

* add test for checking if user-warning is raised

* add optional init kwargs in SolverLookup

* update warning

* update tests

* remove extra spaces
---
 cpmpy/solvers/exact.py |  7 ++++---
 cpmpy/solvers/utils.py |  8 ++++++--
 tests/test_solvers.py  | 24 ++++++++++++++++++++++++
 3 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/cpmpy/solvers/exact.py b/cpmpy/solvers/exact.py
index 1d860f063..ba3eda98d 100644
--- a/cpmpy/solvers/exact.py
+++ b/cpmpy/solvers/exact.py
@@ -112,7 +112,6 @@ def __init__(self, cpm_model=None, subsolver=None, **kwargs):
         assert subsolver is None, "Exact does not allow subsolvers."
 
         from exact import Exact as xct
-
         # initialise the native solver object
         options = list(kwargs.items()) # options is a list of string-pairs, e.g. [("verbosity","1")]
         options = [(opt[0], str(opt[1])) for opt in options] # Ensure values are also strings
@@ -167,10 +166,12 @@ def solve(self, time_limit=None, assumptions=None, **kwargs):
                 - False     if no solution is found
         """
         from exact import Exact as xct
-
+ 
         # set additional keyword arguments
         if(len(kwargs.items())>0):
-            warnings.warn(f"Exact only supports options at initialization: {kwargs.items()}")
+            wrn_txt = f"Exact only supports options at initialization. Ignoring additional options {kwargs.items()}\n"
+            wrn_txt += "Use cp.SolverLookup.lookup('exact', **{parameter-with-hyphen: 42}) to set Exact parameters"
+            warnings.warn(wrn_txt)
 
         # ensure all vars are known to solver
         self.solver_vars(list(self.user_vars))
diff --git a/cpmpy/solvers/utils.py b/cpmpy/solvers/utils.py
index 705744a39..45c35c9f0 100644
--- a/cpmpy/solvers/utils.py
+++ b/cpmpy/solvers/utils.py
@@ -94,11 +94,15 @@ def solvernames(cls):
         return names
 
     @classmethod
-    def get(cls, name=None, model=None):
+    def get(cls, name=None, model=None, **init_kwargs):
         """
             get a specific solver (by name), with 'model' passed to its constructor
 
             This is the preferred way to initialise a solver from its name
+
+            :param name: name of the solver to use
+            :param model: model to pass to the solver constructor
+            :param init_kwargs: additional keyword arguments to pass to the solver constructor
         """
         solver_cls = cls.lookup(name=name)
 
@@ -106,7 +110,7 @@ def get(cls, name=None, model=None):
         subname = None
         if name is not None and ':' in name:
             _,subname = name.split(':',maxsplit=1)
-        return solver_cls(model, subsolver=subname)
+        return solver_cls(model, subsolver=subname, **init_kwargs)
 
     @classmethod
     def lookup(cls, name=None):
diff --git a/tests/test_solvers.py b/tests/test_solvers.py
index 06824ca18..d23df6bc7 100644
--- a/tests/test_solvers.py
+++ b/tests/test_solvers.py
@@ -1,4 +1,5 @@
 import unittest
+import tempfile
 import pytest
 import numpy as np
 import cpmpy as cp
@@ -489,6 +490,29 @@ def _trixor_callback():
         s = cp.SolverLookup.get("exact", m)
         self.assertEqual(s.solveAll(display=_trixor_callback),7)
 
+    @pytest.mark.skipif(not CPM_exact.supported(), 
+                        reason="Exact not installed")
+    def test_parameters_to_exact(self):
+    
+        # php with 5 pigeons, 4 holes
+        p,h = 40,39
+        x = cp.boolvar(shape=(p,h))
+        m = cp.Model(x.sum(axis=1) >= 1, x.sum(axis=0) <= 1)
+
+        # this should raise a warning
+        with self.assertWarns(UserWarning):
+            self.assertFalse(m.solve(solver="exact", verbosity=10))
+        
+        # can we indeed set a parameter? Try with prooflogging
+        proof_file = tempfile.NamedTemporaryFile(delete=False).name
+        
+        # taken from https://gitlab.com/nonfiction-software/exact/-/blob/main/python_examples/proof_logging.py
+        options = {"proof-log": proof_file, "proof-assumptions":"0"}
+        exact = cp.SolverLookup.get("exact",m, **options)
+        self.assertFalse(exact.solve())
+
+        with open(proof_file+".proof", "r") as f:
+            self.assertEquals(f.readline()[:-1], "pseudo-Boolean proof version 1.1") # check header of proof-file
 
     @pytest.mark.skipif(not CPM_choco.supported(),
                         reason="pychoco not installed")

From db3999e2d4e453996c78b3ec18c1a44af0422b28 Mon Sep 17 00:00:00 2001
From: Henk Bierlee <bierlee.henk@gmail.com>
Date: Wed, 16 Apr 2025 12:54:20 +0000
Subject: [PATCH 02/39] Discussing whether we support constants for Element
 decomposition (#630)

* Support constants for Element decomposition

* Add more general approach to handling constant Element indices

* Prevent OR-Tools error by converting integer to constant intvar

* Decompose only intersection between idx and array bounds

* Use better get_bounds for non-expressions

* Fix decomposition (off-by-one + process comments)

* Improve implies typing

* Refactor test

* Fix utils.implies

* Use is_[true,false]_cst

* Linting

* Simplify fixed integer case Element for OT-Tools

* Refactor Element decomp using loop
---
 cpmpy/expressions/globalfunctions.py | 16 ++++++++++++----
 cpmpy/expressions/utils.py           | 11 +++++++++++
 cpmpy/solvers/ortools.py             | 16 +++++++++++-----
 tests/test_constraints.py            |  1 +
 tests/test_globalconstraints.py      | 22 ++++++++++++++++++++++
 5 files changed, 57 insertions(+), 9 deletions(-)

diff --git a/cpmpy/expressions/globalfunctions.py b/cpmpy/expressions/globalfunctions.py
index 86925a108..d85629163 100644
--- a/cpmpy/expressions/globalfunctions.py
+++ b/cpmpy/expressions/globalfunctions.py
@@ -69,9 +69,9 @@ def decompose_comparison(self):
 import cpmpy as cp
 
 from ..exceptions import CPMpyException, IncompleteFunctionError, TypeError
-from .core import Expression, Operator, Comparison
+from .core import Expression, Operator
 from .variables import boolvar, intvar, cpm_array
-from .utils import flatlist, argval, is_num, eval_comparison, is_any_list, is_boolexpr, get_bounds, argvals
+from .utils import flatlist, argval, is_num, eval_comparison, is_any_list, is_boolexpr, get_bounds, argvals, get_bounds, implies
 
 
 class GlobalFunction(Expression):
@@ -238,6 +238,7 @@ def element(arg_list):
     warnings.warn("Deprecated, use Element(arr,idx) instead, will be removed in stable version", DeprecationWarning)
     assert (len(arg_list) == 2), "Element expression takes 2 arguments: Arr, Idx"
     return Element(arg_list[0], arg_list[1])
+
 class Element(GlobalFunction):
     """
         The 'Element' global constraint enforces that the result equals Arr[Idx]
@@ -286,8 +287,15 @@ def decompose_comparison(self, cpm_op, cpm_rhs):
 
         """
         arr, idx = self.args
-        return [(idx == i).implies(eval_comparison(cpm_op, arr[i], cpm_rhs)) for i in range(len(arr))] + \
-               [idx >= 0, idx < len(arr)], []
+        # Find where the array indices and the bounds of `idx` intersect
+        lb, ub = get_bounds(idx)
+        new_lb, new_ub = max(lb, 0), min(ub, len(arr) - 1)
+        cons=[]
+        # For every `i` in that intersection, post `(idx = i) -> idx=i -> arr[i] <CMP_OP> cpm_rhs`.
+        for i in range(new_lb, new_ub+1):
+            cons.append(implies(idx == i, eval_comparison(cpm_op, arr[i], cpm_rhs)))
+        cons+=[idx >= new_lb, idx <= new_ub]  # also enforce the new bounds 
+        return cons, []  # no auxiliary variables
 
     def __repr__(self):
         return "{}[{}]".format(self.args[0], self.args[1])
diff --git a/cpmpy/expressions/utils.py b/cpmpy/expressions/utils.py
index 8cfda1b06..b511a83b8 100644
--- a/cpmpy/expressions/utils.py
+++ b/cpmpy/expressions/utils.py
@@ -194,6 +194,17 @@ def get_bounds(expr):
             return int(expr), int(expr)
         return math.floor(expr), math.ceil(expr)
 
+def implies(expr, other):
+    """ like :func:`~cpmpy.expressions.core.Expression.implies`, but also safe to use for non-expressions """
+    if isinstance(expr, cp.expressions.core.Expression):
+        return expr.implies(other)
+    elif is_true_cst(expr):
+        return other
+    elif is_false_cst(expr):
+        return BoolVal(True)
+    else:
+        return expr.implies(other)
+
 # Specific stuff for ShortTabel global (should this be in globalconstraints.py instead?)
 STAR = "*" # define constant here
 def is_star(arg):
diff --git a/cpmpy/solvers/ortools.py b/cpmpy/solvers/ortools.py
index ef144320c..8cc6bef60 100644
--- a/cpmpy/solvers/ortools.py
+++ b/cpmpy/solvers/ortools.py
@@ -41,9 +41,9 @@
 from ..exceptions import NotSupportedError
 from ..expressions.core import Expression, Comparison, Operator, BoolVal
 from ..expressions.globalconstraints import DirectConstraint
-from ..expressions.variables import _NumVarImpl, _IntVarImpl, _BoolVarImpl, NegBoolView, boolvar
+from ..expressions.variables import _NumVarImpl, _IntVarImpl, _BoolVarImpl, NegBoolView, boolvar, intvar
 from ..expressions.globalconstraints import GlobalConstraint
-from ..expressions.utils import is_num, eval_comparison, flatlist, argval, argvals, get_bounds
+from ..expressions.utils import is_num, is_int, eval_comparison, flatlist, argval, argvals, get_bounds
 from ..transformations.decompose_global import decompose_in_tree
 from ..transformations.get_variables import get_variables
 from ..transformations.flatten_model import flatten_constraint, flatten_objective, get_or_make_var
@@ -480,9 +480,15 @@ def _post_constraint(self, cpm_expr, reifiable=False):
                 elif lhs.name == 'div':
                     return self.ort_model.AddDivisionEquality(ortrhs, *self.solver_vars(lhs.args))
                 elif lhs.name == 'element':
-                    # arr[idx]==rvar (arr=arg0,idx=arg1), ort: (idx,arr,target)
-                    return self.ort_model.AddElement(self.solver_var(lhs.args[1]),
-                                                     self.solver_vars(lhs.args[0]), ortrhs)
+                    arr, idx = lhs.args
+                    if is_int(idx): # OR-Tools does not handle all constant integer cases
+                        idx = intvar(idx,idx)
+                    # OR-Tools has slight different in argument order
+                    return self.ort_model.AddElement(
+                        self.solver_var(idx),
+                        self.solver_vars(arr),
+                        ortrhs
+                    )
                 elif lhs.name == 'mod':
                     # catch tricky-to-find ortools limitation
                     x,y = lhs.args
diff --git a/tests/test_constraints.py b/tests/test_constraints.py
index 60383da66..ef3684591 100644
--- a/tests/test_constraints.py
+++ b/tests/test_constraints.py
@@ -4,6 +4,7 @@
 from cpmpy import Model, SolverLookup, BoolVal
 from cpmpy.expressions.globalconstraints import *
 from cpmpy.expressions.globalfunctions import *
+from cpmpy.expressions.core import Comparison
 
 import pytest
 
diff --git a/tests/test_globalconstraints.py b/tests/test_globalconstraints.py
index 16168ae3f..aaf4efa49 100644
--- a/tests/test_globalconstraints.py
+++ b/tests/test_globalconstraints.py
@@ -1325,3 +1325,25 @@ def test_table(self):
         self.assertRaises(TypeError, cp.Table, [iv[0], iv[1], iv[2], 5], [(5, 2, 2)])
         self.assertRaises(TypeError, cp.Table, [iv[0], iv[1], iv[2], [5]], [(5, 2, 2)])
         self.assertRaises(TypeError, cp.Table, [iv[0], iv[1], iv[2], ['a']], [(5, 2, 2)])
+
+    def test_issue627(self):
+        for s, cls in cp.SolverLookup.base_solvers():
+            if cls.supported():
+                try:
+                    # constant look-up
+                    self.assertTrue(cp.Model([cp.boolvar() == cp.Element([0], 0)]).solve(solver=s))
+                    # constant out-of-bounds look-up
+                    self.assertFalse(cp.Model([cp.boolvar() == cp.Element([0], 1)]).solve(solver=s))
+                except (NotImplementedError, NotSupportedError):
+                    pass
+
+    def test_element_index_dom_mismatched(self):
+        """
+            Check transform of `[0,1,2][x in -1..1] == y in 1..5`
+            Note the index variable has a lower bound *outside* the indexable range, and an upper bound inside AND lower than the indexable range upper bound
+        """
+        constraint=cp.Element([0,1,2], cp.intvar(-1,1, name="x"))
+        self.assertEqual(
+            str(constraint.decompose_comparison("==", cp.intvar(1,5, name="y"))),
+            "([(x == 0) -> (y == 0), (x == 1) -> (y == 1), x >= 0, x <= 1], [])"
+        )

From 357059f3d6468b08b3eabeabf40c0dde1864bebb Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Wed, 16 Apr 2025 15:09:19 +0200
Subject: [PATCH 03/39] Missing user vars for solveAll (#609)

* z3 collect user vars

* minizinc post user vars

* Add unit test

* Exclude test for pysat and pysdd

---
Co-authored-by: Tias Guns <tias@ulyssis.org>
---
 cpmpy/solvers/minizinc.py |  4 ++++
 cpmpy/solvers/z3.py       |  3 +++
 tests/test_solvers.py     | 16 ++++++++++++++++
 3 files changed, 23 insertions(+)

diff --git a/cpmpy/solvers/minizinc.py b/cpmpy/solvers/minizinc.py
index 7fb2737c0..9f67b368b 100644
--- a/cpmpy/solvers/minizinc.py
+++ b/cpmpy/solvers/minizinc.py
@@ -350,6 +350,10 @@ def mzn_time_to_seconds(self, time):
 
     async def _solveAll(self, display=None, time_limit=None, solution_limit=None, **kwargs):
         """ Special 'async' function because mzn.solutions() is async """
+
+        # ensure all vars are known to solver
+        self.solver_vars(list(self.user_vars))
+        
         # make mzn_inst
         (kwargs, mzn_inst) = self._pre_solve(time_limit=time_limit, **kwargs)
         kwargs['all_solutions'] = True
diff --git a/cpmpy/solvers/z3.py b/cpmpy/solvers/z3.py
index e62a34c35..4613918ae 100644
--- a/cpmpy/solvers/z3.py
+++ b/cpmpy/solvers/z3.py
@@ -35,6 +35,7 @@
     Module details
     ==============
 """
+from cpmpy.transformations.get_variables import get_variables
 from .solver_interface import SolverInterface, SolverStatus, ExitStatus
 from ..exceptions import NotSupportedError
 from ..expressions.core import Expression, Comparison, Operator, BoolVal
@@ -317,6 +318,8 @@ def __add__(self, cpm_expr):
         :return: self
         """
         # all variables are user variables, handled in `solver_var()`
+        # unless their constraint gets simplified away, so lets collect them anyway
+        get_variables(cpm_expr, collect=self.user_vars)
 
         # transform and post the constraints
         for cpm_con in self.transform(cpm_expr):
diff --git a/tests/test_solvers.py b/tests/test_solvers.py
index d23df6bc7..2705df7d1 100644
--- a/tests/test_solvers.py
+++ b/tests/test_solvers.py
@@ -828,3 +828,19 @@ def test_partial_div_mod(self, solver):
             assert dv * yv + rv == xv
             assert (Operator('div', [xv, yv])).value() == dv
             assert (Operator('mod', [xv, yv])).value() == rv
+
+    def test_hidden_user_vars(self, solver):
+        """
+        Tests whether decision variables which are part of a constraint that never gets posted to the underlying solver
+        still get correctly captured and posted.
+        """
+        if solver == 'pysdd' or solver == 'pysat':  # pysat and pysdd don't support integer decision variables
+            return
+        
+        x = cp.intvar(1, 4, shape=1)
+        # Dubious constraint which enforces nothing, gets decomposed to empty list
+        # -> resulting CP model is empty
+        m = cp.Model([cp.AllDifferentExceptN([x], 1)])
+        s = cp.SolverLookup().get(solver, m)
+        assert len(s.user_vars) == 1 # check if var captured as a user_var
+        assert s.solveAll() == 4     # check if still correct number of solutions, even though empty model

From e56b66d45cb670d33d5480eeaf1b47ca12903285 Mon Sep 17 00:00:00 2001
From: Tias Guns <tias@ulyssis.org>
Date: Wed, 16 Apr 2025 15:18:38 +0200
Subject: [PATCH 04/39] Rework (start of) docs of solvers API (#633)

* rework (start of) docs of solvers, based on readthedocs rendering/flow

* gurobi: missing line

* Fix section title

underline must be at least as long, otherwise links are broken

* Wrong solver name

* Small changes

typos, rst syntax, consistent wording, ...

* Add example codeblock to solver interface

* exact summary wording streamline

* add pysat direct instructions again for uniformity at this point

* remove poorly explained capabilities from solver docs for now

---------

Co-authored-by: Thomas Sergeys <thomas.s2000@hotmail.com>
---
 cpmpy/solvers/TEMPLATE.py             | 78 ++++++++++++++++-----------
 cpmpy/solvers/__init__.py             | 51 ++++++++++++------
 cpmpy/solvers/choco.py                | 31 ++++++-----
 cpmpy/solvers/cpo.py                  | 56 ++++++++++---------
 cpmpy/solvers/exact.py                | 36 ++++++++-----
 cpmpy/solvers/gcs.py                  | 52 ++++++++++--------
 cpmpy/solvers/gurobi.py               | 30 ++++++-----
 cpmpy/solvers/minizinc.py             | 58 ++++++++++----------
 cpmpy/solvers/ortools.py              | 34 +++++++-----
 cpmpy/solvers/pysat.py                | 50 +++++++++--------
 cpmpy/solvers/pysdd.py                | 35 ++++++------
 cpmpy/solvers/z3.py                   | 42 +++++++++------
 docs/api/solvers/choco.rst            |  2 +-
 docs/api/solvers/solver_interface.rst |  2 +-
 14 files changed, 330 insertions(+), 227 deletions(-)

diff --git a/cpmpy/solvers/TEMPLATE.py b/cpmpy/solvers/TEMPLATE.py
index 0b39b92a0..7dddd6bf9 100644
--- a/cpmpy/solvers/TEMPLATE.py
+++ b/cpmpy/solvers/TEMPLATE.py
@@ -1,16 +1,51 @@
 #!/usr/bin/env python
+#-*- coding:utf-8 -*-
+##
+## TEMPLATE.py
+##
 """
-    Template file for a new solver interface
+    Interface to TEMPLATE's API
+
+    .. note::
+        [GUIDELINE] Replace <TEMPLATE> by the solver's name, and implement the missing pieces
+        The functions are ordered in a way that could be convenient to 
+        start from the top and continue in that order.
+
+    .. note::
+        After you are done filling in the template, remove all comments starting with [GUIDELINE]
+
+    .. warning::
+        [GUIDELINE] do not include the python package at the top of the file,
+        as CPMpy should also work without this solver installed.
+        To ensure that, include it inside supported() and other functions that need it...
+
+    <some information on the solver>
+
+    Always use :func:`cp.SolverLookup.get("TEMPLATE") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
+
+    Requires that the 'TEMPLATEpy' python package is installed:
+
+    .. code-block:: console
+    
+        $ pip install TEMPLATEpy
+
+    See detailed installation instructions at:
+    <URL to detailed solver installation instructions, if any>
+
+    The rest of this documentation is for advanced users.
 
-    Replace <TEMPLATE> by the solver's name, and implement the missing pieces
-    The functions are ordered in a way that could be convenient to 
-    start from the top and continue in that order
+    ===============
+    List of classes
+    ===============
 
-    After you are done filling in the template, remove all comments starting with [GUIDELINE]
+    .. autosummary::
+        :nosignatures:
 
-    WARNING: do not include the python package at the top of the file,
-    as CPMpy should also work without this solver installed.
-    To ensure that, include it inside supported() and other functions that need it...
+        CPM_template
 """
 
 import warnings
@@ -28,36 +63,15 @@
 from ..transformations.comparison import only_numexpr_equality
 from ..transformations.reification import reify_rewrite, only_bv_reifies
 
-"""
-    Interface to TEMPLATE's API
-
-    <some information on the solver>
-
-    Documentation of the solver's own Python API:
-    <URL to docs or source code>
-
-    ===============
-    List of classes
-    ===============
-
-    .. autosummary::
-        :nosignatures:
-
-        CPM_template
-"""
-
 class CPM_template(SolverInterface):
     """
     Interface to TEMPLATE's API
 
-    Requires that the 'TEMPLATEpy' python package is installed:
-    $ pip install TEMPLATEpy
-
-    See detailed installation instructions at:
-    <URL to detailed solver installation instructions, if any>
-
     Creates the following attributes (see parent constructor for more):
     - tpl_model: object, TEMPLATE's model object
+
+    Documentation of the solver's own Python API:
+    <URL to docs or source code>
     """
 
     @staticmethod
diff --git a/cpmpy/solvers/__init__.py b/cpmpy/solvers/__init__.py
index acdd9c13f..509bbff76 100644
--- a/cpmpy/solvers/__init__.py
+++ b/cpmpy/solvers/__init__.py
@@ -1,18 +1,26 @@
 """
-    CPMpy interfaces to (the Python API interface of) solvers
+    Solver interfaces have the same API as :class:`Model <cpmpy.model.Model>`.
+    However some solvers are **incremental**, meaning that after solving a problem, you can add constraints or change
+    the objective, and the next solve will reuse as much information from the previous solve as possible.
+    Some clause learning solvers also support solving with **assumptions**, meaning you can solve the same problem with
+    different assumption variables toggled on/off, and the solver will reuse information from the previous solves.
 
-    Solvers typically use some of the generic transformations in
-    :mod:`cpmpy.transformations` as well as specific reformulations to map the
-    CPMpy expression to the solver's Python API.
+    See :ref:`supported-solvers` for the list of solvers and their capabilities.
 
-    =========================
-    List of helper submodules
-    =========================
-    .. autosummary::
-        :nosignatures:
+    To benefit from incrementality, you have to instantiate the solver object and reuse it, rather than working on a Model object.
+    Solvers must be instantiated throught the static :class:`cp.SolverLookup <cpmpy.solvers.utils.SolverLookup>` class:
+
+    - :meth:`cp.SolverLookup.solvernames() <cpmpy.solvers.utils.SolverLookup.solvernames>` -- List all installed solvers (including subsolvers).
+    - :meth:`cp.SolverLookup.get(solvername, model=None) <cpmpy.solvers.utils.SolverLookup.get>` -- Initialize a specific solver.
+
+    For example creating a CPMpy solver object for OR-Tools:
+
+    .. code-block:: python
+
+        import cpmpy as cp
+        s = cp.SolverLookup.get("ortools")
+        # can now use solver object 's' over and over again 
 
-        solver_interface
-        utils
 
     =========================
     List of solver submodules
@@ -21,15 +29,24 @@
         :nosignatures:
 
         ortools
-        minizinc
-        pysat
-        gurobi
-        pysdd
-        z3
-        exact
         choco
         gcs
+        minizinc
         cpo
+        gurobi
+        exact
+        z3
+        pysat
+        pysdd
+
+    =========================
+    List of helper submodules
+    =========================
+    .. autosummary::
+        :nosignatures:
+
+        solver_interface
+        utils
 
     =================
     List of functions
diff --git a/cpmpy/solvers/choco.py b/cpmpy/solvers/choco.py
index e23a5a9c6..625931251 100644
--- a/cpmpy/solvers/choco.py
+++ b/cpmpy/solvers/choco.py
@@ -4,7 +4,16 @@
 ## choco.py
 ##
 """
-    Interface to Choco solver's Python API
+    Interface to Choco solver's Python API.
+
+    Choco-solver is an open-source Java library for Constraint Programming (see https://choco-solver.org/).
+    It comes with many features such as various types of variables, various state-of-the-art constraints, various search strategies, etc.
+
+    Always use :func:`cp.SolverLookup.get("choco") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
 
     Requires that the 'pychoco' python package is installed:
 
@@ -12,12 +21,13 @@
 
         $ pip install pychoco
 
-
-    Documentation of the solver's own Python API:
+    Detailed installation instructions available at:
     
     - https://pypi.org/project/pychoco/
     - https://pychoco.readthedocs.io/en/latest/
 
+    The rest of this documentation is for advanced users.
+
     ===============
     List of classes
     ===============
@@ -60,19 +70,16 @@ class CPM_choco(SolverInterface):
     """
     Interface to the Choco solver python API
 
-    Requires that the 'pychoco' python package is installed:
-    $ pip install pychoco
-
-    See detailed installation instructions at:
-    
-    - https://pypi.org/project/pychoco/
-    - https://pychoco.readthedocs.io/en/latest/
-
     Creates the following attributes (see parent constructor for more):
     
     - ``chc_model`` : the pychoco.Model() created by _model()
     - ``chc_solver`` : the choco Model().get_solver() instance used in solve()
 
+    Documentation of the solver's own Python API:
+    
+    - https://pypi.org/project/pychoco/
+    - https://pychoco.readthedocs.io/en/latest/
+
     """
 
     @staticmethod
@@ -605,4 +612,4 @@ def _get_constraint(self, cpm_expr):
             return c
 
         # else
-        raise NotImplementedError(cpm_expr)  # if you reach this... please report on github
\ No newline at end of file
+        raise NotImplementedError(cpm_expr)  # if you reach this... please report on github
diff --git a/cpmpy/solvers/cpo.py b/cpmpy/solvers/cpo.py
index 94aad2987..13c99d6ec 100644
--- a/cpmpy/solvers/cpo.py
+++ b/cpmpy/solvers/cpo.py
@@ -1,11 +1,36 @@
 """
-    Interface to CP Optimizers API
+    Interface to CP Optimizer's Python API.
 
     CP Optimizer, also a feature of IBM ILOG Optimization Studio, is a software library of constraint programming tools 
     supporting constraint propagation, domain reduction, and highly optimized solution search.
 
-    Documentation of the solver's own Python API: (all modeling functions)
-    https://ibmdecisionoptimization.github.io/docplex-doc/cp/docplex.cp.modeler.py.html#module-docplex.cp.modeler
+    Always use :func:`cp.SolverLookup.get("cpo") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
+
+    Requires that the 'docplex' python package is installed:
+
+    .. code-block:: console
+    
+        $ pip install docplex
+
+    docplex documentation:
+    https://ibmdecisionoptimization.github.io/docplex-doc/
+
+    You will also need to install CPLEX Optimization Studio from IBM's website,
+    and add the location of the CP Optimizer binary to your path.
+    There is a free community version available.
+    https://www.ibm.com/products/ilog-cplex-optimization-studio
+
+    See detailed installation instructions at:
+    https://www.ibm.com/docs/en/icos/22.1.2?topic=2212-installing-cplex-optimization-studio
+
+    Academic license:
+    https://community.ibm.com/community/user/ai-datascience/blogs/xavier-nodet1/2020/07/09/cplex-free-for-students
+
+    The rest of this documentation is for advanced users.
 
     ===============
     List of classes
@@ -36,32 +61,15 @@
 
 class CPM_cpo(SolverInterface):
     """
-    Interface to CP Optimizers API.
-
-    Requires that the 'docplex' python package is installed:
-
-    .. code-block:: console
-    
-        $ pip install docplex
-
-    docplex documentation:
-    https://ibmdecisionoptimization.github.io/docplex-doc/
-
-    You will also need to install CPLEX Optimization Studio from IBM's website,
-    and add the location of the CP Optimizer binary to your path.
-    There is a free community version available.
-    https://www.ibm.com/products/ilog-cplex-optimization-studio
-
-    See detailed installation instructions at:
-    https://www.ibm.com/docs/en/icos/22.1.2?topic=2212-installing-cplex-optimization-studio
-
-    Academic license:
-    https://community.ibm.com/community/user/ai-datascience/blogs/xavier-nodet1/2020/07/09/cplex-free-for-students
+    Interface to CP Optimizer's Python API.
 
     Creates the following attributes (see parent constructor for more):
 
     - ``cpo_model``: object, CP Optimizers model object
 
+    Documentation of the solver's own Python API: (all modeling functions)
+    https://ibmdecisionoptimization.github.io/docplex-doc/cp/docplex.cp.modeler.py.html#module-docplex.cp.modeler
+
     """
 
     _docp = None  # Static attribute to hold the docplex.cp module
diff --git a/cpmpy/solvers/exact.py b/cpmpy/solvers/exact.py
index ba3eda98d..5b00b0fd0 100644
--- a/cpmpy/solvers/exact.py
+++ b/cpmpy/solvers/exact.py
@@ -4,7 +4,20 @@
 ## exact.py
 ##
 """
-    Interface to Exact
+    Interface to Exact's Python API
+
+    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/nonfiction-software/exact
+
+    Always use :func:`cp.SolverLookup.get("exact") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
 
     Requires that the 'exact' python package is installed:
 
@@ -12,12 +25,13 @@
     
         $ pip install 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.
+    .. warning::
+        Exact requires Python 3.10 or higher and the pip install only works on Linux and Windows.
+        On MacOS, you have to install the package from source.
 
-    The solver's git repository:
-    https://gitlab.com/nonfiction-software/exact
+    See https://pypi.org/project/exact for more information.
+
+    The rest of this documentation is for advanced users.
 
     ===============
     List of classes
@@ -57,17 +71,15 @@
 
 class CPM_exact(SolverInterface):
     """
-    Interface to the Python interface of Exact
-
-    Requires that the 'exact' python package is installed:
-    $ pip install exact
-
-    See https://pypi.org/project/exact for more information.
+    Interface to Exact's Python API
 
     Creates the following attributes (see parent constructor for more):
 
     - ``xct_solver`` : the Exact instance used in solve() and solveAll()
     - ``assumption_dict`` : maps Exact variables to (Exact value, CPM assumption expression)
+
+    Documentation of the solver's own Python API is sparse, but example usage can be found at:
+    https://gitlab.com/nonfiction-software/exact/-/tree/main/python_examples
     """
 
     @staticmethod
diff --git a/cpmpy/solvers/gcs.py b/cpmpy/solvers/gcs.py
index 785efc799..12e0ac72d 100644
--- a/cpmpy/solvers/gcs.py
+++ b/cpmpy/solvers/gcs.py
@@ -4,7 +4,18 @@
 ## gcs.py
 ##
 """
-    Interface to the Glasgow Constraint Solver's API for the cpmpy library.
+    Interface to the Glasgow Constraint Solver's API for the CPMpy library.
+
+    See:
+    https://github.com/ciaranm/glasgow-constraint-solver
+
+    The key feature of this CP solver is the ability to produce proof logs.
+
+    Always use :func:`cp.SolverLookup.get("gcs") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
 
     Requires that the 'gcspy' python package is installed:
 
@@ -12,10 +23,23 @@
 
         $ pip install gcspy
 
-    The key feature of this solver is the ability to produce proof logs.
+    Source installation instructions:
 
-    See:
-    https://github.com/ciaranm/glasgow-constraint-solver
+    - Ensure you have C++20 compiler such as GCC 10.3  / clang 15
+    - (on Debian-based systems, see https://apt.llvm.org for easy installation)
+    - If necessary ``export CXX=<your up to date C++ compiler (e.g. clang++-15)>``
+    - Ensure you have Boost installed
+    - ``git clone https://github.com/ciaranm/glasgow-constraint-solver.git``
+    - ``cd glasgow-constraint-solver/python``
+    - ``pip install .``
+
+    .. note::
+        If for any reason you need to retry the build, ensure you remove glasgow-constraints-solver/generator before rebuilding.
+
+    For the verifier functionality, the 'veripb' tool is also required.
+    See https://gitlab.com/MIAOresearch/software/VeriPB#installation for installation instructions of veripb. 
+
+    The rest of this documentation is for advanced users.
 
     ===============
     List of classes
@@ -51,23 +75,6 @@ class CPM_gcs(SolverInterface):
     """
     Interface to Glasgow Constraint Solver's API.
 
-    Requires that the 'gcspy' python package is installed: $ pip install gcspy
-
-    Current installation instructions:
-
-    - Ensure you have C++20 compiler such as GCC 10.3  / clang 15
-    - (on Debian-based systems, see https://apt.llvm.org for easy installation)
-    - If necessary `export CXX=<your up to date C++ compiler (e.g. clang++-15)>`
-    - Ensure you have Boost installed
-    - `git clone https://github.com/ciaranm/glasgow-constraint-solver.git`
-    - `cd glasgow-constraint-solver/python`
-    - `pip install .`
-
-    NB: if for any reason you need to retry the build, ensure you remove glasgow-constraints-solver/generator before rebuilding.
-
-    For the verifier functionality, the 'veripb' tool is also required.
-    See https://gitlab.com/MIAOresearch/software/VeriPB#installation for installation instructions. 
-
     Creates the following attributes (see parent constructor for more):
 
     - ``gcs`` : the gcspy solver object
@@ -76,6 +83,9 @@ class CPM_gcs(SolverInterface):
     - ``proof_name`` : name of the last proof (means <proof_name>.opb and <proof_name>.pbp will be present at the proof location)
     - ``veripb_return_code`` : return code from the last VeriPB check.
     - ``proof_check_timeout`` : whether the last VeriPB check timed out.
+
+    Documentation of the solver's own Python API is sparse, but example usage can be found at:
+    https://github.com/ciaranm/glasgow-constraint-solver/blob/main/python/python_test.py
     """
 
     @staticmethod
diff --git a/cpmpy/solvers/gurobi.py b/cpmpy/solvers/gurobi.py
index 396e6f642..b038b4d6f 100644
--- a/cpmpy/solvers/gurobi.py
+++ b/cpmpy/solvers/gurobi.py
@@ -4,7 +4,15 @@
 ## gurobi.py
 ##
 """
-    Interface to the python 'gurobi' package
+    Interface to Gurobi Optimizer's Python API.
+
+    Gurobi Optimizer is a highly efficient commercial solver for Integer Linear Programming (and more).
+
+    Always use :func:`cp.SolverLookup.get("gurobi") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
 
     Requires that the 'gurobipy' python package is installed:
 
@@ -12,12 +20,13 @@
 
         $ pip install gurobipy
     
-    
-    In contrast to other solvers in this package, Gurobi is not free to use and requires an active licence
+    Gurobi Optimizer requires an active licence (for example a free academic license)
     You can read more about available licences at https://www.gurobi.com/downloads/
 
-    Documentation of the solver's own Python API:
-    https://docs.gurobi.com/projects/optimizer/en/current/reference/python.html
+    See detailed installation instructions at:
+    https://support.gurobi.com/hc/en-us/articles/360044290292-How-do-I-install-Gurobi-for-Python-
+
+    The rest of this documentation is for advanced users.
 
     ===============
     List of classes
@@ -57,19 +66,16 @@
 
 class CPM_gurobi(SolverInterface):
     """
-    Interface to Gurobi's API
-
-    Requires that the 'gurobipy' python package is installed:
-    $ pip install gurobipy
-
-    See detailed installation instructions at:
-    https://support.gurobi.com/hc/en-us/articles/360044290292-How-do-I-install-Gurobi-for-Python-
+    Interface to Gurobi's Python API
 
     Creates the following attributes (see parent constructor for more):
     
     - ``grb_model``: object, TEMPLATE's model object
 
     The :class:`~cpmpy.expressions.globalconstraints.DirectConstraint`, when used, calls a function on the ``grb_model`` object.
+    
+    Documentation of the solver's own Python API:
+    https://docs.gurobi.com/projects/optimizer/en/current/reference/python.html
     """
 
     @staticmethod
diff --git a/cpmpy/solvers/minizinc.py b/cpmpy/solvers/minizinc.py
index 9f67b368b..022e57770 100644
--- a/cpmpy/solvers/minizinc.py
+++ b/cpmpy/solvers/minizinc.py
@@ -4,7 +4,22 @@
 ## minizinc.py
 ##
 """
-    Interface to MiniZinc's Python API
+    Interface to MiniZinc's Python API.
+
+    MiniZinc is a free and open-source constraint modeling language.
+    MiniZinc is used to model constraint satisfaction and optimization problems in
+    a high-level, solver-independent way, taking advantage of a large library of
+    pre-defined constraints. The model is then compiled into FlatZinc, a solver input
+    language that is understood by a wide range of solvers.
+    https://www.minizinc.org
+
+    The MiniZinc interface is text-based: CPMpy writes a textfile and passes it to the minizinc Python package.
+
+    Always use :func:`cp.SolverLookup.get("minizinc") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
 
     Requires that the 'minizinc' python package is installed:
 
@@ -12,21 +27,18 @@
 
         $ pip install minizinc
 
-    as well as the Minizinc bundled binary packages, downloadable from:
-    https://github.com/MiniZinc/MiniZincIDE/releases
-
+    as well as the MiniZinc bundled binary packages, downloadable from:
+    https://www.minizinc.org/software.html
 
-    MiniZinc is a free and open-source constraint modeling language.
-    MiniZinc is used to model constraint satisfaction and optimization problems in
-    a high-level, solver-independent way, taking advantage of a large library of
-    pre-defined constraints. The model is then compiled into FlatZinc, a solver input
-    language that is understood by a wide range of solvers.
-    https://www.minizinc.org
+    See detailed installation instructions at:
+    https://minizinc-python.readthedocs.io/en/latest/getting_started.html
 
-    Documentation of the solver's own Python API:
-    https://minizinc-python.readthedocs.io/
+    Note for **Jupyter notebook** users: MiniZinc uses AsyncIO, so using it in a Jupyter notebook gives
+    you the following error: ``RuntimeError: asyncio.run() cannot be called from a running event loop``
+    You can overcome this by ``pip install nest_asyncio``
+    and adding in the top cell ``import nest_asyncio; nest_asyncio.apply()``
 
-    CPMpy can translate CPMpy models to the (text-based) MiniZinc language.
+    The rest of this documentation is for advanced users.
 
     ===============
     List of classes
@@ -65,21 +77,6 @@ class CPM_minizinc(SolverInterface):
     """
     Interface to MiniZinc's Python API
 
-    Requires that the 'minizinc' python package is installed:
-    $ pip install minizinc
-    
-    as well as the MiniZinc bundled binary packages, downloadable from:
-    https://www.minizinc.org/software.html
-
-    See detailed installation instructions at:
-    https://minizinc-python.readthedocs.io/en/latest/getting_started.html
-
-    Note for Jupyter users: MiniZinc uses AsyncIO, so using it in a jupyter notebook gives
-    you the following error: RuntimeError: asyncio.run() cannot be called from a running event loop
-    You can overcome this by `pip install nest_asyncio`
-    and adding in the top cell `import nest_asyncio; nest_asyncio.apply()`
-
-
     Creates the following attributes (see parent constructor for more):
 
     - ``mzn_model``: object, the minizinc.Model instance
@@ -88,6 +85,9 @@ class CPM_minizinc(SolverInterface):
     - ``mzn_result``: object, containing solve results
 
     The :class:`~cpmpy.expressions.globalconstraints.DirectConstraint`, when used, adds a constraint with that name and the given args to the MiniZinc model.
+
+    Documentation of the solver's own Python API:
+    https://minizinc-python.readthedocs.io/
     """
 
     required_version = (2, 8, 2)
@@ -771,4 +771,4 @@ def flatzinc_string(self, **kwargs) -> str:
             with open(fzn.name) as f:
                 f.seek(0)
                 contents = f.readlines()
-        return "".join(contents)
\ No newline at end of file
+        return "".join(contents)
diff --git a/cpmpy/solvers/ortools.py b/cpmpy/solvers/ortools.py
index 8cc6bef60..318b294ac 100644
--- a/cpmpy/solvers/ortools.py
+++ b/cpmpy/solvers/ortools.py
@@ -5,21 +5,30 @@
 ##
 """
     Interface to OR-Tools' CP-SAT Python API. 
+
+    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.
+    The OR-Tools CP-SAT solver is an award-winning constraint programming solver
+    that uses SAT (satisfiability) methods and lazy-clause generation 
+    (see https://developers.google.com/optimization).
+
+    Always use :func:`cp.SolverLookup.get("ortools") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
     
     The 'ortools' python package is bundled by default with CPMpy.
-    It can be installed through `pip`:
+    It can also be installed separately through `pip`:
 
     .. code-block:: console
     
         $ 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.
-    The OR-Tools CP-SAT solver is an award-winning constraint programming solver
-    that uses SAT (satisfiability) methods and lazy-clause generation.
+    Detailed installation instructions available at:
+    https://developers.google.com/optimization/install
 
-    Documentation of the solver's own Python API:
-    https://developers.google.com/optimization/reference/python/sat/python/cp_model
+    The rest of this documentation is for advanced users.
 
     ===============
     List of classes
@@ -55,13 +64,7 @@
 
 class CPM_ortools(SolverInterface):
     """
-    Interface to the Python 'ortools' CP-SAT API
-
-    Requires that the 'ortools' python package is installed:
-    $ pip install ortools
-
-    See detailed installation instructions at:
-    https://developers.google.com/optimization/install
+    Interface to OR-Tools' CP-SAT Python API. 
 
     Creates the following attributes (see parent constructor for more):
 
@@ -69,6 +72,9 @@ class CPM_ortools(SolverInterface):
     - ``ort_solver``: the ortools cp_model.CpSolver() instance used in solve()
 
     The :class:`~cpmpy.expressions.globalconstraints.DirectConstraint`, when used, calls a function on the ``ort_model`` object.
+
+    Documentation of the solver's own Python API:
+    https://developers.google.com/optimization/reference/python/sat/python/cp_model
     """
 
     @staticmethod
diff --git a/cpmpy/solvers/pysat.py b/cpmpy/solvers/pysat.py
index e5e3847ec..9844b74e1 100644
--- a/cpmpy/solvers/pysat.py
+++ b/cpmpy/solvers/pysat.py
@@ -6,26 +6,32 @@
 """
     Interface to PySAT's API
 
-    Requires that the 'pysat' optional dependency is installed:
-
-    .. code-block:: console
-
-        $ pip install cpmpy[pysat]
-
     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.
-    https://pysathq.github.io/
+    (see https://pysathq.github.io/)
 
-    This solver can be used if the model only has Boolean variables,
-    and only logical constraints (`and`, `or`, `implies`, `==`, `!=`) or cardinality constraints.
+    .. warning::
+        This solver can only be used if the model only uses Boolean variables.
+        It does not support optimization.
+    
+    Always use :func:`cp.SolverLookup.get("pysat") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
 
-    Documentation of the solver's own Python API:
-    https://pysathq.github.io/docs/html/api/solvers.html
+    ============
+    Installation
+    ============
 
-    .. warning::
-        WARNING: CPMpy uses 'model' to refer to a constraint specification,
-        the PySAT docs use 'model' to refer to a solution.
+    Requires that the 'python-sat' package is installed. If you want to also solve
+    pseudo-Boolean constraints, you should also install its optional dependency 'pblib', as follows:
+
+    .. code-block:: console
+
+        $ pip install python-sat[pblib]
+
+    See detailed installation instructions at:
+    https://pysathq.github.io/installation
+
+    The rest of this documentation is for advanced users.
 
     ===============
     List of classes
@@ -58,13 +64,7 @@
 
 class CPM_pysat(SolverInterface):
     """
-    Interface to PySAT's API
-
-    Requires that the 'python-sat' python package. The recommend :
-    $ pip install cpmpy[pysat]
-
-    See detailed installation instructions at:
-    https://pysathq.github.io/installation
+    Interface to PySAT's API.
 
     Creates the following attributes (see parent constructor for more):
 
@@ -72,6 +72,14 @@ class CPM_pysat(SolverInterface):
     - ``pysat_solver``: a pysat.solver.Solver() (default: glucose4)
 
     The :class:`~cpmpy.expressions.globalconstraints.DirectConstraint`, when used, calls a function on the ``pysat_solver`` object.
+
+    Documentation of the solver's own Python API:
+    https://pysathq.github.io/docs/html/api/solvers.html
+
+    .. note::
+        CPMpy uses 'model' to refer to a constraint specification,
+        the PySAT docs use 'model' to refer to a solution.
+
     """
 
     IMPORT_PYSAT_PBLIB_ERROR = ImportError("PySAT was installed without optional dependency `pblib`, which is required to encode (weighted) sums. To install PySAT with recommended optional dependencies, run `pip install cpmpy[pysat]`.")
diff --git a/cpmpy/solvers/pysdd.py b/cpmpy/solvers/pysdd.py
index 4223a92da..e50d0eef1 100644
--- a/cpmpy/solvers/pysdd.py
+++ b/cpmpy/solvers/pysdd.py
@@ -6,21 +6,29 @@
 """
     Interface to PySDD's API
 
+    PySDD is a knowledge compilation package for Sentential Decision Diagrams (SDD).
+    (see https://pysdd.readthedocs.io/en/latest/)
+
+    .. warning::    
+        This solver can ONLY be used for solution checking and enumeration over Boolean variables!
+        It does not support optimization.
+
+    Always use :func:`cp.SolverLookup.get("pysdd") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
+
     Requires that the 'PySDD' python package is installed:
 
     .. code-block:: console
 
         $ pip install PySDD
 
-    PySDD is a knowledge compilation package for Sentential Decision Diagrams (SDD)
-    https://pysdd.readthedocs.io/en/latest/
-
-    This solver can ONLY be used for solution checking and enumeration over Boolean variables!
-    That is, only logical constraints (`and`, `or`, `implies`, `==`, `!=`) and Boolean global constraints.
-
-    Documentation of the solver's own Python API:
-    https://pysdd.readthedocs.io/en/latest/classes/SddManager.html
+    See detailed installation instructions at:
+    https://pysdd.readthedocs.io/en/latest/usage/installation.html
 
+    The rest of this documentation is for advanced users.
 
     ===============
     List of classes
@@ -48,13 +56,7 @@
 
 class CPM_pysdd(SolverInterface):
     """
-    Interface to pysdd's API
-
-    Requires that the 'PySDD' python package is installed:
-    $ pip install pysdd
-
-    See detailed installation instructions at:
-    https://pysdd.readthedocs.io/en/latest/usage/installation.html
+    Interface to PySDD's API.
 
     Creates the following attributes (see parent constructor for more):
 
@@ -63,6 +65,9 @@ class CPM_pysdd(SolverInterface):
     - ``pysdd_root`` : a pysdd.sdd.SddNode (changes whenever a formula is added)
 
     The :class:`~cpmpy.expressions.globalconstraints.DirectConstraint`, when used, calls a function on the ``pysdd_manager`` object and replaces the root node with a conjunction of the previous root node and the result of this function call.
+
+    Documentation of the solver's own Python API:
+    https://pysdd.readthedocs.io/en/latest/classes/SddManager.html
     """
 
     @staticmethod
diff --git a/cpmpy/solvers/z3.py b/cpmpy/solvers/z3.py
index 4613918ae..5309cdd33 100644
--- a/cpmpy/solvers/z3.py
+++ b/cpmpy/solvers/z3.py
@@ -4,7 +4,22 @@
 ## z3.py
 ##
 """
-    Interface to z3's API
+    Interface to Z3's Python API.
+
+    Z3 is a highly versatile and effective theorem prover from Microsoft.
+    Underneath, it is an SMT solver with a wide scala of theory solvers.
+    We will interface to the finite-domain integer related parts of the API.
+    (see https://github.com/Z3Prover/z3)
+
+    .. warning::
+        For incrementally solving an optimisation function, instantiate the solver object
+        with a model that has an objective function, e.g. ``s = cp.SolverLookup.get("z3", Model(maximize=1))``.
+
+    Always use :func:`cp.SolverLookup.get("z3") <cpmpy.solvers.utils.SolverLookup.get>` to instantiate the solver object.
+
+    ============
+    Installation
+    ============
 
     Requires that the 'z3-solver' python package is installed:
 
@@ -12,15 +27,10 @@
     
         $ pip install z3-solver
 
-    Z3 is a highly versatile and effective theorem prover from Microsoft.
-    Underneath, it is an SMT solver with a wide scala of theory solvers.
-    We will interface to the finite-domain integer related parts of the API
-
-    Documentation of the solver's own Python API:
-    https://z3prover.github.io/api/html/namespacez3py.html
+    See detailed installation instructions at:
+    https://github.com/Z3Prover/z3#python
 
-    .. note::
-        Terminology note: a 'model' for z3 is a solution!
+    The rest of this documentation is for advanced users.
 
     ===============
     List of classes
@@ -50,19 +60,19 @@
 
 class CPM_z3(SolverInterface):
     """
-    Interface to z3's API
-
-    Requires that the 'z3-solver' python package is installed:
-    $ pip install z3-solver
-
-    See detailed installation instructions at:
-    https://github.com/Z3Prover/z3#python
+    Interface to Z3's Python API.
 
     Creates the following attributes (see parent constructor for more):
         
     - ``z3_solver``: object, z3's Solver() object
 
     The :class:`~cpmpy.expressions.globalconstraints.DirectConstraint`, when used, calls a function in the `z3` namespace and ``z3_solver.add()``'s the result.
+
+    Documentation of the solver's own Python API:
+    https://z3prover.github.io/api/html/namespacez3py.html
+
+    .. note::
+        Terminology note: a 'model' for z3 is a solution!
     """
 
     @staticmethod
diff --git a/docs/api/solvers/choco.rst b/docs/api/solvers/choco.rst
index 66f739ed8..5a6d11368 100644
--- a/docs/api/solvers/choco.rst
+++ b/docs/api/solvers/choco.rst
@@ -1,4 +1,4 @@
-CPMpy exact interface (:mod:`cpmpy.solvers.choco`)
+CPMpy choco interface (:mod:`cpmpy.solvers.choco`)
 =====================================================
 
 .. automodule:: cpmpy.solvers.choco
diff --git a/docs/api/solvers/solver_interface.rst b/docs/api/solvers/solver_interface.rst
index f0c46cdc4..70b529f1a 100644
--- a/docs/api/solvers/solver_interface.rst
+++ b/docs/api/solvers/solver_interface.rst
@@ -1,5 +1,5 @@
 Solver Interface (:mod:`cpmpy.solvers.solver_interface`)
-=====================================================
+========================================================
 
 .. automodule:: cpmpy.solvers.solver_interface
     :members:

From 8c7eda2780e7050f7a3fff2e9ff21b974c403bbb Mon Sep 17 00:00:00 2001
From: kostis <kostismich@gmail.com>
Date: Wed, 16 Apr 2025 15:21:21 +0200
Subject: [PATCH 05/39] Docs api quickstart page (#629)

* add missing documentation in global constraints and functions files

* add API quickstart page

* doc improvements

* from quickstart to summary sheet, work in progress

* docs update part 2

* rework summary part 2

* fix link to modeling page from summary.rst

* wrap the shape examples in code format for visibility

* Fix Element cross reference

* Add small example on reification

earlier in the quickstart only implication was mentioned, never the word reification

---------

Co-authored-by: Tias Guns <tias@ulyssis.org>
Co-authored-by: Thomas Sergeys <thomas.s2000@hotmail.com>
---
 docs/index.rst   |   1 +
 docs/summary.rst | 157 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 158 insertions(+)
 create mode 100644 docs/summary.rst

diff --git a/docs/index.rst b/docs/index.rst
index 9b0ce0135..8797b4c81 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,6 +10,7 @@ CPMpy is ideal for solving combinatorial problems like assignment problems or co
    :caption: Getting started:
 
    modeling
+   summary
 
 .. _supported-solvers:
 
diff --git a/docs/summary.rst b/docs/summary.rst
new file mode 100644
index 000000000..0430bc4c5
--- /dev/null
+++ b/docs/summary.rst
@@ -0,0 +1,157 @@
+Summary sheet
+=============
+
+More extensive user documentation in :doc:`Modeling and solving with CPMpy <modeling>`.
+
+``import cpmpy as cp``
+
+Model class
+~~~~~~~~~~~
+
+- :meth:`model = cp.Model() <cpmpy.model.Model.__init__>` -- Create a :class:`Model <cpmpy.model.Model>`.
+- :meth:`model += constraint <cpmpy.model.Model.__add__>` -- Add a constraint (an :mod:`Expression <cpmpy.expressions>`) to the model.
+- :meth:`model.maximize(obj) <cpmpy.model.Model.maximize>` or :meth:`model.minimize(obj) <cpmpy.model.Model.minimize>` -- Set the objective (an :mod:`Expression <cpmpy.expressions>`).
+- :meth:`model.solve() <cpmpy.model.Model.solve>` -- Solve the model with the default solver, returns True/False.
+- :meth:`model.solveAll() <cpmpy.model.Model.solveAll>` -- Solve and enumerate all solutions, returns number of solutions.
+- :meth:`model.status() <cpmpy.model.Model.status>` -- Get the status of the last solver run.
+- :meth:`model.objective_value() <cpmpy.model.Model.objective_value>` -- Get the objective value obtained during the last solver run.
+
+Solvers
+~~~~~~~
+
+:mod:`Solvers <cpmpy.solvers>` have the same API as :class:`Model <cpmpy.model.Model>`. Solvers are instantiated throught the static :class:`cp.SolverLookup <cpmpy.solvers.utils.SolverLookup>` class:
+
+- :meth:`cp.SolverLookup.solvernames() <cpmpy.solvers.utils.SolverLookup.solvernames>` -- List all installed solvers (including subsolvers).
+- :meth:`cp.SolverLookup.get(solvername, model=None) <cpmpy.solvers.utils.SolverLookup.get>` -- Initialize a specific solver.
+
+
+Decision Variables
+~~~~~~~~~~~~~~~~~~
+
+:mod:`Decision variables <cpmpy.expressions.variables>` are NumPy-like objects: ``shape=None|1`` creates one variable, ``shape=4`` creates a vector of 4 variables, ``shape=(2,3)`` creates a matrix of 2x3 variables, etc.
+Name is optional too, indices are automatically added to the name so each variable has a unique name.
+
+- :meth:`x = cp.boolvar(shape=4, name="x") <cpmpy.expressions.variables.boolvar>` -- Create four Boolean decision variables.
+- :meth:`x = cp.intvar(lb, ub) <cpmpy.expressions.variables.intvar>` -- Create one integer decision variable with domain ``[lb, ub]`` (inclusive).
+- :meth:`x.value() <cpmpy.expressions.variables._NumVarImpl.value>` -- Get the value of ``x`` obtained during the last solver run.
+
+Core Expressions
+~~~~~~~~~~~~~~~~
+
+You can apply the following standard Python operators on CPMpy expressions, which creates the corresponding :class:`Core Expression <cpmpy.expressions.core>` object:
+
+- Comparison: ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``
+- Arithmetic: ``+``, ``-``, ``*``, ``//`` (integer division), ``%`` (modulo), ``**`` (power)
+- Logical: ``&`` (and), ``|`` (or), ``~`` (not), ``^`` (xor)
+- Logical implication: :meth:`x.implies(y) <cpmpy.expressions.core.Expression.implies>`
+
+Logical operators only work on Boolean variables/constraints, numeric operators work on both integer and Boolean variables/expressions.
+
+CPMpy overwrites the following :mod:`Python built-ins <cpmpy.expressions.python_builtins>`, they allow vectorized operations:
+
+- :meth:`cp.sum <cpmpy.expressions.python_builtins.sum>`, :meth:`cp.abs <cpmpy.expressions.python_builtins.abs>`, :meth:`cp.max <cpmpy.expressions.python_builtins.max>`, :meth:`cp.min <cpmpy.expressions.python_builtins.min>`
+- :meth:`cp.all <cpmpy.expressions.python_builtins.all>`, :meth:`cp.any <cpmpy.expressions.python_builtins.any>`
+
+You can **index** CPMpy expressions with an integer decision variable: ``x[y]``, which will create an :class:`Element <cpmpy.expressions.globalfunctions.Element>` expression object.
+To index non-CPMpy arrays, wrap them with :func:`~cpmpy.expressions.variables.cpm_array`: ``cpm_array([1,2,3])[y]``.
+
+Global Functions
+~~~~~~~~~~~~~~~~
+
+:mod:`Global functions <cpmpy.expressions.globalfunctions>` are numeric functions that some solvers support natively (through a solver-specific global constraint). CPMpy automatically rewrites the global function as needed to work with any solver.
+
+.. currentmodule:: cpmpy.expressions.globalfunctions
+.. autosummary::
+    :nosignatures:
+
+        Minimum
+        Maximum
+        Abs
+        Element
+        Count
+        Among
+        NValue
+        NValueExcept
+
+
+Global Constraints
+~~~~~~~~~~~~~~~~~~
+
+:mod:`Global constraints <cpmpy.expressions.globalconstraints>` are constraints (Boolean functions) that some solvers support natively. All global constraints can be reified (implication, equivalence) and used in other expressions, which CPMpy will handle.
+
+.. currentmodule:: cpmpy.expressions.globalconstraints
+.. autosummary::
+    :nosignatures:
+
+        AllDifferent
+        AllDifferentExcept0
+        AllDifferentExceptN
+        AllEqual
+        AllEqualExceptN
+
+        Circuit
+        Inverse
+        Table
+        ShortTable
+        NegativeTable
+        IfThenElse
+        InDomain
+        Xor
+        Cumulative
+        Precedence
+        NoOverlap
+        GlobalCardinalityCount
+
+        Increasing
+        Decreasing
+        IncreasingStrict
+        DecreasingStrict
+
+        LexLess
+        LexLessEq
+        LexChainLess
+        LexChainLessEq
+
+        DirectConstraint
+
+
+Guidelines and tips
+~~~~~~~~~~~~~~~~~~~
+
+- Do not ``from cpmpy import *``, the implicit overloading of any/all and sum may break or slow down other libraries.
+- Explicitly use CPMpy versions of built-in functions (``cp.sum``, ``cp.all``, etc.).
+- Use global constraints/global functions where possible, some solvers will be much faster.
+- Stick to integer constants; floats and fractional numbers are not supported.
+- For maintainability, use logical code organization and comments to explain your constraints.
+
+
+Toy example
+~~~~~~~~~~~
+
+.. code-block:: python
+
+    import cpmpy as cp
+
+    # Decision Variables
+    b = cp.boolvar()
+    x1, x2, x3 = x = cp.intvar(1, 10, shape=3)
+
+    # Constraints
+    model = cp.Model()
+
+    model += (x[0] == 1)
+    model += cp.AllDifferent(x)
+    model += cp.Count(x, 9) == 1
+    model += b.implies(x[1] + x[2] > 5)
+
+    # Objective
+    model.maximize(cp.sum(x) + 100 * b)
+
+    # Solving
+    solved = model.solve()
+    if solved:
+        print("Solution found:")
+        print('b:', b.value(), ' x:', x.value().tolist())
+    else:
+        print("No solution found.")
+

From 926e9e7616326f1a38f5b0fd5e03f53c299d60e6 Mon Sep 17 00:00:00 2001
From: Henk Bierlee <bierlee.henk@gmail.com>
Date: Wed, 16 Apr 2025 14:20:46 +0000
Subject: [PATCH 06/39] Use optional dependencies in CI and other minor
 improvements (#636)

* Remove `flake8` code style checker (seemingly unused?)

* Bump setup-python action

* Use optional dependencies in CI

* Fix xdist dependency
---
 .github/workflows/python-test.yml | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml
index 52ce6734b..9959d1677 100644
--- a/.github/workflows/python-test.yml
+++ b/.github/workflows/python-test.yml
@@ -6,21 +6,16 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python 3.10
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.10'
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install flake8 pytest pytest-xdist requests pandas
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-          pip install python-sat[pblib]
-          pip install z3-solver
-          pip install exact
-          pip install pysdd
-          pip install pychoco
+          pip install ".[test, z3, choco, exact, pysat, pysdd, choco, minizinc]"
+          pip install pytest-xdist
           sudo snap install minizinc --classic
-          pip install minizinc
       - name: Test with pytest
         run: |
           python -m pytest -n 4 tests/

From 1594ecc76d620f7482a175f634abeeb6c39884a5 Mon Sep 17 00:00:00 2001
From: Ignace Bleukx <ignace.bleukx@kuleuven.be>
Date: Wed, 16 Apr 2025 17:01:35 +0200
Subject: [PATCH 07/39] Linearize subtraction (#639)

* make sure sub is turned into a wsum

* add test
---
 cpmpy/transformations/linearize.py |  2 +-
 tests/test_trans_linearize.py      | 16 ++++++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/cpmpy/transformations/linearize.py b/cpmpy/transformations/linearize.py
index 68c63e192..ffd0293dd 100644
--- a/cpmpy/transformations/linearize.py
+++ b/cpmpy/transformations/linearize.py
@@ -152,7 +152,7 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
 
             if lhs.name == "sub":
                 # convert to wsum
-                lhs = sum([1 * lhs.args[0] + -1 * lhs.args[1]])
+                lhs = Operator("wsum", [[1, -1], [lhs.args[0], lhs.args[1]]])
                 cpm_expr = eval_comparison(cpm_expr.name, lhs, rhs)
 
             if lhs.name == "-":
diff --git a/tests/test_trans_linearize.py b/tests/test_trans_linearize.py
index ad8870301..4a41d77f4 100644
--- a/tests/test_trans_linearize.py
+++ b/tests/test_trans_linearize.py
@@ -209,6 +209,22 @@ def test_issue_546(self):
             model = cp.Model(c)
             model.solve(solver="exact")
 
+    def test_sub(self):
+        x = cp.intvar(0,10, name="x")
+        y = cp.intvar(0,10, name="y")
+
+        cons = Operator("sub", [3, x]) == y
+        [lin_cons] = linearize_constraint([cons])
+        self.assertEqual(str(lin_cons), "sum([-1, -1] * [x, y]) == -3")
+
+        cons = Operator("sub", [x, 3]) == y
+        [lin_cons] = linearize_constraint([cons])
+        self.assertEqual(str(lin_cons), "sum([1, -1] * [x, y]) == 3")
+
+        cons = Operator("sub", [x,y]) == 3
+        [lin_cons] = linearize_constraint([cons])
+        self.assertEqual(str(lin_cons), "sum([1, -1] * [x, y]) == 3")
+
 
 
 class TestConstRhs(unittest.TestCase):

From 7fb6f607df05064c20ad184f68486bb26f62dec0 Mon Sep 17 00:00:00 2001
From: Tias Guns <tias@ulyssis.org>
Date: Wed, 16 Apr 2025 17:48:47 +0200
Subject: [PATCH 08/39] rework (start of) transformations docs (#634)

Co-authored-by: Thomas Sergeys <thomas.s2000@hotmail.com>
---
 cpmpy/transformations/__init__.py         | 36 ++++++++++++++++-------
 cpmpy/transformations/comparison.py       | 23 +++++++--------
 cpmpy/transformations/decompose_global.py |  8 ++---
 cpmpy/transformations/get_variables.py    | 12 ++++----
 cpmpy/transformations/linearize.py        | 32 ++++++++++----------
 cpmpy/transformations/negation.py         | 14 ++++-----
 cpmpy/transformations/normalize.py        | 12 ++++----
 cpmpy/transformations/reification.py      |  2 +-
 cpmpy/transformations/safening.py         |  8 +++--
 cpmpy/transformations/to_cnf.py           | 16 ++++++----
 10 files changed, 93 insertions(+), 70 deletions(-)

diff --git a/cpmpy/transformations/__init__.py b/cpmpy/transformations/__init__.py
index 2fd216545..e971952e7 100644
--- a/cpmpy/transformations/__init__.py
+++ b/cpmpy/transformations/__init__.py
@@ -1,28 +1,42 @@
 """
-    Methods to transform CPMpy expressions into other CPMpy expressions.
+    Transformations are used by solvers to convert (high-level) CPMpy expressions
+    into the low-level constraints they support.
 
-    Input and output are always CPMpy expressions, so transformations can
-    be chained and called multiple times, as needed.
+    Typical users never need to use these functions directly.
 
-    A transformation can not modify expressions in place but in that case
-    should create and return new expression objects. In this way, the
+    **CPMpy’s transformations** selectively rewrite only those constraint expressions that a solver does not support. While solvers can use any transformation they need, lower-level solvers largely reuse those of higher-level ones, creating a waterfall pattern:
+
+    .. image:: ../waterfall.png
+        :width: 480
+        :alt: Waterfall from model to solvers
+
+    The rest of this documentation is for solver developers and other advanced users.
+    Make sure you read `Adding a new solver <../adding_solver.html>`_ first.
+     
+    A transformation can not modify expressions in-place but in that case
+    should create and return new expression objects (copy-on-write). In this way, the
     expressions prior to the transformation remain intact, and could be
     used for other purposes too.
 
     ==================
     List of submodules
     ==================
+
+    Input and output to transformations are always CPMpy expressions, so transformations can
+    be chained and called multiple times, as needed. While there is no fixed ordering,
+    the following ordering corresponds to the waterfall:
+
     .. autosummary::
         :nosignatures:
 
-        comparison
-        decompose_global
-        flatten_model
         get_variables
-        linearize
-        negation
         normalize
-        reification
         safening
+        decompose_global
+        negation
+        flatten_model
+        reification
+        comparison
+        linearize
         to_cnf
 """
diff --git a/cpmpy/transformations/comparison.py b/cpmpy/transformations/comparison.py
index b8a806883..eb6f51909 100644
--- a/cpmpy/transformations/comparison.py
+++ b/cpmpy/transformations/comparison.py
@@ -1,15 +1,14 @@
 """
-  Transformations regarding :class:`~cpmpy.expressions.core.Comparison` constraints (originally).
-  Now, it is regarding numeric expressions in general, including nested ones.
+  Transforms non-equality comparisons into equality comparisons as needed.
   
-  Let with <op> one of == or !=,<,<=,>,>=
-  Numeric expressions in Flat Normal Form are of the kind
-    - NumExpr <op> IV
-    - BoolVar == NumExpr <op> IV
-    - BoolVar -> NumExpr <op> IV
-    - NumExpr <op> IV -> BoolVar
-
-  The NumExpr can be a sum, wsum or global function with a non-bool return type.
+  Let <op> be one of `==` or `!=`, `<`, `<=`, `>`, `>=`. Numeric expressions in **Flat Normal Form** are of the kind:
+
+    - `NumExpr <op> IV`
+    - `BoolVar == NumExpr <op> IV`
+    - `BoolVar -> NumExpr <op> IV`
+    - `NumExpr <op> IV -> BoolVar`
+
+  The `NumExpr` can be a sum, wsum or global function with a non-bool return type.
     
   This file implements:
     - :func:`only_numexpr_equality()`:    transforms `NumExpr <op> IV` (also reified) to `(NumExpr == A) & (A <op> IV)` if not supported
@@ -23,8 +22,8 @@
 
 def only_numexpr_equality(constraints, supported=frozenset()):
     """
-        transforms `NumExpr <op> IV` to `(NumExpr == A) & (A <op> IV)` if not supported
-        also for the reified uses of NumExpr
+        Transforms ``NumExpr <op> IV`` to ``(NumExpr == A) & (A <op> IV)`` if not supported.
+        Also for the reified uses of `NumExpr`
 
         :param supported:  a (frozen)set of expression names that supports all comparisons in the solver
     """
diff --git a/cpmpy/transformations/decompose_global.py b/cpmpy/transformations/decompose_global.py
index 58ed8cb0f..cf92c2c26 100644
--- a/cpmpy/transformations/decompose_global.py
+++ b/cpmpy/transformations/decompose_global.py
@@ -1,5 +1,5 @@
 """
-    Decompose any global constraint not supported by the solver.
+    Decompose global constraints not supported by the solver.
 """
 
 import copy
@@ -17,8 +17,8 @@
 
 def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _toplevel=None, nested=False):
     """
-        Decomposes any global constraint not supported by the solver
-        Accepts a list of CPMpy expressions as input and returns a list of CPMpy expressions,
+        Decomposes any global constraint not supported by the solver.
+        Accepts a list of CPMpy expressions as input and returns a list of CPMpy expressions.
             
         :param supported: a set of supported global constraints or global functions
         :param supported_reified: a set of supported reified global constraints (globals with Boolean return type only)
@@ -30,7 +30,7 @@ def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _to
 
         Supported numerical global functions remain in the expression tree as is. They can be rewritten using
         :func:`cpmpy.transformations.reification.reify_rewrite`
-        The following `bv -> NumExpr <comp> Var/Const` can be rewritten as  [bv -> IV0 <comp> Var/Const, NumExpr == IV0].
+        The following ``bv -> NumExpr <comp> Var/Const`` can be rewritten as  ``[bv -> IV0 <comp> Var/Const, NumExpr == IV0]``.
         So even if numerical constraints are not supported in reified context, we can rewrite them to non-reified versions if they are total.
     """
     if _toplevel is None:
diff --git a/cpmpy/transformations/get_variables.py b/cpmpy/transformations/get_variables.py
index 00292515f..005f57837 100644
--- a/cpmpy/transformations/get_variables.py
+++ b/cpmpy/transformations/get_variables.py
@@ -1,7 +1,7 @@
 """
-Returns an list of all variables in the model or expressions
+Getting and printing variables in the model or expression.
 
-Variables are ordered by appearance, e.g. first encountered first
+Variables are ordered by appearance, e.g. first encountered first.
 """
 import warnings # for deprecation warning
 import numpy as np
@@ -33,8 +33,9 @@ def get_variables(expr, collect=None):
     """
         Get variables of an expression
 
-        - expr: Expression or list of expressions
-        - collect: optional set, variables will be added to this set of given
+        Arguments:
+            expr: Expression or list of expressions
+            collect: optional set, variables will be added to this set of given
    """
     def extract(lst, append):
         for e in lst:
@@ -80,7 +81,8 @@ def print_variables(expr_or_model):
     """
         Print variables **and their domains**
 
-        argument 'expr_or_model' can be an expression or a model
+        Arguments:
+            expr_or_model: can be an expression or a model
     """
 
     if isinstance(expr_or_model, cp.Model):
diff --git a/cpmpy/transformations/linearize.py b/cpmpy/transformations/linearize.py
index ffd0293dd..13ab44fc4 100644
--- a/cpmpy/transformations/linearize.py
+++ b/cpmpy/transformations/linearize.py
@@ -1,19 +1,19 @@
 """
-Transformations regarding linearization of constraints.
+Transforms flat constraints into linear constraints.
 
 Linearized constraints have one of the following forms:
 
 Linear comparison:
 ------------------
-- LinExpr == Constant
-- LinExpr >= Constant
-- LinExpr <= Constant
+- ``LinExpr == Constant``
+- ``LinExpr >= Constant``
+- ``LinExpr <= Constant``
 
 LinExpr can be any of:
 
-- NumVar
-- sum
-- wsum
+- `NumVar`
+- `sum`
+- `wsum`
 
 Indicator constraints:
 ----------------------
@@ -77,10 +77,10 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
     Only apply after :func:'cpmpy.transformations.flatten_model.flatten_constraint()' and :func:'cpmpy.transformations.reification.only_implies()'.
 
     Arguments:
-    - `supported`: which constraint and variable types are supported, i.e. `sum`, `and`, `or`, `alldifferent`
-    :class:`~cpmpy.expressions.globalconstraints.AllDifferent` has a special linearization and is decomposed as such if not in `supported`.
-    Any other unsupported global constraint should be decomposed using :func:`cpmpy.transformations.decompose_global.decompose_in_tree()`
-    - `reified`: whether the constraint is fully reified
+        supported: which constraint and variable types are supported, i.e. `sum`, `and`, `or`, `alldifferent`
+            :class:`~cpmpy.expressions.globalconstraints.AllDifferent` has a special linearization and is decomposed as such if not in `supported`.
+            Any other unsupported global constraint should be decomposed using :func:`cpmpy.transformations.decompose_global.decompose_in_tree()`
+        reified: whether the constraint is fully reified
     """
 
     newlist = []
@@ -389,8 +389,8 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
 
 def only_positive_bv(lst_of_expr):
     """
-        Replaces constraints containing NegBoolView with equivalent expression using only BoolVar.
-        cpm_expr is expected to be linearized. Only apply after applying linearize_constraint(cpm_expr)
+        Replaces constraints containing :class:`~cpmpy.expressions.variables.NegBoolView` with equivalent expression using only :class:`~cpmpy.expressions.variables.BoolVar`.
+        `lst_of_expr` is expected to be linearized. Only apply after applying :func:`linearize_constraint(cpm_expr) <linearize_constraint>`.
 
         Resulting expression is linear.
     """
@@ -530,9 +530,9 @@ def canonical_comparison(lst_of_expr):
 def only_positive_coefficients(lst_of_expr):
     """
         Replaces Boolean terms with negative coefficients in linear constraints with terms with positive coefficients by negating its literal.
-        This can simplify a wsum into sum.
-        cpm_expr is expected to be a canonical comparison.
-        Only apply after applying canonical_comparison(cpm_expr)
+        This can simplify a `wsum` into `sum`.
+        `cpm_expr` is expected to be a canonical comparison.
+        Only apply after applying :func:`canonical_comparison(cpm_expr) <canonical_comparison>`
 
         Resulting expression is linear.
     """
diff --git a/cpmpy/transformations/negation.py b/cpmpy/transformations/negation.py
index cd0857619..8829e7e3e 100644
--- a/cpmpy/transformations/negation.py
+++ b/cpmpy/transformations/negation.py
@@ -1,5 +1,5 @@
 """
-    Transformations dealing with negations.
+    Transformations dealing with negations (used by other transformations).
 """
 import copy
 import warnings  # for deprecation warning
@@ -15,8 +15,8 @@ def push_down_negation(lst_of_expr, toplevel=True):
         Transformation that checks all elements from the list,
         and pushes down any negation it finds with the :func:`recurse_negation()` function.
 
-        Assumes the input is a list (typically from :func:`~cpmpy.transformations.normalize.toplevel_list()`) en ensures the output is
-        a toplevel_list if the input was.
+        Assumes the input is a list (typically from :func:`~cpmpy.transformations.normalize.toplevel_list()`) and ensures the output is
+        a `toplevel_list` if the input was.
     """
     if isinstance(lst_of_expr, np.ndarray) and not (lst_of_expr.dtype == object):
         # shortcut for data array, return as is
@@ -65,11 +65,11 @@ def push_down_negation(lst_of_expr, toplevel=True):
 
 def recurse_negation(expr):
     """
-        Negate 'expr' by pushing the negation down into it and its args
+        Negate `expr` by pushing the negation down into it and its args.
 
-        Comparison: swap comparison sign
-        :func:`Operator.is_bool() <cpmpy.expressions.core.Operator.is_bool()>`: apply DeMorgan
-        Global: leave "NOT" operator before global constraint. Use :func:`cpmpy.transformations.decompose_global.decompose_in_tree()` for this (AFTER ISSUE #293)
+        - :class:`~cpmpy.expressions.core.Comparison`: swap comparison sign
+        - :func:`Operator.is_bool() <cpmpy.expressions.core.Operator.is_bool()>`: apply DeMorgan
+        - :class:`~cpmpy.expressions.globalconstraints.GlobalConstraint`: leave "NOT" operator before global constraint. Use :func:`~cpmpy.transformations.decompose_global.decompose_in_tree()` for this (AFTER ISSUE #293)
     """
 
     if isinstance(expr, (_BoolVarImpl,BoolVal)):
diff --git a/cpmpy/transformations/normalize.py b/cpmpy/transformations/normalize.py
index 267ae09d4..129c941f0 100644
--- a/cpmpy/transformations/normalize.py
+++ b/cpmpy/transformations/normalize.py
@@ -1,5 +1,5 @@
 """
-    Normalizing the constraints given to a CPMpy model.
+    Normalize a toplevel list, or simplify Boolean expressions.
 """
 
 import copy
@@ -17,7 +17,7 @@
 
 def toplevel_list(cpm_expr, merge_and=True):
     """
-    unravels nested lists and top-level AND's and ensures every element returned is a CPMpy Expression with :func:`~cpmpy.expressions.core.Expression.is_bool()` true.
+    Unravels nested lists and top-level AND's and ensures every element returned is a CPMpy Expression with :func:`~cpmpy.expressions.core.Expression.is_bool()` true.
 
     Arguments:
         cpm_expr:   Expression or list of Expressions
@@ -51,10 +51,10 @@ def unravel(lst, append):
 
 def simplify_boolean(lst_of_expr, num_context=False):
     """
-    removes boolean constants from all CPMpy expressions
-    only resulting boolean constant is literal 'false'
-    Boolean constants are promoted to int if in numerical context,
-    ints are never converted to Bool
+    Removes boolean constants from all CPMpy expressions.
+    Only resulting boolean constant is literal 'false'.
+    Boolean constants are promoted to `int` if in a numerical context,
+    `ints` are never converted to `bool`.
     
     Arguments:
         list_of_expr: list of CPMpy expressions
diff --git a/cpmpy/transformations/reification.py b/cpmpy/transformations/reification.py
index 76fec4226..e566beca0 100644
--- a/cpmpy/transformations/reification.py
+++ b/cpmpy/transformations/reification.py
@@ -1,5 +1,5 @@
 """
-    Transformations regarding reification constraints.
+    Transformations that rewrite reified constraints as needed.
 
     There are three types of reification (BV=BoolVar, BE=BoolExpr):
 
diff --git a/cpmpy/transformations/safening.py b/cpmpy/transformations/safening.py
index fdf773140..f2e9e0f1d 100644
--- a/cpmpy/transformations/safening.py
+++ b/cpmpy/transformations/safening.py
@@ -1,4 +1,5 @@
 """
+    Transforms partial functions into total functions.
 """
 
 from copy import copy
@@ -44,9 +45,10 @@ def no_partial_functions(lst_of_expr, _toplevel=None, _nbc=None, safen_toplevel=
         argument must equal the original argument so the two are coupled again. If `is_defined` is false, the new
         argument remains decoupled (can take any value, as will the function's output).
 
-        WARNING! Under the relational semantics, ``b <-> ~(partial==5)`` and ``b <-> (partial!=5)`` mean
-        different things! The second is ``b <-> (is_defined & (total!=5))`` the first is
-        ``b <-> (~is_defined | (total!=5))``.
+        .. warning::
+            Under the relational semantics, ``b <-> ~(partial==5)`` and ``b <-> (partial!=5)`` mean
+            different things! The second is ``b <-> (is_defined & (total!=5))`` the first is
+            ``b <-> (~is_defined | (total!=5))``.
 
 
         A clever observation of the implementation below is that for the above 3 expressions, the 'safe'
diff --git a/cpmpy/transformations/to_cnf.py b/cpmpy/transformations/to_cnf.py
index 23c7a08c1..019dc8a5b 100644
--- a/cpmpy/transformations/to_cnf.py
+++ b/cpmpy/transformations/to_cnf.py
@@ -1,12 +1,18 @@
 """
+  Meta-transformation for obtaining a CNF from a list of constraints.
+
   Converts the logical constraints into disjuctions using the tseitin transform,
-        including flattening global constraints that are :func:`~cpmpy.expressions.core.Expression.is_bool()` and not in `supported`.
+  including flattening global constraints that are :func:`~cpmpy.expressions.core.Expression.is_bool()` and not in `supported`.
+
+  .. note::
+    The transformation is no longer used by the SAT solvers, and may be outdated.
+    Check :meth:`CPM_pysat.transform <cpmpy.solvers.pysat.CPM_pysat.transform>` for an up-to-date alternative.
   
   Other constraints are copied verbatim so this transformation
-  can also be used in non-pure CNF settings
+  can also be used in non-pure CNF settings.
 
   The implementation first converts the list of constraints
-  to 'flat normal form', this already flattens subexpressions using
+  to **Flat Normal Form**, this already flattens subexpressions using
   auxiliary variables.
 
   What is then left to do is to tseitin encode the following into CNF:
@@ -26,7 +32,7 @@
 
 def to_cnf(constraints):
     """
-        Converts all logical constraints into Conjunctive Normal Form
+        Converts all logical constraints into **Conjunctive Normal Form**
 
         Arguments:
             constraints:    list[Expression] or Operator
@@ -38,7 +44,7 @@ def to_cnf(constraints):
 
 def flat2cnf(constraints):
     """
-        Converts from 'flat normal form' all logical constraints into Conjunctive Normal Form,
+        Converts from **Flat Normal Form** all logical constraints into **Conjunctive Normal Form**,
         including flattening global constraints that are :func:`~cpmpy.expressions.core.Expression.is_bool()` and not in `supported`.
 
         What is now left to do is to tseitin encode:

From 2de7df37d1df15f8cc6032cff819ee492a564fc1 Mon Sep 17 00:00:00 2001
From: Tias Guns <tias@ulyssis.org>
Date: Wed, 16 Apr 2025 22:26:36 +0200
Subject: [PATCH 09/39] add add() function, will use as default (#640)

---
 cpmpy/model.py                    |  3 ++-
 cpmpy/solvers/TEMPLATE.py         |  9 +++++----
 cpmpy/solvers/choco.py            |  3 ++-
 cpmpy/solvers/cpo.py              |  5 +++--
 cpmpy/solvers/exact.py            |  3 ++-
 cpmpy/solvers/gcs.py              |  3 ++-
 cpmpy/solvers/gurobi.py           |  5 +++--
 cpmpy/solvers/minizinc.py         |  3 ++-
 cpmpy/solvers/ortools.py          |  5 +++--
 cpmpy/solvers/pysat.py            |  3 ++-
 cpmpy/solvers/pysdd.py            |  3 ++-
 cpmpy/solvers/solver_interface.py | 10 +++++++---
 cpmpy/solvers/z3.py               |  3 ++-
 13 files changed, 37 insertions(+), 21 deletions(-)

diff --git a/cpmpy/model.py b/cpmpy/model.py
index 5e73cace1..7bcb3b6e0 100644
--- a/cpmpy/model.py
+++ b/cpmpy/model.py
@@ -80,7 +80,7 @@ def __init__(self, *args, minimize=None, maximize=None):
             self.minimize(minimize)
 
         
-    def __add__(self, con):
+    def add(self, con):
         """
         Add one or more constraints to the model.
 
@@ -115,6 +115,7 @@ def __add__(self, con):
 
         self.constraints.append(con)
         return self
+    __add__ = add  # Make __add__() (for the += operation) be the same as add() 
 
 
     def minimize(self, expr):
diff --git a/cpmpy/solvers/TEMPLATE.py b/cpmpy/solvers/TEMPLATE.py
index 7dddd6bf9..15079d03c 100644
--- a/cpmpy/solvers/TEMPLATE.py
+++ b/cpmpy/solvers/TEMPLATE.py
@@ -114,7 +114,7 @@ def __init__(self, cpm_model=None, subsolver=None):
 
         # initialise everything else and post the constraints/objective
         # [GUIDELINE] this superclass call should happen AFTER all solver-native objects are created.
-        #           internally, the constructor relies on __add__ which uses the above solver native object(s)
+        #           internally, the constructor relies on `add()` which uses the above solver native object(s)
         super().__init__(name="TEMPLATE", cpm_model=cpm_model)
 
 
@@ -254,7 +254,7 @@ def _make_numexpr(self, cpm_expr):
 
         # [GUIDELINE] not all solver interfaces have a native "numerical expression" object.
         #       in that case, this function may be removed and a case-by-case analysis of the numerical expression
-        #           used in the constraint at hand is required in __add__
+        #           used in the constraint at hand is required in `add()`
         #       For an example of such solver interface, check out solvers/choco.py or solvers/exact.py
 
         if is_num(cpm_expr):
@@ -279,7 +279,7 @@ def _make_numexpr(self, cpm_expr):
         raise NotImplementedError("TEMPLATE: Not a known supported numexpr {}".format(cpm_expr))
 
 
-    # `__add__()` first calls `transform()`
+    # `add()` first calls `transform()`
     def transform(self, cpm_expr):
         """
             Transform arbitrary CPMpy expressions to constraints the solver supports
@@ -305,7 +305,7 @@ def transform(self, cpm_expr):
         # ...
         return cpm_cons
 
-    def __add__(self, cpm_expr_orig):
+    def add(self, cpm_expr_orig):
         """
             Eagerly add a constraint to the underlying solver.
 
@@ -398,6 +398,7 @@ def __add__(self, cpm_expr_orig):
                 raise NotImplementedError("TEMPLATE: constraint not (yet) supported", cpm_expr)
 
         return self
+    __add__ = add  # avoid redirect in superclass
 
     # Other functions from SolverInterface that you can overwrite:
     # solveAll, solution_hint, get_core
diff --git a/cpmpy/solvers/choco.py b/cpmpy/solvers/choco.py
index 625931251..52a8b704e 100644
--- a/cpmpy/solvers/choco.py
+++ b/cpmpy/solvers/choco.py
@@ -379,7 +379,7 @@ def transform(self, cpm_expr):
 
         return cpm_cons
 
-    def __add__(self, cpm_expr):
+    def add(self, cpm_expr):
         """
             Eagerly add a constraint to the underlying solver.
 
@@ -408,6 +408,7 @@ def __add__(self, cpm_expr):
                 c.post()
 
         return self
+    __add__ = add  # avoid redirect in superclass
 
     def _get_constraint(self, cpm_expr):
         """
diff --git a/cpmpy/solvers/cpo.py b/cpmpy/solvers/cpo.py
index 13c99d6ec..846e0e323 100644
--- a/cpmpy/solvers/cpo.py
+++ b/cpmpy/solvers/cpo.py
@@ -312,7 +312,7 @@ def objective(self, expr, minimize=True):
     def has_objective(self):
         return self.cpo_model.get_objective() is not None
 
-    # `__add__()` first calls `transform()`
+    # `add()` first calls `transform()`
     def transform(self, cpm_expr):
         """
             Transform arbitrary CPMpy expressions to constraints the solver supports
@@ -338,7 +338,7 @@ def transform(self, cpm_expr):
         # no flattening required
         return cpm_cons
 
-    def __add__(self, cpm_expr):
+    def add(self, cpm_expr):
         """
             Eagerly add a constraint to the underlying solver.
 
@@ -366,6 +366,7 @@ def __add__(self, cpm_expr):
             self.cpo_model.add(cpo_con)
 
         return self
+    __add__ = add  # avoid redirect in superclass
 
     def _cpo_expr(self, cpm_con):
         """
diff --git a/cpmpy/solvers/exact.py b/cpmpy/solvers/exact.py
index 5b00b0fd0..036175990 100644
--- a/cpmpy/solvers/exact.py
+++ b/cpmpy/solvers/exact.py
@@ -448,7 +448,7 @@ def _add_xct_reif_right(self, head, sign, xct_cfvars, xct_rhs):
     def is_multiplication(cpm_expr): # helper function
         return isinstance(cpm_expr, Operator) and cpm_expr.name == 'mul'
 
-    def __add__(self, cpm_expr_orig):
+    def add(self, cpm_expr_orig):
         """
             Eagerly add a constraint to the underlying solver.
 
@@ -543,6 +543,7 @@ def __add__(self, cpm_expr_orig):
                 raise NotImplementedError(cpm_expr)  # if you reach this... please report on github
             
         return self
+    __add__ = add  # avoid redirect in superclass
 
     def get_core(self):
         from exact import Exact as xct
diff --git a/cpmpy/solvers/gcs.py b/cpmpy/solvers/gcs.py
index 12e0ac72d..49b8dfdf7 100644
--- a/cpmpy/solvers/gcs.py
+++ b/cpmpy/solvers/gcs.py
@@ -451,7 +451,7 @@ def verify(self, name=None, location=".", time_limit=None, display_output=False,
 
         return self.veripb_return_code
     
-    def __add__(self, cpm_cons):
+    def add(self, cpm_cons):
         """
         Post a (list of) CPMpy constraints(=expressions) to the solver
         Note that we don't store the constraints in a cpm_model,
@@ -649,6 +649,7 @@ def __add__(self, cpm_cons):
                 raise NotImplementedError(cpm_expr)
 
         return self
+    __add__ = add  # avoid redirect in superclass
 
 
         
diff --git a/cpmpy/solvers/gurobi.py b/cpmpy/solvers/gurobi.py
index b038b4d6f..c859d55fd 100644
--- a/cpmpy/solvers/gurobi.py
+++ b/cpmpy/solvers/gurobi.py
@@ -128,7 +128,7 @@ def __init__(self, cpm_model=None, subsolver=None):
         self.grb_model = gp.Model(env=GRB_ENV)
 
         # initialise everything else and post the constraints/objective
-        # it is sufficient to implement __add__() and minimize/maximize() below
+        # it is sufficient to implement add() and minimize/maximize() below
         super().__init__(name="gurobi", cpm_model=cpm_model)
 
     @property
@@ -338,7 +338,7 @@ def transform(self, cpm_expr):
         cpm_cons = only_positive_bv(cpm_cons)  # after linearization, rewrite ~bv into 1-bv
         return cpm_cons
 
-    def __add__(self, cpm_expr_orig):
+    def add(self, cpm_expr_orig):
       """
             Eagerly add a constraint to the underlying solver.
 
@@ -455,6 +455,7 @@ def __add__(self, cpm_expr_orig):
             raise NotImplementedError(cpm_expr)  # if you reach this... please report on github
 
       return self
+    __add__ = add  # avoid redirect in superclass
 
     def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from_model=False, **kwargs):
         """
diff --git a/cpmpy/solvers/minizinc.py b/cpmpy/solvers/minizinc.py
index 022e57770..8c14f4779 100644
--- a/cpmpy/solvers/minizinc.py
+++ b/cpmpy/solvers/minizinc.py
@@ -486,7 +486,7 @@ def transform(self, cpm_expr):
                      "lex_chain_lesseq", "among"}
         return decompose_in_tree(cpm_cons, supported, supported_reified=supported - {"circuit", "precedence"})
 
-    def __add__(self, cpm_expr):
+    def add(self, cpm_expr):
         """
             Translate a CPMpy constraint to MiniZinc string and add it to the solver
 
@@ -512,6 +512,7 @@ def __add__(self, cpm_expr):
             self.mzn_model.add_string(mzn_str)
 
         return self
+    __add__ = add  # avoid redirect in superclass
 
     def _convert_expression(self, expr) -> str:
         """
diff --git a/cpmpy/solvers/ortools.py b/cpmpy/solvers/ortools.py
index 318b294ac..6b86d7289 100644
--- a/cpmpy/solvers/ortools.py
+++ b/cpmpy/solvers/ortools.py
@@ -388,7 +388,7 @@ def transform(self, cpm_expr):
                                              # reified expr must go before this
         return cpm_cons
 
-    def __add__(self, cpm_expr):
+    def add(self, cpm_expr):
         """
             Eagerly add a constraint to the underlying solver.
 
@@ -414,11 +414,12 @@ def __add__(self, cpm_expr):
             self._post_constraint(con)
 
         return self
+    __add__ = add  # avoid redirect in superclass
 
     # TODO: 'reifiable' is an artefact from the early days
     # only 3 constraints support it (and,or,sum),
     # we can just add reified support for those and not need `reifiable` or returning the constraint
-    # then we can remove _post_constraint and have its code inside the for loop of __add__
+    # then we can remove _post_constraint and have its code inside the for loop of `add()`
     # like for other solvers
     def _post_constraint(self, cpm_expr, reifiable=False):
         """
diff --git a/cpmpy/solvers/pysat.py b/cpmpy/solvers/pysat.py
index 9844b74e1..c42a91229 100644
--- a/cpmpy/solvers/pysat.py
+++ b/cpmpy/solvers/pysat.py
@@ -295,7 +295,7 @@ def transform(self, cpm_expr):
         cpm_cons = only_positive_coefficients(cpm_cons)
         return cpm_cons
 
-    def __add__(self, cpm_expr_orig):
+    def add(self, cpm_expr_orig):
       """
             Eagerly add a constraint to the underlying solver.
 
@@ -390,6 +390,7 @@ def __add__(self, cpm_expr_orig):
             raise NotImplementedError(f"CPM_pysat: Non supported constraint {cpm_expr}")
 
       return self
+    __add__ = add  # avoid redirect in superclass
 
     def solution_hint(self, cpm_vars, vals):
         """
diff --git a/cpmpy/solvers/pysdd.py b/cpmpy/solvers/pysdd.py
index e50d0eef1..dbe126e8c 100644
--- a/cpmpy/solvers/pysdd.py
+++ b/cpmpy/solvers/pysdd.py
@@ -261,7 +261,7 @@ def transform(self, cpm_expr):
         cpm_cons = simplify_boolean(cpm_cons)  # for cleaning (BE >= 0) and such
         return cpm_cons
 
-    def __add__(self, cpm_expr):
+    def add(self, cpm_expr):
         """
             Eagerly add a constraint to the underlying solver.
 
@@ -310,6 +310,7 @@ def __add__(self, cpm_expr):
                                                 self._pysdd_expr(cpm_con))
 
         return self
+    __add__ = add  # avoid redirect in superclass
 
     def _pysdd_expr(self, cpm_con):
         """
diff --git a/cpmpy/solvers/solver_interface.py b/cpmpy/solvers/solver_interface.py
index 7f05393ea..80e291c49 100644
--- a/cpmpy/solvers/solver_interface.py
+++ b/cpmpy/solvers/solver_interface.py
@@ -78,7 +78,7 @@ def __init__(self, name="dummy", cpm_model=None, subsolver=None):
 
         # rest uses own API
         if cpm_model is not None:
-            # post all constraints at once, implemented in __add__()
+            # post all constraints at once, implemented in `add()`
             self += cpm_model.constraints
 
             # post objective
@@ -193,7 +193,7 @@ def transform(self, cpm_expr):
         """
         return toplevel_list(cpm_expr)  # replace by the transformations your solver needs
 
-    def __add__(self, cpm_expr):
+    def add(self, cpm_expr):
         """
             Eagerly add a constraint to the underlying solver.
 
@@ -216,9 +216,13 @@ def __add__(self, cpm_expr):
 
         # transform and post the constraints
         for con in self.transform(cpm_expr):
-            raise NotImplementedError("solver __add__(): abstract function, overwrite")
+            raise NotImplementedError("solver add(): abstract function, overwrite")
 
         return self
+    
+    # needed here for subclasses that don't do the more direct `__add__ = add` in their class
+    def __add__(self, cpm_expr):
+        return self.add(cpm_expr)
 
 
     # OPTIONAL functions
diff --git a/cpmpy/solvers/z3.py b/cpmpy/solvers/z3.py
index 5309cdd33..dc0e40095 100644
--- a/cpmpy/solvers/z3.py
+++ b/cpmpy/solvers/z3.py
@@ -309,7 +309,7 @@ def transform(self, cpm_expr):
         cpm_cons = decompose_in_tree(cpm_cons, supported, supported)
         return cpm_cons
 
-    def __add__(self, cpm_expr):
+    def add(self, cpm_expr):
         """
             Z3 supports nested expressions so translate expression tree and post to solver API directly
 
@@ -338,6 +338,7 @@ def __add__(self, cpm_expr):
             self.z3_solver.add(z3_con)
 
         return self
+    __add__ = add  # avoid redirect in superclass
 
     def _z3_expr(self, cpm_con):
         """

From 03a53dcee10b00d2b7cd8c46948a566601a65398 Mon Sep 17 00:00:00 2001
From: Dimos Tsouros <dimosts988@gmail.com>
Date: Thu, 17 Apr 2025 20:14:45 +0200
Subject: [PATCH 10/39] Handle non-positive time limit consistently (#642)

* Handle non-positive time limit with valueerror

* tests

* don't need the double if-statement
---
 cpmpy/solvers/choco.py    |  5 ++++-
 cpmpy/solvers/cpo.py      |  4 ++++
 cpmpy/solvers/exact.py    | 11 +++++++++--
 cpmpy/solvers/gcs.py      | 10 ++++++++++
 cpmpy/solvers/gurobi.py   |  5 ++++-
 cpmpy/solvers/minizinc.py |  8 ++++++++
 cpmpy/solvers/ortools.py  |  4 +++-
 cpmpy/solvers/pysat.py    |  5 ++++-
 cpmpy/solvers/pysdd.py    |  3 +++
 cpmpy/solvers/z3.py       |  3 +++
 tests/test_solvers.py     | 14 ++++++++++++++
 11 files changed, 66 insertions(+), 6 deletions(-)

diff --git a/cpmpy/solvers/choco.py b/cpmpy/solvers/choco.py
index 52a8b704e..10cfe9c6e 100644
--- a/cpmpy/solvers/choco.py
+++ b/cpmpy/solvers/choco.py
@@ -157,8 +157,11 @@ def solve(self, time_limit=None, **kwargs):
         self.chc_solver = self.chc_model.get_solver()
 
         start = time.time()
-
+        
+        # set time limit
         if time_limit is not None:
+            if time_limit <= 0:
+                raise ValueError("Time limit must be positive")
             self.chc_solver.limit_time(str(time_limit) + "s")
 
         if self.has_objective():
diff --git a/cpmpy/solvers/cpo.py b/cpmpy/solvers/cpo.py
index 846e0e323..9f38efadb 100644
--- a/cpmpy/solvers/cpo.py
+++ b/cpmpy/solvers/cpo.py
@@ -160,6 +160,10 @@ def solve(self, time_limit=None, **kwargs):
         # call the solver, with parameters
         if 'LogVerbosity' not in kwargs:
             kwargs['LogVerbosity'] = 'Quiet'
+        
+        # set time limit
+        if time_limit is not None and time_limit <= 0:
+            raise ValueError("Time limit must be positive")
         self.cpo_result = self.cpo_model.solve(TimeLimit=time_limit, **kwargs)
 
         # new status, translate runtime
diff --git a/cpmpy/solvers/exact.py b/cpmpy/solvers/exact.py
index 036175990..2323dd45e 100644
--- a/cpmpy/solvers/exact.py
+++ b/cpmpy/solvers/exact.py
@@ -198,10 +198,17 @@ def solve(self, time_limit=None, assumptions=None, **kwargs):
             self.assumption_dict = {xct_var: (xct_val,cpm_assump) for (xct_var, xct_val, cpm_assump) in zip(assump_vars,assump_vals,assumptions)}
             self.xct_solver.setAssumptions(list(zip(assump_vars,assump_vals)))
 
+        # set time limit
+        if time_limit is not None:
+            if time_limit <= 0:
+                raise ValueError("Time limit must be positive")
+            timeout = time_limit
+        else:
+            timeout = 0
+            
         # call the solver, with parameters
         start = time.time()
-        my_status, obj_val = self.xct_solver.toOptimum(timeout=time_limit if time_limit is not None else 0)
-        #                                     timeout=time_limit if time_limit is not None else 0)
+        my_status, obj_val = self.xct_solver.toOptimum(timeout=timeout)
         end = time.time()
 
         # new status, translate runtime
diff --git a/cpmpy/solvers/gcs.py b/cpmpy/solvers/gcs.py
index 49b8dfdf7..0da94f3d6 100644
--- a/cpmpy/solvers/gcs.py
+++ b/cpmpy/solvers/gcs.py
@@ -162,6 +162,10 @@ def solve(self, time_limit=None, prove=False, proof_name=None, proof_location=".
             self.proof_name = proof_name
         self.proof_location = proof_location
      
+        # set time limit
+        if time_limit is not None and time_limit <= 0:
+            raise ValueError("Time limit must be positive")
+                 
         # call the solver, with parameters    
         self.gcs_result = self.gcs.solve(
             all_solutions=self.has_objective(), 
@@ -209,6 +213,12 @@ def solve(self, time_limit=None, prove=False, proof_name=None, proof_location=".
 
         # Verify proof, if requested
         if verify:
+
+            # set time limit
+            if verify_time_limit is not None:
+                if verify_time_limit <= 0:
+                    raise ValueError("Time limit for verifying must be positive")
+
             self.verify(name=self.proof_name, location=proof_location, time_limit=verify_time_limit,
                         veripb_args=veripb_args, display_output=display_verifier_output)
             
diff --git a/cpmpy/solvers/gurobi.py b/cpmpy/solvers/gurobi.py
index c859d55fd..0b8afdde2 100644
--- a/cpmpy/solvers/gurobi.py
+++ b/cpmpy/solvers/gurobi.py
@@ -161,8 +161,11 @@ def solve(self, time_limit=None, solution_callback=None, **kwargs):
 
         # ensure all vars are known to solver
         self.solver_vars(list(self.user_vars))
-
+        
+        # set time limit
         if time_limit is not None:
+            if time_limit <= 0:
+                raise ValueError("Time limit must be positive")
             self.grb_model.setParam("TimeLimit", time_limit)
 
         # call the solver, with parameters
diff --git a/cpmpy/solvers/minizinc.py b/cpmpy/solvers/minizinc.py
index 8c14f4779..c575ce41f 100644
--- a/cpmpy/solvers/minizinc.py
+++ b/cpmpy/solvers/minizinc.py
@@ -250,6 +250,9 @@ def solve(self, time_limit=None, **kwargs):
             Does not store the ``minizinc.Instance()`` or ``minizinc.Result()``
         """
 
+        if time_limit is not None and time_limit <= 0:
+            raise ValueError("Time limit must be positive")
+
         # ensure all vars are known to solver
         self.solver_vars(list(self.user_vars))
 
@@ -736,6 +739,11 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
 
         import asyncio
 
+        # set time limit
+        if time_limit is not None:
+            if time_limit <= 0:
+                raise ValueError("Time limit must be positive")
+
         # HAD TO DEFINE OUR OWN ASYNC HANDLER
         coroutine = self._solveAll(display=display, time_limit=time_limit,
                                     solution_limit=solution_limit, **kwargs)
diff --git a/cpmpy/solvers/ortools.py b/cpmpy/solvers/ortools.py
index 6b86d7289..9b754bc7d 100644
--- a/cpmpy/solvers/ortools.py
+++ b/cpmpy/solvers/ortools.py
@@ -174,8 +174,10 @@ def solve(self, time_limit=None, assumptions=None, solution_callback=None, **kwa
         # ensure all user vars are known to solver
         self.solver_vars(list(self.user_vars))
 
-        # set time limit?
+        # set time limit
         if time_limit is not None:
+            if time_limit <= 0:
+                raise ValueError("Time limit must be positive")
             self.ort_solver.parameters.max_time_in_seconds = float(time_limit)
 
         if assumptions is not None:
diff --git a/cpmpy/solvers/pysat.py b/cpmpy/solvers/pysat.py
index c42a91229..6e8e614e5 100644
--- a/cpmpy/solvers/pysat.py
+++ b/cpmpy/solvers/pysat.py
@@ -191,8 +191,11 @@ def solve(self, time_limit=None, assumptions=None):
             self.assumption_vars = assumptions
 
         import time
-        # set time limit?
+        # set time limit
         if time_limit is not None:
+            if time_limit <= 0:
+                raise ValueError("Time limit must be positive")
+            
             from threading import Timer
             t = Timer(time_limit, lambda s: s.interrupt(), [self.pysat_solver])
             t.start()
diff --git a/cpmpy/solvers/pysdd.py b/cpmpy/solvers/pysdd.py
index dbe126e8c..d5c1e1a45 100644
--- a/cpmpy/solvers/pysdd.py
+++ b/cpmpy/solvers/pysdd.py
@@ -119,6 +119,9 @@ def solve(self, time_limit=None, assumptions=None):
             - checking for a solution is trivial after that
         """
 
+        if time_limit is not None:
+            raise NotImplementedError("PySDD.solve(), time_limit not (yet?) supported")
+        
         # ensure all vars are known to solver
         self.solver_vars(list(self.user_vars))
 
diff --git a/cpmpy/solvers/z3.py b/cpmpy/solvers/z3.py
index dc0e40095..156a9c633 100644
--- a/cpmpy/solvers/z3.py
+++ b/cpmpy/solvers/z3.py
@@ -161,7 +161,10 @@ def solve(self, time_limit=None, assumptions=[], **kwargs):
         # ensure all vars are known to solver
         self.solver_vars(list(self.user_vars))
 
+        # set time limit
         if time_limit is not None:
+            if time_limit <= 0:
+                raise ValueError("Time limit must be positive")
             # z3 expects milliseconds in int
             self.z3_solver.set(timeout=int(time_limit*1000))
 
diff --git a/tests/test_solvers.py b/tests/test_solvers.py
index 2705df7d1..0db8ef331 100644
--- a/tests/test_solvers.py
+++ b/tests/test_solvers.py
@@ -694,6 +694,20 @@ def test_installed_solvers(self, solver):
         s.solve()
         assert [int(a) for a in v.value()] == [0, 1, 0]
 
+    def test_time_limit(self, solver):
+        if solver == "pysdd": # pysdd does not support time limit
+            return
+        
+        x = cp.boolvar(shape=3)
+        m = cp.Model(x[0] | x[1] | x[2])
+        assert m.solve(solver=solver, time_limit=1)
+
+        try:
+            m.solve(solver=solver, time_limit=-1)
+            assert False
+        except ValueError:
+            pass
+
     def test_installed_solvers_solveAll(self, solver):
         # basic model
         v = cp.boolvar(3)

From 9df4926e9d58d91b9da250ec22f244ccb4f01ee2 Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <thomas.s2000@hotmail.com>
Date: Fri, 18 Apr 2025 10:35:48 +0200
Subject: [PATCH 11/39] Pass gurobi env params on construction

If empty=True is not set upon env creation, .start() is already called internally causing prints to stdout (like licence status). This messes up other printing if gurobi is imported for first time.
---
 cpmpy/solvers/gurobi.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/cpmpy/solvers/gurobi.py b/cpmpy/solvers/gurobi.py
index 0b8afdde2..d5fb041fb 100644
--- a/cpmpy/solvers/gurobi.py
+++ b/cpmpy/solvers/gurobi.py
@@ -102,8 +102,7 @@ def license_ok():
             global GRB_ENV
             if GRB_ENV is None:
                 # initialise the native gurobi model object
-                GRB_ENV = gp.Env()
-                GRB_ENV.setParam("OutputFlag", 0)
+                GRB_ENV = gp.Env(params={"OutputFlag": 0})
                 GRB_ENV.start()
             return True
         except Exception as e:

From 8154c97a5c9f921da9af13f35a95ce9da3ed0ee2 Mon Sep 17 00:00:00 2001
From: Tias Guns <tias@ulyssis.org>
Date: Fri, 18 Apr 2025 14:02:52 +0200
Subject: [PATCH 12/39] SolverLookup: add supported() and print_status() (#641)

Co-authored-by: Thomas Sergeys <thomas.s2000@hotmail.com>
---
 cpmpy/solvers/utils.py | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/cpmpy/solvers/utils.py b/cpmpy/solvers/utils.py
index 45c35c9f0..e4ea011f2 100644
--- a/cpmpy/solvers/utils.py
+++ b/cpmpy/solvers/utils.py
@@ -82,7 +82,27 @@ def base_solvers(cls):
                ]
 
     @classmethod
-    def solvernames(cls):
+    def print_status(cls):
+        """
+            Print all CPMpy solvers and their installation status on this system.
+        """
+        for (basename, CPM_slv) in cls.base_solvers():
+            if CPM_slv.supported():
+                print(f"{basename}: Supported, ready to use.")
+            else:
+                print(f"{basename}: Not supported (missing Python package, binary or license).")
+
+    @classmethod
+    def supported(cls):
+        """
+            Return the list of names of all solvers (and subsolvers) supported on this system.
+
+            If a solver name is returned, it means that the solver's `.supported()` function returns True
+            and it is hence ready for immediate use
+            (e.g. any separate binaries are also installed if necessary, and licenses are active if needed).
+
+            Typical use case is to use these names in `SolverLookup.get(name)`.
+        """
         names = []
         for (basename, CPM_slv) in cls.base_solvers():
             if CPM_slv.supported():
@@ -93,6 +113,12 @@ def solvernames(cls):
                         names.append(basename+":"+subn)
         return names
 
+    @classmethod
+    def solvernames(cls):
+        # The older (more indirectly named) way to get the list of names of *supported* solvers.
+        # Will be deprecated at some point.
+        return cls.supported()
+
     @classmethod
     def get(cls, name=None, model=None, **init_kwargs):
         """

From e49b871ac741129acb11c82d52df23d2d872cb20 Mon Sep 17 00:00:00 2001
From: ThomSerg <thomas.s2000@hotmail.com>
Date: Fri, 18 Apr 2025 18:15:40 +0200
Subject: [PATCH 13/39] Fix BoolVal in canonical comparison

---
 cpmpy/transformations/linearize.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/cpmpy/transformations/linearize.py b/cpmpy/transformations/linearize.py
index 13ab44fc4..a0ad70284 100644
--- a/cpmpy/transformations/linearize.py
+++ b/cpmpy/transformations/linearize.py
@@ -473,6 +473,8 @@ def canonical_comparison(lst_of_expr):
                 lhs2 = []
                 if isinstance(rhs, _NumVarImpl):
                     lhs2, rhs = [-1 * rhs], 0
+                elif isinstance(rhs, BoolVal):
+                    lhs2, rhs = [-1] if rhs.value() else [], 0 
                 elif isinstance(rhs, Operator) and rhs.name == "-":
                     lhs2, rhs = [rhs.args[0]], 0
                 elif isinstance(rhs, Operator) and rhs.name == "sum":
@@ -484,6 +486,7 @@ def canonical_comparison(lst_of_expr):
                                     if isinstance(b, _NumVarImpl)], \
                                     sum(-a * b for a, b in zip(rhs.args[0], rhs.args[1])
                                     if not isinstance(b, _NumVarImpl))
+                
                 # 2) add collected variables to lhs
                 if isinstance(lhs, Operator) and lhs.name == "sum":
                     lhs, rhs = sum([1 * a for a in lhs.args] + lhs2), rhs

From 585dbba3d5972d98f90756b115ba62f20a2e6352 Mon Sep 17 00:00:00 2001
From: Henk Bierlee <bierlee.henk@gmail.com>
Date: Fri, 18 Apr 2025 19:56:50 +0000
Subject: [PATCH 14/39] Undefault `pypblib` dependency for `pysat` (#649)

---
 .github/workflows/python-test.yml |  1 +
 cpmpy/solvers/pysat.py            | 42 ++++++++++++++++++-------------
 setup.py                          |  2 +-
 tests/test_pysat_wsum.py          | 17 ++++++++++++-
 4 files changed, 42 insertions(+), 20 deletions(-)

diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml
index 9959d1677..8653e7736 100644
--- a/.github/workflows/python-test.yml
+++ b/.github/workflows/python-test.yml
@@ -14,6 +14,7 @@ jobs:
           python -m pip install --upgrade pip
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
           pip install ".[test, z3, choco, exact, pysat, pysdd, choco, minizinc]"
+          pip install pypblib  # dependency of pysat for PB constraints
           pip install pytest-xdist
           sudo snap install minizinc --classic
       - name: Test with pytest
diff --git a/cpmpy/solvers/pysat.py b/cpmpy/solvers/pysat.py
index 6e8e614e5..e7f6557f1 100644
--- a/cpmpy/solvers/pysat.py
+++ b/cpmpy/solvers/pysat.py
@@ -21,12 +21,17 @@
     Installation
     ============
 
-    Requires that the 'python-sat' package is installed. If you want to also solve
-    pseudo-Boolean constraints, you should also install its optional dependency 'pblib', as follows:
+    Requires that the 'python-sat' package is installed:
 
     .. code-block:: console
 
-        $ pip install python-sat[pblib]
+        $ pip install pysat
+
+    If you want to also solve pseudo-Boolean constraints, you should also install its optional dependency 'pypblib', as follows:
+
+    .. code-block:: console
+
+        $ pip install pypblib
 
     See detailed installation instructions at:
     https://pysathq.github.io/installation
@@ -82,8 +87,6 @@ class CPM_pysat(SolverInterface):
 
     """
 
-    IMPORT_PYSAT_PBLIB_ERROR = ImportError("PySAT was installed without optional dependency `pblib`, which is required to encode (weighted) sums. To install PySAT with recommended optional dependencies, run `pip install cpmpy[pysat]`.")
-
     @staticmethod
     def supported():
         # try to import the package
@@ -93,6 +96,19 @@ def supported():
             # while we need the 'python-sat' package, some more checks:
             from pysat.formula import IDPool
             from pysat.solvers import Solver
+
+            from pysat import card
+            CPM_pysat._card = card  # native
+
+            # try to import pypblib and avoid ever re-import by setting `_pb`
+            if not hasattr(CPM_pysat, ("_pb")):
+                try:
+                    from pysat import pb  # require pypblib
+                    """The `pysat.pb` module if its dependency `pypblib` installed, `None` if we have not checked it yet, or `False` if we checked and it is *not* installed"""
+                    CPM_pysat._pb = pb
+                except (ModuleNotFoundError, NameError):  # pysat returns the wrong error type (latter i/o former)
+                    CPM_pysat._pb = None  # not installed, avoid reimporting
+
             return True
         except ModuleNotFoundError:
             return False
@@ -142,15 +158,6 @@ def __init__(self, cpm_model=None, subsolver=None):
         elif subsolver.startswith('pysat:'):
             subsolver = subsolver[6:] # strip 'pysat:'
 
-        # try to import the pblib module once
-        try:
-            from pysat import card, pb
-            self._card = card
-            self._pb = pb
-        except NameError:
-            self._card = None
-            self._pb = None
-
         # initialise the native solver object
         self.pysat_vpool = IDPool()
         self.pysat_solver = Solver(use_timer=True, name=subsolver)
@@ -441,8 +448,6 @@ def get_core(self):
 
     def _pysat_cardinality(self, cpm_expr, reified=False):
         """ Convert CPMpy comparison of `sum` (over Boolean variables) into PySAT list of clauses """
-        if self._card is None:
-            raise self.IMPORT_PYSAT_PBLIB_ERROR
 
         # unpack and transform to PySAT argument
         lhs, rhs = cpm_expr.args
@@ -468,9 +473,9 @@ def _pysat_cardinality(self, cpm_expr, reified=False):
             raise ValueError(f"PySAT: Expected Comparison to be either <=, ==, or >=, but was {cpm_expr.name}")
 
     def _pysat_pseudoboolean(self, cpm_expr):
-        """ Convert CPMpy comparison of `wsum` (over Boolean variables) into PySAT list of clauses """
+        """Convert CPMpy comparison of `wsum` (over Boolean variables) into PySAT list of clauses."""
         if self._pb is None:
-            raise self.IMPORT_PYSAT_PBLIB_ERROR
+            raise ImportError("The model contains a PB constraint, for which PySAT needs an additional dependency (PBLib). To install it, run `pip install pypblib`.")
 
         if cpm_expr.args[0].name != "wsum":
             raise NotSupportedError(
@@ -482,6 +487,7 @@ def _pysat_pseudoboolean(self, cpm_expr):
         lits = self.solver_vars(lhs.args[1])
         pysat_args = {"weights": lhs.args[0], "lits": lits, "bound": rhs, "vpool":self.pysat_vpool }
 
+
         if cpm_expr.name == "<=":
             return self._pb.PBEnc.atmost(**pysat_args).clauses
         elif cpm_expr.name == ">=":
diff --git a/setup.py b/setup.py
index 26f90def7..98b9f0748 100644
--- a/setup.py
+++ b/setup.py
@@ -44,7 +44,7 @@ def get_version(rel_path):
         "choco": ["pychoco>=0.2.1"],
         "exact": ["exact>=2.1.0"],
         "minizinc": ["minizinc"],
-        "pysat": ["python-sat[pblib]"],
+        "pysat": ["python-sat"],
         "gurobi": ["gurobipy"],
         "pysdd": ["pysdd"],
         "gcs": ["gcspy"],
diff --git a/tests/test_pysat_wsum.py b/tests/test_pysat_wsum.py
index 3af3191d2..bbd8451f1 100644
--- a/tests/test_pysat_wsum.py
+++ b/tests/test_pysat_wsum.py
@@ -1,9 +1,24 @@
 import unittest
+import pytest
 import cpmpy as cp 
 from cpmpy import *
 from cpmpy.solvers.pysat import CPM_pysat
-from cpmpy.transformations.to_cnf import to_cnf
 
+import importlib # can check for modules *without* importing them
+pblib_available = importlib.util.find_spec("pypblib") is not None
+
+@pytest.mark.skipif(pblib_available, reason="`pypblib` is installed")
+def test_pypblib_error():
+    # NOTE if you want to run this but pypblib is already installed, run `pip uninstall pypblib && pip install -e .[pysat]`
+    unittest.TestCase().assertRaises(
+            ImportError, # just solve a pb constraint with pypblib not installed
+            lambda : CPM_pysat(cp.Model(2*cp.boolvar() + 3 * cp.boolvar() + 5 * cp.boolvar() <= 6)).solve()
+        )
+
+    # this one should still work without `pypblib`
+    assert CPM_pysat(cp.Model(1*cp.boolvar() + 1 * cp.boolvar() + 1 * cp.boolvar() <= 2)).solve()
+
+@pytest.mark.skipif(not pblib_available, reason="pypblib not installed")
 class TestEncodePseudoBooleanConstraint(unittest.TestCase):
     def setUp(self):
         self.bv = boolvar(shape=3)

From 7826a14719550528575054375cb16e1934681f4d Mon Sep 17 00:00:00 2001
From: Wout <wout.vanroose@gmail.com>
Date: Fri, 18 Apr 2025 23:45:24 +0200
Subject: [PATCH 15/39] linearize objectives (#495)

* linear objectives contain no negboolviews

* add testcases

---------

Co-authored-by: OrestisLomis <orestis.lomisg7@gmail.com>
Co-authored-by: Tias Guns <tias@ulyssis.org>
---
 cpmpy/solvers/exact.py             |   9 +-
 cpmpy/solvers/gurobi.py            |   7 +-
 cpmpy/transformations/linearize.py | 138 +++++++++++++++++++++++------
 tests/test_trans_linearize.py      | 117 +++++++++++++++++++++++-
 4 files changed, 235 insertions(+), 36 deletions(-)

diff --git a/cpmpy/solvers/exact.py b/cpmpy/solvers/exact.py
index 2323dd45e..33a5200f6 100644
--- a/cpmpy/solvers/exact.py
+++ b/cpmpy/solvers/exact.py
@@ -54,12 +54,12 @@
 
 from .solver_interface import SolverInterface, SolverStatus, ExitStatus
 from ..expressions.core import *
-from ..expressions.variables import _BoolVarImpl, NegBoolView, _IntVarImpl, _NumVarImpl, intvar
+from ..expressions.variables import _BoolVarImpl, NegBoolView, _IntVarImpl, _NumVarImpl
 from ..transformations.comparison import only_numexpr_equality
 from ..transformations.flatten_model import flatten_constraint, flatten_objective
 from ..transformations.get_variables import get_variables
 from ..transformations.decompose_global import decompose_in_tree
-from ..transformations.linearize import linearize_constraint, only_positive_bv
+from ..transformations.linearize import linearize_constraint, only_positive_bv, only_positive_bv_wsum
 from ..transformations.reification import only_implies, reify_rewrite, only_bv_reifies
 from ..transformations.normalize import toplevel_list
 from ..transformations.safening import no_partial_functions
@@ -361,10 +361,11 @@ def objective(self, expr, minimize):
         self.objective_ = expr
         self.objective_is_min_ = minimize
 
-        # make objective function non-nested
+        # make objective function non-nested and with positive BoolVars only
         (flat_obj, flat_cons) = flatten_objective(expr)
-        self += flat_cons  # add potentially created constraints
+        flat_obj = only_positive_bv_wsum(flat_obj)  # remove negboolviews
         self.user_vars.update(get_variables(flat_obj))  # add objvars to vars
+        self += flat_cons  # add potentially created constraints
 
         # make objective function or variable and post
         xct_cfvars,xct_rhs = self._make_numexpr(flat_obj,0)
diff --git a/cpmpy/solvers/gurobi.py b/cpmpy/solvers/gurobi.py
index d5fb041fb..3aaad5005 100644
--- a/cpmpy/solvers/gurobi.py
+++ b/cpmpy/solvers/gurobi.py
@@ -52,7 +52,7 @@
 from ..transformations.decompose_global import decompose_in_tree
 from ..transformations.flatten_model import flatten_constraint, flatten_objective
 from ..transformations.get_variables import get_variables
-from ..transformations.linearize import linearize_constraint, only_positive_bv
+from ..transformations.linearize import linearize_constraint, only_positive_bv, only_positive_bv_wsum
 from ..transformations.normalize import toplevel_list
 from ..transformations.reification import only_implies, reify_rewrite, only_bv_reifies
 from ..transformations.safening import no_partial_functions
@@ -267,9 +267,10 @@ def objective(self, expr, minimize=True):
         from gurobipy import GRB
 
         # make objective function non-nested
-        (flat_obj, flat_cons) = (flatten_objective(expr))
+        (flat_obj, flat_cons) = flatten_objective(expr)
+        flat_obj = only_positive_bv_wsum(flat_obj)  # remove negboolviews
+        get_variables(flat_obj, collect=self.user_vars)  # add potentially created variables
         self += flat_cons
-        get_variables(flat_obj, collect=self.user_vars)  # add potentially created constraints
 
         # make objective function or variable and post
         obj = self._make_numexpr(flat_obj)
diff --git a/cpmpy/transformations/linearize.py b/cpmpy/transformations/linearize.py
index a0ad70284..be560aa6f 100644
--- a/cpmpy/transformations/linearize.py
+++ b/cpmpy/transformations/linearize.py
@@ -389,43 +389,43 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
 
 def only_positive_bv(lst_of_expr):
     """
-        Replaces constraints containing :class:`~cpmpy.expressions.variables.NegBoolView` with equivalent expression using only :class:`~cpmpy.expressions.variables.BoolVar`.
-        `lst_of_expr` is expected to be linearized. Only apply after applying :func:`linearize_constraint(cpm_expr) <linearize_constraint>`.
+        Replaces :class:`~cpmpy.expressions.comparison.Comparison` containing :class:`~cpmpy.expressions.variables.NegBoolView` with equivalent expression using only :class:`~cpmpy.expressions.variables.BoolVar`.
+        Comparisons are expected to be linearized. Only apply after applying :func:`linearize_constraint(cpm_expr) <linearize_constraint>`.
 
-        Resulting expression is linear.
+        Resulting expression is linear if the original expression was linear.
     """
     newlist = []
     for cpm_expr in lst_of_expr:
 
         if isinstance(cpm_expr, Comparison):
             lhs, rhs = cpm_expr.args
+            new_lhs = lhs
             new_cons = []
 
-            if isinstance(lhs, _NumVarImpl):
-                if isinstance(lhs,NegBoolView):
-                    lhs, rhs = Operator("wsum",[[-1], [lhs._bv]]), 1 - rhs
-
-            if lhs.name == "sum" and any(isinstance(a, NegBoolView) for a in lhs.args):
-                lhs = Operator("wsum",[[1]*len(lhs.args), lhs.args])
+            if isinstance(lhs, _NumVarImpl) or lhs.name in {"sum","wsum"}:
+                new_lhs, const = only_positive_bv_wsum_const(lhs)
+                rhs -= const
+            else:
+                # other operators in comparison such as "min", "max"
+                nbv_sel = [isinstance(a, NegBoolView) for a in lhs.args]
+                if any(nbv_sel):
+                    new_args = []
+                    for i, nbv in enumerate(nbv_sel):
+                        if nbv:
+                            aux = cp.boolvar()
+                            new_args.append(aux)
+                            new_cons += [aux + lhs.args[i]._bv == 1]  # aux == 1 - arg._bv
+                        else:
+                            new_args.append(lhs.args[i])
 
-            if lhs.name == "wsum":
-                weights, args = lhs.args
-                idxes = {i for i, a in enumerate(args) if isinstance(a, NegBoolView)}
-                nw, na = zip(*[(-w,a._bv) if i in idxes else (w,a) for i, (w,a) in enumerate(zip(weights, args))])
-                lhs = Operator("wsum", [list(nw), list(na)]) # force making wsum, even for arity = 1
-                rhs -= sum(weights[i] for i in idxes)
-
-            if isinstance(lhs, Operator) and lhs.name not in {"sum","wsum"}:
-            # other operators in comparison such as "min", "max"
-                lhs = copy.copy(lhs)
-                for i,arg in enumerate(list(lhs.args)):
-                    if isinstance(arg, NegBoolView):
-                        new_arg, cons = get_or_make_var(1 - arg)
-                        lhs.args[i] = new_arg
-                        new_cons += cons
+                    new_lhs = copy.copy(lhs)
+                    new_lhs.update_args(new_args)
 
-            newlist.append(eval_comparison(cpm_expr.name, lhs, rhs))
-            newlist += linearize_constraint(new_cons)
+            if new_lhs != lhs:
+                newlist.append(eval_comparison(cpm_expr.name, new_lhs, rhs))
+                newlist += new_cons  # already linear
+            else:
+                newlist.append(cpm_expr)
 
         # reification
         elif isinstance(cpm_expr, Operator) and cpm_expr.name == "->":
@@ -445,6 +445,91 @@ def only_positive_bv(lst_of_expr):
 
     return newlist
 
+def only_positive_bv_wsum(expr):
+    """
+        Replaces a var/sum/wsum expression containing :class:`~cpmpy.expressions.variables.NegBoolView` with an equivalent expression 
+        using only :class:`~cpmpy.expressions.variables.BoolVar`. 
+
+        It might add a constant term to the expression, if you want the constant separately, use :func:`only_positive_bv_wsum_const`.
+        
+        Arguments:
+        - `cpm_expr`: linear expression (sum, wsum, var)
+        
+        Returns tuple of:
+        - `pos_expr`: linear expression (sum, wsum, var) without NegBoolView
+    """
+    if isinstance(expr, _NumVarImpl) or expr.name in {"sum","wsum"}:
+        pos_expr, const = only_positive_bv_wsum_const(expr)
+        if const == 0:
+            return pos_expr
+        else:
+            assert isinstance(pos_expr, Operator) and pos_expr.name == "wsum", f"unexpected expression, should be wsum but got {pos_expr}"
+            # should we check if it already has a constant term?
+            return Operator("wsum", [pos_expr.args[0]+[1], pos_expr.args[1]+[const]])
+    else:
+        return expr
+
+def only_positive_bv_wsum_const(cpm_expr):
+    """
+        Replaces a var/sum/wsum expression containing :class:`~cpmpy.expressions.variables.NegBoolView` with an equivalent expression 
+        using only :class:`~cpmpy.expressions.variables.BoolVar` as well as a constant term that must be added to the new expression to be equivalent.
+
+        If you want the expression where the constant term is part of the wsum returned, use :func:`only_positive_bv_wsum`.
+        
+        Arguments:
+        - `cpm_expr`: linear expression (sum, wsum, var)
+        
+        Returns tuple of:
+        - `pos_expr`: linear expression (sum, wsum, var) without NegBoolView
+        - `const`: The difference between the original expression and the new expression, 
+                   i.e. a constant term that must be added to pos_expr to be an equivalent linear expression.
+    """
+    if isinstance(cpm_expr, _NumVarImpl):
+        if isinstance(cpm_expr,NegBoolView):
+            return Operator("wsum",[[-1], [cpm_expr._bv]]), 1
+        else:
+            return cpm_expr, 0
+
+    elif cpm_expr.name == "sum":
+        # indicator on arguments being negboolviews
+        nbv_sel = [isinstance(a, NegBoolView) for a in cpm_expr.args]
+        if any(nbv_sel):
+            const = 0
+            weights = []
+            variables = []
+            for i, nbv in enumerate(nbv_sel):
+                if nbv:
+                    const += 1
+                    weights.append(-1)
+                    variables.append(cpm_expr.args[i]._bv)
+                else:
+                    weights.append(1)
+                    variables.append(cpm_expr.args[i])
+            return Operator("wsum", [weights, variables]), const
+        else:
+            return cpm_expr, 0
+
+    elif cpm_expr.name == "wsum":
+        # indicator on arguments of the wsum variable being negboolviews
+        nbv_sel = [isinstance(a, NegBoolView) for a in cpm_expr.args[1]]
+        if any(nbv_sel):
+            # copy weights and variables
+            weights = [w for w in cpm_expr.args[0]]
+            variables = [v for v in cpm_expr.args[1]]
+            const = 0
+            for i, nbv in enumerate(nbv_sel):
+                if nbv:
+                    const += weights[i]
+                    weights[i] = -weights[i]
+                    variables[i] = variables[i]._bv
+            return Operator("wsum", [weights, variables]), const
+        else:
+            return cpm_expr, 0
+
+    else:
+        raise ValueError(f"unexpected expression, should be sum, wsum or var but got {cpm_expr}")
+
+
 def canonical_comparison(lst_of_expr):
 
     lst_of_expr = toplevel_list(lst_of_expr)               # ensure it is a list
@@ -574,4 +659,3 @@ def only_positive_coefficients(lst_of_expr):
             newlist.append(cpm_expr)
 
     return newlist
-
diff --git a/tests/test_trans_linearize.py b/tests/test_trans_linearize.py
index 4a41d77f4..5e8a45dd7 100644
--- a/tests/test_trans_linearize.py
+++ b/tests/test_trans_linearize.py
@@ -4,7 +4,9 @@
 from cpmpy.expressions import boolvar, intvar
 from cpmpy.expressions.core import Operator
 from cpmpy.expressions.utils import argvals
-from cpmpy.transformations.linearize import linearize_constraint, canonical_comparison, only_positive_bv, only_positive_coefficients
+from cpmpy.transformations.decompose_global import decompose_global
+from cpmpy.transformations.flatten_model import flatten_objective
+from cpmpy.transformations.linearize import linearize_constraint, canonical_comparison, only_positive_bv, only_positive_coefficients, only_positive_bv_wsum_const, only_positive_bv_wsum
 from cpmpy.expressions.variables import _IntVarImpl, _BoolVarImpl
 
 
@@ -40,9 +42,20 @@ def test_bug_168(self):
             iv = intvar(1, 9)
             e1 = (bv[0] * bv[1] == iv)
             s1 = cp.Model(e1).solve("gurobi")
-            s1 = cp.Model(e1).solve("ortools")
             self.assertTrue(s1)
             self.assertEqual([bv[0].value(), bv[1].value(), iv.value()],[True, True, 1])
+            
+    def test_bug_468(self):
+        from cpmpy.solvers import CPM_exact, CPM_gurobi
+        a, b, c = boolvar(shape=3)
+        m = cp.Model(cp.any([a, b, c]))
+        m.minimize(3*a + 4*~b + 3*~c)
+        if CPM_gurobi.supported():
+            m.solve("gurobi")
+            self.assertEqual([a.value(), b.value(), c.value()], [False, True, True])
+        if CPM_exact.supported():
+            m.solve("exact")
+            self.assertEqual([a.value(), b.value(), c.value()], [False, True, True])
 
     def test_constraint(self):
         x,y,z = [cp.intvar(0,5, name=n) for n in "xyz"]
@@ -385,6 +398,12 @@ def test_others(self):
         self.assertEqual("alldifferent(a,b,c)", str(cons))
 
 class testCanonical_comparison(unittest.TestCase):
+    def setUp(self):
+        _IntVarImpl.counter = 0
+        _BoolVarImpl.counter = 0
+        self.ivars = cp.intvar(1, 10, shape=(5,))
+        self.bvars = cp.boolvar((3,))
+    
     def test_sum(self):
         a,b,c = [cp.intvar(0,10,name=n) for n in "abc"]
         rhs = 5
@@ -465,3 +484,97 @@ def test_only_positive_bv_implied_by_literal(self):
     def test_only_positive_bv_implied_by_negated_literal(self):
         p = cp.boolvar(name="p")
         self.assertEqual(str([p <= 0]), str(only_positive_bv(linearize_constraint([~p]))))
+        
+        
+class testOnlyPositiveBv(unittest.TestCase):
+    def setUp(self):
+        _IntVarImpl.counter = 0
+        _BoolVarImpl.counter = 0
+        self.ivars = cp.intvar(1, 10, shape=(5,))
+        self.bvars = cp.boolvar((3,))
+
+    def test_only_positive_bv_wsum_const_positive_literal(self):
+        p = cp.boolvar(name="p")
+        self.assertEqual(str((p, 0)), str(only_positive_bv_wsum_const(p)))
+        
+    def test_only_positive_bv_wsum_const_negated_litral(self):
+        p = cp.boolvar(name="p")
+        self.assertEqual(str((Operator("wsum",[[-1],[p]]), 1)), str(only_positive_bv_wsum_const(~p)))
+        
+    def test_only_positive_bv_wsum_const_sum_positive_input(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        self.assertEqual(str((Operator("sum",[a,b,c]), 0)), str(only_positive_bv_wsum_const(a+b+c)))
+        
+    def test_only_positive_bv_wsum_const_sum(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        self.assertEqual(str((Operator("wsum",[[-1, -1, 1],[a,b,c]]), 2)), str(only_positive_bv_wsum_const(~a+~b+c)))
+        
+    def test_only_positive_bv_wsum_const_wsum_positive_input(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        self.assertEqual(str((Operator("wsum",[[4, 5, 1],[a,b,c]]), 0)), str(only_positive_bv_wsum_const(4*a+5*b+c)))
+        
+    def test_only_positive_bv_wsum_const_wsum(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        self.assertEqual(str((Operator("wsum",[[-4, 5, 1],[a,b,c]]), 4)), str(only_positive_bv_wsum_const(4*~a+5*b+c)))
+        
+    def test_only_positive_bv_wsum_const_non_linear(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        with self.assertRaises(ValueError) as cm:
+            only_positive_bv_wsum_const(~a * b * c)
+            self.assertEqual(str(cm.exception), "unexpected expression, should be sum, wsum or var but got ((~a) * (b)) * (c)")
+            
+    def test_only_positive_bv_wsum_positive_literal(self):
+        p = cp.boolvar(name="p")
+        obj = only_positive_bv_wsum(p)
+        self.assertEqual(str(obj), str(p))
+            
+    def test_only_positive_bv_wsum_negated_literal(self):
+        p = cp.boolvar(name="p")
+        obj = only_positive_bv_wsum(~p)
+        self.assertEqual(str(obj), str(Operator("wsum",[[-1, 1],[p, 1]])))
+        
+    def test_only_positive_bv_wsum_sum_positive_input(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        obj = only_positive_bv_wsum(a + b + c)
+        self.assertEqual(str(obj), str(Operator("sum",[a,b,c])))
+        
+    def test_only_positive_bv_wsum_sum(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        obj = only_positive_bv_wsum(~a + ~b + c)
+        self.assertEqual(str(obj), str(Operator("wsum",[[-1, -1, 1, 1],[a,b,c,2]])))
+        
+    def test_only_positive_bv_wsum_wsum_positive_input(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        obj = only_positive_bv_wsum(4*a + 5*b + c)
+        self.assertEqual(str(obj), str(Operator("wsum",[[4, 5, 1],[a,b,c]])))
+        
+    def test_only_positive_bv_wsum_wsum(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        obj = only_positive_bv_wsum(4*~a + 5*~b + c)
+        self.assertEqual(str(obj), str(Operator("wsum",[[-4, -5, 1, 1],[a,b,c,9]])))
+        
+    def test_only_positive_bv_wsum_non_linear_positive_input(self): # TODO: make boolvars
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        flat_obj, flat_cons = flatten_objective(a * b * c)
+        flat_obj = only_positive_bv_wsum(flat_obj)
+        self.assertEqual(str((flat_obj, flat_cons)), "(IV6, [((IV5) * (c)) == (IV6), ((a) * (b)) == (IV5)])")
+        
+    def test_only_positive_bv_wsum_non_linear(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        flat_obj, flat_cons = flatten_objective(~a * b * c)
+        flat_obj = only_positive_bv_wsum(flat_obj)
+        self.assertEqual(str((flat_obj, flat_cons)), "(IV6, [((IV5) * (c)) == (IV6), ((~a) * (b)) == (IV5)])")
+        
+    def test_only_flat_positive_bv_wsum_max(self):
+        a, b = [cp.boolvar(name=n) for n in "ab"]
+        expr = cp.max((~a * b), (a * ~b ))
+        flat_obj, flat_cons = flatten_objective(expr)
+        # self.assertEqual(str(expr.args), "(max((~a) * (b), (a) * (~b)))")
+        obj = only_positive_bv_wsum(flat_obj)
+        self.assertEqual(str((obj, flat_cons)), "(IV7, [(max(IV5,IV6)) == (IV7), ((~a) * (b)) == (IV5), ((a) * (~b)) == (IV6)])")
+        
+    def test_only_flat_positive_bv_max(self):
+        a, b, c = [cp.boolvar(name=n) for n in "abc"]
+        obj = only_positive_bv(linearize_constraint([cp.max(~a,b) >= c], supported={"sum", "wsum", "max"}))
+        self.assertEqual(str(obj), "[(max(BV3,b)) >= (c), (BV3) + (a) == 1]")
+        

From 6ed45372afb11296e3d188bda617ee11ec775d26 Mon Sep 17 00:00:00 2001
From: Dimos Tsouros <dimosts988@gmail.com>
Date: Mon, 21 Apr 2025 16:29:35 +0200
Subject: [PATCH 16/39] Convert ints to vars in GCC first argument for Choco
 (#646)

---
 cpmpy/solvers/choco.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cpmpy/solvers/choco.py b/cpmpy/solvers/choco.py
index 10cfe9c6e..85ccac66f 100644
--- a/cpmpy/solvers/choco.py
+++ b/cpmpy/solvers/choco.py
@@ -592,7 +592,7 @@ def _get_constraint(self, cpm_expr):
                 return self.chc_model.int_value_precede_chain(self._to_vars(cpm_expr.args[0]), cpm_expr.args[1])
             elif cpm_expr.name == "gcc":
                 vars, vals, occ = cpm_expr.args
-                return self.chc_model.global_cardinality(*self.solver_vars([vars, vals]), self._to_vars(occ), cpm_expr.closed)
+                return self.chc_model.global_cardinality(self._to_vars(vars), self.solver_vars(vals), self._to_vars(occ), cpm_expr.closed)
             else:
                 raise NotImplementedError(f"Unknown global constraint {cpm_expr}, should be decomposed! If you reach this, please report on github.")
 

From f501f15db560a7a8fe03a0da3c1bf90aff4f7a3d Mon Sep 17 00:00:00 2001
From: Dimos Tsouros <dimosts988@gmail.com>
Date: Thu, 24 Apr 2025 16:30:07 +0300
Subject: [PATCH 17/39] Fix in NValueExceptN for 1 value range (#645)

* fix in nvalueexceptn for 1 value range

* ensure bvars is array

* double check shape when making aux vars

* comment for readability

---------

Co-authored-by: IgnaceBleukx <ignace.bleukx@kuleuven.be>
---
 cpmpy/expressions/globalconstraints.py | 6 ++++++
 cpmpy/expressions/globalfunctions.py   | 4 ++--
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/cpmpy/expressions/globalconstraints.py b/cpmpy/expressions/globalconstraints.py
index 66402b405..9ec83445b 100644
--- a/cpmpy/expressions/globalconstraints.py
+++ b/cpmpy/expressions/globalconstraints.py
@@ -868,6 +868,9 @@ def decompose(self):
         """
         X, Y = cpm_array(self.args)
 
+        if len(X) == 0 == len(Y):
+            return [cp.BoolVal(False)], [] # based on the decomp, it's false...
+
         bvar = boolvar(shape=(len(X) + 1))
 
         # Constraint ensuring that each element in X is less than or equal to the corresponding element in Y,
@@ -914,6 +917,9 @@ def decompose(self):
         """
         X, Y = cpm_array(self.args)
 
+        if len(X) == 0 == len(Y):
+            return [cp.BoolVal(False)], [] # based on the decomp, it's false...
+
         bvar = boolvar(shape=(len(X) + 1))
         defining = [bvar == ((X <= Y) & ((X < Y) | bvar[1:]))]
         defining.append(bvar[-1] == (X[-1] <= Y[-1]))
diff --git a/cpmpy/expressions/globalfunctions.py b/cpmpy/expressions/globalfunctions.py
index d85629163..dba6b0f19 100644
--- a/cpmpy/expressions/globalfunctions.py
+++ b/cpmpy/expressions/globalfunctions.py
@@ -395,7 +395,7 @@ def decompose_comparison(self, cmp_op, cpm_rhs):
         constraints = []
 
         # introduce boolvar for each possible value
-        bvars = boolvar(shape=(ub+1-lb))
+        bvars = boolvar(shape=(ub+1-lb,)) # shape is tuple to ensure it is a 1D array
 
         args = cpm_array(self.args)
         # bvar is true if the value is taken by any variable
@@ -447,7 +447,7 @@ def decompose_comparison(self, cmp_op, cpm_rhs):
         constraints = []
 
         # introduce boolvar for each possible value
-        bvars = boolvar(shape=(ub + 1 - lb))
+        bvars = boolvar(shape=(ub+1-lb,)) # shape is tuple to ensure it is a 1D array
         idx_of_n = n - lb
         if 0 <= idx_of_n < len(bvars):
             count_of_vals = cp.sum(bvars[:idx_of_n]) + cp.sum(bvars[idx_of_n+1:])

From 5574948401d779a6dc27ef6a5831b5a47f7ce9cb Mon Sep 17 00:00:00 2001
From: Ignace Bleukx <ignace.bleukx@kuleuven.be>
Date: Fri, 2 May 2025 12:29:26 +0200
Subject: [PATCH 18/39] fix empty clause in gcs (#662)

* fix empty clause

* add comment
---
 cpmpy/solvers/gcs.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/cpmpy/solvers/gcs.py b/cpmpy/solvers/gcs.py
index 0da94f3d6..dbf1fce4f 100644
--- a/cpmpy/solvers/gcs.py
+++ b/cpmpy/solvers/gcs.py
@@ -481,7 +481,9 @@ def add(self, cpm_cons):
                 self.gcs.post_or([self.solver_var(cpm_expr)])
             elif isinstance(cpm_expr, BoolVal):
                 if not cpm_expr:
-                    self.gcs.post_or([])
+                    # bit a hack, empty clause does not work (issue #73 on gcs github)
+                    a = boolvar()
+                    self.gcs.post_and(self.solver_vars([a,~a]))
             elif isinstance(cpm_expr, Operator) or \
                 (cpm_expr.name == '==' and isinstance(cpm_expr.args[0], _BoolVarImpl) \
                 and not isinstance(cpm_expr.args[1], _NumVarImpl)): 

From 15951926ea9e6cd2506d9b9dff9addd968ef4732 Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Mon, 5 May 2025 16:45:04 +0200
Subject: [PATCH 19/39] Changelog recovery (#666)

* Changelog backport previous releases

* Add GitHub compare links
---
 changelog.md | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 175 insertions(+)

diff --git a/changelog.md b/changelog.md
index 1dee36de5..f0a5439a5 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,180 @@
 # Change log
 
+<!-- ---------------------------------- - ---------------------------------- -->
+
+## 0.9.24
+
+### Release Notes
+
+#### Enhancements and Features
+- **Safening of partial functions**: New transformation to safen partial function. [#515](https://github.com/CPMpy/cpmpy/pull/515)
+- **Update Choco interface with native reification**: Improved the Choco solver interface with native reification support. [#526](https://github.com/CPMpy/cpmpy/pull/526)  
+- **Reals in objective function**: Added support for real numbers in the objective function. [#529](https://github.com/CPMpy/cpmpy/pull/529)  
+- **Better naive grow**: Enhanced the "naive grow" strategy for better performance. [#528](https://github.com/CPMpy/cpmpy/pull/528)  
+- **Blocks world**: Introduced a "blocks world" example for demonstration purposes. [#533](https://github.com/CPMpy/cpmpy/pull/533)  
+- **Examples Colab links**: Added direct Colab links to examples for easier experimentation. [#553](https://github.com/CPMpy/cpmpy/pull/553)  
+- **Circuit decomposition for all ranges**: Extended circuit decomposition to handle all ranges. [#424](https://github.com/CPMpy/cpmpy/pull/424)  
+- **Global function in Z3 objective**: Introduced global functions in Z3 solver objectives. [#560](https://github.com/CPMpy/cpmpy/pull/560)  
+- **Z3 auto subsolver**: Implemented automatic subsolver selection for Z3 when solving optimization problems. [#567](https://github.com/CPMpy/cpmpy/pull/567)  
+- **Parametrize solver tests**: Streamlined solver test cases using parameterization. [#572](https://github.com/CPMpy/cpmpy/pull/572)  
+- **Linearize power**: Added linearization for power operations. [#538](https://github.com/CPMpy/cpmpy/pull/538)  
+- **Improve Boolean normalization for PySAT**: Enhanced normalization of Boolean terms for PySAT. [#569](https://github.com/CPMpy/cpmpy/pull/569)  
+
+#### Performance Improvements
+- **Has subexpr optimization**: Skip transformations of leaf expressions for improved efficiency. [#532](https://github.com/CPMpy/cpmpy/pull/532)  
+- **Only implied speedup**: Optimized "only implied" handling for significant speedups. [#541](https://github.com/CPMpy/cpmpy/pull/541)  
+- **Distribute tests over CPUs**: Distributed tests over 4 CPUs, reducing runtime from `21m30s` to `8m45s`. [#571](https://github.com/CPMpy/cpmpy/pull/571)  
+- **ndvar_getitem optimization**: Improved `ndvar_getitem` by moving fetch casts to initialization. [#550](https://github.com/CPMpy/cpmpy/pull/550) 
+- **Remove inline imports**: Instead use `import as x` at top of file. [#542](https://github.com/CPMpy/cpmpy/pull/542)  
+
+#### Bug Fixes
+- **Remove broadcast in min/max**: Fixed issues when forwarding to built-in min/max functions. [#536](https://github.com/CPMpy/cpmpy/pull/536)  
+- **Convert numpy array in Table constraint**: Ensured proper conversion of NumPy arrays to lists in Table constraints. [#540](https://github.com/CPMpy/cpmpy/pull/540)  
+- **Clear values on UNSAT**: Added functionality to clear variable values when UNSAT is detected. [#523](https://github.com/CPMpy/cpmpy/pull/523)  
+- **Fix cpm_array with order='F'**: Resolved issues with `cpm_array()` when using column-major order. [#555](https://github.com/CPMpy/cpmpy/pull/555)  
+- **Car sequencing index fix**: Corrected indexing issues in the car sequencing problem. [#565](https://github.com/CPMpy/cpmpy/pull/565)  
+
+#### Code Quality and Maintenance
+- **Improve exception messages**: Enhanced clarity of exception messages and removed unused imports. [#539](https://github.com/CPMpy/cpmpy/pull/539)  
+- **Edits to the docs**: Updated documentation for clarity and completeness. [#530](https://github.com/CPMpy/cpmpy/pull/530)    
+- **Gurobi license check**: Separated Gurobi license checks into a distinct process. [#566](https://github.com/CPMpy/cpmpy/pull/566)  
+- **Standardize solver version checks**: Unified approach to checking solver version compatibility. [#568](https://github.com/CPMpy/cpmpy/pull/568)  
+- **Update requirements**: Upped our minimal python requirement from 3.6 to 3.7. [#573](https://github.com/CPMpy/cpmpy/pull/573)
+
+**Full Changelog**: https://github.com/CPMpy/cpmpy/compare/v0.9.23...v0.9.24
+
+<!-- ---------------------------------- - ---------------------------------- -->
+
+## 0.9.23
+
+Quick release, because we want the updated tools to be available.
+
+### What's Changed
+* Extension to tools: MARCO and SMUS 
+* Added tests for incremental solving and fixed incemental solving with objective in Exact
+* Cumulative decomposition fix when capacity was numpy integer.
+
+**Full Changelog**: https://github.com/CPMpy/cpmpy/compare/v0.9.22...v0.9.23
+
+<!-- ---------------------------------- - ---------------------------------- -->
+
+## 0.9.22
+
+### What's New
+* New solver: GlasgowConstraintSolver (GCS)
+* Upgraded to Exact 2
+* Minizinc print: easily extract MiniZinc and FlatZinc text from CPMpy model.
+* Update TEMPLATE.py to make it clearer how to add new solvers.
+* SolverLookup gives clear error message in stead of returning None
+* allow kwargs in Model.solve()
+* call python builtins for sum, abs, min and max without expressions in the arguments.
+* All solvers now have a native_model() function, to allow native solver access.
+* It's now possible to name multiple new variables at once, by providing the names in a list.
+* Linearize transformation can now rewrite modulo (if multiplication is supported)
+* Fix behaviour of "all", "any", "max", "min", "sum", "prod" on higher dimensional NDVarArrays (maintain dimensionality)
+* Value function of expressions now always returns a python integer, where it could sometimes be a numpy integer.
+* Fixed performance issue where all solver vars where seen as user vars when solving with MiniZinc
+
+### Documentation
+* Overall improvement of documentation
+* update documentation of 'comparison' transformation
+
+### New Contributors
+Thanks to 2 new contributors!
+* [@ThomSerg](https://github.com/ThomSerg) and [@sin3000x](https://github.com/sin3000x)
+
+**Full Changelog**: https://github.com/CPMpy/cpmpy/compare/v0.9.21...v0.9.22
+
+<!-- ---------------------------------- - ---------------------------------- -->
+
+## 0.9.21
+
+### New Global constraints:
+* Increasing, Decreasing, IncreasingStrict, DecreasingStrict
+* Lexicographical ordering constraints: LexLess, LexLessEq, LexChainLess, LexChainLessEq
+* Scheduling constraints Precedence and NoOverlap
+* Closed version of GCC
+* AllDiffExceptN, AllEqualExceptN 
+* Nvalues except n
+* Negative table
+* Among
+
+### Bug Fixes:
+* count nested in a wsum crashed MiniZinc [#461](https://github.com/CPMpy/cpmpy/issues/461)
+* AllDifferentExcept0 now correctly works with MiniZinc
+* User variables that get simplified away during transformation steps are now saved.
+* Add missing case in simplify bool transformation.
+
+### Quality of life
+* Removed type restriction for InDomain
+* Extending automatic testsuite
+* Check if minizinc executable is installed
+
+**Full Changelog**: https://github.com/CPMpy/cpmpy/compare/v0.9.20...v0.9.21
+
+<!-- ---------------------------------- - ---------------------------------- -->
+
+## 0.9.20
+
+### What's Changed
+* Choco is now a tier 2 solver, available to use after installing the pychoco package! 
+* new DIMACS parser and writer
+* SolverLookup is now a classmethod for easier use of custom solvers.
+* Fixed a bug where expression bounds didn't get rounded to integers when creating an intvar
+* Added a warning when expressions have non-integer bounds, as these will be rounded
+* Fixed a bug in our helper function is_bool, now also recognises our BoolVal objects
+* Updated our ortools and minizinc version requirements.
+
+**Full Changelog**: https://github.com/CPMpy/cpmpy/compare/v0.9.19..v0.9.20
+
+<!-- ---------------------------------- - ---------------------------------- -->
+
+## 0.9.19
+
+### What's Changed
+* Update on tools/subsets, add mcs and mss tools with grow-variants.
+* Full propagation with exact
+* Adding NValue global constraint
+* Minizinc result now saved in solver object, this allows to access the solver statistics.
+
+### Documentation
+* Update docs for tools.
+* Docs on solver statistics
+* Format solver api, and add missing links in docs
+* Update version and copyright date
+* Remove bug where python comment (#) got interpreted as a header.
+
+### Bug Fixes
+* Properly handle reified global constraints for Minizinc
+* Correctly handle global constraints with list-arguments of length 1
+* Add missing edge case in flatten
+* Type check table constraint first argument, cannot be a constant.
+
+**Full Changelog**: https://github.com/CPMpy/cpmpy/compare/v0.9.18...v0.9.19
+
+<!-- ---------------------------------- - ---------------------------------- -->
+
+## 0.9.18
+Minor release with some bugfixes, we are trying to do monthly releases now, so they will be more concise.
+
+### What's new?
+* get_bounds() helper function now works on arrays and lists, returning arrays (lists) of bounds
+* Pysdd added to our automated GitHub tests
+* Pysdd does not support Xor anymore.
+
+### Bugfixes
+* Fixed Cumulative bug when capacity was a numpy int.
+* Cumulative now works in Minizinc with only one task.
+* Docs look good again
+* Corrected default parameter value in docs
+* Fixed visualisations in Nonogram and Room assignment notebook examples
+* Adopted the new ORtools 9.8 names of tuneable parameters.
+
+## New Contributors
+* [@KennyVDV](https://github.com/KennyVDV) made their first contribution by adding a new example: chess_position
+
+<!-- ---------------------------------- - ---------------------------------- -->
+
 ## 0.9.17
 Some new solvers supported at tier 3, update to our transformations and bugfixes.
 

From 251171f31740db9d4da089f459bea6a7426f90b0 Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Wed, 7 May 2025 09:59:53 +0200
Subject: [PATCH 20/39] Optional dependency 'all' solvers (#665)

* optional dependency all solvers

* Documentation for adding new solver to setup.py
---
 docs/adding_solver.md |  2 ++
 setup.py              | 32 ++++++++++++++++++--------------
 2 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/docs/adding_solver.md b/docs/adding_solver.md
index 641ac4949..61d99da74 100644
--- a/docs/adding_solver.md
+++ b/docs/adding_solver.md
@@ -17,6 +17,8 @@ Implementing the template consists of the following parts:
 
 For your new solver to appear in CPMpy's [API documentation](./api/solvers.rst), add a `.rst` file in ``/docs/api/solvers`` (copy one of the other solvers' file and make the necessary changes) and add your solver to the *"List of submodules"* and the *"List of classes"* in the file ``/cpmpy/solvers/__init__.py``.
 
+To ease the installation process of your solver, be sure to add it to CPMpy's `setup.py`. Simply add an entry to `solver_dependencies`, mapping the cpmpy-native name for your solver (the same one used when calling `model.solve(solver=<SOLVER_NAME>)`) to the name of your pip-installable Python package and all its required dependencies.
+
 ## Transformations and posting constraints
 
 CPMpy solver interfaces are *eager*, meaning that any CPMpy expression given to it (through `__add__()`) is immediately transformed (throught `transform()`) and then posted to the solver.
diff --git a/setup.py b/setup.py
index 98b9f0748..42207e37c 100644
--- a/setup.py
+++ b/setup.py
@@ -18,6 +18,21 @@ def get_version(rel_path):
 with open("README.md", "r") as readme_file:
     long_description = readme_file.read()
 
+
+solver_dependencies = {
+    "ortools": ["ortools"],
+    "z3": ["z3-solver"],
+    "choco": ["pychoco>=0.2.1"],
+    "exact": ["exact>=2.1.0"],
+    "minizinc": ["minizinc"],
+    "pysat": ["python-sat"],
+    "gurobi": ["gurobipy"],
+    "pysdd": ["pysdd"],
+    "gcs": ["gcspy"],
+    "cpo": ["docplex"],
+}
+solver_dependencies["all"] = list({pkg for group in solver_dependencies.values() for pkg in group}) 
+
 setup(
     name='cpmpy',
     version=get_version("cpmpy/__init__.py"),
@@ -35,26 +50,15 @@ def get_version(rel_path):
         'ortools>=9.9',
         'numpy>=1.5',
     ],
-    #extra dependency, only needed if minizinc is to be used.
-    extras_require={
-        "FULL":  ["minizinc"],
+    extras_require=(
         # Solvers
-        "ortools": ["ortools"],
-        "z3": ["z3-solver"],
-        "choco": ["pychoco>=0.2.1"],
-        "exact": ["exact>=2.1.0"],
-        "minizinc": ["minizinc"],
-        "pysat": ["python-sat"],
-        "gurobi": ["gurobipy"],
-        "pysdd": ["pysdd"],
-        "gcs": ["gcspy"],
-        "cpo": ["docplex"],
+        solver_dependencies | {
         # Tools
         # "xcsp3": ["pycsp3"], <- for when xcsp3 is merged
         # Other
         "test": ["pytest"],
         "docs": ["sphinx>=5.3.0", "sphinx_rtd_theme>=2.0.0", "myst_parser", "sphinx-automodapi", "readthedocs-sphinx-search>=0.3.2"],
-    },
+    }),
     classifiers=[
         "Programming Language :: Python :: 3 :: Only",
         "Programming Language :: Python :: 3.8",

From 88d867a368255a97cb1fc52cc69e0d4eb257381a Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Wed, 7 May 2025 10:13:21 +0200
Subject: [PATCH 21/39] Skip tests on missing pblib (#668)

* Fix failing test if `pysat` is not installed

* Update reasons for test skip

* Fix pysat availability check

* Skip tests with decorator

* Fix import

* Decorator to skip entire testcase class

* More test to skip

* Missing importlib

* Reusable decorators

* Without brackets?

* Revert "Without brackets?"

This reverts commit 61119a79592fa630b31ea6ed26539d5643ffa136.

* Remove decorator argument

* Combine pytest skip into decorator

* Missing comment

* Remove unnecessary import

---------

Co-authored-by: Hendrik 'Henk' Bierlee <bierlee.henk@gmail.com>
---
 tests/test_constraints.py       |   5 ++
 tests/test_globalconstraints.py |   3 +
 tests/test_pysat_cardinality.py |   2 +
 tests/test_pysat_wsum.py        |   5 +-
 tests/test_solvers.py           |  10 ++-
 tests/utils.py                  | 105 ++++++++++++++++++++++++++++++++
 6 files changed, 126 insertions(+), 4 deletions(-)
 create mode 100644 tests/utils.py

diff --git a/tests/test_constraints.py b/tests/test_constraints.py
index ef3684591..aadcdf09a 100644
--- a/tests/test_constraints.py
+++ b/tests/test_constraints.py
@@ -8,6 +8,8 @@
 
 import pytest
 
+from utils import skip_on_missing_pblib
+
 # CHANGE THIS if you want test a different solver
 #   make sure that `SolverLookup.get(solver)` works
 # also add exclusions to the 3 EXCLUDE_* below as needed
@@ -272,6 +274,7 @@ def verify(cons):
 
 
 @pytest.mark.parametrize(("solver","constraint"),list(_generate_inputs(bool_exprs)), ids=str)
+@skip_on_missing_pblib(skip_on_exception_only=True)
 def test_bool_constraints(solver, constraint):
     """
         Tests boolean constraint by posting it to the solver and checking the value after solve.
@@ -286,6 +289,7 @@ def test_bool_constraints(solver, constraint):
 
 
 @pytest.mark.parametrize(("solver","constraint"), list(_generate_inputs(comp_constraints)),  ids=str)
+@skip_on_missing_pblib(skip_on_exception_only=True)
 def test_comparison_constraints(solver, constraint):
     """
         Tests comparison constraint by posting it to the solver and checking the value after solve.
@@ -300,6 +304,7 @@ def test_comparison_constraints(solver, constraint):
 
 
 @pytest.mark.parametrize(("solver","constraint"), list(_generate_inputs(reify_imply_exprs)),  ids=str)
+@skip_on_missing_pblib(skip_on_exception_only=True)
 def test_reify_imply_constraints(solver, constraint):
     """
         Tests boolean expression by posting it to solver and checking the value after solve.
diff --git a/tests/test_globalconstraints.py b/tests/test_globalconstraints.py
index aaf4efa49..f3846165f 100644
--- a/tests/test_globalconstraints.py
+++ b/tests/test_globalconstraints.py
@@ -9,7 +9,10 @@
 from cpmpy.expressions.utils import STAR
 from cpmpy.solvers import CPM_minizinc
 
+from utils import skip_on_missing_pblib
 
+
+@skip_on_missing_pblib(skip_on_exception_only=True)
 class TestGlobal(unittest.TestCase):
     def test_alldifferent(self):
         """Test all different constraint with a set of
diff --git a/tests/test_pysat_cardinality.py b/tests/test_pysat_cardinality.py
index 04b20672e..c3dc2f61d 100644
--- a/tests/test_pysat_cardinality.py
+++ b/tests/test_pysat_cardinality.py
@@ -6,6 +6,7 @@
 from cpmpy.solvers.pysat import CPM_pysat
 from cpmpy.transformations.linearize import only_positive_coefficients
 
+from utils import skip_on_missing_pblib
 
 SOLVER = "pysat"
 
@@ -134,6 +135,7 @@ def test_pysat_different(self):
         self.assertTrue(ps.solve())
         self.assertGreaterEqual(sum(self.bvs.value()), 2)
 
+    @skip_on_missing_pblib()
     def test_pysat_card_implied(self):
         b = cp.boolvar()
         x = cp.boolvar(shape=5)
diff --git a/tests/test_pysat_wsum.py b/tests/test_pysat_wsum.py
index bbd8451f1..1de62dde3 100644
--- a/tests/test_pysat_wsum.py
+++ b/tests/test_pysat_wsum.py
@@ -5,9 +5,10 @@
 from cpmpy.solvers.pysat import CPM_pysat
 
 import importlib # can check for modules *without* importing them
+pysat_available = CPM_pysat.supported()
 pblib_available = importlib.util.find_spec("pypblib") is not None
 
-@pytest.mark.skipif(pblib_available, reason="`pypblib` is installed")
+@pytest.mark.skipif(not (pysat_available and not pblib_available), reason="`pysat` is not installed" if not pysat_available else "`pypblib` is installed")
 def test_pypblib_error():
     # NOTE if you want to run this but pypblib is already installed, run `pip uninstall pypblib && pip install -e .[pysat]`
     unittest.TestCase().assertRaises(
@@ -18,7 +19,7 @@ def test_pypblib_error():
     # this one should still work without `pypblib`
     assert CPM_pysat(cp.Model(1*cp.boolvar() + 1 * cp.boolvar() + 1 * cp.boolvar() <= 2)).solve()
 
-@pytest.mark.skipif(not pblib_available, reason="pypblib not installed")
+@pytest.mark.skipif(not (pysat_available and pblib_available), reason="`pysat` is not installed" if not pysat_available else "`pypblib` not installed")
 class TestEncodePseudoBooleanConstraint(unittest.TestCase):
     def setUp(self):
         self.bv = boolvar(shape=3)
diff --git a/tests/test_solvers.py b/tests/test_solvers.py
index 0db8ef331..bb470a87e 100644
--- a/tests/test_solvers.py
+++ b/tests/test_solvers.py
@@ -1,3 +1,4 @@
+import importlib
 import unittest
 import tempfile
 import pytest
@@ -15,6 +16,11 @@
 from cpmpy import SolverLookup
 from cpmpy.exceptions import MinizincNameException, NotSupportedError
 
+from utils import skip_on_missing_pblib
+
+pysat_available = CPM_pysat.supported()
+pblib_available = importlib.util.find_spec("pypblib") is not None
+
 class TestSolvers(unittest.TestCase):
 
     # should move this test elsewhere later
@@ -313,8 +319,8 @@ def test_pysat(self):
         self.assertFalse(ps2.solve(assumptions=[mayo]+[v for v in inds]))
         self.assertEqual(ps2.get_core(), [mayo,inds[6],inds[9]])
 
-    @pytest.mark.skipif(not CPM_pysat.supported(),
-                        reason="PySAT not installed")
+    @pytest.mark.skipif(not (pysat_available and pblib_available), reason="`pysat` is not installed" if not pysat_available else "`pypblib` not installed")
+    @skip_on_missing_pblib()
     def test_pysat_card(self):
         b = cp.boolvar()
         x = cp.boolvar(shape=5)
diff --git a/tests/utils.py b/tests/utils.py
new file mode 100644
index 000000000..35afd0c2c
--- /dev/null
+++ b/tests/utils.py
@@ -0,0 +1,105 @@
+import importlib
+import pytest
+from functools import wraps
+import cpmpy as cp
+
+# ---------------------------------------------------------------------------- #
+#                              Generic Decorators                              #
+# ---------------------------------------------------------------------------- #
+
+"""
+These should probably not be used on their own, 
+but rather as building blocks for the more "specific" decorators below.
+"""
+
+def skip_on_exception(exc_type, message_contains=None, skip_message=None):
+    """
+    Skip test when expected failure occurs.
+    """
+
+    def decorator(func):
+        """
+        The actual decorator that gets placed around the function.
+        """
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            """
+            The function that gets called instead of the decorated function.
+            """
+            try:
+                # Try calling the decorated function
+                return func(*args, **kwargs)
+            except exc_type as e:
+                # Check if expected exception
+                if message_contains is None or message_contains in str(e):
+                    msg = skip_message or f"Skipped due to {exc_type.__name__}: {e}"
+                    pytest.skip(msg) # expected -> skip test
+                raise  # Re-raise if not the expected exception
+        return wrapper
+    return decorator
+
+
+def apply_decorator_to_tests(decorator):
+    """
+    Decorator wrapper for unittest.TestCase classes.
+    Applies `decorator` to all methods with a name starting with `test_`.
+    """
+    def class_decorator(cls):
+        for attr_name in dir(cls):
+            if attr_name.startswith("test_"):
+                attr = getattr(cls, attr_name)
+                if callable(attr):
+                    setattr(cls, attr_name, decorator(attr))
+        return cls
+    return class_decorator
+
+
+def smart_decorator(method_decorator):
+    """
+    Wraps a method decorator so it can be applied to either:
+    - a function/method: applies the decorator directly
+    - a class: applies the decorator to all test_* methods
+    """
+    def wrapper(obj):
+        if isinstance(obj, type):
+            return apply_decorator_to_tests(method_decorator)(obj)
+        elif callable(obj):
+            return method_decorator(obj)
+        else:
+            raise TypeError("smart_decorator can only be used on classes or callables")
+    return wrapper
+
+
+# ---------------------------------------------------------------------------- #
+#                              Specific Decorators                             #
+# ---------------------------------------------------------------------------- #
+
+from cpmpy.solvers.pysat import CPM_pysat
+pblib_available = importlib.util.find_spec("pypblib") is not None
+
+def skip_on_missing_pblib(skip_on_exception_only:bool=False):
+    """
+    Skips the decorated test when the optional `pblib` dependency is not available on the current system.
+
+    Arguments:
+        skip_on_exception_only (bool): If set to `True`, still run the test but ignore any exception related to missing `pblib`.
+                                        If exception occurs, test gets reported as being skipped.
+                                       If set to `False`, test doesn't get run (even if test does not rely on `pblib`) 
+
+    Notes:
+        `@skip_on_missing_pblib()` should be used for test which we know require `pblib`. 
+            These tests then never get run, reducing runtime.
+        `@skip_on_missing_pblib(skip_on_exception_only=True)` should be used when we're not sure if it requires 
+            `pblib` but would like to ignore any exception related to missing `pblib` dependency.
+    """
+
+    if not skip_on_exception_only:
+        return pytest.mark.skipif(not pblib_available, reason="`pypblib` not installed")
+    
+    return smart_decorator(
+        skip_on_exception(
+            ImportError,
+            message_contains="PB constraint",
+            skip_message="`pypblib` not installed"
+        )
+    )

From a3395227783e674f671ad8e763cc2514faf01b1c Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Wed, 7 May 2025 10:22:05 +0200
Subject: [PATCH 22/39] Setup fixes (#664)

* Move setuptools required dependency

Checks whether solvers are supported make use of pkg_resources

* Setup README encoding

pip install -e failed on windows system
---
 setup.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/setup.py b/setup.py
index 42207e37c..9ebbf74df 100644
--- a/setup.py
+++ b/setup.py
@@ -15,7 +15,7 @@ def get_version(rel_path):
     else:
         raise RuntimeError("Unable to find version string.")
 
-with open("README.md", "r") as readme_file:
+with open("README.md", "r", encoding="utf8") as readme_file:
     long_description = readme_file.read()
 
 
@@ -49,6 +49,7 @@ def get_version(rel_path):
     install_requires=[
         'ortools>=9.9',
         'numpy>=1.5',
+        'setuptools',
     ],
     extras_require=(
         # Solvers

From 313bcd17fba2fb1266490f67e21e8aa7cf17a0b7 Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Wed, 7 May 2025 11:55:02 +0200
Subject: [PATCH 23/39] Last changes before release 0.9.25 (#670)

* Add setuptools to required deps in setup.py

* Skip test if pysat not installed

* assertEquals -> assertEqual

* Solution limit for gurobi

* Ignore more tests if pysat not installed

* changelog

* Add new commits to changelog

* Group similar changes in changelog

* Small reformulation in changelog
---
 changelog.md          | 62 +++++++++++++++++++++++++++++++++++++++++++
 tests/test_solvers.py |  5 ++--
 2 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/changelog.md b/changelog.md
index f0a5439a5..626376695 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,67 @@
 # Change log
 
+## 0.9.25
+
+### Added
+* **New solver**: IBM CP Optimizer [#576](https://github.com/CPMpy/cpmpy/pull/576)
+* **New global**: `ShortTable` [#469](https://github.com/CPMpy/cpmpy/pull/469)
+* `model.add()` as new default to add constraints to model (same behaviour as `+=`) [#640](https://github.com/CPMpy/cpmpy/pull/640)
+* Easy install of all solvers through the `"all"` optional dependency, i.e. `pip install cpmpy[all]` [#665](https://github.com/CPMpy/cpmpy/pull/665)
+* More complex variants of the Sudoku puzzle (in examples) [#577](https://github.com/CPMpy/cpmpy/pull/577)
+* API summery sheet [#629](https://github.com/CPMpy/cpmpy/pull/629)
+
+* Linearisation for `div`, `abs` and `mod` [#516](https://github.com/CPMpy/cpmpy/pull/516)
+* Linearisation for subtraction [#639](https://github.com/CPMpy/cpmpy/pull/639)
+* `div` linearisation for Gurobi [#593](https://github.com/CPMpy/cpmpy/pull/593)
+* Native cardinality constraints for PySAT [#588](https://github.com/CPMpy/cpmpy/pull/588)
+* `wsum` support for PySAT
+
+* Support for constants in `Element` global function [#630](https://github.com/CPMpy/cpmpy/pull/630)
+
+* `SolverLookup` now has `.supported()` and `.print_status()` to get information on the available solvers on the current system [#641](https://github.com/CPMpy/cpmpy/pull/641)
+* `solveAll()` now accepts solver-specific kwargs, just like `solve()` [#582](https://github.com/CPMpy/cpmpy/pull/582)
+
+* Optional dependencies for solvers and tools (setup.py) [#599](https://github.com/CPMpy/cpmpy/pull/599)
+* Documentation for all CPMpy exceptions [#622](https://github.com/CPMpy/cpmpy/pull/622)
+
+
+
+### Changed
+* Bumped minimal Python version from 3.7 to 3.8 [#575](https://github.com/CPMpy/cpmpy/pull/575)
+* `mod` and `div` now default to integer division
+* Improved reading of DIMACS formatted files [#587](https://github.com/CPMpy/cpmpy/pull/587)
+* Avoid max-based decomposition for `abs` if possible [#595](https://github.com/CPMpy/cpmpy/pull/595)
+* Cleanup semantics of Boolean Python builtins [#602](https://github.com/CPMpy/cpmpy/pull/602)
+* Performance optimisation of `simplify_bool` [#592](https://github.com/CPMpy/cpmpy/pull/592)
+* Ensure `AllDifferent` decomposition is linear [#614](https://github.com/CPMpy/cpmpy/pull/614)
+* Much improved README 
+* Improved docs formatting, especially for the Python API docstrings [#603](https://github.com/CPMpy/cpmpy/pull/603)
+* Improved API documentation of explanation tools [#512](https://github.com/CPMpy/cpmpy/pull/512)
+* Better exceptions for explanation tools [#512](https://github.com/CPMpy/cpmpy/pull/512)
+* Improve documentation of non-standard solver args passing for Exact [#616](https://github.com/CPMpy/cpmpy/pull/616)
+* General documentation improvements [#619](https://github.com/CPMpy/cpmpy/pull/619), [#633](https://github.com/CPMpy/cpmpy/pull/633), [#634](https://github.com/CPMpy/cpmpy/pull/634)
+* Skip subset of `PySAT` tests when optional dependency `pblib` is not available [#668](https://github.com/CPMpy/cpmpy/pull/668)
+
+### Fixed
+* Linearisation with boolean constants [#581](https://github.com/CPMpy/cpmpy/pull/581)
+* Linearisation of `AllDifferent` with integer constants [#547](https://github.com/CPMpy/cpmpy/pull/547)
+* Side conditions for `Precedence` global [#589](https://github.com/CPMpy/cpmpy/pull/589)
+* `simplify_bool` on non-CPMpy expressions [#626](https://github.com/CPMpy/cpmpy/pull/626)
+* Handling of negative variables in objective during linearisation [#495](https://github.com/CPMpy/cpmpy/pull/495)
+* Integers in `GCC` global for Choco-solver [#646](https://github.com/CPMpy/cpmpy/pull/646)
+* `NValueExceptN` for single value range [#645](https://github.com/CPMpy/cpmpy/pull/645)
+* Handling of empty clauses in GCS [#662](https://github.com/CPMpy/cpmpy/pull/662)
+* Missing user vars when calling `solveAll()`, resulting in incorrect number of solutions [#609](https://github.com/CPMpy/cpmpy/pull/609)
+* Consistent handling of non-positive `time_limit` [#642](https://github.com/CPMpy/cpmpy/pull/642)
+* Added `setuptools` to required dependencies (can be missing on some installs) [#664](https://github.com/CPMpy/cpmpy/pull/664)
+* DIMACS tempfiles on Windows [#601](https://github.com/CPMpy/cpmpy/pull/601)
+
+### Removed
+
+* Removed support for Python version 3.7 [#575](https://github.com/CPMpy/cpmpy/pull/575)
+
+**Full Changelog**: https://github.com/CPMpy/cpmpy/compare/v0.9.24...v0.9.25
+
 <!-- ---------------------------------- - ---------------------------------- -->
 
 ## 0.9.24
diff --git a/tests/test_solvers.py b/tests/test_solvers.py
index bb470a87e..ef19cc1dd 100644
--- a/tests/test_solvers.py
+++ b/tests/test_solvers.py
@@ -518,7 +518,7 @@ def test_parameters_to_exact(self):
         self.assertFalse(exact.solve())
 
         with open(proof_file+".proof", "r") as f:
-            self.assertEquals(f.readline()[:-1], "pseudo-Boolean proof version 1.1") # check header of proof-file
+            self.assertEqual(f.readline()[:-1], "pseudo-Boolean proof version 1.1") # check header of proof-file
 
     @pytest.mark.skipif(not CPM_choco.supported(),
                         reason="pychoco not installed")
@@ -863,4 +863,5 @@ def test_hidden_user_vars(self, solver):
         m = cp.Model([cp.AllDifferentExceptN([x], 1)])
         s = cp.SolverLookup().get(solver, m)
         assert len(s.user_vars) == 1 # check if var captured as a user_var
-        assert s.solveAll() == 4     # check if still correct number of solutions, even though empty model
+        solution_limit = 5 if solver == "gurobi" else None
+        assert s.solveAll(solution_limit=solution_limit) == 4     # check if still correct number of solutions, even though empty model

From 028219d97be8ad45755be553e2f90ec3458332e1 Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <thomas.s2000@hotmail.com>
Date: Wed, 7 May 2025 11:58:02 +0200
Subject: [PATCH 24/39] Bump version number

---
 cpmpy/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cpmpy/__init__.py b/cpmpy/__init__.py
index 74b2508a9..bab710adb 100644
--- a/cpmpy/__init__.py
+++ b/cpmpy/__init__.py
@@ -14,7 +14,7 @@
 """
 # Tias Guns, 2019-2024
 
-__version__ = "0.9.24"
+__version__ = "0.9.25"
 
 
 from .expressions import *

From 49df2d9bb68efe92dc663eb5ef6f55538011c45f Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <thomas.s2000@hotmail.com>
Date: Wed, 7 May 2025 11:59:33 +0200
Subject: [PATCH 25/39] release 0.9.25

---
 cpmpy/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cpmpy/__init__.py b/cpmpy/__init__.py
index bab710adb..e1922b1d3 100644
--- a/cpmpy/__init__.py
+++ b/cpmpy/__init__.py
@@ -12,7 +12,7 @@
     - `solvers`: CPMpy classes that translate a model into approriate calls of a solver's API
     - `transformations`: common methods for transforming expressions into other expressions, used by `solvers` modules to simplify/rewrite expressions
 """
-# Tias Guns, 2019-2024
+# Tias Guns, 2019-2025
 
 __version__ = "0.9.25"
 

From dab22cc0557179c4fd72c069217a167dde914231 Mon Sep 17 00:00:00 2001
From: Ignace Bleukx <ignace.bleukx@kuleuven.be>
Date: Wed, 7 May 2025 22:53:56 +0200
Subject: [PATCH 26/39] Fix inverse decomposition (#673)

* do safening before returning decomposition of inverse

* perf

* fix intendation

* re-enable inverse in testsuite

* fix comment
---
 cpmpy/expressions/globalconstraints.py | 17 ++++++++++++++++-
 tests/test_constraints.py              |  8 ++++----
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/cpmpy/expressions/globalconstraints.py b/cpmpy/expressions/globalconstraints.py
index 9ec83445b..0674010ea 100644
--- a/cpmpy/expressions/globalconstraints.py
+++ b/cpmpy/expressions/globalconstraints.py
@@ -374,9 +374,24 @@ def __init__(self, fwd, rev):
         super().__init__("inverse", [fwd, rev])
 
     def decompose(self):
+
         fwd, rev = self.args
         rev = cpm_array(rev)
-        return [cp.all(rev[x] == i for i, x in enumerate(fwd))], []
+
+        constraining, defining = [], []
+        for i,x in enumerate(fwd):
+            if is_num(x) and not 0 <= x < len(rev): 
+                return [cp.BoolVal(False)], [] # can never satisfy the Inverse constraint
+           
+            lb, ub = get_bounds(x)
+            if lb >= 0 and ub < len(rev): # safe, index is within bounds
+                constraining.append(rev[x] == i)
+            else: # partial! need safening here
+                is_defined, total_expr, toplevel = cp.transformations.safening._safen_range(rev[x], (0, len(rev)-1), 1)
+                constraining += [is_defined, total_expr == i]
+                defining += toplevel
+        
+        return constraining, defining
 
     def value(self):
         fwd = argvals(self.args[0])
diff --git a/tests/test_constraints.py b/tests/test_constraints.py
index aadcdf09a..8471c9f3f 100644
--- a/tests/test_constraints.py
+++ b/tests/test_constraints.py
@@ -33,10 +33,10 @@
 
 EXCLUDE_GLOBAL = {"pysat": NUM_GLOBAL,
                   "pysdd": NUM_GLOBAL | {"Xor"},
-                  "z3": {"Inverse"},
-                  "choco": {"Inverse"},
-                  "ortools":{"Inverse"},
-                  "exact": {"Inverse"},
+                  "z3": {},
+                  "choco": {},
+                  "ortools":{},
+                  "exact": {},
                   "minizinc": {"IncreasingStrict"}, # bug #813 reported on libminizinc
                   "gcs": {}
                   }

From 2409ab7f723b8927b5e0638ce52735cc354856e2 Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Mon, 12 May 2025 16:17:45 +0200
Subject: [PATCH 27/39] remove 3.9 syntax for setup (#675)

---
 setup.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/setup.py b/setup.py
index 9ebbf74df..583160942 100644
--- a/setup.py
+++ b/setup.py
@@ -51,15 +51,15 @@ def get_version(rel_path):
         'numpy>=1.5',
         'setuptools',
     ],
-    extras_require=(
+    extras_require={
         # Solvers
-        solver_dependencies | {
+        **solver_dependencies,
         # Tools
         # "xcsp3": ["pycsp3"], <- for when xcsp3 is merged
         # Other
         "test": ["pytest"],
         "docs": ["sphinx>=5.3.0", "sphinx_rtd_theme>=2.0.0", "myst_parser", "sphinx-automodapi", "readthedocs-sphinx-search>=0.3.2"],
-    }),
+    },
     classifiers=[
         "Programming Language :: Python :: 3 :: Only",
         "Programming Language :: Python :: 3.8",

From 25c2fec50b2f7454a6a324270aff52f66b0a928e Mon Sep 17 00:00:00 2001
From: Ignace Bleukx <ignace.bleukx@kuleuven.be>
Date: Fri, 16 May 2025 09:34:01 +0200
Subject: [PATCH 28/39] Check for bool conversion on Expressions (#660)

* check if __bool__ is called on expression

* fix failing tests

* add explicit testcases for container testing

* override __bool__ in comparison

* fix blocking clause in minizinc

* fix minizinc solution translation

* remove wrong test (tests if True == True...)

* ensure reproducability of linearize tests

* process review

* update valueerror
---
 cpmpy/expressions/core.py              | 10 ++++
 cpmpy/expressions/globalconstraints.py |  6 +-
 cpmpy/solvers/minizinc.py              | 25 ++++----
 cpmpy/transformations/linearize.py     |  2 +-
 tests/test_expressions.py              | 79 ++++++++++++++++++++------
 tests/test_flatten.py                  | 16 +++---
 tests/test_globalconstraints.py        | 12 ++--
 tests/test_inequality_chaining.py      | 14 -----
 tests/test_solvers.py                  | 12 ++--
 tests/test_tools_mus.py                |  4 +-
 tests/test_trans_linearize.py          | 10 +++-
 11 files changed, 118 insertions(+), 72 deletions(-)
 delete mode 100644 tests/test_inequality_chaining.py

diff --git a/cpmpy/expressions/core.py b/cpmpy/expressions/core.py
index 7f3583fce..cc1ac040d 100644
--- a/cpmpy/expressions/core.py
+++ b/cpmpy/expressions/core.py
@@ -430,6 +430,10 @@ def __invert__(self):
             raise TypeError("Not operator is only allowed on boolean expressions: {0}".format(self))
         return Operator("not", [self])
 
+    def __bool__(self):
+        raise ValueError(f"__bool__ should not be called on a CPMPy expression {self} as it will always return True\n"
+                         "Do not use an expression as argument in an `if` statement and use cpmpy.any, cpmpy.max instead of python builtins\n"
+                         "If you think this is an error, please report on github")
 
 class BoolVal(Expression):
     """
@@ -551,6 +555,12 @@ def __repr__(self):
             return "({}) {} ({})".format(self.args[0], self.name, self.args[1]) 
         # if not: prettier printing without braces
         return "{} {} {}".format(self.args[0], self.name, self.args[1]) 
+    
+    def __bool__(self):
+        # will be called when comparing elements in a container, but always with `==`
+        if self.name == "==":
+            return repr(self.args[0]) == repr(self.args[1])
+        super().__bool__() # default to exception
 
     # return the value of the expression
     # optional, default: None
diff --git a/cpmpy/expressions/globalconstraints.py b/cpmpy/expressions/globalconstraints.py
index 0674010ea..0b7737323 100644
--- a/cpmpy/expressions/globalconstraints.py
+++ b/cpmpy/expressions/globalconstraints.py
@@ -526,11 +526,11 @@ def decompose(self):
                they should be enforced toplevel.
         """
         expr, arr = self.args
-        lb, ub = expr.get_bounds()
-
+        lb, ub = get_bounds(expr)
+        
         defining = []
         #if expr is not a var
-        if not isinstance(expr,_IntVarImpl):
+        if not isinstance(expr,Expression):
             aux = intvar(lb, ub)
             defining.append(aux == expr)
             expr = aux
diff --git a/cpmpy/solvers/minizinc.py b/cpmpy/solvers/minizinc.py
index c575ce41f..f7e8de488 100644
--- a/cpmpy/solvers/minizinc.py
+++ b/cpmpy/solvers/minizinc.py
@@ -64,6 +64,7 @@
 from .solver_interface import SolverInterface, SolverStatus, ExitStatus
 from ..exceptions import MinizincNameException, MinizincBoundsException
 from ..expressions.core import Expression, Comparison, Operator, BoolVal
+from ..expressions.python_builtins import any as cpm_any
 from ..expressions.variables import _NumVarImpl, _IntVarImpl, _BoolVarImpl, NegBoolView, cpm_array
 from ..expressions.globalconstraints import DirectConstraint
 from ..expressions.utils import is_num, is_any_list, argvals, argval
@@ -368,19 +369,17 @@ async def _solveAll(self, display=None, time_limit=None, solution_limit=None, **
             if mzn_result.solution is None:
                 break
 
-            # display (and reverse-map first) if needed
-            if display is not None:
-                mznsol = mzn_result.solution
-
-                # fill in variable values
-                for cpm_var in self.user_vars:
-                    sol_var = self.solver_var(cpm_var)
-                    if hasattr(mznsol, sol_var):
-                        cpm_var._value = getattr(mznsol, sol_var)
-                    else:
-                        print("Warning, no value for ", sol_var)
+             # fill in variable values
+            mznsol = mzn_result.solution
+            for cpm_var in self.user_vars:
+                sol_var = self.solver_var(cpm_var)
+                if hasattr(mznsol, sol_var):
+                    cpm_var._value = getattr(mznsol, sol_var)
+                else:
+                    raise ValueError(f"Var {cpm_var} is unknown to the Minizinc solver, this is unexpected - please report on github...")
 
-                # and the actual displaying
+            # display if needed
+            if display is not None:
                 if isinstance(display, Expression):
                     print(argval(display))
                 elif isinstance(display, list):
@@ -394,7 +393,7 @@ async def _solveAll(self, display=None, time_limit=None, solution_limit=None, **
                 break
 
             # add nogood on the user variables
-            self += any([v != v.value() for v in self.user_vars])
+            self += cpm_any([v != v.value() for v in self.user_vars])
 
         if solution_count == 0:
             # clear user vars if no solution found
diff --git a/cpmpy/transformations/linearize.py b/cpmpy/transformations/linearize.py
index be560aa6f..a9f6d7ec6 100644
--- a/cpmpy/transformations/linearize.py
+++ b/cpmpy/transformations/linearize.py
@@ -421,7 +421,7 @@ def only_positive_bv(lst_of_expr):
                     new_lhs = copy.copy(lhs)
                     new_lhs.update_args(new_args)
 
-            if new_lhs != lhs:
+            if new_lhs is not lhs:
                 newlist.append(eval_comparison(cpm_expr.name, new_lhs, rhs))
                 newlist += new_cons  # already linear
             else:
diff --git a/tests/test_expressions.py b/tests/test_expressions.py
index b3fa59ae6..49e067cea 100644
--- a/tests/test_expressions.py
+++ b/tests/test_expressions.py
@@ -172,7 +172,7 @@ def test_mul_const(self):
         expr = self.ivar * 10
         self.assertIsInstance(expr, Operator)
         self.assertEqual(expr.name, "mul")
-        self.assertIn(self.ivar, expr.args)
+        self.assertIn(self.ivar, set(expr.args))
 
         expr = self.ivar * True
         self.assertEqual(expr.name, self.ivar.name)
@@ -180,11 +180,12 @@ def test_mul_const(self):
         expr = self.ivar * np.True_
         self.assertEqual(expr.name, self.ivar.name)
 
-        expr = self.ivar * False
-        self.assertEqual(0, expr)
-        # same for numpy false
-        expr = self.ivar * np.False_
-        self.assertEqual(0, expr)
+        # TODO do we want the following? see issue #342
+        # expr = self.ivar * False # this test failes now
+        # self.assertEqual(0, expr)
+        # # same for numpy false
+        # expr = self.ivar * np.False_
+        # self.assertEqual(0, expr)
 
 
 
@@ -193,20 +194,20 @@ def test_mul_var(self):
         expr = self.ivar * self.bvar
         self.assertIsInstance(expr, Operator)
         self.assertEqual(expr.name, "mul")
-        self.assertIn(self.ivar, expr.args)
-        self.assertIn(self.bvar, expr.args)
+        self.assertIn(self.ivar, set(expr.args))
+        self.assertIn(self.bvar, set(expr.args))
 
         #ivar and ivar
         expr = self.ivar * self.ivar
         self.assertIsInstance(expr, Operator)
         self.assertEqual(expr.name, "mul")
-        self.assertIn(self.ivar, expr.args)
+        self.assertIn(self.ivar, set(expr.args))
 
         #bvar and bvar
         expr = self.bvar * self.bvar
         self.assertIsInstance(expr, Operator)
         self.assertEqual(expr.name, "mul")
-        self.assertIn(self.bvar, expr.args)
+        self.assertIn(self.bvar, set(expr.args))
 
     def test_nullarg_mul(self):
         x = intvar(0,5,shape=3, name="x")
@@ -576,12 +577,6 @@ def test_dtype(self):
         self.assertEqual(int, type((a % b).value()))
 
 
-
-
-
-
-
-
 class TestBuildIns(unittest.TestCase):
 
     def setUp(self):
@@ -603,5 +598,57 @@ def test_max(self):
         self.assertEqual(str(gt), str(cp.max(v for v in self.x)))
         self.assertEqual(str(gt), str(cp.max(self.x[0], self.x[1], self.x[2])))
 
+
+class TestContainer(unittest.TestCase):
+
+    def setUp(self):
+        self.x = cp.intvar(0,10,name="x")
+        self.y = cp.intvar(0,10,name="y")
+        self.z = cp.intvar(0,10,name="z")
+
+    def test_list(self):
+        lst = [self.x, self.y, self.z]
+        assert lst == [self.x, self.y, self.z]
+        assert not lst == [self.x, self.z, self.y]
+        assert lst != [self.x, self.z, self.y]
+     
+    def test_set(self):
+        s = {self.x, self.y, self.z}
+        assert s == {self.x, self.y, self.z}
+        assert {self.x} <= s # test subset
+        assert s & {self.x} == {self.x} # test intersection
+        assert s | {self.x} == s # test union
+        assert s - {self.x} == {self.y, self.z} # test difference
+        assert s ^ {self.x} == {self.y, self.z} # test symmetric difference
+        assert s ^ {self.x, self.y} == {self.z}
+        assert s ^ {self.x, self.y, self.z} == set()
+
+        # tricky cases, force hash collisions
+        self.x.__hash__ = lambda self: 1
+        self.y.__hash__ = lambda self: 1
+        assert s == {self.x, self.y, self.z}
+        assert {self.x} <= s # test subset
+        assert s & {self.x} == {self.x} # test intersection
+        assert s | {self.x} == s # test union
+        assert s - {self.x} == {self.y, self.z} # test difference
+        assert s ^ {self.x} == {self.y, self.z} # test symmetric difference
+        assert s ^ {self.x, self.y} == {self.z}
+        assert s ^ {self.x, self.y, self.z} == set()
+
+    def test_dict(self):
+        d = {self.x: "x", self.y: "y", self.z: "z"}
+        assert d == {self.x: "x", self.y: "y", self.z: "z"}
+        assert d[self.x] == "x"
+        assert d[self.y] == "y"
+        assert d[self.z] == "z"
+
+        # tricky cases, force hash collisions
+        self.x.__hash__ = lambda self: 1
+        self.y.__hash__ = lambda self: 1
+        assert d == {self.x: "x", self.y: "y", self.z: "z"}
+        assert d[self.x] == "x"
+        assert d[self.y] == "y"
+        assert d[self.z] == "z"
+
 if __name__ == '__main__':
     unittest.main()
diff --git a/tests/test_flatten.py b/tests/test_flatten.py
index 9b1b8cdd3..5384c5260 100644
--- a/tests/test_flatten.py
+++ b/tests/test_flatten.py
@@ -49,31 +49,31 @@ def test_eq(self):
         (x,y,z) = self.bvars[:3]
 
         e = (x == y) 
-        self.assertEqual( e, flatten_constraint(e) )
+        self.assertEqual(str([e]), str(flatten_constraint(e)) )
         e = (x == ~y) 
-        self.assertEqual( e, flatten_constraint(e) )
+        self.assertEqual(str([e]), str(flatten_constraint(e)) )
         e = (a == b) 
-        self.assertEqual( e, flatten_constraint(e) )
+        self.assertEqual(str([e]), str(flatten_constraint(e)) )
 
     def test_nq(self):
         (a,b,c,d,e) = self.ivars[:5]
         (x,y,z) = self.bvars[:3]
 
         e = (x != y) 
-        self.assertEqual( e, flatten_constraint(e) )
+        self.assertEqual("[(~BV1) == (BV0)]", str(flatten_constraint(e)) )
         e = (x != ~y) 
-        self.assertEqual( e, flatten_constraint(e) )
+        self.assertEqual("[(~BV1) == (~BV0)]", str(flatten_constraint(e)) )
         e = (a != b) 
-        self.assertEqual( e, flatten_constraint(e) )
+        self.assertEqual("[(IV0) != (IV1)]", str(flatten_constraint(e)) )
 
     def test_eq_comp(self):
         (a,b,c,d,e) = self.ivars[:5]
         (x,y,z) = self.bvars[:3]
 
         e = ((a > 5) == x)
-        self.assertEqual( e, flatten_constraint(e) )
+        self.assertEqual("[(IV0 > 5) == (BV0)]", str(flatten_constraint(e)))
         e = (x == (b < 3))
-        self.assertEqual( e, flatten_constraint(e) )
+        self.assertEqual("[(IV1 < 3) == (BV0)]", str(flatten_constraint(e)))
         e = ((a > 5) == (b < 3))
         self.assertEqual(len(flatten_constraint(e)), 2)
     
diff --git a/tests/test_globalconstraints.py b/tests/test_globalconstraints.py
index f3846165f..3405226bb 100644
--- a/tests/test_globalconstraints.py
+++ b/tests/test_globalconstraints.py
@@ -6,7 +6,7 @@
 import cpmpy as cp
 from cpmpy.expressions.globalfunctions import GlobalFunction
 from cpmpy.exceptions import TypeError, NotSupportedError
-from cpmpy.expressions.utils import STAR
+from cpmpy.expressions.utils import STAR, argvals
 from cpmpy.solvers import CPM_minizinc
 
 from utils import skip_on_missing_pblib
@@ -297,7 +297,7 @@ def test_InDomain(self):
         model = cp.Model(cons)
         self.assertTrue(model.solve())
         self.assertEqual(iv.value(),1)
-        cons = cp.InDomain(min(iv_arr), vals)
+        cons = cp.InDomain(cp.min(iv_arr), vals)
         model = cp.Model(cons)
         self.assertTrue(model.solve())
         iv2 = cp.intvar(-8, 8)
@@ -305,25 +305,25 @@ def test_InDomain(self):
         cons = [cp.InDomain(iv, vals)]
         model = cp.Model(cons)
         self.assertTrue(model.solve())
-        self.assertIn(iv.value(), vals)
+        self.assertIn(iv.value(), argvals(vals))
         vals = [1, 5, 8, -4]
         bv = cp.boolvar()
         cons = [cp.InDomain(bv, vals)]
         model = cp.Model(cons)
         self.assertTrue(model.solve())
-        self.assertIn(bv.value(), vals)
+        self.assertIn(bv.value(), set(vals))
         vals = [iv2, 5, 8, -4]
         bv = cp.boolvar()
         cons = [cp.InDomain(bv, vals)]
         model = cp.Model(cons)
         self.assertTrue(model.solve())
-        self.assertIn(bv.value(), vals)
+        self.assertIn(bv.value(), argvals(vals))
         vals = [bv & bv, 5, 8, -4]
         bv = cp.boolvar()
         cons = [cp.InDomain(bv, vals)]
         model = cp.Model(cons)
         self.assertTrue(model.solve())
-        self.assertIn(bv.value(), vals)
+        self.assertIn(bv.value(), argvals(vals))
 
     def test_lex_lesseq(self):
         from cpmpy import BoolVal
diff --git a/tests/test_inequality_chaining.py b/tests/test_inequality_chaining.py
deleted file mode 100644
index c45318abf..000000000
--- a/tests/test_inequality_chaining.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from cpmpy import *
-import unittest
-
-class TestInequalityChaining(unittest.TestCase):
-    def test_chaining_lt(self):
-
-        bv1, bv2, bv3 = boolvar(shape=3)
-        c1  = (bv1 < bv2) and (bv2 < bv3)
-        c2  = (bv1 < bv2 < bv3)
-        self.assertEqual(str(c1), str(c2))
-
-
-if __name__ == '__main__':
-    unittest.main()
\ No newline at end of file
diff --git a/tests/test_solvers.py b/tests/test_solvers.py
index ef19cc1dd..ef49a405d 100644
--- a/tests/test_solvers.py
+++ b/tests/test_solvers.py
@@ -149,7 +149,7 @@ def on_solution_callback(self):
         s = CPM_ortools(m)
         s.ort_solver.parameters.enumerate_all_solutions=True
         cpm_status = s.solve(solution_callback=cb)
-        self.assertGreater(x[0], x[1])
+        self.assertGreater(x[0].value(), x[1].value())
         self.assertEqual(cb.solcount, 6)
 
 
@@ -176,7 +176,7 @@ def on_solution_callback(self):
         s = CPM_ortools(m)
         s.ort_solver.parameters.enumerate_all_solutions=True
         cpm_status = s.solve(solution_callback=cb)
-        self.assertGreater(x[0], x[1])
+        self.assertGreater(x[0].value(), x[1].value())
         self.assertEqual(cb.solcount, 6)
 
 
@@ -186,7 +186,7 @@ def on_solution_callback(self):
         cpm_status = s.solve(solution_callback=cb)
         self.assertEqual(s.objective_value(), 5.0)
 
-        self.assertGreater(x[0], x[1])
+        self.assertGreater(x[0].value(), x[1].value())
 
 
         # manually enumerating solutions
@@ -313,11 +313,11 @@ def test_pysat(self):
 
         # check get core, simple
         self.assertFalse(ps2.solve(assumptions=[mayo,~mayo]))
-        self.assertEqual(ps2.get_core(), [mayo,~mayo])
+        self.assertSetEqual(set(ps2.get_core()), set([mayo,~mayo]))
 
         # check get core, more realistic
         self.assertFalse(ps2.solve(assumptions=[mayo]+[v for v in inds]))
-        self.assertEqual(ps2.get_core(), [mayo,inds[6],inds[9]])
+        self.assertSetEqual(set(ps2.get_core()), set([mayo,inds[6],inds[9]]))
 
     @pytest.mark.skipif(not (pysat_available and pblib_available), reason="`pysat` is not installed" if not pysat_available else "`pypblib` not installed")
     @skip_on_missing_pblib()
@@ -490,7 +490,7 @@ def test_exact(self):
 
 
         def _trixor_callback():
-            assert bv[0]+bv[1]+bv[2] >= 1
+            assert (bv[0]+bv[1]+bv[2]).value() >= 1
 
         m = cp.Model([bv[0] | bv[1] | bv[2]])
         s = cp.SolverLookup.get("exact", m)
diff --git a/tests/test_tools_mus.py b/tests/test_tools_mus.py
index e15807c4c..54231baa2 100644
--- a/tests/test_tools_mus.py
+++ b/tests/test_tools_mus.py
@@ -25,8 +25,8 @@ def test_circular(self):
             (x[3] > x[1]).implies((x[3] > x[2]) & ((x[3] == 3) | (x[1] == x[2])))
         ]
 
-        self.assertEqual(self.mus_func(cons), cons[:3])
-        self.assertEqual(self.naive_func(cons), cons[:3])
+        self.assertEqual(set(self.mus_func(cons)), set(cons[:3]))
+        self.assertEqual(set(self.naive_func(cons)), set(cons[:3]))
 
     def test_bug_191(self):
         """
diff --git a/tests/test_trans_linearize.py b/tests/test_trans_linearize.py
index 5e8a45dd7..c34c4cf25 100644
--- a/tests/test_trans_linearize.py
+++ b/tests/test_trans_linearize.py
@@ -294,6 +294,10 @@ def test_others(self):
 
 class TestVarsLhs(unittest.TestCase):
 
+    def setUp(self): # reset counters
+        _IntVarImpl.counter = 0
+        _BoolVarImpl.counter = 0
+
     def test_trivial_unsat_sum(self):
         a,b,c = [cp.intvar(0,10,name=n) for n in "abc"]
         rhs = 5
@@ -337,9 +341,9 @@ def test_pow(self):
         cons = a ** 3 == b
         lin_cons = linearize_constraint([cons], supported={"sum", "wsum", "mul"})
 
-        self.assertEqual(lin_cons[0], "((a) * (a)) == (IV0)")
-        self.assertEqual(lin_cons[1], "((a) * (IV0)) == (IV1)")
-        self.assertEqual(lin_cons[2], "sum([1, -1] * [IV1, b]) == 0")
+        self.assertEqual(str(lin_cons[0]), "((a) * (a)) == (IV0)")
+        self.assertEqual(str(lin_cons[1]), "((a) * (IV0)) == (IV1)")
+        self.assertEqual(str(lin_cons[2]), "sum([1, -1] * [IV1, b]) == 0")
 
         # this is not supported
         cons = a ** b == 3

From 428dca3e742b5d189521186596c85eb8cdaad065 Mon Sep 17 00:00:00 2001
From: Ignace Bleukx <ignace.bleukx@kuleuven.be>
Date: Fri, 16 May 2025 19:29:00 +0200
Subject: [PATCH 29/39] update docs and error messages for canonical comparison
 (#678)

---
 cpmpy/transformations/linearize.py | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/cpmpy/transformations/linearize.py b/cpmpy/transformations/linearize.py
index a9f6d7ec6..a1b74c0d1 100644
--- a/cpmpy/transformations/linearize.py
+++ b/cpmpy/transformations/linearize.py
@@ -63,10 +63,10 @@
 from .. import Abs
 from ..exceptions import TransformationNotImplementedError
 
-from ..expressions.core import Comparison, Operator, BoolVal
+from ..expressions.core import Comparison, Expression, Operator, BoolVal
 from ..expressions.globalconstraints import GlobalConstraint, DirectConstraint
 from ..expressions.globalfunctions import GlobalFunction
-from ..expressions.utils import is_num, eval_comparison, get_bounds, is_true_cst, is_false_cst
+from ..expressions.utils import is_bool, is_num, eval_comparison, get_bounds, is_true_cst, is_false_cst
 
 from ..expressions.variables import _BoolVarImpl, boolvar, NegBoolView, _NumVarImpl, intvar
 
@@ -531,8 +531,16 @@ def only_positive_bv_wsum_const(cpm_expr):
 
 
 def canonical_comparison(lst_of_expr):
+    """
+        Canonicalize a comparison expression.
+        Transforms linear expressions, or a reification thereof into canonical form by:
+            - moving all variables to the left-hand side
+            - moving constants to the right-hand side
+
+        Expects the input constraints to be flat. Only apply after applying :func:`flatten_constraint`
+    """
 
-    lst_of_expr = toplevel_list(lst_of_expr)               # ensure it is a list
+    lst_of_expr = toplevel_list(lst_of_expr) # ensure it is a list
 
     newlist = []
     for cpm_expr in lst_of_expr:
@@ -550,7 +558,8 @@ def canonical_comparison(lst_of_expr):
 
         elif isinstance(cpm_expr, Comparison):
             lhs, rhs = cpm_expr.args
-            if isinstance(lhs, Comparison) and cpm_expr.name == "==":  # reification of comparison
+            if isinstance(lhs, Comparison) and (is_bool(rhs) or isinstance(rhs, Expression) and rhs.is_bool()):
+                assert cpm_expr.name == "==", "Expected a reification of a comparison here, but got {}".format(cpm_expr.name)
                 lhs = canonical_comparison(lhs)[0]
             elif is_num(lhs) or isinstance(lhs, _NumVarImpl) or (isinstance(lhs, Operator) and lhs.name in {"sum", "wsum"}):
                 # Bring all vars from rhs to lhs
@@ -578,8 +587,7 @@ def canonical_comparison(lst_of_expr):
                 elif isinstance(lhs, _NumVarImpl) or (isinstance(lhs, Operator) and lhs.name == "wsum"):
                     lhs = lhs + lhs2
                 else:
-                    raise ValueError(
-                        f"unexpected expression on lhs of expression, should be sum, wsum or intvar but got {lhs}")
+                    raise ValueError(f"unexpected expression on lhs of expression, should be sum, wsum or intvar but got {lhs}")
 
                 assert not is_num(lhs), "lhs cannot be an integer at this point!"
 
@@ -606,7 +614,7 @@ def canonical_comparison(lst_of_expr):
                     else:
                         raise ValueError(f"lhs should be sum or wsum, but got {lhs}")
                 else:
-                    assert isinstance(lhs, _NumVarImpl)
+                    assert isinstance(lhs, _NumVarImpl), f"Expected variable here, but got {lhs} in expression {cpm_expr}"
                     lhs = Operator("sum", [lhs])
 
             newlist.append(eval_comparison(cpm_expr.name, lhs, rhs))

From f4140fdf2e4574e80e425dcf832e764dc2380023 Mon Sep 17 00:00:00 2001
From: Tias Guns <tias@ulyssis.org>
Date: Mon, 19 May 2025 22:03:00 -0400
Subject: [PATCH 30/39] expr/utils: no need for copy (from pumpkin branch)

---
 cpmpy/expressions/utils.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/cpmpy/expressions/utils.py b/cpmpy/expressions/utils.py
index b511a83b8..036b7ec91 100644
--- a/cpmpy/expressions/utils.py
+++ b/cpmpy/expressions/utils.py
@@ -28,8 +28,6 @@
         eval_comparison
         get_bounds     
 """
-import copy
-
 import cpmpy as cp
 import numpy as np
 import math

From ff0bdb44a78c1faff3334b48909774d8d85624af Mon Sep 17 00:00:00 2001
From: Ignace Bleukx <ignace.bleukx@kuleuven.be>
Date: Tue, 20 May 2025 15:09:31 +0200
Subject: [PATCH 31/39] Regular constraint (#677)

* MDD constraint

* Regular constraint

* tests MDD constraint

* tests regular constraint

* modify regular and mdd decomposition to be correct if negated (removed symmetries linked to auxilliary vars)

* root node is the start of the first transition

* Improvement doc to MDD constraint

* Improvement doc to MDD constraint (typo)

* Improvement doc to Regular constraint (typo)

* Improvement tests MDD/Regular (typo)

* test_constraints for MDD and regular

* cleanup regular implementation

* add regular to ortools

* add regular to choco

* update tests

* fix choco interface

* fix bound for arguments to regular cons

* update docs on regular

* process review on regular

* enable for all solvers again

* remove duplicate IfThenElse

---------

Co-authored-by: hverhaeghe <helene.verhaeghe27@gmail.com>
---
 cpmpy/expressions/__init__.py          |  2 +-
 cpmpy/expressions/globalconstraints.py | 81 ++++++++++++++++++++++++++
 cpmpy/expressions/utils.py             |  8 +--
 cpmpy/solvers/choco.py                 | 19 +++++-
 cpmpy/solvers/ortools.py               |  7 ++-
 tests/test_constraints.py              |  5 +-
 tests/test_globalconstraints.py        | 28 +++++++++
 7 files changed, 140 insertions(+), 10 deletions(-)

diff --git a/cpmpy/expressions/__init__.py b/cpmpy/expressions/__init__.py
index 9f9a08765..3f6ed724e 100644
--- a/cpmpy/expressions/__init__.py
+++ b/cpmpy/expressions/__init__.py
@@ -24,7 +24,7 @@
 from .globalconstraints import AllDifferent, AllDifferentExcept0, AllDifferentExceptN, AllEqual, AllEqualExceptN, Circuit, Inverse, Table, ShortTable, Xor, Cumulative, \
     IfThenElse, GlobalCardinalityCount, DirectConstraint, InDomain, Increasing, Decreasing, IncreasingStrict, DecreasingStrict, \
     LexLess, LexLessEq, LexChainLess, LexChainLessEq, Precedence, NoOverlap, \
-    NegativeTable
+    NegativeTable, Regular
 from .globalconstraints import alldifferent, allequal, circuit # Old, to be deprecated
 from .globalfunctions import Maximum, Minimum, Abs, Element, Count, NValue, NValueExcept, Among
 from .core import BoolVal
diff --git a/cpmpy/expressions/globalconstraints.py b/cpmpy/expressions/globalconstraints.py
index 0b7737323..0715b7fff 100644
--- a/cpmpy/expressions/globalconstraints.py
+++ b/cpmpy/expressions/globalconstraints.py
@@ -108,6 +108,7 @@ def my_circuit_decomp(self):
         Table
         ShortTable
         NegativeTable
+        Regular
         IfThenElse
         InDomain
         Xor
@@ -473,7 +474,87 @@ def value(self):
         arrval = argvals(arr)
         tabval = argvals(tab)
         return arrval not in tabval
+    
+
+class Regular(GlobalConstraint):
+    """
+    Regular-constraint (or Automaton-constraint)
+    Takes as input a sequence of variables and a automaton representation using a transition table.
+    The constraint is satisfied if the sequence of variables corresponds to an accepting path in the automaton.
+
+    The automaton is defined by a list of transitions, a starting node and a list of accepting nodes.
+    The transitions are represented as a list of tuples, where each tuple is of the form (id1, value, id2).
+    An id is an integer or string representing a state in the automaton, and value is an integer representing the value of the variable in the sequence.
+    The starting node is an integer or string representing the starting state of the automaton.
+    The accepting nodes are a list of integers or strings representing the accepting states of the automaton.
+
+    Example: an automaton that accepts the language 0*10* (exactly 1 variable taking value 1) is defined as:
+        cp.Regular(array = cp.intvar(0,1, shape=4),
+                   transitions = [("A",0,"A"), ("A",1,"B"), ("B",0,"C"), ("C",0,"C")],
+                   start = "A",
+                   accepting = ["C"])
+    """
+    def __init__(self, array, transitions, start, accepting):
+        array = flatlist(array)
+        if not all(isinstance(x, Expression) for x in array):
+            raise TypeError("The first argument of a regular constraint should only contain variables/expressions")
+        
+        if not is_any_list(transitions):
+            raise TypeError("The second argument of a regular constraint should be a list of transitions")
+        _node_type = type(transitions[0][0])
+        for s,v,e in transitions:
+            if not isinstance(s, _node_type) or not isinstance(e, _node_type) or not isinstance(v, int):
+                raise TypeError(f"The second argument of a regular constraint should be a list of transitions ({_node_type}, int, {_node_type})")
+        if not isinstance(start, _node_type):
+            raise TypeError("The third argument of a regular constraint should be a node id")
+        if not (is_any_list(accepting) and all(isinstance(e, _node_type) for e in accepting)):
+            raise TypeError("The fourth argument of a regular constraint should be a list of node ids")
+        super().__init__("regular", [array, transitions, start, list(accepting)])
+
+        self.nodes = set()
+        self.trans_dict = {}
+        for s, v, e in transitions:
+            self.nodes.update([s,e])
+            self.trans_dict[(s, v)] = e
+        self.nodes = sorted(self.nodes)
+        # normalize node_ids to be 0..n-1, allows for smaller domains
+        self.node_map = {n: i for i, n in enumerate(self.nodes)}
 
+    def decompose(self):
+        # Decompose to transition table using Table constraints
+        
+        arr, transitions, start, accepting = self.args
+        lbs, ubs = get_bounds(arr)
+        lb, ub = min(lbs), max(ubs)
+        
+        transitions = [[self.node_map[n_in], v, self.node_map[n_out]] for n_in, v, n_out in transitions]
+
+        # add a sink node for transitions that are not defined
+        sink = len(self.nodes)
+        transitions += [[self.node_map[n], v, sink] for n in self.nodes for v in range(lb, ub + 1) if (n, v) not in self.trans_dict]
+        transitions += [[sink, v, sink] for v in range(lb, ub + 1)]
+
+        # keep track of current state when traversing the array
+        state_vars = intvar(0, sink, shape=len(arr))
+        id_start = self.node_map[start]
+        # optimization: we know the entry node of the automaton, results in smaller table
+        defining = [Table([arr[0], state_vars[0]], [[v,e] for s,v,e in transitions if s == id_start])]        
+        # define the rest of the automaton using transition table
+        defining += [Table([state_vars[i - 1], arr[i], state_vars[i]], transitions) for i in range(1, len(arr))]
+        
+        # constraint is satisfied iff last state is accepting
+        return [InDomain(state_vars[-1], [self.node_map[e] for e in accepting])], defining
+
+    def value(self):
+        arr, transitions, start, accepting = self.args
+        arrval = [argval(a) for a in arr]
+        curr_node = start
+        for v in arrval:
+            if (curr_node, v) in self.trans_dict:
+                curr_node = self.trans_dict[curr_node, v]
+            else:
+                return False
+        return curr_node in accepting
 
 # syntax of the form 'if b then x == 9 else x == 0' is not supported (no override possible)
 # same semantic as CPLEX IfThenElse constraint
diff --git a/cpmpy/expressions/utils.py b/cpmpy/expressions/utils.py
index 036b7ec91..5eb79b1fd 100644
--- a/cpmpy/expressions/utils.py
+++ b/cpmpy/expressions/utils.py
@@ -28,6 +28,7 @@
         eval_comparison
         get_bounds     
 """
+
 import cpmpy as cp
 import numpy as np
 import math
@@ -95,7 +96,6 @@ def is_any_list(arg):
     """
     return isinstance(arg, (list, tuple, np.ndarray))
 
-
 def flatlist(args):
     """ recursively flatten arguments into one single list
     """
@@ -122,7 +122,7 @@ def all_pairs(args):
 
 def argval(a):
     """ returns .value() of Expression, otherwise the variable itself
-        
+
         We check with hasattr instead of isinstance to avoid circular dependency
     """
     if hasattr(a, "value"):
@@ -199,7 +199,7 @@ def implies(expr, other):
     elif is_true_cst(expr):
         return other
     elif is_false_cst(expr):
-        return BoolVal(True)
+        return cp.BoolVal(True)
     else:
         return expr.implies(other)
 
@@ -210,5 +210,3 @@ def is_star(arg):
         Check if arg is star as used in the ShortTable global constraint
     """
     return isinstance(arg, type(STAR)) and arg == STAR
-
-
diff --git a/cpmpy/solvers/choco.py b/cpmpy/solvers/choco.py
index 85ccac66f..9f9415802 100644
--- a/cpmpy/solvers/choco.py
+++ b/cpmpy/solvers/choco.py
@@ -63,7 +63,7 @@
 from ..transformations.linearize import canonical_comparison
 from ..transformations.safening import no_partial_functions
 from ..transformations.reification import reify_rewrite
-from ..exceptions import ChocoBoundsException
+from ..exceptions import ChocoBoundsException, NotSupportedError
 
 
 class CPM_choco(SolverInterface):
@@ -370,7 +370,7 @@ def transform(self, cpm_expr):
 
         cpm_cons = toplevel_list(cpm_expr)
         supported = {"min", "max", "abs", "count", "element", "alldifferent", "alldifferent_except0", "allequal",
-                     "table", 'negative_table', "short_table", "InDomain", "cumulative", "circuit", "gcc", "inverse", "nvalue", "increasing",
+                     "table", 'negative_table', "short_table", "regular", "InDomain", "cumulative", "circuit", "gcc", "inverse", "nvalue", "increasing",
                      "decreasing","strictly_increasing","strictly_decreasing","lex_lesseq", "lex_less", "among", "precedence"}
 
         cpm_cons = no_partial_functions(cpm_cons)
@@ -575,6 +575,21 @@ def _get_constraint(self, cpm_expr):
                 chc_star = min(np.nanmin(table), *get_bounds(array)[0]) -1
                 chc_table = np.nan_to_num(table, nan=chc_star).astype(int).tolist()
                 return self.chc_model.table(self.solver_vars(array), chc_table, universal_value=chc_star, algo="STR2+")
+            elif cpm_expr.name == "regular":
+                from pychoco.objects.automaton.finite_automaton import FiniteAutomaton
+                array, transitions, start, accepting = cpm_expr.args
+                for i, (lb, ub) in enumerate(zip(*get_bounds(array))):
+                    if lb < 0 or ub > 65535:
+                        raise NotSupportedError(f"Choco regular only supports variables within domain 0..65535, got {array[i]} with bounds {lb}..{ub}")
+                # convert to Automaton Choco object
+                automaton = FiniteAutomaton()
+                for node, i in cpm_expr.node_map.items(): automaton.add_state()
+                for src, label, dst in transitions:
+                    automaton.add_transition(cpm_expr.node_map[src], cpm_expr.node_map[dst], label)
+                automaton.set_initial_state(cpm_expr.node_map[start])
+                automaton.set_final(*[cpm_expr.node_map[a] for a in accepting])
+                return self.chc_model.regular(self._to_vars(array), automaton)
+            
             elif cpm_expr.name == 'InDomain':
                 assert len(cpm_expr.args) == 2  # args = [array, list of vals]
                 expr, table = self.solver_vars(cpm_expr.args)
diff --git a/cpmpy/solvers/ortools.py b/cpmpy/solvers/ortools.py
index 9b754bc7d..764c15f27 100644
--- a/cpmpy/solvers/ortools.py
+++ b/cpmpy/solvers/ortools.py
@@ -379,7 +379,7 @@ def transform(self, cpm_expr):
             :return: list of Expression
         """
         cpm_cons = toplevel_list(cpm_expr)
-        supported = {"min", "max", "abs", "element", "alldifferent", "xor", "table", "negative_table", "cumulative", "circuit", "inverse", "no_overlap"}
+        supported = {"min", "max", "abs", "element", "alldifferent", "xor", "table", "negative_table", "cumulative", "circuit", "inverse", "no_overlap", "regular"}
         cpm_cons = no_partial_functions(cpm_cons, safen_toplevel=frozenset({"div", "mod"})) # before decompose, assumes total decomposition for partial functions
         cpm_cons = decompose_in_tree(cpm_cons, supported)
         cpm_cons = flatten_constraint(cpm_cons)  # flat normal form
@@ -540,6 +540,11 @@ def _post_constraint(self, cpm_expr, reifiable=False):
                 array, table = cpm_expr.args
                 array = self.solver_vars(array)
                 return self.ort_model.AddForbiddenAssignments(array, table)
+            elif cpm_expr.name == "regular":
+                array, transitions, start, accepting = cpm_expr.args
+                array = self.solver_vars(array)
+                return self.ort_model.AddAutomaton(array, cpm_expr.node_map[start], [cpm_expr.node_map[n] for n in accepting], 
+                                                   [(cpm_expr.node_map[src], label, cpm_expr.node_map[dst]) for src, label, dst in transitions])
             elif cpm_expr.name == "cumulative":
                 start, dur, end, demand, cap = self.solver_vars(cpm_expr.args)
                 intervals = [self.ort_model.NewIntervalVar(s,d,e,f"interval_{s}-{d}-{e}") for s,d,e in zip(start,dur,end)]
diff --git a/tests/test_constraints.py b/tests/test_constraints.py
index 8471c9f3f..f34603d00 100644
--- a/tests/test_constraints.py
+++ b/tests/test_constraints.py
@@ -20,7 +20,8 @@
 NUM_GLOBAL = {
     "AllEqual", "AllDifferent", "AllDifferentExcept0",
     "AllDifferentExceptN", "AllEqualExceptN",
-    "GlobalCardinalityCount", "InDomain", "Inverse", "Table", 'NegativeTable', "ShortTable", "Circuit",
+    "GlobalCardinalityCount", "InDomain", "Inverse","Circuit",
+    "Table", 'NegativeTable', "ShortTable", "Regular",
     "Increasing", "IncreasingStrict", "Decreasing", "DecreasingStrict", 
     "Precedence", "Cumulative", "NoOverlap",
     "LexLess", "LexLessEq", "LexChainLess", "LexChainLessEq",
@@ -192,6 +193,8 @@ def global_constraints(solver):
             expr = cls(NUM_ARGS, [1,0,2])
         elif name == "Table":
             expr = cls(NUM_ARGS, [[0,1,2],[1,2,0],[1,0,2]])
+        elif name == "Regular":
+            expr = Regular(intvar(0,3, shape=3), [("a", 1, "b"), ("b", 1, "c"), ("b", 0, "b"), ("c", 1, "c"), ("c", 0, "b")], "a", ["c"])
         elif name == "NegativeTable":
             expr = cls(NUM_ARGS, [[0, 1, 2], [1, 2, 0], [1, 0, 2]])
         elif name == "ShortTable":
diff --git a/tests/test_globalconstraints.py b/tests/test_globalconstraints.py
index 3405226bb..c9d6921c2 100644
--- a/tests/test_globalconstraints.py
+++ b/tests/test_globalconstraints.py
@@ -529,6 +529,34 @@ def test_table_onearg(self):
                 except (NotImplementedError, NotSupportedError):
                     pass
 
+    def test_regular(self):
+        # test based on the example from XCSP3 specifications https://arxiv.org/pdf/1611.03398
+        x = cp.intvar(0, 1, shape=7)
+
+        transitions = [("a", 0, "a"), ("a", 1, "b"), ("b", 1, "c"), ("c", 0, "d"), ("d", 0, "d"), ("d", 1, "e"),
+                       ("e", 0, "e")]
+        start = "a"
+        ends = ["e"]
+
+        true_sols = set()
+        false_sols = set()
+
+        solutions = [(0,0,0,1,1,0,1), (0,0,1,1,0,0,1), (0,0,1,1,0,1,0), (0,1,1,0,0,0,1), (0,1,1,0,0,1,0),
+                     (0,1,1,0,1,0,0), (1,1,0,0,0,0,1), (1,1,0,0,0,1,0), (1,1,0,0,1,0,0), (1,1,0,1,0,0,0)]
+
+        true_model = cp.Model(cp.Regular(x, transitions, start, ends))
+        false_model = cp.Model(~cp.Regular(x, transitions, start, ends))
+
+        num_true = true_model.solveAll(display=lambda : true_sols.add(tuple(argvals(x))))
+        num_false = false_model.solveAll(display=lambda : false_sols.add(tuple(argvals(x))))
+
+        self.assertEqual(num_true, len(solutions))
+        self.assertSetEqual(true_sols, set(solutions))
+
+        self.assertEqual(num_true + num_false, 2**7)
+        self.assertEqual(len(true_sols & false_sols), 0) # no solutions can be in both
+
+
     def test_minimum(self):
         iv = cp.intvar(-8, 8, 3)
         constraints = [cp.Minimum(iv) + 9 == 8]

From dbfc858d2601cae43569b0bc260dd006a5bbd4e3 Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Wed, 21 May 2025 02:55:17 +0200
Subject: [PATCH 32/39] CPO: Special setting for 0 duration (#681)

---
 cpmpy/solvers/cpo.py | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/cpmpy/solvers/cpo.py b/cpmpy/solvers/cpo.py
index 9f38efadb..4bdd49a41 100644
--- a/cpmpy/solvers/cpo.py
+++ b/cpmpy/solvers/cpo.py
@@ -471,7 +471,16 @@ def _cpo_expr(self, cpm_con):
                 total_usage = []
                 cons = []
                 for s, d, e, h in zip(start, dur, end, height):
-                    cpo_s, cpo_d, cpo_e, cpo_h = self.solver_vars([s, d, e, h])
+                    bounds_d = get_bounds(d)
+                    # Special case for tasks with duration 0
+                    # -> cpo immediately returns UNSAT if done through tasks
+                    if bounds_d[1] == bounds_d[0] == 0:
+                        cpo_s, cpo_e = self.solver_vars([s, e])
+                        cons += [cpo_s == cpo_e] # enforce 0 duration
+                        # no restrictions on height due to zero duration and thus no contribution to capacity
+                        continue
+                    # Normal setting
+                    cpo_s, cpo_d, cpo_e, cpo_h = self.solver_vars([s, d, e, h])                   
                     task = docp.expression.interval_var(start=get_bounds(s), size=get_bounds(d), end=get_bounds(e))
                     task_height = dom.pulse(task, get_bounds(h))
                     cons += [dom.start_of(task) == cpo_s, dom.size_of(task) == cpo_d, dom.end_of(task) == cpo_e]

From e7405de6f72ce61e414dd94c63d152533b262ac5 Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Wed, 21 May 2025 09:53:02 +0200
Subject: [PATCH 33/39] Consistent state reporting (#545)

* OR-Tools correct state reporting for CSP

* Fix choco solveAll timelimit

attempted to set time limit before solver object was created

* Missing argval imports

* Standardised solver state for solve()

* Standardised solver state for solveAll()

* Add solver status instructions to template

* update gcs

* add tests

* pysat also optimal, even w/o obj

* update pysdd

* solve from model instead of solver obj

* add semantics of status to docs

* update test for solveAll

* Small typos in docs

* Update solve status

use feasible for CSP instead of optimal

* Update solveAll

* Update test

* Update another test

* Disable test for pysdd

* Update status documentation

---------

Co-authored-by: IgnaceBleukx <ignace.bleukx@kuleuven.be>
---
 cpmpy/solvers/TEMPLATE.py         | 34 +++++++++++--
 cpmpy/solvers/choco.py            | 32 +++++++++++--
 cpmpy/solvers/cpo.py              | 50 ++++++++++++++-----
 cpmpy/solvers/exact.py            | 77 +++++++++++++++++++++++++----
 cpmpy/solvers/gcs.py              | 12 ++++-
 cpmpy/solvers/gurobi.py           | 23 +++++++--
 cpmpy/solvers/minizinc.py         | 16 +++++--
 cpmpy/solvers/ortools.py          | 12 ++++-
 cpmpy/solvers/pysat.py            |  7 ++-
 cpmpy/solvers/pysdd.py            | 20 +++++---
 cpmpy/solvers/solver_interface.py | 24 +++++++++-
 cpmpy/solvers/z3.py               | 31 +++++++++---
 docs/modeling.md                  | 14 +++++-
 glasgow-constraint-solver         |  1 +
 tests/test_solvers.py             | 80 +++++++++++++++++++++++++++++++
 tests/test_tool_dimacs.py         |  2 +-
 16 files changed, 381 insertions(+), 54 deletions(-)
 create mode 160000 glasgow-constraint-solver

diff --git a/cpmpy/solvers/TEMPLATE.py b/cpmpy/solvers/TEMPLATE.py
index 15079d03c..6e859b344 100644
--- a/cpmpy/solvers/TEMPLATE.py
+++ b/cpmpy/solvers/TEMPLATE.py
@@ -151,9 +151,19 @@ def solve(self, time_limit=None, **kwargs):
         self.cpm_status = SolverStatus(self.name)
         self.cpm_status.runtime = self.TPL_solver.time() # wallclock time in (float) seconds
 
-        # translate solver exit status to CPMpy exit status
+        # Translate solver exit status to CPMpy exit status
+        # CSP:                         COP:
+        # ├─ sat -> FEASIBLE           ├─ optimal -> OPTIMAL
+        # ├─ unsat -> UNSATISFIABLE    ├─ sub-optimal -> FEASIBLE
+        # └─ timeout -> UNKNOWN        ├─ unsat -> UNSATISFIABLE
+        #                              └─ timeout -> UNKNOWN
         if my_status is True:
-            self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            # COP
+            if self.has_objective():
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            # CSP
+            else:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         elif my_status is False:
             self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
         elif my_status is None:
@@ -409,7 +419,7 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
 
             If the problem is an optimization problem, returns only optimal solutions.
 
-           Arguments:
+            Arguments:
                 - display: either a list of CPMpy expressions, OR a callback function, called with the variables after value-mapping
                         default/None: nothing displayed
                 - time_limit: stop after this many seconds (default: None)
@@ -420,7 +430,7 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
             Returns: number of solutions found
         """
 
-        # check if objective function
+        # check if objective function (optional if solver doesn't support finding all solutions for COP)
         if self.has_objective():
             raise NotSupportedError("TEMPLATE does not support finding all optimal solutions")
 
@@ -430,7 +440,21 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
         else:
             callback = display
 
-        self.solve(time_limit, callback=callback, enumerate_all_solutions=True, **kwargs)
+        my_status = self.solve(time_limit, callback=callback, enumerate_all_solutions=True, **kwargs)
+
+        # new status, translate runtime
+        self.cpm_status = SolverStatus(self.name)
+        self.cpm_status.runtime = self.TPL_solver.time() # wallclock time in (float) seconds (of entire solveAll call)
+
+        # Translate solver exit status to CPMpy exit status
+        # CSP & COP:
+        # ├─ all solutions found -> OPTIMAL
+        # ├─ at least 1 found (timeout / solution limit reached) -> FEASIBLE
+        # ├─ 0 solutions found due to timeout -> UNKNOWN
+        # └─ unsat -> UNSATISFIABLE
+
+        # self.cpm_status.exitstatus = ...
+
         # clear user vars if no solution found
         if self.TPL_solver.SolutionCount() == 0:
             for var in self.user_vars:
diff --git a/cpmpy/solvers/choco.py b/cpmpy/solvers/choco.py
index 9f9415802..ff93ab99f 100644
--- a/cpmpy/solvers/choco.py
+++ b/cpmpy/solvers/choco.py
@@ -177,13 +177,21 @@ def solve(self, time_limit=None, **kwargs):
         self.cpm_status.runtime = end - start
 
         # translate exit status
+        # A) Found a solution
         if sol is not None:
-            if time_limit is None or self.cpm_status.runtime < time_limit: # solved to optimality
-                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
-            else: # solved, but optimality not proven
+            # COP
+            if self.has_objective():
+                if time_limit is None or self.cpm_status.runtime < time_limit: # solved to optimality
+                    self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+                else: # solved, but optimality not proven
+                    self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            # CSP
+            else:
                 self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+        # B) Found unsat
         elif time_limit is None or self.cpm_status.runtime < time_limit: # proven unsat
             self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
+        # C) Timeout
         else:
             self.cpm_status.exitstatus = ExitStatus.UNKNOWN  # can happen when timeout is reached...
 
@@ -228,10 +236,13 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
         # ensure all vars are known to solver
         self.solver_vars(list(self.user_vars))
 
+        # create solver object
+        self.chc_solver = self.chc_model.get_solver()
+
+        # set time limit (if given)
         if time_limit is not None:
             self.chc_solver.limit_time(str(time_limit) + "s")
 
-        self.chc_solver = self.chc_model.get_solver()
         start = time.time()
         if self.has_objective():
             sols = self.chc_solver.find_all_optimal_solutions(maximize=not self.minimize_obj,
@@ -246,6 +257,19 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
         self.cpm_status = SolverStatus(self.name)
         self.cpm_status.runtime = end - start
 
+        if len(sols): # solutions found
+            if (len(sols) == solution_limit): # matched the set limit (if given)
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            elif (time_limit is None) or (self.cpm_status.runtime < time_limit): # found all solutions
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            else: # reached timeout
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+        else: # no solutions found
+            if (time_limit is None) or (self.cpm_status.runtime < time_limit): # unsat problem
+                self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
+            else: # timeout
+                self.cpm_status.exitstatus = ExitStatus.UNKNOWN
+
         # if no solutions, clear values of variables
         if len(sols) == 0:
             for var in self.user_vars:
diff --git a/cpmpy/solvers/cpo.py b/cpmpy/solvers/cpo.py
index 4bdd49a41..82b70db3b 100644
--- a/cpmpy/solvers/cpo.py
+++ b/cpmpy/solvers/cpo.py
@@ -43,6 +43,7 @@
 """
 
 import shutil
+import time
 import warnings
 
 from .solver_interface import SolverInterface, SolverStatus, ExitStatus
@@ -234,14 +235,28 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
 
         docp = self.get_docp()
         solution_count = 0
-        while solution_limit is None or solution_count < solution_limit:
-            cpo_result = self.solve(time_limit=time_limit, **kwargs)
-            if not cpo_result:
-                break
+        start = time.time()
+        while ((time_limit is None) or (time_limit > 0)) and self.solve(time_limit=time_limit, **kwargs):
+
+            # display if needed
+            if display is not None:
+                if isinstance(display, Expression):
+                    print(argval(display))
+                elif isinstance(display, list):
+                    print(argvals(display))
+                else:
+                    display()  # callback
+
+            # count and stop
             solution_count += 1
+            if solution_count == solution_limit:
+                break
+
             if self.has_objective():
                 # only find all optimal solutions
                 self.cpo_model.add(self.cpo_model.get_objective_expression().children[0] == self.objective_value_)
+
+            # add nogood on the user variables
             solvars = []
             vals = []
             for cpm_var in self.user_vars:
@@ -255,13 +270,26 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
                 solvars.append(sol_var)
                 vals.append(cpm_value)
             self.cpo_model.add(docp.modeler.forbidden_assignments(solvars, [vals]))
-            if display is not None:
-                if isinstance(display, Expression):
-                    print(argval(display))
-                elif isinstance(display, list):
-                    print(argvals(display))
-                else:
-                    display()  # callback
+
+            if time_limit is not None: # update remaining time
+                time_limit -= self.status().runtime
+        end = time.time()
+
+        # update solver status
+        self.cpm_status.runtime = end - start
+        if solution_count:
+            if solution_count == solution_limit:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            elif self.cpm_status.exitstatus == ExitStatus.UNSATISFIABLE:
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            else:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+        # else: <- is implicit since nothing needs to update
+        #     if self.cpm_status.exitstatus == ExitStatus.UNSATISFIABLE:
+        #         self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
+        #     elif self.cpm_status.exitstatus == ExitStatus.UNKNOWN:
+        #         self.cpm_status.exitstatus = ExitStatus.UNKNOWN
+
         return solution_count
 
     def solver_var(self, cpm_var):
diff --git a/cpmpy/solvers/exact.py b/cpmpy/solvers/exact.py
index 33a5200f6..c2c5cc5ed 100644
--- a/cpmpy/solvers/exact.py
+++ b/cpmpy/solvers/exact.py
@@ -217,18 +217,28 @@ def solve(self, time_limit=None, assumptions=None, **kwargs):
 
         self.objective_value_ = None
         # translate exit status
+        #   see 'toOptimum' documentation:
+        #   https://gitlab.com/nonfiction-software/exact/-/blob/main/src/interface/IntProg.cpp#L877
         if my_status == "UNSAT": # found unsatisfiability
-            if self.has_objective() and self.xct_solver.hasSolution():
+            if self.has_objective() and self.xct_solver.hasSolution(): # optimisation problem -> unsat = no better solution found
                 self.cpm_status.exitstatus = ExitStatus.OPTIMAL
             else:
                 self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
-        elif my_status == "SAT": # found solution, but not optimality proven
+        elif my_status == "SAT": # the optimal value has been found
             assert self.xct_solver.hasSolution()
-            self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            # COP
+            if self.has_objective():
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            # CSP
+            else:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         elif my_status == "INCONSISTENT": # found inconsistency over assumptions
             self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
         elif my_status == "TIMEOUT": # found timeout
-            self.cpm_status.exitstatus = ExitStatus.UNKNOWN
+            if self.xct_solver.hasSolution(): # found a (sub-)optimal solution
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            else: # no solution found
+                self.cpm_status.exitstatus = ExitStatus.UNKNOWN
         else:
             raise NotImplementedError(my_status)  # a new status type was introduced, please report on github
         
@@ -242,6 +252,15 @@ def solve(self, time_limit=None, assumptions=None, **kwargs):
         # True/False depending on self.cpm_status
         return self._solve_return(self.cpm_status)
 
+    def _update_time(self, timelim, start, end):
+        """
+            Internal helper function to keep track of remaining time.
+        """
+        if timelim != 0:
+            timelim -= (end - start)
+            if timelim == 0: timelim = -1
+        return timelim
+
     def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from_model=False, **kwargs):
         """
             Compute all solutions and optionally, display the solutions.
@@ -267,30 +286,52 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
 
         timelim = time_limit if time_limit is not None else 0
 
+        total_start = time.time()
+
         if self.has_objective():
+            start = time.time()
             if not call_from_model:
                 warnings.warn("Adding constraints to solver object to find all solutions, solver state will be invalid after this call!")
 
             (my_status, objval) = self.xct_solver.toOptimum(timelim) # fix the solution to the optimal objective
             if my_status == "UNSAT": # found unsatisfiability
+                total_end = time.time()
                 self._fillVars() # erases the solution
+                # update exit status
+                self.cpm_status = SolverStatus(self.name)
+                self.cpm_status.runtime = total_end - total_start
+                self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
+                # early exit
                 return 0
             elif my_status == "INCONSISTENT": # found inconsistency
                 raise ValueError("Error: inconsistency during solveAll should not happen, please warn the developers of this bug")
             elif my_status == "TIMEOUT": # found timeout
+                total_end = time.time()
+                # update exit status
+                self.cpm_status = SolverStatus(self.name)
+                self.cpm_status.runtime = total_end - total_start
+                self.cpm_status.exitstatus = ExitStatus.UNKNOWN
+                # early exit
                 return 0
             else:
                 assert my_status == "SAT", "Unexpected status from Exact"
             self += self.objective_ == objval # fix obj val
+            end = time.time()
+            timelim = self._update_time(timelim, start, end) # update remaining time
+
 
         solsfound = 0
-        while solution_limit is None or solsfound < solution_limit:
+        while timelim >= 0 and (solution_limit is None or solsfound < solution_limit):
             # call the solver, with parameters
+            start = time.time()
             my_status = self.xct_solver.runFull(optimize=False, timeout=timelim)
+            end = time.time()
+            timelim = self._update_time(timelim, start, end) # update remaining time
+
             assert my_status in ["UNSAT","SAT","INCONSISTENT","TIMEOUT"], "Unexpected status code for Exact: " + my_status
-            if my_status == "UNSAT": # found unsatisfiability
+            if my_status == "UNSAT": # found unsatisfiability (no more solutions to be found)
                 self._fillVars() # erases the solution
-                return solsfound
+                break
             elif my_status == "SAT": # found solution, but not optimality proven
                 assert self.xct_solver.hasSolution()
                 solsfound += 1
@@ -306,7 +347,27 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
             elif my_status == "INCONSISTENT": # found inconsistency
                 raise ValueError("Error: inconsistency during solveAll should not happen, please warn the developers of this bug")
             elif my_status == "TIMEOUT": # found timeout
-                return solsfound
+                break
+        total_end = time.time()
+
+        # new status, translate runtime
+        self.cpm_status = SolverStatus(self.name)
+        self.cpm_status.runtime = total_end - total_start
+
+        if solsfound: # found some solutions
+            if solsfound == solution_limit: # matched solution limit
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            elif my_status == "UNSAT": # found all solutions (before limits were reached)
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            else: # timeout
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+        else:
+            if my_status == "UNSAT": # unsat problem
+                self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
+            elif my_status == "TIMEOUT": # timeout
+                self.cpm_status.exitstatus = ExitStatus.UNKNOWN
+            else:
+                raise NotImplementedError(my_status) # please report on GitHub
 
         return solsfound
 
diff --git a/cpmpy/solvers/gcs.py b/cpmpy/solvers/gcs.py
index dbf1fce4f..da7b2ec1f 100644
--- a/cpmpy/solvers/gcs.py
+++ b/cpmpy/solvers/gcs.py
@@ -303,6 +303,16 @@ def display_callback(solution_map):
         self.cpm_status = SolverStatus(self.name)
         self.cpm_status.runtime = self.gcs_result["solve_time"]
 
+        num_sols = self.gcs_result["solutions"]
+        if self.gcs_result["completed"] and num_sols >= 1:
+            self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+        elif self.gcs_result["completed"] and num_sols == 0:
+            self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
+        elif num_sols >= 1:
+            self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+        else: # maybe unsat, maybe not (maybe a timeout)
+            self.cpm_status.exitstatus = ExitStatus.UNKNOWN
+
         # clear user vars if no solution found
         if self._solve_return(self.cpm_status, self.objective_value_) is False:
             for var in self.user_vars:
@@ -313,7 +323,7 @@ def display_callback(solution_map):
             self.verify(name=self.proof_name, location=proof_location, time_limit=verify_time_limit, 
                         veripb_args=veripb_args, display_output=display_verifier_output)
 
-        return self.gcs_result["solutions"]
+        return num_sols
 
     def solver_var(self, cpm_var):
         """
diff --git a/cpmpy/solvers/gurobi.py b/cpmpy/solvers/gurobi.py
index 3aaad5005..5d36d3973 100644
--- a/cpmpy/solvers/gurobi.py
+++ b/cpmpy/solvers/gurobi.py
@@ -181,10 +181,13 @@ def solve(self, time_limit=None, solution_callback=None, **kwargs):
         self.cpm_status.runtime = self.grb_model.runtime
 
         # translate exit status
-        if grb_status == GRB.OPTIMAL and not self.has_objective():
-            self.cpm_status.exitstatus = ExitStatus.FEASIBLE
-        elif grb_status == GRB.OPTIMAL and self.has_objective():
-            self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+        if grb_status == GRB.OPTIMAL:
+            # COP
+            if self.has_objective():
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            # CSP
+            else:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         elif grb_status == GRB.INFEASIBLE:
             self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
         elif grb_status == GRB.TIME_LIMIT:
@@ -477,6 +480,7 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
 
             Returns: number of solutions found
         """
+        from gurobipy import GRB
 
         if time_limit is not None:
             self.grb_model.setParam("TimeLimit", time_limit)
@@ -537,4 +541,15 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
         # Reset pool search mode to default
         self.grb_model.setParam("PoolSearchMode", 0)
 
+        if opt_sol_count:
+            if opt_sol_count == solution_limit:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE 
+            else:
+                grb_status = self.grb_model.Status
+                if grb_status == GRB.TIME_LIMIT: # reached time limit
+                    self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+                else: # found all solutions   
+                    self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+        # if unsat or timout with no solution, .solve() will have already set the state accordingly (so nothing to update)
+
         return opt_sol_count
diff --git a/cpmpy/solvers/minizinc.py b/cpmpy/solvers/minizinc.py
index f7e8de488..5dd42c623 100644
--- a/cpmpy/solvers/minizinc.py
+++ b/cpmpy/solvers/minizinc.py
@@ -305,7 +305,7 @@ def solve(self, time_limit=None, **kwargs):
 
         return has_sol
 
-    def _post_solve(self, mzn_result):
+    def _post_solve(self, mzn_result, solve_all:bool=False):
         """ shared by solve() and solveAll() """
         import minizinc
 
@@ -328,7 +328,10 @@ def _post_solve(self, mzn_result):
         if mzn_status == minizinc.result.Status.SATISFIED:
             self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         elif mzn_status == minizinc.result.Status.ALL_SOLUTIONS:
-            self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            if solve_all:
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            else:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         elif mzn_status == minizinc.result.Status.OPTIMAL_SOLUTION:
             self.cpm_status.exitstatus = ExitStatus.OPTIMAL
         elif mzn_status == minizinc.result.Status.UNSATISFIABLE:
@@ -402,7 +405,14 @@ async def _solveAll(self, display=None, time_limit=None, solution_limit=None, **
                 var._value = None
 
         # status handling
-        self._post_solve(mzn_result)
+        self._post_solve(mzn_result, solve_all=True)
+
+        if solution_count: # found at least one solution
+            if solution_count == solution_limit: # matched solution limit
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            # elif mzn_result.solution is None: <- is implicit since nothing needs to update
+                # last iteration didn't find a solution
+                # nothing needs to update since _post_solve already set state correctly (state from the second-last iteration)
 
         return solution_count
 
diff --git a/cpmpy/solvers/ortools.py b/cpmpy/solvers/ortools.py
index 764c15f27..66e9f91ce 100644
--- a/cpmpy/solvers/ortools.py
+++ b/cpmpy/solvers/ortools.py
@@ -214,7 +214,17 @@ def solve(self, time_limit=None, assumptions=None, solution_callback=None, **kwa
         if self.ort_status == ort.FEASIBLE:
             self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         elif self.ort_status == ort.OPTIMAL:
-            self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            # COP
+            if self.has_objective():
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            # CSP
+            else:
+                # for .solveAll(), if all solutions found status is OPTIMAL
+                if kwargs.get("enumerate_all_solutions", False):
+                    self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+                # regular .solve()
+                else:
+                    self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         elif self.ort_status == ort.INFEASIBLE:
             self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
         elif self.ort_status == ort.MODEL_INVALID:
diff --git a/cpmpy/solvers/pysat.py b/cpmpy/solvers/pysat.py
index e7f6557f1..39224a391 100644
--- a/cpmpy/solvers/pysat.py
+++ b/cpmpy/solvers/pysat.py
@@ -220,7 +220,12 @@ def solve(self, time_limit=None, assumptions=None):
 
         # translate exit status
         if my_status is True:
-            self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            # COP
+            if self.has_objective():
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            # CSP
+            else:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         elif my_status is False:
             self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
         elif my_status is None:
diff --git a/cpmpy/solvers/pysdd.py b/cpmpy/solvers/pysdd.py
index d5c1e1a45..7cf40251d 100644
--- a/cpmpy/solvers/pysdd.py
+++ b/cpmpy/solvers/pysdd.py
@@ -135,6 +135,7 @@ def solve(self, time_limit=None, assumptions=None):
 
         # translate exit status
         if has_sol:
+            # Only CSP (does not support COP)
             self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         else:
             self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
@@ -197,27 +198,32 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
                 projected_sols.add(tuple(projectedsol))
         else:
             projected_sols = set(sddmodels)
-        if display is None:
-            # the desired, fast computation
-            return len(projected_sols)
 
+        if projected_sols:
+            if projected_sols == solution_limit:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            else:
+                # time limit not (yet) supported -> always all solutions found
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
         else:
+            self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
+
+        # display if needed
+        if display is not None:
             # manually walking over the tree, much slower...
-            solution_count = 0
             for sol in projected_sols:
-                solution_count += 1
                 # fill in variable values
                 for i, cpm_var in enumerate(self.user_vars):
                     cpm_var._value = sol[i]
 
-                # display is not None:
                 if isinstance(display, Expression):
                     print(argval(display))
                 elif isinstance(display, list):
                     print(argvals(display))
                 else:
                     display()  # callback
-            return solution_count
+        
+        return len(projected_sols)
 
     def solver_var(self, cpm_var):
         """
diff --git a/cpmpy/solvers/solver_interface.py b/cpmpy/solvers/solver_interface.py
index 80e291c49..37205f4ea 100644
--- a/cpmpy/solvers/solver_interface.py
+++ b/cpmpy/solvers/solver_interface.py
@@ -251,9 +251,12 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
         if not call_from_model:
             warnings.warn("Adding constraints to solver object to find all solutions, "
                           "solver state will be invalid after this call!")
+            
+        self.cpm_status = SolverStatus(self.name)
 
         solution_count = 0
-        while self.solve(time_limit=time_limit, **kwargs):
+        start = time.time()
+        while ((time_limit is None) or (time_limit > 0)) and self.solve(time_limit=time_limit, **kwargs):
             # display if needed
             if display is not None:
                 if isinstance(display, Expression):
@@ -271,6 +274,25 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
             # add nogood on the user variables
             self += any([v != v.value() for v in self.user_vars if v.value() is not None])
 
+            if time_limit is not None: # update remaining time
+                time_limit -= self.status().runtime
+        end = time.time()
+
+        # update solver status
+        self.cpm_status.runtime = end - start
+        if solution_count:
+            if solution_count == solution_limit:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            elif self.cpm_status.exitstatus == ExitStatus.UNSATISFIABLE:
+                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            else:
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+        # else: <- is implicit since nothing needs to update
+        #     if self.cpm_status.exitstatus == ExitStatus.UNSATISFIABLE:
+        #         self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
+        #     elif self.cpm_status.exitstatus == ExitStatus.UNKNOWN:
+        #         self.cpm_status.exitstatus = ExitStatus.UNKNOWN
+
         return solution_count
 
     def solution_hint(self, cpm_vars, vals):
diff --git a/cpmpy/solvers/z3.py b/cpmpy/solvers/z3.py
index 156a9c633..3dd9ed254 100644
--- a/cpmpy/solvers/z3.py
+++ b/cpmpy/solvers/z3.py
@@ -113,6 +113,9 @@ def __init__(self, cpm_model=None, subsolver="sat"):
         if "opt" in subsolver:
             self.z3_solver = z3.Optimize()
 
+        # handle of objective (as returned by solver)
+        self.obj_handle = None
+
         # initialise everything else and post the constraints/objective
         super().__init__(name="z3", cpm_model=cpm_model)
 
@@ -189,14 +192,30 @@ def solve(self, time_limit=None, assumptions=[], **kwargs):
 
         # translate exit status
         if my_status == "sat":
-            self.cpm_status.exitstatus = ExitStatus.FEASIBLE
-            if isinstance(self.z3_solver, z3.Optimize):
-                self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+            if self.has_objective(): # COP
+                # check if optimal solution found and proven, i.e. bounds are equal
+                lower_bound = self.z3_solver.lower(self.obj_handle)
+                upper_bound = self.z3_solver.upper(self.obj_handle)
+                if lower_bound == upper_bound: # found optimal
+                    self.cpm_status.exitstatus = ExitStatus.OPTIMAL
+                else: # suboptimal / not proven
+                    self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+            else: # CSP
+                self.cpm_status.exitstatus = ExitStatus.FEASIBLE
         elif my_status == "unsat":
             self.cpm_status.exitstatus = ExitStatus.UNSATISFIABLE
         elif my_status == "unknown":
+            try:
+                model = self.z3_solver.model()
+                if model: # a solution was found, just not the optimal one (or not proven)
+                    self.cpm_status.exitstatus = ExitStatus.FEASIBLE
+                # can happen when timeout is reached...
+                else:
+                    self.cpm_status.exitstatus = ExitStatus.UNKNOWN
             # can happen when timeout is reached...
-            self.cpm_status.exitstatus = ExitStatus.UNKNOWN
+            except z3.Z3Exception as e: # no model has been initialized, not even an empty one
+                self.cpm_status.exitstatus = ExitStatus.UNKNOWN
+
         else:  # another?
             raise NotImplementedError(my_status)  # a new status type was introduced, please report on github
 
@@ -286,9 +305,9 @@ def objective(self, expr, minimize=True):
 
         obj = self._z3_expr(expr)
         if minimize:
-            self.z3_solver.minimize(obj)
+            self.obj_handle = self.z3_solver.minimize(obj)
         else:
-            self.z3_solver.maximize(obj)
+            self.obj_handle = self.z3_solver.maximize(obj)
 
 
     def transform(self, cpm_expr):
diff --git a/docs/modeling.md b/docs/modeling.md
index 626d5ab22..68aada792 100644
--- a/docs/modeling.md
+++ b/docs/modeling.md
@@ -436,7 +436,12 @@ if hassol:
 else:
     print("No solution found.")
 ```
-
+The status of solve-call can be the following:
+1. `ExitStatus.OPTIMAL`: The solver found a solution to an optimisation problem and proved its optimality.
+2. `ExitStatus.FEASIBLE`: The solver found a solution to a satisfaction problem, or a feasible solution to an optimization problem but did not prove optimality
+3. `ExitStatus.UNSATIFIABLE`: The solver proved the input problem is unsatisfiable.
+4. `ExitStatus.UNKNOWN`: The solver did not find a feasible solution, nor proved the problem is unsatisfiable. Can happen when a time-limit is reached.
+5. `ExitStatus.NOT_RUN`: The solver is not run yet (default when initializing a solver)
 
 ## Finding all solutions
 
@@ -451,6 +456,13 @@ n = m.solveAll()
 print("Nr of solutions:", n)  # Nr of solutions: 6
 ```
 
+The status of solveAll-call can be the following:
+1. `ExitStatus.OPTIMAL`: The solver found all possible solutions to a problem and proved there to be none remaining.
+2. `ExitStatus.FEASIBLE`: The solver found a subset of all solutions, or found all solutions but did not prove there to be none remaining.
+3. `ExitStatus.UNSATIFIABLE`: The solver proved the input problem is unsatisfiable.
+4. `ExitStatus.UNKNOWN`: The solver did not find a feasible solution, nor proved the problem is unsatisfiable. Can happen when a time-limit is reached.
+5. `ExitStatus.NOT_RUN`: The solver is not run yet (default when initializing a solver)
+
 When using `solveAll()`, a solver will use an optimized native implementation behind the scenes when that exists. Otherwise it will be emulated with an iterative approach, resulting in a performance impact.
 
 It has a `display=...` argument that can be used to display expressions (provide a list of expressions to be evaluated) or as a more generic callback (provide a function), both to be evaluated for each found solution.
diff --git a/glasgow-constraint-solver b/glasgow-constraint-solver
new file mode 160000
index 000000000..502355af5
--- /dev/null
+++ b/glasgow-constraint-solver
@@ -0,0 +1 @@
+Subproject commit 502355af5ca02acbae10bed84fb196ae54eae14b
diff --git a/tests/test_solvers.py b/tests/test_solvers.py
index ef49a405d..5b8d3d50e 100644
--- a/tests/test_solvers.py
+++ b/tests/test_solvers.py
@@ -8,6 +8,7 @@
 from cpmpy.expressions.utils import argvals
 
 from cpmpy.solvers.pysat import CPM_pysat
+from cpmpy.solvers.solver_interface import ExitStatus
 from cpmpy.solvers.z3 import CPM_z3
 from cpmpy.solvers.minizinc import CPM_minizinc
 from cpmpy.solvers.gurobi import CPM_gurobi
@@ -849,6 +850,85 @@ def test_partial_div_mod(self, solver):
             assert (Operator('div', [xv, yv])).value() == dv
             assert (Operator('mod', [xv, yv])).value() == rv
 
+
+    def test_status(self, solver):
+
+        bv = cp.boolvar(shape=3, name="bv")
+        m = cp.Model(cp.any(bv))
+
+        assert m.status().exitstatus == ExitStatus.NOT_RUN
+        assert m.solve(solver=solver)
+        assert m.status().exitstatus == ExitStatus.FEASIBLE
+
+        try: # now try optimization, not supported for all solvers
+            m.maximize(cp.sum(bv))
+            assert m.solve(solver=solver)
+            assert m.status().exitstatus == ExitStatus.OPTIMAL
+        except NotSupportedError:
+            return
+
+        # now making a tricky problem to solve
+        np.random.seed(0)
+        start = cp.intvar(0,100, shape=50)
+        dur = np.random.randint(1,5, size=50)
+        end = cp.intvar(0,100, shape=50)
+        demand  = np.random.randint(10,15, size=50)
+
+        m += cp.Cumulative(start, dur, end,demand, 30)
+        m.minimize(cp.max(end))
+        m.solve(solver=solver, time_limit=1)
+        # normally, should not be able to solve within 1s...
+        assert m.status().exitstatus == ExitStatus.FEASIBLE or m.status().exitstatus == ExitStatus.UNKNOWN
+
+        # now trivally unsat
+        m += cp.sum(bv) <= 0
+        m.solve(solver=solver)
+        assert m.status().exitstatus == ExitStatus.UNSATISFIABLE
+
+
+
+    def test_status_solveall(self, solver):
+
+        bv = cp.boolvar(shape=3, name="bv")
+        m = cp.Model(cp.any(bv))
+
+        limit = None
+        if solver == "gurobi": limit = 100000
+
+        num_sols = m.solveAll(solver=solver, solution_limit=limit)
+        assert num_sols == 7
+        assert m.status().exitstatus == ExitStatus.OPTIMAL  # optimal
+
+
+
+        # adding a bunch of variables to increase nb of sols
+        try:
+            x = cp.boolvar(shape=32, name="x")
+            m = cp.Model(cp.any(x))
+            num_sols = m.solveAll(solver=solver, time_limit=1, solution_limit=limit)
+            assert m.status().exitstatus == ExitStatus.FEASIBLE
+
+            num_sols = m.solveAll(solver=solver, solution_limit=10)
+            assert num_sols == 10
+            assert m.status().exitstatus == ExitStatus.FEASIBLE
+
+            # edge-case: nb of solutions is exactly the sol limit
+            m = cp.Model(cp.any(bv))
+            num_sols = m.solveAll(solver=solver, solution_limit=7)
+            assert num_sols ==  7
+            assert m.status().exitstatus in (ExitStatus.OPTIMAL, ExitStatus.FEASIBLE) # which of the two?
+
+        except NotImplementedError:
+            pass # not all solvers support time/solution limits
+
+        # making the problem unsat
+        if solver != "pysdd": # constraint not supported by pysdd
+            m  = cp.Model([cp.sum(bv) <= 0, cp.any(bv)])
+            num_sols = m.solveAll(solver=solver, solution_limit=limit)
+            assert num_sols == 0
+            assert m.status().exitstatus == ExitStatus.UNSATISFIABLE
+
+
     def test_hidden_user_vars(self, solver):
         """
         Tests whether decision variables which are part of a constraint that never gets posted to the underlying solver
diff --git a/tests/test_tool_dimacs.py b/tests/test_tool_dimacs.py
index d7c29e0d9..57e43f587 100644
--- a/tests/test_tool_dimacs.py
+++ b/tests/test_tool_dimacs.py
@@ -33,7 +33,7 @@ def test_read_cnf(self):
     def test_empty_formula(self):
         model = self.dimacs_to_model("p cnf 0 0")
         self.assertTrue(model.solve())
-        self.assertEqual(model.status().exitstatus, ExitStatus.OPTIMAL)
+        self.assertEqual(model.status().exitstatus, ExitStatus.FEASIBLE)
 
     def test_empty_clauses(self):
         model = self.dimacs_to_model("p cnf 0 2\n0\n0")

From 1ea0ec5d3f54f1948c686d13bdc4f07eb4ca7d80 Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <49067410+ThomSerg@users.noreply.github.com>
Date: Wed, 21 May 2025 10:42:14 +0200
Subject: [PATCH 34/39] CPO solution callback (#682)

* Add callbacks

* typo

---------

Co-authored-by: Tias Guns <tias@ulyssis.org>
---
 cpmpy/solvers/cpo.py | 147 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 145 insertions(+), 2 deletions(-)

diff --git a/cpmpy/solvers/cpo.py b/cpmpy/solvers/cpo.py
index 82b70db3b..51955f73c 100644
--- a/cpmpy/solvers/cpo.py
+++ b/cpmpy/solvers/cpo.py
@@ -129,12 +129,14 @@ def __init__(self, cpm_model=None, subsolver=None):
         self.cpo_model = docp.model.CpoModel()
         super().__init__(name="cpo", cpm_model=cpm_model)
 
-    def solve(self, time_limit=None, **kwargs):
+    def solve(self, time_limit=None, solution_callback=None, **kwargs):
         """
             Call the CP Optimizer solver
 
             Arguments:
                 time_limit (float, optional):   maximum solve time in seconds 
+                solution_callback (an `docplex.cp.solver.solver_listener.CpoSolverListener` object):   CPMpy includes its own, namely `CpoSolutionCounter`. If you want to count all solutions, 
+                                                                                                        don't forget to also add the keyword argument 'enumerate_all_solutions=True'.
                 kwargs:                         any keyword argument, sets parameters of solver object
 
             Arguments that correspond to solver parameters:
@@ -154,6 +156,7 @@ def solve(self, time_limit=None, **kwargs):
             All solver parameters are documented here: https://ibmdecisionoptimization.github.io/docplex-doc/cp/docplex.cp.parameters.py.html#docplex.cp.parameters.CpoParameters
 
         """
+        docp = self.get_docp()
 
         # ensure all vars are known to solver
         self.solver_vars(list(self.user_vars))
@@ -165,7 +168,16 @@ def solve(self, time_limit=None, **kwargs):
         # set time limit
         if time_limit is not None and time_limit <= 0:
             raise ValueError("Time limit must be positive")
-        self.cpo_result = self.cpo_model.solve(TimeLimit=time_limit, **kwargs)
+        
+        # create solver object
+        self.cpo_solver = docp.solver.solver.CpoSolver(
+            self.cpo_model,
+            TimeLimit=time_limit, 
+            **kwargs, 
+            listeners=[solution_callback] if solution_callback is not None else None
+        )
+
+        self.cpo_result = self.cpo_solver.solve()
 
         # new status, translate runtime
         self.cpo_status = self.cpo_result.get_solve_status()
@@ -235,6 +247,8 @@ def solveAll(self, display=None, time_limit=None, solution_limit=None, call_from
 
         docp = self.get_docp()
         solution_count = 0
+
+        # TODO: convert to use 'start_search' and solution callback handlers
         start = time.time()
         while ((time_limit is None) or (time_limit > 0)) and self.solve(time_limit=time_limit, **kwargs):
 
@@ -551,3 +565,132 @@ def _cpo_expr(self, cpm_con):
                 return dom.count_different(self._cpo_expr(cpm_con.args))
 
         raise NotImplementedError("CP Optimizer: constraint not (yet) supported", cpm_con)
+
+
+# solvers are optional, so this file should be interpretable
+# even if cpo is not installed...
+try:
+    from docplex.cp.solver.solver_listener import CpoSolverListener
+    import time
+
+    class CpoSolutionCounter(CpoSolverListener):
+        """
+        Native CP Optimizer callback for solution counting.
+
+        It is based on cpo's built-in `CpoSolverListener`.
+
+        use with CPM_cpo as follows:
+
+        .. code-block:: python
+            
+            cb = CpoSolutionCounter()
+            s.solve(solution_callback=cb)
+
+        then retrieve the solution count with ``cb.solution_count()``
+
+        Arguments:
+            verbose (bool, default: False): whether to print info on every solution found 
+    """
+
+        def __init__(self, verbose=False):
+            super().__init__()
+            self.__solution_count = 0
+            self.__verbose = verbose
+            if self.__verbose:
+                self.__start_time = time.time()
+
+        def result_found(self, solver, sres):
+            """Called on each new solution."""
+            if self.__verbose:
+                current_time = time.time()
+                obj = sres.get_objective_value()
+                print('Solution %i, time = %0.2f s, objective = %i' %
+                      (self.__solution_count, current_time - self.__start_time, obj))
+            self.__solution_count += 1
+
+        def solution_count(self):
+            """Returns the number of solutions found."""
+            return self.__solution_count
+
+    class CpoSolutionPrinter(CpoSolutionCounter):
+        """
+            Native CP Optimizer callback for solution printing.
+
+            Subclasses :class:`CpoSolutionCounter`, see those docs too.
+
+            Use with :class:`CPM_cpo` as follows:
+
+            .. code-block:: python
+
+                cb = CpoSolutionPrinter(s, display=vars)
+                s.solve(solution_callback=cb)
+
+            For multiple variables (single or NDVarArray), use:
+            ``cb = CpoSolutionPrinter(s, display=[v, x, z])``.
+
+            For a custom print function, use for example:
+            
+            .. code-block:: python
+
+                def myprint():
+                    print(f"x0={x[0].value()}, x1={x[1].value()}")
+                
+                cb = CpoSolutionPrinter(s, printer=myprint)
+
+            Optionally retrieve the solution count with ``cb.solution_count()``.
+
+            Arguments:
+                verbose (bool, default = False): whether to print info on every solution found 
+                display: either a list of CPMpy expressions, OR a callback function, called with the variables after value-mapping
+                            default/None: nothing displayed
+                solution_limit (default = None): stop after this many solutions 
+        """
+        def __init__(self, solver, display=None, solution_limit=None, verbose=False):
+            super().__init__(verbose)
+            self._solution_limit = solution_limit
+            # we only need the cpmpy->solver varmap from the solver
+            self._varmap = solver._varmap
+            # identify which variables to populate with their values
+            self._cpm_vars = []
+            self._display = display
+            if isinstance(display, (list,Expression)):
+                self._cpm_vars = get_variables(display)
+            elif callable(display):
+                # might use any, so populate all (user) variables with their values
+                self._cpm_vars = solver.user_vars
+
+        def result_found(self, solver, sres):
+            """Called on each new solution."""
+            if len(self._cpm_vars):
+                # populate values before printing
+                for cpm_var in self._cpm_vars:
+                    # it might be an NDVarArray
+                    if hasattr(cpm_var, "flat"):
+                        for cpm_subvar in cpm_var.flat:
+                            sol_var = self._varmap[cpm_subvar]
+                            if isinstance(cpm_var,_BoolVarImpl):
+                                sol_var = sol_var.children[0]
+                                cpm_var._value = bool(sres.get_var_solution(sol_var).get_value())
+                            else:
+                                cpm_var._value = sres.get_var_solution(sol_var).get_value()
+                    elif isinstance(cpm_var, _BoolVarImpl):
+                        sol_var = self._varmap[cpm_subvar].children[0]
+                        cpm_var._value = bool(sres.get_var_solution(sol_var).get_value())
+                    else:
+                        sol_var = self._varmap[cpm_subvar]
+                        cpm_var._value = sres.get_var_solution(sol_var).get_value()
+
+                if isinstance(self._display, Expression):
+                    print(argval(self._display))
+                elif isinstance(self._display, list):
+                    # explicit list of expressions to display
+                    print(argvals(self._display))
+                else: # callable
+                    self._display()
+
+            # check for count limit
+            if self.solution_count() == self._solution_limit:
+                self.end_solve()
+
+except ImportError:
+    pass  # Ok, no cpo installed...

From f1205790f5d7712c5ff335e88f7aec76842b142f Mon Sep 17 00:00:00 2001
From: Thomas Sergeys <thomas.s2000@hotmail.com>
Date: Wed, 21 May 2025 10:53:42 +0200
Subject: [PATCH 35/39] Remove accidental inclusion of gcs

---
 glasgow-constraint-solver | 1 -
 1 file changed, 1 deletion(-)
 delete mode 160000 glasgow-constraint-solver

diff --git a/glasgow-constraint-solver b/glasgow-constraint-solver
deleted file mode 160000
index 502355af5..000000000
--- a/glasgow-constraint-solver
+++ /dev/null
@@ -1 +0,0 @@
-Subproject commit 502355af5ca02acbae10bed84fb196ae54eae14b

From bd0ee484fb389b8a3b69b7f93a32372dd8a4bc96 Mon Sep 17 00:00:00 2001
From: Tias Guns <tias@ulyssis.org>
Date: Wed, 21 May 2025 09:38:51 -0400
Subject: [PATCH 36/39] only_implies: avoid retransform if no subexpressions
 (#680)

---
 cpmpy/transformations/reification.py | 25 ++++++++++++++++++++++---
 tests/test_transf_reif.py            |  4 ++--
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/cpmpy/transformations/reification.py b/cpmpy/transformations/reification.py
index e566beca0..358576cbf 100644
--- a/cpmpy/transformations/reification.py
+++ b/cpmpy/transformations/reification.py
@@ -83,7 +83,7 @@ def only_implies(constraints):
             else:
                 newcons.append(cpm_expr)
 
-        # Comparisons: transform bV == BE
+        # Comparisons: transform BV == BE
         elif cpm_expr.name == '==' and cpm_expr.args[0].is_bool():
             # a0 is a boolvar, because of previous transformation only_bv_reifies.
             a0,a1 = cpm_expr.args
@@ -96,8 +96,27 @@ def only_implies(constraints):
                 # then it is actually an integer expression, keep
                 newcons.append(cpm_expr)
             else:
-                # BVar1 == BE0 :: ~BVar1 -> ~BE0, BVar1 -> BE0
-                retransform.extend(( (~a0).implies(recurse_negation(a1)), a0.implies(a1) ))
+                # BVar1 == BE0 :: BVar1 -> BE0, ~BVar1 -> ~BE0
+                # assume that if a0 == a1 was fine, that a0 -> a1 is too
+                # EXCEPT, optimisation a0 -> a1_0 & ... & a1_n :: a0 -> a1_0 & ... & a0 -> a1_n
+                if a1.name == 'and':
+                    # optimisation without going through retransform
+                    newcons.extend(a0.implies(a1_i) for a1_i in a1.args)
+                elif a1.has_subexpr():
+                    # requires retransform
+                    retransform.append(a0.implies(a1))
+                else:
+                    newcons.append(a0.implies(a1))
+
+                neg_a1 = recurse_negation(a1)
+                if neg_a1.name == 'and':
+                    # optimisation without going through retransform
+                    newcons.extend((~a0).implies(na1_i) for na1_i in neg_a1.args)
+                elif neg_a1.has_subexpr():
+                    # requires retransform
+                    retransform.append((~a0).implies(neg_a1))
+                else:
+                    newcons.append((~a0).implies(neg_a1))
         else:
             # all other flat normal form expressions are fine
             newcons.append(cpm_expr)
diff --git a/tests/test_transf_reif.py b/tests/test_transf_reif.py
index 15f36ca22..9dcea9540 100644
--- a/tests/test_transf_reif.py
+++ b/tests/test_transf_reif.py
@@ -23,8 +23,8 @@ def test_only_implies(self):
                  ((b&c).implies(a), "[(~a) -> ((~b) or (~c))]"),
                  ((a)==(b), "[(a) -> (b), (b) -> (a)]"),
                  ((~a)==(b), "[(~a) -> (b), (b) -> (~a)]"),
-                 ((b|c)==(a), "[(~a) -> (~b), (~a) -> (~c), (a) -> ((b) or (c))]"),
-                 ((b&c)==(a), "[(~a) -> ((~b) or (~c)), (a) -> (b), (a) -> (c)]"),
+                 ((b|c)==(a), "[(a) -> ((b) or (c)), (~a) -> (~b), (~a) -> (~c)]"),
+                 ((b&c)==(a), "[(a) -> (b), (a) -> (c), (~a) -> ((~b) or (~c))]"),
                 ]
 
         # test transformation

From 2828276cb75dd65bbb856793e1e0a34af8b53759 Mon Sep 17 00:00:00 2001
From: IgnaceBleukx <ignace.bleukx@kuleuven.be>
Date: Fri, 14 Feb 2025 11:41:22 +0100
Subject: [PATCH 37/39] cherry pick incremental_assumption test

---
 tests/test_solvers.py | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/tests/test_solvers.py b/tests/test_solvers.py
index 5b8d3d50e..baf3e11c5 100644
--- a/tests/test_solvers.py
+++ b/tests/test_solvers.py
@@ -1,4 +1,5 @@
 import importlib
+import inspect
 import unittest
 import tempfile
 import pytest
@@ -805,6 +806,36 @@ def test_incremental(self, solver):
         assert x.value()
         assert y.value() + z.value() == 1
 
+
+    def test_incremental_assumptions(self, solver):
+        x, y, z = cp.boolvar(shape=3, name=["x","y","z"])
+        s = cp.SolverLookup.get(solver)
+        if "assumptions" not in inspect.signature((s.solve)).parameters:
+            return # solver does not support solving under assumptions
+        
+        if solver == "pysdd":
+            return # not implemented in pysdd
+        
+        s += x | y
+        assert s.solve(assumptions=[x])
+        assert x.value()
+        assert (s.solve(assumptions=[~x]))
+        assert not (x.value())
+        assert (y.value())
+
+        s += ~x | z
+        assert s.solve(assumptions=[x,~y])
+        assert z.value()
+
+        s += y | ~z
+        assert not s.solve(assumptions=[~x, ~y])
+
+        core = s.get_core()
+        assert ~y in set([~x,~y])
+        assert cp.Model([x | y, ~x | z, y | ~z] + core).solve() is False # ensure it is indeed unsat
+
+        assert s.solve(assumptions=[])
+
     def test_vars_not_removed(self, solver):
             bvs = cp.boolvar(shape=3)
             m = cp.Model([cp.any(bvs) <= 2])

From f33dbd7931aa0ae4f111d54795cc1d0cb3721739 Mon Sep 17 00:00:00 2001
From: Ignace Bleukx <ignace.bleukx@kuleuven.be>
Date: Thu, 22 May 2025 10:54:26 +0200
Subject: [PATCH 38/39] CSE in flattening and decompose (#679)

* check if __bool__ is called on expression

* fix failing tests

* add explicit testcases for container testing

* override __bool__ in comparison

* fix blocking clause in minizinc

* fix minizinc solution translation

* remove wrong test (tests if True == True...)

* ensure reproducability of linearize tests

* process review

* update valueerror

* add get_repr() function to expressions

* finish merge conflict after cherry ppicking

* update solver interfaces

* update transformations

* forgot one

* update get_repr

* actually save something too...

* update default

* make more use of expr_dict in tranformations

* pass expr_dict everywhere

* do not make expr_dict

* add cse to all solvers and catch duplicate expressions

* remove get_repr

* further removal of get_repr

* avoid objects in memory during hash

* fix flatten_constraint

* proper test in decompose

* start of tests, wip

* no_partial_functions does not need expr_dict

* update tests

* revert solver interfaces

* update test

* cosmetic

* cleanup and merge master

* undo whitespace changes

* undo whitespace changes

* undo whitespace changes

* undo whitespace changes

* undo whitespace changes

* whitspace

* whitespace

* whitespace

* whitespace

* undo double-constraint optim

* consistency and fast path optim

* remove duplicate constraint from linearize

* rename to csemap

---------

Co-authored-by: wout4 <wout.vanroose@gmail.com>
Co-authored-by: Tias Guns <tias@ulyssis.org>
---
 cpmpy/solvers/choco.py                    |   8 +-
 cpmpy/solvers/cpo.py                      |   2 +-
 cpmpy/solvers/exact.py                    |  16 +--
 cpmpy/solvers/gcs.py                      |  14 +--
 cpmpy/solvers/gurobi.py                   |  16 +--
 cpmpy/solvers/minizinc.py                 |   2 +-
 cpmpy/solvers/ortools.py                  |  16 +--
 cpmpy/solvers/pysat.py                    |  10 +-
 cpmpy/solvers/pysdd.py                    |   2 +-
 cpmpy/solvers/solver_interface.py         |   1 +
 cpmpy/solvers/z3.py                       |   2 +-
 cpmpy/transformations/comparison.py       |  19 ++--
 cpmpy/transformations/decompose_global.py |  30 +++---
 cpmpy/transformations/flatten_model.py    |  89 +++++++++-------
 cpmpy/transformations/linearize.py        |  66 ++++++------
 cpmpy/transformations/reification.py      |  15 +--
 cpmpy/transformations/to_cnf.py           |   6 +-
 tests/test_cse.py                         | 124 ++++++++++++++++++++++
 tests/test_trans_linearize.py             |   2 +-
 19 files changed, 294 insertions(+), 146 deletions(-)
 create mode 100644 tests/test_cse.py

diff --git a/cpmpy/solvers/choco.py b/cpmpy/solvers/choco.py
index ff93ab99f..2eedcaf53 100644
--- a/cpmpy/solvers/choco.py
+++ b/cpmpy/solvers/choco.py
@@ -398,11 +398,11 @@ def transform(self, cpm_expr):
                      "decreasing","strictly_increasing","strictly_decreasing","lex_lesseq", "lex_less", "among", "precedence"}
 
         cpm_cons = no_partial_functions(cpm_cons)
-        cpm_cons = decompose_in_tree(cpm_cons, supported, supported) # choco supports any global also (half-) reified
-        cpm_cons = flatten_constraint(cpm_cons)  # flat normal form
+        cpm_cons = decompose_in_tree(cpm_cons, supported, supported, csemap=self._csemap) # choco supports any global also (half-) reified
+        cpm_cons = flatten_constraint(cpm_cons, csemap=self._csemap)  # flat normal form
         cpm_cons = canonical_comparison(cpm_cons)
-        cpm_cons = reify_rewrite(cpm_cons, supported = supported | {"sum", "wsum"})  # constraints that support reification
-        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum", "sub"]))  # support >, <, !=
+        cpm_cons = reify_rewrite(cpm_cons, supported = supported | {"sum", "wsum"}, csemap=self._csemap)  # constraints that support reification
+        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum", "sub"]), csemap=self._csemap)  # support >, <, !=
 
         return cpm_cons
 
diff --git a/cpmpy/solvers/cpo.py b/cpmpy/solvers/cpo.py
index 51955f73c..1dcdfea93 100644
--- a/cpmpy/solvers/cpo.py
+++ b/cpmpy/solvers/cpo.py
@@ -380,7 +380,7 @@ def transform(self, cpm_expr):
         supported = {"alldifferent", 'inverse', 'nvalue', 'element', 'table', 'indomain',
                      "negative_table", "gcc", 'max', 'min', 'abs', 'cumulative', 'no_overlap'}
         supported_reified = {"alldifferent", 'table', 'indomain', "negative_table"} # global functions by default here
-        cpm_cons = decompose_in_tree(cpm_cons, supported=supported, supported_reified=supported_reified)
+        cpm_cons = decompose_in_tree(cpm_cons, supported=supported, supported_reified=supported_reified, csemap=self._csemap)
         # no flattening required
         return cpm_cons
 
diff --git a/cpmpy/solvers/exact.py b/cpmpy/solvers/exact.py
index c2c5cc5ed..bbb811144 100644
--- a/cpmpy/solvers/exact.py
+++ b/cpmpy/solvers/exact.py
@@ -491,14 +491,14 @@ def transform(self, cpm_expr):
 
         cpm_cons = toplevel_list(cpm_expr)
         cpm_cons = no_partial_functions(cpm_cons, safen_toplevel={"mod", "div"}) # linearize expects safe exprs
-        cpm_cons = decompose_in_tree(cpm_cons, supported=frozenset({'alldifferent', 'abs'})) # Abs and Alldiff have a specialized MIP decomp
-        cpm_cons = flatten_constraint(cpm_cons)  # flat normal form
-        cpm_cons = reify_rewrite(cpm_cons, supported=frozenset(['sum', 'wsum']))  # constraints that support reification
-        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum"]))  # supports >, <, !=
-        cpm_cons = only_bv_reifies(cpm_cons)
-        cpm_cons = only_implies(cpm_cons)  # anything that can create full reif should go above...
-        cpm_cons = linearize_constraint(cpm_cons, supported=frozenset({"sum","wsum","mul"}))  # the core of the MIP-linearization
-        cpm_cons = only_positive_bv(cpm_cons)  # after linearisation, rewrite ~bv into 1-bv
+        cpm_cons = decompose_in_tree(cpm_cons, supported=frozenset({'alldifferent', 'abs'}), csemap=self._csemap) # Abs and Alldiff have a specialized MIP decomp
+        cpm_cons = flatten_constraint(cpm_cons, csemap=self._csemap)  # flat normal form
+        cpm_cons = reify_rewrite(cpm_cons, supported=frozenset(['sum', 'wsum']), csemap=self._csemap)  # constraints that support reification
+        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum"]), csemap=self._csemap)  # supports >, <, !=
+        cpm_cons = only_bv_reifies(cpm_cons, csemap=self._csemap)
+        cpm_cons = only_implies(cpm_cons, csemap=self._csemap)  # anything that can create full reif should go above...
+        cpm_cons = linearize_constraint(cpm_cons, supported=frozenset({"sum","wsum","mul"}), csemap=self._csemap)  # the core of the MIP-linearization
+        cpm_cons = only_positive_bv(cpm_cons, csemap=self._csemap)  # after linearisation, rewrite ~bv into 1-bv
 
         return cpm_cons
 
diff --git a/cpmpy/solvers/gcs.py b/cpmpy/solvers/gcs.py
index da7b2ec1f..3ff3f0d88 100644
--- a/cpmpy/solvers/gcs.py
+++ b/cpmpy/solvers/gcs.py
@@ -367,7 +367,7 @@ def objective(self, expr, minimize=True):
         self += flat_cons # add potentially created constraints
         self.user_vars.update(get_variables(flat_obj)) # add objvars to vars
 
-        (obj, obj_cons) = get_or_make_var(flat_obj)
+        (obj, obj_cons) = get_or_make_var(flat_obj, csemap=self._csemap)
         self += obj_cons
 
         self.objective_var = obj
@@ -406,18 +406,18 @@ def transform(self, cpm_expr):
             'circuit', 
             'xor'}
         cpm_cons = no_partial_functions(cpm_cons)
-        cpm_cons = decompose_in_tree(cpm_cons, supported)
-        cpm_cons = flatten_constraint(cpm_cons)  # flat normal form
+        cpm_cons = decompose_in_tree(cpm_cons, supported, csemap=self._csemap)
+        cpm_cons = flatten_constraint(cpm_cons, csemap=self._csemap)  # flat normal form
 
         # NB: GCS supports full reification for linear equality and linear inequaltiy constraints
         # but no reification for linear not equals and not half reification for linear equality. 
         # Maybe a future transformation (or future work on the GCS solver).
-        cpm_cons = reify_rewrite(cpm_cons, supported=frozenset(['==']))
-        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum"]))  # supports >, <, !=
+        cpm_cons = reify_rewrite(cpm_cons, supported=frozenset(['==']), csemap=self._csemap)
+        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum"]), csemap=self._csemap)  # supports >, <, !=
 
         # NB: GCS supports a small number of simple expressions as the reifying term
-        # e.g. (x > 3) -> constraint could in principle be supported in future. 
-        cpm_cons = only_bv_reifies(cpm_cons)
+        # e.g. (x > 3) -> constraint could in principle be supported in the future.
+        cpm_cons = only_bv_reifies(cpm_cons, csemap=self._csemap)
         str_rep = ""
         for c in cpm_cons:
             str_rep += str(c) + '\n'
diff --git a/cpmpy/solvers/gurobi.py b/cpmpy/solvers/gurobi.py
index 5d36d3973..70472c230 100644
--- a/cpmpy/solvers/gurobi.py
+++ b/cpmpy/solvers/gurobi.py
@@ -333,15 +333,15 @@ def transform(self, cpm_expr):
         cpm_cons = toplevel_list(cpm_expr)
         cpm_cons = no_partial_functions(cpm_cons, safen_toplevel={"mod", "div"})  # linearize expects safe exprs
         supported = {"min", "max", "abs", "alldifferent"} # alldiff has a specialized MIP decomp in linearize
-        cpm_cons = decompose_in_tree(cpm_cons, supported)
-        cpm_cons = flatten_constraint(cpm_cons)  # flat normal form
-        cpm_cons = reify_rewrite(cpm_cons, supported=frozenset(['sum', 'wsum']))  # constraints that support reification
-        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum", "sub"]))  # supports >, <, !=
-        cpm_cons = only_bv_reifies(cpm_cons)
-        cpm_cons = only_implies(cpm_cons)  # anything that can create full reif should go above...
+        cpm_cons = decompose_in_tree(cpm_cons, supported, csemap=self._csemap)
+        cpm_cons = flatten_constraint(cpm_cons, csemap=self._csemap)  # flat normal form
+        cpm_cons = reify_rewrite(cpm_cons, supported=frozenset(['sum', 'wsum']), csemap=self._csemap)  # constraints that support reification
+        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum", "sub"]), csemap=self._csemap)  # supports >, <, !=
+        cpm_cons = only_bv_reifies(cpm_cons, csemap=self._csemap)
+        cpm_cons = only_implies(cpm_cons, csemap=self._csemap)  # anything that can create full reif should go above...
         # gurobi does not round towards zero, so no 'div' in supported set: https://github.com/CPMpy/cpmpy/pull/593#issuecomment-2786707188
-        cpm_cons = linearize_constraint(cpm_cons, supported=frozenset({"sum", "wsum","sub","min","max","mul","abs","pow"}))  # the core of the MIP-linearization
-        cpm_cons = only_positive_bv(cpm_cons)  # after linearization, rewrite ~bv into 1-bv
+        cpm_cons = linearize_constraint(cpm_cons, supported=frozenset({"sum", "wsum","sub","min","max","mul","abs","pow"}), csemap=self._csemap)  # the core of the MIP-linearization
+        cpm_cons = only_positive_bv(cpm_cons, csemap=self._csemap)  # after linearization, rewrite ~bv into 1-bv
         return cpm_cons
 
     def add(self, cpm_expr_orig):
diff --git a/cpmpy/solvers/minizinc.py b/cpmpy/solvers/minizinc.py
index 5dd42c623..ceff42f51 100644
--- a/cpmpy/solvers/minizinc.py
+++ b/cpmpy/solvers/minizinc.py
@@ -496,7 +496,7 @@ def transform(self, cpm_expr):
                      "precedence", "no_overlap",
                      "strictly_increasing", "strictly_decreasing", "lex_lesseq", "lex_less", "lex_chain_less", 
                      "lex_chain_lesseq", "among"}
-        return decompose_in_tree(cpm_cons, supported, supported_reified=supported - {"circuit", "precedence"})
+        return decompose_in_tree(cpm_cons, supported, supported_reified=supported - {"circuit", "precedence"}, csemap=self._csemap)
 
     def add(self, cpm_expr):
         """
diff --git a/cpmpy/solvers/ortools.py b/cpmpy/solvers/ortools.py
index 66e9f91ce..14d2b1f4d 100644
--- a/cpmpy/solvers/ortools.py
+++ b/cpmpy/solvers/ortools.py
@@ -391,12 +391,12 @@ def transform(self, cpm_expr):
         cpm_cons = toplevel_list(cpm_expr)
         supported = {"min", "max", "abs", "element", "alldifferent", "xor", "table", "negative_table", "cumulative", "circuit", "inverse", "no_overlap", "regular"}
         cpm_cons = no_partial_functions(cpm_cons, safen_toplevel=frozenset({"div", "mod"})) # before decompose, assumes total decomposition for partial functions
-        cpm_cons = decompose_in_tree(cpm_cons, supported)
-        cpm_cons = flatten_constraint(cpm_cons)  # flat normal form
-        cpm_cons = reify_rewrite(cpm_cons, supported=frozenset(['sum', 'wsum']))  # constraints that support reification
-        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum", "sub"]))  # supports >, <, !=
-        cpm_cons = only_bv_reifies(cpm_cons)
-        cpm_cons = only_implies(cpm_cons)  # everything that can create
+        cpm_cons = decompose_in_tree(cpm_cons, supported, csemap=self._csemap)
+        cpm_cons = flatten_constraint(cpm_cons, csemap=self._csemap)  # flat normal form
+        cpm_cons = reify_rewrite(cpm_cons, supported=frozenset(['sum', 'wsum']), csemap=self._csemap)  # constraints that support reification
+        cpm_cons = only_numexpr_equality(cpm_cons, supported=frozenset(["sum", "wsum", "sub"]), csemap=self._csemap)  # supports >, <, !=
+        cpm_cons = only_bv_reifies(cpm_cons, csemap=self._csemap)
+        cpm_cons = only_implies(cpm_cons, csemap=self._csemap)  # everything that can create
                                              # reified expr must go before this
         return cpm_cons
 
@@ -512,7 +512,7 @@ def _post_constraint(self, cpm_expr, reifiable=False):
                     # catch tricky-to-find ortools limitation
                     x,y = lhs.args
                     if get_bounds(y)[0] <= 0: # not supported, but result of modulo is agnositic to sign of second arg
-                        y, link = get_or_make_var(-lhs.args[1])
+                        y, link = get_or_make_var(-lhs.args[1], csemap=self._csemap)
                         self += link
                     return self.ort_model.AddModuloEquality(ortrhs, *self.solver_vars([x,y]))
                 elif lhs.name == 'pow':
@@ -526,7 +526,7 @@ def _post_constraint(self, cpm_expr, reifiable=False):
                         b, n = lhs.args
                         new_lhs = 1
                         for exp in range(n):
-                            new_lhs, new_cons = get_or_make_var(b * new_lhs)
+                            new_lhs, new_cons = get_or_make_var(b * new_lhs, csemap=self._csemap)
                             self += new_cons
                         return self.ort_model.Add(eval_comparison("==", self.solver_var(new_lhs), ortrhs))
 
diff --git a/cpmpy/solvers/pysat.py b/cpmpy/solvers/pysat.py
index 39224a391..f49d5a117 100644
--- a/cpmpy/solvers/pysat.py
+++ b/cpmpy/solvers/pysat.py
@@ -301,12 +301,12 @@ def transform(self, cpm_expr):
             :return: list of Expression
         """
         cpm_cons = toplevel_list(cpm_expr)
-        cpm_cons = decompose_in_tree(cpm_cons, supported=frozenset({"alldifferent"}))
+        cpm_cons = decompose_in_tree(cpm_cons, supported=frozenset({"alldifferent"}), csemap=self._csemap)
         cpm_cons = simplify_boolean(cpm_cons)
-        cpm_cons = flatten_constraint(cpm_cons)  # flat normal form
-        cpm_cons = only_bv_reifies(cpm_cons)
-        cpm_cons = only_implies(cpm_cons)
-        cpm_cons = linearize_constraint(cpm_cons, supported=frozenset({"sum","wsum", "and", "or"}))  # the core of the MIP-linearization
+        cpm_cons = flatten_constraint(cpm_cons, csemap=self._csemap)  # flat normal form
+        cpm_cons = only_bv_reifies(cpm_cons, csemap=self._csemap)
+        cpm_cons = only_implies(cpm_cons, csemap=self._csemap)
+        cpm_cons = linearize_constraint(cpm_cons, supported=frozenset({"sum","wsum", "and", "or"}), csemap=self._csemap)  # the core of the MIP-linearization
         cpm_cons = only_positive_coefficients(cpm_cons)
         return cpm_cons
 
diff --git a/cpmpy/solvers/pysdd.py b/cpmpy/solvers/pysdd.py
index 7cf40251d..9c4622fca 100644
--- a/cpmpy/solvers/pysdd.py
+++ b/cpmpy/solvers/pysdd.py
@@ -266,7 +266,7 @@ def transform(self, cpm_expr):
         """
         # works on list of nested expressions
         cpm_cons = toplevel_list(cpm_expr)
-        cpm_cons = decompose_in_tree(cpm_cons,supported={'xor'}, supported_reified={'xor'}) #keep unsupported xor for error message purposes.
+        cpm_cons = decompose_in_tree(cpm_cons,supported={'xor'}, supported_reified={'xor'}, csemap=self._csemap) #keep unsupported xor for error message purposes.
         cpm_cons = simplify_boolean(cpm_cons)  # for cleaning (BE >= 0) and such
         return cpm_cons
 
diff --git a/cpmpy/solvers/solver_interface.py b/cpmpy/solvers/solver_interface.py
index 37205f4ea..e4b56c699 100644
--- a/cpmpy/solvers/solver_interface.py
+++ b/cpmpy/solvers/solver_interface.py
@@ -75,6 +75,7 @@ def __init__(self, name="dummy", cpm_model=None, subsolver=None):
         # initialise variable handling
         self.user_vars = set()  # variables in the original (non-transformed) model
         self._varmap = dict()  # maps cpmpy variables to native solver variables
+        self._csemap = dict()  # maps cpmpy expressions to solver expressions
 
         # rest uses own API
         if cpm_model is not None:
diff --git a/cpmpy/solvers/z3.py b/cpmpy/solvers/z3.py
index 3dd9ed254..8f786fca0 100644
--- a/cpmpy/solvers/z3.py
+++ b/cpmpy/solvers/z3.py
@@ -328,7 +328,7 @@ def transform(self, cpm_expr):
         cpm_cons = toplevel_list(cpm_expr)
         cpm_cons = no_partial_functions(cpm_cons, safen_toplevel={"div", "mod"})
         supported = {"alldifferent", "xor", "ite"}  # z3 accepts these reified too
-        cpm_cons = decompose_in_tree(cpm_cons, supported, supported)
+        cpm_cons = decompose_in_tree(cpm_cons, supported, supported, csemap=self._csemap)
         return cpm_cons
 
     def add(self, cpm_expr):
diff --git a/cpmpy/transformations/comparison.py b/cpmpy/transformations/comparison.py
index eb6f51909..64a44d2b5 100644
--- a/cpmpy/transformations/comparison.py
+++ b/cpmpy/transformations/comparison.py
@@ -20,7 +20,7 @@
 from ..expressions.utils import is_boolexpr
 from ..expressions.variables import _NumVarImpl, _BoolVarImpl
 
-def only_numexpr_equality(constraints, supported=frozenset()):
+def only_numexpr_equality(constraints, supported=frozenset(), csemap=None):
     """
         Transforms ``NumExpr <op> IV`` to ``(NumExpr == A) & (A <op> IV)`` if not supported.
         Also for the reified uses of `NumExpr`
@@ -36,13 +36,13 @@ def only_numexpr_equality(constraints, supported=frozenset()):
         if isinstance(cpm_expr, Operator) and cpm_expr.name == "->":
             cond, subexpr = cpm_expr.args
             if not isinstance(cond, _BoolVarImpl): # expr -> bv
-                res = only_numexpr_equality([cond], supported)
+                res = only_numexpr_equality([cond], supported, csemap=csemap)
                 if len(res) > 1:
                     newcons[i] = res[1].implies(subexpr)
                     newcons.insert(i, res[0])
 
             elif not isinstance(subexpr, _BoolVarImpl):  # bv -> expr
-                res = only_numexpr_equality([subexpr], supported)
+                res = only_numexpr_equality([subexpr], supported, csemap=csemap)
                 if len(res) > 1:
                     newcons[i] = cond.implies(res[1])
                     newcons.insert(i, res[0])
@@ -56,13 +56,13 @@ def only_numexpr_equality(constraints, supported=frozenset()):
             if cpm_expr.name == "==" and is_boolexpr(lhs) and is_boolexpr(rhs): # reification, check recursively
 
                 if not isinstance(lhs, _BoolVarImpl):  # expr == bv
-                    res = only_numexpr_equality([lhs], supported)
+                    res = only_numexpr_equality([lhs], supported, csemap=csemap)
                     if len(res) > 1:
                         newcons[i] = res[1] == rhs
                         newcons.insert(i, res[0])
 
                 elif not isinstance(rhs, _BoolVarImpl):  # bv == expr
-                    res = only_numexpr_equality([rhs], supported)
+                    res = only_numexpr_equality([rhs], supported, csemap=csemap)
                     if len(res) > 1:
                         newcons[i] = lhs == res[1]
                         newcons.insert(i, res[0])
@@ -74,11 +74,14 @@ def only_numexpr_equality(constraints, supported=frozenset()):
                 lhs = cpm_expr.args[0]
                 if not isinstance(lhs, _NumVarImpl) and lhs.name not in supported:
                     # LHS is unsupported for LHS <op> IV, rewrite to `(LHS == A) & (A <op> IV)`
-                    (lhsvar, lhscons) = get_or_make_var(lhs)
+                    (lhsvar, lhscons) = get_or_make_var(lhs, csemap=csemap)
                     # replace comparison by A <op> IV
                     newcons[i] = Comparison(cpm_expr.name, lhsvar, cpm_expr.args[1])
                     # add lhscon(s), which will be [(LHS == A)]
-                    assert(len(lhscons) == 1), "only_numexpr_eq: lhs surprisingly non-flat"
-                    newcons.insert(i, lhscons[0])
+                    if len(lhscons) == 1:
+                        newcons.insert(i, lhscons[0])
+                    else:
+                        assert (len(lhscons) == 0), "only_numexpr_eq: lhs surprisingly non-flat"
+                        # can be 0 because of CSE
 
     return newcons
diff --git a/cpmpy/transformations/decompose_global.py b/cpmpy/transformations/decompose_global.py
index cf92c2c26..0b752080f 100644
--- a/cpmpy/transformations/decompose_global.py
+++ b/cpmpy/transformations/decompose_global.py
@@ -15,7 +15,7 @@
 from .flatten_model import flatten_constraint, normalized_numexpr
 
 
-def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _toplevel=None, nested=False):
+def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _toplevel=None, nested=False, csemap=None):
     """
         Decomposes any global constraint not supported by the solver.
         Accepts a list of CPMpy expressions as input and returns a list of CPMpy expressions.
@@ -48,12 +48,12 @@ def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _to
             if isinstance(expr, NDVarArray):  # NDVarArray is also an expression,
                                               # so we can call has_subexpr on it for a possible early-exit
                 if expr.has_subexpr():
-                    newexpr = decompose_in_tree(expr, supported, supported_reified, _toplevel, nested=True)
+                    newexpr = decompose_in_tree(expr, supported, supported_reified, _toplevel, nested=True, csemap=csemap)
                     newlist.append(cpm_array(newexpr))
                 else:
                     newlist.append(expr)
             else: # a normal list-like (list, tuple, np.ndarray), must be called recursively and check all elements
-                newexpr = decompose_in_tree(expr, supported, supported_reified, _toplevel, nested=True)
+                newexpr = decompose_in_tree(expr, supported, supported_reified, _toplevel, nested=True, csemap=csemap)
                 newlist.append(newexpr)
             continue
 
@@ -64,10 +64,10 @@ def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _to
                 continue
 
             if any(isinstance(a,GlobalFunction) for a in expr.args):
-                expr, base_con = normalized_numexpr(expr)
+                expr, base_con = normalized_numexpr(expr, csemap=csemap)
                 _toplevel.extend(base_con)  # should be added toplevel
             # recurse into arguments, recreate through constructor (we know it stores no other state)
-            args = decompose_in_tree(expr.args, supported, supported_reified, _toplevel, nested=True)
+            args = decompose_in_tree(expr.args, supported, supported_reified, _toplevel, nested=True, csemap=csemap)
             newlist.append(Operator(expr.name, args))
 
         elif isinstance(expr, GlobalConstraint) or isinstance(expr, GlobalFunction):
@@ -86,7 +86,7 @@ def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _to
                 # Recursively decompose the subexpression arguments
                 else:
                     expr = copy.copy(expr)
-                    expr.update_args(decompose_in_tree(expr.args, supported, supported_reified, _toplevel, nested=True))
+                    expr.update_args(decompose_in_tree(expr.args, supported, supported_reified, _toplevel, nested=True, csemap=csemap))
                     newlist.append(expr)
 
             else:
@@ -103,14 +103,20 @@ def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _to
 
                     _toplevel.extend(define)  # definitions should be added toplevel
                     # the `decomposed` expression might contain other global constraints, check it
-                    decomposed = decompose_in_tree(decomposed, supported, supported_reified, _toplevel, nested=nested)
+                    decomposed = decompose_in_tree(decomposed, supported, supported_reified, _toplevel, nested=nested, csemap=csemap)
                     newlist.append(all(decomposed))
 
                 else:
                     # global function, replace by a fresh variable and decompose the equality to this
                     assert isinstance(expr, GlobalFunction)
                     lb,ub = expr.get_bounds()
-                    aux = intvar(lb, ub)
+                    
+                    if csemap is not None and expr in csemap:
+                        aux = csemap[expr]
+                    else:
+                        aux = intvar(lb, ub)
+                        if csemap is not None:
+                            csemap[expr] = aux
 
                     # NOTE Do we need to decompose here (the expr's args)? As done in the Comparison's section?
 
@@ -142,7 +148,7 @@ def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _to
                 if not decomp_rhs:
                     # nothing special, create a fresh version and recurse into arguments
                     expr = copy.copy(expr)
-                    expr.update_args(decompose_in_tree(expr.args, supported, supported_reified, _toplevel, nested=True))
+                    expr.update_args(decompose_in_tree(expr.args, supported, supported_reified, _toplevel, nested=True, csemap=csemap))
                     newlist.append(expr)
 
                 else:
@@ -155,7 +161,7 @@ def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _to
                 if lhs.has_subexpr():
                     # recurse into lhs args and decompose nested subexpressions
                     lhs = copy.copy(lhs)
-                    lhs.update_args(decompose_in_tree(lhs.args, supported, supported_reified, _toplevel, nested=True))
+                    lhs.update_args(decompose_in_tree(lhs.args, supported, supported_reified, _toplevel, nested=True, csemap=csemap))
 
                 # decompose comparison of lhs and rhs
                 dec = lhs.decompose_comparison(exprname, rhs)
@@ -168,7 +174,7 @@ def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _to
 
                 _toplevel.extend(define)  # definitions should be added toplevel
                 # the `decomposed` expression (and rhs) might contain other global constraints, check it
-                decomposed = decompose_in_tree(decomposed, supported, supported_reified, _toplevel, nested=True)
+                decomposed = decompose_in_tree(decomposed, supported, supported_reified, _toplevel, nested=True, csemap=csemap)
                 newlist.append(all(decomposed))
 
         else:  # constants, variables, direct constraints
@@ -181,7 +187,7 @@ def decompose_in_tree(lst_of_expr, supported=set(), supported_reified=set(), _to
         return toplevel_list(newlist)
     else:
         # we are toplevel and some new constraints are introduced, decompose new constraints!
-        return toplevel_list(newlist) + decompose_in_tree(toplevel_list(_toplevel), supported, supported_reified, nested=False)
+        return toplevel_list(newlist) + decompose_in_tree(toplevel_list(_toplevel), supported, supported_reified, nested=False, csemap=csemap)
 
 
 # DEPRECATED!
diff --git a/cpmpy/transformations/flatten_model.py b/cpmpy/transformations/flatten_model.py
index 2d6f0349d..bed4c5a9e 100644
--- a/cpmpy/transformations/flatten_model.py
+++ b/cpmpy/transformations/flatten_model.py
@@ -120,7 +120,7 @@ def flatten_model(orig_model):
             return cp.Model(*basecons, maximize=newobj)
 
 
-def flatten_constraint(expr):
+def flatten_constraint(expr, csemap=None):
     """
         input is any expression; except is_num(), pure _NumVarImpl,
         or Operator/GlobalConstraint with not is_bool()
@@ -164,7 +164,7 @@ def flatten_constraint(expr):
                         if isinstance(a, Operator) and a.name == '->':
                             newargs[i:i+1] = [~a.args[0],a.args[1]]
                     # there could be nested implications
-                    newlist.extend(flatten_constraint(Operator('or', newargs)))
+                    newlist.extend(flatten_constraint(Operator('or', newargs), csemap=csemap))
                     continue
                 # conjunctions in disjunctions could be split out by applying distributivity,
                 # but this would explode the number of constraints in favour of having less auxiliary variables.
@@ -175,30 +175,30 @@ def flatten_constraint(expr):
                 if expr.args[1].name == 'and':
                     a1s = expr.args[1].args
                     a0 = expr.args[0]
-                    newlist.extend(flatten_constraint([a0.implies(a1) for a1 in a1s]))
+                    newlist.extend(flatten_constraint([a0.implies(a1) for a1 in a1s], csemap=csemap))
                     continue
                 # 2) if lhs is 'or' then or([a01..a0n])->a1 :: ~a1->and([~a01..~a0n] and split
                 elif expr.args[0].name == 'or':
                     a0s = expr.args[0].args
                     a1 = expr.args[1]
-                    newlist.extend(flatten_constraint([(~a1).implies(~a0) for a0 in a0s]))
+                    newlist.extend(flatten_constraint([(~a1).implies(~a0) for a0 in a0s], csemap=csemap))
                     continue
                 # 2b) if lhs is ->, like 'or': a01->a02->a1 :: (~a01|a02)->a1 :: ~a1->a01,~a1->~a02
                 elif expr.args[0].name == '->':
                     a01,a02 = expr.args[0].args
                     a1 = expr.args[1]
-                    newlist.extend(flatten_constraint([(~a1).implies(a01), (~a1).implies(~a02)]))
+                    newlist.extend(flatten_constraint([(~a1).implies(a01), (~a1).implies(~a02)], csemap=csemap))
                     continue
 
                 # ->, allows a boolexpr on one side
                 elif isinstance(expr.args[0], _BoolVarImpl):
                     # LHS is var, ensure RHS is normalized 'Boolexpr'
                     lhs,lcons = expr.args[0], ()
-                    rhs,rcons = normalized_boolexpr(expr.args[1])
+                    rhs,rcons = normalized_boolexpr(expr.args[1], csemap=csemap)
                 else:
                     # make LHS normalized 'Boolexpr', RHS must be a var
-                    lhs,lcons = normalized_boolexpr(expr.args[0])
-                    rhs,rcons = get_or_make_var(expr.args[1])
+                    lhs,lcons = normalized_boolexpr(expr.args[0], csemap=csemap)
+                    rhs,rcons = get_or_make_var(expr.args[1], csemap=csemap)
 
                 newlist.append(Operator(expr.name, (lhs,rhs)))
                 newlist.extend(lcons)
@@ -209,7 +209,7 @@ def flatten_constraint(expr):
 
             # if none of the above cases + continue matched:
             # a normalizable boolexpr
-            (con, flatcons) = normalized_boolexpr(expr)
+            (con, flatcons) = normalized_boolexpr(expr, csemap=csemap)
             newlist.append(con)
             newlist.extend(flatcons)
 
@@ -253,18 +253,18 @@ def flatten_constraint(expr):
                 continue
 
             # ensure rhs is var
-            (rvar, rcons) = get_or_make_var(rexpr)
+            (rvar, rcons) = get_or_make_var(rexpr, csemap=csemap)
             # Reification (double implication): Boolexpr == Var
             # normalize the lhs (does not have to be a var, hence we call normalize instead of get_or_make_var
             if exprname == '==' and lexpr.is_bool():
                 if rvar.is_bool():
                     # this is a reification
-                    (lhs, lcons) = normalized_boolexpr(lexpr)
+                    (lhs, lcons) = normalized_boolexpr(lexpr, csemap=csemap)
                 else:
                     # integer comparison
-                    (lhs, lcons) = get_or_make_var(lexpr)
+                    (lhs, lcons) = get_or_make_var(lexpr, csemap=csemap)
             else:
-                (lhs, lcons) = normalized_numexpr(lexpr)
+                (lhs, lcons) = normalized_numexpr(lexpr, csemap=csemap)
 
             newlist.append(Comparison(exprname, lhs, rvar))
             newlist.extend(lcons)
@@ -274,7 +274,7 @@ def flatten_constraint(expr):
             """
     - Global constraint: global([Var]*)          (CPMpy class 'GlobalConstraint')
             """
-            (con, flatcons) = normalized_boolexpr(expr)
+            (con, flatcons) = normalized_boolexpr(expr, csemap=csemap)
             newlist.append(con)
             newlist.extend(flatcons)
 
@@ -285,7 +285,7 @@ def flatten_constraint(expr):
     return newlist
 
 
-def flatten_objective(expr, supported=frozenset(["sum","wsum"])):
+def flatten_objective(expr, supported=frozenset(["sum", "wsum"]), csemap=None):
     """
     - Decision variable: Var
     - Linear: 
@@ -305,7 +305,7 @@ def flatten_objective(expr, supported=frozenset(["sum","wsum"])):
         return (flatexpr, flatcons)
     else:
         # any other numeric expression,
-        var, cons = get_or_make_var(flatexpr)
+        var, cons = get_or_make_var(flatexpr, csemap=csemap)
         return (var, cons+flatcons)
 
 
@@ -322,32 +322,40 @@ def __is_flat_var_or_list(arg):
            is_any_list(arg) and all(__is_flat_var_or_list(el) for el in arg) or \
            is_star(arg)
 
-def get_or_make_var(expr):
+def get_or_make_var(expr, csemap=None):
     """
         Must return a variable, and list of flat normal constraints
         Determines whether this is a Boolean or Integer variable and returns
         the equivalent of: (var, normalize(expr) == var)
     """
+
     if __is_flat_var(expr):
         return (expr, [])
 
     if is_any_list(expr):
         raise Exception(f"Expected single variable, not a list for: {expr}")
 
+    if csemap is not None and expr in csemap:
+        return csemap[expr], []
+
     if expr.is_bool():
         # normalize expr into a boolexpr LHS, reify LHS == bvar
-        (flatexpr, flatcons) = normalized_boolexpr(expr)
+        (flatexpr, flatcons) = normalized_boolexpr(expr, csemap=csemap)
 
         if isinstance(flatexpr,_BoolVarImpl):
             # avoids unnecessary bv == bv or bv == ~bv assignments
             return flatexpr,flatcons
         bvar = _BoolVarImpl()
+
+        # save expr in dict
+        if csemap is not None:
+            csemap[expr] = bvar
         return bvar, [flatexpr == bvar] + flatcons
 
     else:
         # normalize expr into a numexpr LHS,
         # then compute bounds and return (newintvar, LHS == newintvar)
-        (flatexpr, flatcons) = normalized_numexpr(expr)
+        (flatexpr, flatcons) = normalized_numexpr(expr, csemap=csemap)
 
         lb, ub = flatexpr.get_bounds()
         if not is_int(lb) or not is_int(ub):
@@ -355,22 +363,27 @@ def get_or_make_var(expr):
                           f" - {ub}({type(ub)}. CPMpy will rewrite this constriants with integer bounds instead.")
             lb, ub = math.floor(lb), math.ceil(ub)
         ivar = _IntVarImpl(lb, ub)
+
+        # save expr in dict
+        if csemap is not None:
+            csemap[expr] = ivar
         return ivar, [flatexpr == ivar] + flatcons
 
-def get_or_make_var_or_list(expr):
+def get_or_make_var_or_list(expr, csemap=None):
     """ Like get_or_make_var() but also accepts and recursively transforms lists
         Used to convert arguments of globals
     """
+
     if __is_flat_var_or_list(expr):
         return (expr,[])
     elif is_any_list(expr):
-        flatvars, flatcons = zip(*[get_or_make_var(arg) for arg in expr])
+        flatvars, flatcons = zip(*[get_or_make_var(arg, csemap=csemap) for arg in expr])
         return (flatvars, [c for con in flatcons for c in con])
     else:
-        return get_or_make_var(expr)
+        return get_or_make_var(expr, csemap=csemap)
 
 
-def normalized_boolexpr(expr):
+def normalized_boolexpr(expr, csemap=None):
     """
         input is any Boolean (is_bool()) expression
         output are all 'flat normal form' Boolean expressions that can be 'reified', meaning that
@@ -406,18 +419,18 @@ def normalized_boolexpr(expr):
         # apply De Morgan's transform for "implies"
         if expr.name == '->':
             # TODO, optimisation if args0 is an 'and'?
-            (lhs,lcons) = get_or_make_var(expr.args[0])
+            (lhs,lcons) = get_or_make_var(expr.args[0], csemap=csemap)
             # TODO, optimisation if args1 is an 'or'?
-            (rhs,rcons) = get_or_make_var(expr.args[1])
+            (rhs,rcons) = get_or_make_var(expr.args[1], csemap=csemap)
             return ((~lhs | rhs), lcons+rcons)
         if expr.name == 'not':
-            flatvar, flatcons = get_or_make_var(expr.args[0])
+            flatvar, flatcons = get_or_make_var(expr.args[0], csemap=csemap)
             return (~flatvar, flatcons)
         if not expr.has_subexpr():
             return (expr, [])
         else:
             # one of the arguments is not flat, flatten all
-            flatvars, flatcons = zip(*[get_or_make_var(arg) for arg in expr.args])
+            flatvars, flatcons = zip(*[get_or_make_var(arg, csemap=csemap) for arg in expr.args])
             newexpr = Operator(expr.name, flatvars)
             return (newexpr, [c for con in flatcons for c in con])
 
@@ -436,19 +449,19 @@ def normalized_boolexpr(expr):
                 lexpr, rexpr = rexpr, lexpr
 
             # ensure rhs is var
-            (rvar, rcons) = get_or_make_var(rexpr)
+            (rvar, rcons) = get_or_make_var(rexpr, csemap=csemap)
 
             # LHS: check if Boolexpr == smth:
             if (exprname == '==' or exprname == '!=') and lexpr.is_bool():
                 # this is a reified constraint, so lhs must be var too to be in normal form
-                (lhs, lcons) = get_or_make_var(lexpr)
+                (lhs, lcons) = get_or_make_var(lexpr, csemap=csemap)
                 if expr.name == '!=' and rvar.is_bool():
                     # != not needed, negate RHS variable
                     rvar = ~rvar
                     exprname = '=='
             else:
                 # other cases: LHS is numexpr
-                (lhs, lcons) = normalized_numexpr(lexpr)
+                (lhs, lcons) = normalized_numexpr(lexpr, csemap=csemap)
 
             return (Comparison(exprname, lhs, rvar), lcons+rcons)
 
@@ -461,7 +474,7 @@ def normalized_boolexpr(expr):
             return (expr, [])
         else:
             # recursively flatten all children
-            flatargs, flatcons = zip(*[get_or_make_var_or_list(arg) for arg in expr.args])
+            flatargs, flatcons = zip(*[get_or_make_var_or_list(arg, csemap=csemap) for arg in expr.args])
 
             # take copy, replace args
             newexpr = copy.copy(expr) # shallow or deep? currently shallow
@@ -469,7 +482,7 @@ def normalized_boolexpr(expr):
             return (newexpr, [c for con in flatcons for c in con])
 
 
-def normalized_numexpr(expr):
+def normalized_numexpr(expr, csemap=None):
     """
         all 'flat normal form' numeric expressions...
 
@@ -493,12 +506,12 @@ def normalized_numexpr(expr):
     elif expr.is_bool():
         # unusual case, but its truth-value is a valid numexpr
         # so reify and return the boolvar
-        return get_or_make_var(expr)
+        return get_or_make_var(expr, csemap=csemap)
 
     elif isinstance(expr, Operator):
         # rewrite -a, const*a and a*const into a weighted sum, so it can be used as objective
         if expr.name == '-' or (expr.name == 'mul' and _wsum_should(expr)):
-            return normalized_numexpr(Operator("wsum", _wsum_make(expr)))
+            return normalized_numexpr(Operator("wsum", _wsum_make(expr)), csemap=csemap)
 
         if not expr.has_subexpr():
             return (expr, [])
@@ -510,7 +523,7 @@ def normalized_numexpr(expr):
             we = [_wsum_make(a) for a in expr.args]
             w = [wi for w,_ in we for wi in w]
             e = [ei for _,e in we for ei in e]
-            return normalized_numexpr(Operator("wsum", (w,e)))
+            return normalized_numexpr(Operator("wsum", (w,e)), csemap=csemap)
 
         # wsum needs special handling because expr.args is a tuple of which only 2nd one has exprs
         if expr.name == 'wsum':
@@ -531,13 +544,13 @@ def normalized_numexpr(expr):
                     i = i+1
 
             # now flatten the resulting subexprs
-            flatvars, flatcons = map(list, zip(*[get_or_make_var(arg) for arg in sub_exprs])) # also bool, reified...
+            flatvars, flatcons = map(list, zip(*[get_or_make_var(arg, csemap=csemap) for arg in sub_exprs])) # also bool, reified...
             newexpr = Operator(expr.name, (weights, flatvars))
             return (newexpr, [c for con in flatcons for c in con])
 
         else: # generic operator
             # recursively flatten all children
-            flatvars, flatcons = zip(*[get_or_make_var(arg) for arg in expr.args])
+            flatvars, flatcons = zip(*[get_or_make_var(arg, csemap=csemap) for arg in expr.args])
 
             newexpr = Operator(expr.name, flatvars)
             return (newexpr, [c for con in flatcons for c in con])
@@ -549,7 +562,7 @@ def normalized_numexpr(expr):
             return (expr, [])
         else:
             # recursively flatten all children
-            flatvars, flatcons = zip(*[get_or_make_var_or_list(arg) for arg in expr.args])
+            flatvars, flatcons = zip(*[get_or_make_var_or_list(arg, csemap=csemap) for arg in expr.args])
 
             # take copy, replace args
             newexpr = copy.copy(expr) # shallow or deep? currently shallow
diff --git a/cpmpy/transformations/linearize.py b/cpmpy/transformations/linearize.py
index a1b74c0d1..8735fff1a 100644
--- a/cpmpy/transformations/linearize.py
+++ b/cpmpy/transformations/linearize.py
@@ -70,7 +70,7 @@
 
 from ..expressions.variables import _BoolVarImpl, boolvar, NegBoolView, _NumVarImpl, intvar
 
-def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
+def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False, csemap=None):
     """
     Transforms all constraints to a linear form.
     This function assumes all constraints are in 'flat normal form' with only boolean variables on the lhs of an implication.
@@ -124,7 +124,7 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
 
                 # BV -> LinExpr
                 elif isinstance(cond, _BoolVarImpl):
-                    lin_sub = linearize_constraint([sub_expr], supported=supported, reified=True)
+                    lin_sub = linearize_constraint([sub_expr], supported=supported, reified=True, csemap=csemap)
                     # BV -> (C1 and ... and Cn) == (BV -> C1) and ... and (BV -> Cn)
                     indicator_constraints=[]
                     for lin in lin_sub:
@@ -132,7 +132,7 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
                             continue
                         elif is_false_cst(lin):
                             indicator_constraints=[] # do not add any constraints
-                            newlist+=linearize_constraint([~cond], supported=supported) # post linear version of unary constraint
+                            newlist+=linearize_constraint([~cond], supported=supported, csemap=csemap) # post linear version of unary constraint
                             break # do not need to add other
                         else:
                             indicator_constraints.append(cond.implies(lin)) # Add indicator constraint
@@ -140,7 +140,7 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
 
                     # ensure no new solutions are created
                     new_vars = set(get_variables(lin_sub)) - set(get_variables(sub_expr))
-                    newlist += linearize_constraint([(~cond).implies(nv == nv.lb) for nv in new_vars], supported=supported, reified=reified)
+                    newlist += linearize_constraint([(~cond).implies(nv == nv.lb) for nv in new_vars], supported=supported, reified=reified, csemap=csemap)
 
             else: # supported operator
                 newlist.append(cpm_expr)
@@ -175,7 +175,7 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
                     x, n = lhs.args
                     new_lhs = 1
                     for exp in range(n):
-                        new_lhs, new_cons = get_or_make_var(x * new_lhs)
+                        new_lhs, new_cons = get_or_make_var(x * new_lhs, csemap=csemap)
                         newlist.extend(new_cons)
                     cpm_expr = eval_comparison(cpm_expr.name, new_lhs, rhs)
 
@@ -185,9 +185,9 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
                         raise NotImplementedError("Cannot linearize modulo without multiplication")
 
                     if cpm_expr.name != "==":
-                        new_rhs, newcons = get_or_make_var(lhs)
+                        new_rhs, newcons = get_or_make_var(lhs, csemap=csemap)
                         newlist.append(eval_comparison(cpm_expr.name, new_rhs, rhs))
-                        newlist += linearize_constraint(newcons, supported=supported, reified=reified)
+                        newlist += linearize_constraint(newcons, supported=supported, reified=reified, csemap=csemap)
                         continue
                     else:
                         # mod != remainder after division because defined on integer div (rounding towards 0)
@@ -201,11 +201,11 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
 
                         # k * y + z == x
                         k = intvar(*get_bounds((x - rhs) // y))
-                        mult_res, side_cons = get_or_make_var(k * y)
+                        mult_res, side_cons = get_or_make_var(k * y, csemap=csemap)
                         cpm_expr = (mult_res + rhs) == x
                         # |z| < |y|
-                        abs_of_z = cp.intvar(*get_bounds(abs(rhs)))
-                        side_cons.append(abs(rhs) == abs_of_z)
+                        abs_of_z, new_cons = get_or_make_var(abs(rhs), csemap=csemap)
+                        side_cons += new_cons
                         # TODO: do the following in constructor of abs instead?
                         # we know y is strictly positive or negative due to safening.
                         if lby >= 0:
@@ -227,16 +227,16 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
                             ]
 
                         side_cons = toplevel_list(side_cons) # get rid of bools that may result from the above
-                        newlist += linearize_constraint(side_cons, supported, reified=reified)
+                        newlist += linearize_constraint(side_cons, supported, reified=reified, csemap=csemap)
 
                 elif lhs.name == 'div' and 'div' not in supported:
                     if "mul" not in supported:
                         raise NotImplementedError("Cannot linearize division without multiplication")
 
                     if cpm_expr.name != "==":
-                        new_rhs, newcons = get_or_make_var(lhs)
+                        new_rhs, newcons = get_or_make_var(lhs, csemap=csemap)
                         newlist.append(eval_comparison(cpm_expr.name, new_rhs, rhs))
-                        newlist += linearize_constraint(newcons, supported=supported, reified=reified)
+                        newlist += linearize_constraint(newcons, supported=supported, reified=reified, csemap=csemap)
                         continue
 
                     else:
@@ -249,22 +249,22 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
                             raise ValueError("Attempting linerarization of unsafe division, safen expression first (cpmpy/transformations/safen.py)")
 
                         r = intvar(*get_bounds(a % b)) # r is the remainder, reuse our bound calculations
-                        mult_res, side_cons = get_or_make_var(b * rhs)
+                        mult_res, side_cons = get_or_make_var(b * rhs, csemap=csemap)
                         cpm_expr = eval_comparison(cpm_expr.name, a, mult_res + r)
 
                         # need absolute values of variables later
-                        abs_of_a = intvar(*get_bounds(abs(a)))
-                        abs_of_b = intvar(*get_bounds(abs(b)))
-                        abs_of_rhs = intvar(*get_bounds(abs(rhs)))
-                        abs_of_r = intvar(*get_bounds(abs(r)))
-                        side_cons += [abs(a) == abs_of_a, abs(b) == abs_of_b, abs(rhs) == abs_of_rhs, abs(r) == abs_of_r]
+                        abs_of_a, side_cons_a = get_or_make_var(abs(a), csemap=csemap)
+                        abs_of_b, side_cons_b = get_or_make_var(abs(b), csemap=csemap)
+                        abs_of_rhs, side_cons_rhs = get_or_make_var(abs(rhs), csemap=csemap)
+                        abs_of_r, side_cons_r = get_or_make_var(abs(r), csemap=csemap)
+                        side_cons += side_cons_a + side_cons_b + side_cons_rhs + side_cons_r
                         # |r| < |b|
                         side_cons.append(abs_of_r < abs_of_b)
 
                         # ensure we round towards zero
-                        mul_abs, extra_cons = get_or_make_var(abs_of_b * abs_of_rhs)
+                        mul_abs, extra_cons = get_or_make_var(abs_of_b * abs_of_rhs, csemap=csemap)
                         side_cons += extra_cons + [mul_abs <= abs_of_a]
-                        newlist += linearize_constraint(side_cons, supported=supported, reified=reified)
+                        newlist += linearize_constraint(side_cons, supported=supported, reified=reified, csemap=csemap)
 
                 else:
                     raise TransformationNotImplementedError(f"lhs of constraint {cpm_expr} cannot be linearized, should"
@@ -273,8 +273,8 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
 
             elif isinstance(lhs, GlobalFunction) and lhs.name == "abs" and "abs" not in supported:
                 if cpm_expr.name != "==": # TODO: remove this restriction, requires comparison flipping
-                    newvar = intvar(*get_bounds(lhs))
-                    newlist += linearize_constraint([lhs == newvar])
+                    newvar, newcons = get_or_make_var(lhs, csemap=csemap)
+                    newlist += linearize_constraint(newcons, supported=supported, reified=reified, csemap=csemap)
                     cpm_expr = eval_comparison(cpm_expr.name, newvar, rhs)
                 else:
                     x = lhs.args[0]
@@ -287,7 +287,7 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
                         lhs_is_pos = cp.boolvar()
                         newcons = [lhs_is_pos.implies(x >= 0), (~lhs_is_pos).implies(x <= -1),
                                    lhs_is_pos.implies(x == rhs), (~lhs_is_pos).implies(x + rhs == 0)]
-                        newlist += linearize_constraint(newcons, supported=supported, reified=reified)
+                        newlist += linearize_constraint(newcons, supported=supported, reified=reified, csemap=csemap)
                     continue # all should be linear now
 
 
@@ -306,18 +306,18 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
                 if t_lb and t_ub:
                     continue
                 elif not t_lb and not t_ub:
-                    newlist += linearize_constraint([BoolVal(False)], supported=supported) # post the linear version of False
+                    newlist += linearize_constraint([BoolVal(False)], supported=supported, csemap=csemap) # post the linear version of False
                     break
 
             # now fix the comparisons themselves
             if cpm_expr.name == "<":
-                new_rhs, cons = get_or_make_var(rhs - 1) # if rhs is constant, will return new constant
+                new_rhs, cons = get_or_make_var(rhs - 1, csemap=csemap) # if rhs is constant, will return new constant
                 newlist.append(lhs <= new_rhs)
-                newlist += linearize_constraint(cons)
+                newlist += linearize_constraint(cons, csemap=csemap)
             elif cpm_expr.name == ">":
-                new_rhs, cons = get_or_make_var(rhs + 1) # if rhs is constant, will return new constant
+                new_rhs, cons = get_or_make_var(rhs + 1, csemap=csemap) # if rhs is constant, will return new constant
                 newlist.append(lhs >= new_rhs)
-                newlist += linearize_constraint(cons)
+                newlist += linearize_constraint(cons, csemap=csemap)
             elif cpm_expr.name == "!=":
                 # Special case: BV != BV
                 if isinstance(lhs, _BoolVarImpl) and isinstance(rhs, _BoolVarImpl):
@@ -337,13 +337,13 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
                     _, M1 = (lhs - rhs + 1).get_bounds()
                     _, M2 = (rhs - lhs + 1).get_bounds()
                     cons = [lhs + -M1*z <= rhs-1, lhs  + -M2*z >= rhs-M2+1]
-                    newlist += linearize_constraint(flatten_constraint(cons), supported=supported, reified=reified)
+                    newlist += linearize_constraint(flatten_constraint(cons, csemap=csemap), supported=supported, reified=reified, csemap=csemap)
 
                 else:
                     # introduce new indicator constraints
                     z = boolvar()
                     constraints = [z.implies(lhs < rhs), (~z).implies(lhs > rhs)]
-                    newlist += linearize_constraint(constraints, supported=supported, reified=reified)
+                    newlist += linearize_constraint(constraints, supported=supported, reified=reified, csemap=csemap)
             else:
                 # supported comparison
                 newlist.append(eval_comparison(cpm_expr.name, lhs, rhs))
@@ -387,7 +387,7 @@ def linearize_constraint(lst_of_expr, supported={"sum","wsum"}, reified=False):
 
     return newlist
 
-def only_positive_bv(lst_of_expr):
+def only_positive_bv(lst_of_expr, csemap=None):
     """
         Replaces :class:`~cpmpy.expressions.comparison.Comparison` containing :class:`~cpmpy.expressions.variables.NegBoolView` with equivalent expression using only :class:`~cpmpy.expressions.variables.BoolVar`.
         Comparisons are expected to be linearized. Only apply after applying :func:`linearize_constraint(cpm_expr) <linearize_constraint>`.
@@ -433,7 +433,7 @@ def only_positive_bv(lst_of_expr):
             assert isinstance(cond, _BoolVarImpl), f"{cpm_expr} is not a supported linear expression. Apply " \
                                                    f"`linearize_constraint` before calling `only_positive_bv` "
             if isinstance(cond, _BoolVarImpl): # BV -> Expr
-                subexpr = only_positive_bv([subexpr])
+                subexpr = only_positive_bv([subexpr], csemap=csemap)
                 newlist += [cond.implies(expr) for expr in subexpr]
 
         elif isinstance(cpm_expr, _BoolVarImpl):
diff --git a/cpmpy/transformations/reification.py b/cpmpy/transformations/reification.py
index 358576cbf..b3d682fad 100644
--- a/cpmpy/transformations/reification.py
+++ b/cpmpy/transformations/reification.py
@@ -29,7 +29,8 @@
 from .flatten_model import flatten_constraint, get_or_make_var
 from .negation import recurse_negation
 
-def only_bv_reifies(constraints):
+def only_bv_reifies(constraints, csemap=None):
+
     newcons = []
     for cpm_expr in constraints:
         if cpm_expr.name in ['->', "=="]:
@@ -39,11 +40,11 @@ def only_bv_reifies(constraints):
                 # BE -> BV :: ~BV -> ~BE
                 if cpm_expr.name == '->':
                     newexpr = (~a1).implies(recurse_negation(a0))
-                    newexpr = only_bv_reifies(flatten_constraint(newexpr))
+                    newexpr = only_bv_reifies(flatten_constraint(newexpr, csemap=csemap), csemap=csemap)
                 else:
                     newexpr = [a1 == a0]  # BE == BV :: BV == BE
                     if not a0.is_bool():
-                        newexpr = flatten_constraint(newexpr)
+                        newexpr = flatten_constraint(newexpr, csemap=csemap)
                 newcons.extend(newexpr)
             else:
                 newcons.append(cpm_expr)
@@ -51,7 +52,7 @@ def only_bv_reifies(constraints):
             newcons.append(cpm_expr)
     return newcons
 
-def only_implies(constraints):
+def only_implies(constraints, csemap=None):
     """
         Transforms all reifications to ``BV -> BE`` form
 
@@ -122,12 +123,12 @@ def only_implies(constraints):
             newcons.append(cpm_expr)
     
     if len(retransform) != 0:
-        newcons.extend(only_implies(only_bv_reifies(flatten_constraint(retransform))))
+        newcons.extend(only_implies(only_bv_reifies(flatten_constraint(retransform, csemap=csemap), csemap=csemap), csemap=csemap))
 
     return newcons
 
 
-def reify_rewrite(constraints, supported=frozenset()):
+def reify_rewrite(constraints, supported=frozenset(), csemap=None):
     """
         Rewrites reified constraints not natively supported by a solver,
         to a version that uses standard constraints and reification over equalities between variables.
@@ -195,7 +196,7 @@ def reify_rewrite(constraints, supported=frozenset()):
                     #     introduce aux var and bring function to toplevel
                     #     (AUX,c) = get_or_make_var(LHS)
                     #     return c+[Comp(OP,AUX,RHS) == BV] or +[Comp(OP,AUX,RHS) -> BV] or +[Comp(OP,AUX,RHS) <- BV]
-                    (auxvar, cons) = get_or_make_var(lhs)
+                    (auxvar, cons) = get_or_make_var(lhs, csemap=csemap)
                     newcons += cons
                     reifexpr = copy.copy(cpm_expr)
                     reifexpr.args[boolexpr_index] = Comparison(op, auxvar, rhs)  # Comp(OP,AUX,RHS)
diff --git a/cpmpy/transformations/to_cnf.py b/cpmpy/transformations/to_cnf.py
index 019dc8a5b..5a03f28e2 100644
--- a/cpmpy/transformations/to_cnf.py
+++ b/cpmpy/transformations/to_cnf.py
@@ -30,7 +30,7 @@
 from .reification import only_implies
 from .flatten_model import flatten_constraint
 
-def to_cnf(constraints):
+def to_cnf(constraints, csemap=None):
     """
         Converts all logical constraints into **Conjunctive Normal Form**
 
@@ -38,8 +38,8 @@ def to_cnf(constraints):
             constraints:    list[Expression] or Operator
             supported:      (frozen)set of global constraint names that do not need to be decomposed
     """
-    fnf = flatten_constraint(constraints)
-    fnf = only_implies(fnf)
+    fnf = flatten_constraint(constraints, csemap=csemap)
+    fnf = only_implies(fnf, csemap=csemap)
     return flat2cnf(fnf)
 
 def flat2cnf(constraints):
diff --git a/tests/test_cse.py b/tests/test_cse.py
new file mode 100644
index 000000000..071c1e346
--- /dev/null
+++ b/tests/test_cse.py
@@ -0,0 +1,124 @@
+import unittest
+import cpmpy as cp
+
+from cpmpy.transformations.comparison import only_numexpr_equality
+from cpmpy.transformations.flatten_model import flatten_constraint
+from cpmpy.transformations.decompose_global import decompose_in_tree
+from cpmpy.expressions.variables import _IntVarImpl, _BoolVarImpl
+from cpmpy.transformations.linearize import linearize_constraint
+from cpmpy.transformations.reification import only_bv_reifies
+
+
+class TestCSE(unittest.TestCase):
+
+    def setUp(self) -> None:
+        # ensure reproducable variable names
+        _IntVarImpl.counter = 0 
+        _BoolVarImpl.counter = 0   
+
+
+    def test_flatten(self):
+        
+        x,y,z = cp.intvar(0,10, shape=3, name=tuple("xyz"))
+       
+        nested_alldiff = cp.AllDifferent(x,y+y,z)      
+        csemap = dict()
+
+        flat_cons = flatten_constraint(nested_alldiff, csemap=csemap)
+
+        self.assertEqual(len(flat_cons), 2)
+        fc = flat_cons[0]
+        self.assertEqual(str(fc), "alldifferent(x,IV0,z)")
+        self.assertEqual(len(csemap), 1)
+
+        self.assertEqual(str(next(iter(csemap.keys()))), "(y) + (y)")
+        self.assertEqual(str(csemap[y + y]), "IV0")
+
+        # next time we use y + y, it should replace it IV0
+        nested_cons2 = (y + y) % 3 == 0
+        flat_cons = flatten_constraint(nested_cons2, csemap=csemap)
+        self.assertEqual(len(flat_cons), 1)
+        self.assertEqual(str(flat_cons[0]), "(IV0) mod 3 == 0")
+        self.assertEqual(len(csemap), 1)
+        
+
+        # should also work for Boolean variables (introduce reification)
+        nested_cons = (x + y + z <= 10) | (cp.AllDifferent(x,y,z))
+        flat_cons = flatten_constraint(nested_cons, csemap=csemap)
+        
+        self.assertEqual(len(flat_cons), 3)
+        
+        self.assertEqual(str(flat_cons[0]), "(BV0) or (BV1)")
+        self.assertEqual(str(flat_cons[1]), "(sum([x, y, z]) <= 10) == (BV0)")
+        self.assertEqual(str(flat_cons[2]), "(alldifferent(x,y,z)) == (BV1)")
+        
+        # next time we use x + y + z <= 10, it should replace it with BV0
+        nested_cons2 = ((x + y + z <= 10) ^ cp.boolvar(name="a"))
+        flat_cons = flatten_constraint(nested_cons2, csemap=csemap)
+
+        self.assertEqual(len(flat_cons), 1)
+        self.assertEqual(str(flat_cons[0]), "BV0 xor a")
+
+
+
+    def test_decompose(self):
+        x,y,z = cp.intvar(0,10, shape=3, name=tuple("xyz"))
+        q = cp.intvar(0,2, name="q")
+
+        b = cp.boolvar(name="b")
+        nested_cons = b == ((cp.max([x,y,z]) + q) <= 10)
+        csemap = dict()
+        decomp = decompose_in_tree([nested_cons], csemap=csemap)
+    
+        self.assertEqual(len(decomp), 6)
+        self.assertEqual(str(decomp[0]), "(b) == ((IV0) + (q) <= 10)")
+        self.assertEqual(str(decomp[1]), "(IV1) == (IV0)") # TODO... this seems stupid, why do we need this (comes from _max in Maximul decomp)?
+        self.assertEqual(str(decomp[2]), "or([(x) >= (IV1), (y) >= (IV1), (z) >= (IV1)])")
+        self.assertEqual(str(decomp[3]), "(x) <= (IV1)")
+        self.assertEqual(str(decomp[4]), "(y) <= (IV1)")
+        self.assertEqual(str(decomp[5]), "(z) <= (IV1)")
+
+        # next time we use max([x,y,z]) it should replace the max-constraint with IV0
+        #  ... it seems like we should be able to do more here e.g., cp.max([x,y,z]) != 42 should be replaced with IV0 != 42
+        #  ...      but the current code-flow of decompose_in_tree and .decompose_comparison does not allow this
+        nested2 = (q + cp.max([x,y,z]) != 42)
+        decomp = decompose_in_tree([nested2], csemap=csemap)
+
+        self.assertEqual(len(decomp), 1)
+        self.assertEqual(str(decomp[0]), "(q) + (IV0) != 42")
+
+    def test_only_numexpr_equality(self):
+        x,y,z = cp.intvar(0,10, shape=3, name=tuple("xyz"))
+
+        cons = cp.max([x,y,z]) <= 42
+        csemap = dict()
+        eq_cons = only_numexpr_equality([cons], csemap=csemap)
+        
+        self.assertEqual(len(eq_cons), 2)
+        self.assertEqual(str(eq_cons[0]), "(max(x,y,z)) == (IV0)")
+        self.assertEqual(str(eq_cons[1]), "IV0 <= 42")
+        self.assertEqual(len(csemap), 1)
+        
+        # next time we use max([x,y,z]) it should replace it with IV0
+        non_eq_cons = cp.max([x,y,z]) != 1337
+        eq_cons = only_numexpr_equality([non_eq_cons], csemap=csemap)
+        self.assertEqual(len(eq_cons), 1)
+        self.assertEqual(str(eq_cons[0]), "IV0 != 1337")
+        self.assertEqual(len(csemap), 1)
+
+    def test_linearize(self):
+        x,y,z = cp.intvar(0,10, shape=3, name=tuple("xyz"))
+        
+        cons = cp.max(x,y) < z
+        csemap = dict()
+        lin_cons = linearize_constraint([cons], supported={"max"}, csemap=csemap)
+        
+        self.assertEqual(len(lin_cons), 2)
+        self.assertEqual(str(lin_cons[0]), "(max(x,y)) <= (IV0)")
+        self.assertEqual(str(lin_cons[1]), "sum([1, -1] * [z, IV0]) == 1")
+        
+        # next time we use z - 1 it should replace it with IV0
+        # ... not sure how to find a test for this...        
+
+    ### other transformations only use csemap as argument to flatten_constraint internally, not sure how to easily test them
+
diff --git a/tests/test_trans_linearize.py b/tests/test_trans_linearize.py
index c34c4cf25..5935e0824 100644
--- a/tests/test_trans_linearize.py
+++ b/tests/test_trans_linearize.py
@@ -196,7 +196,7 @@ def test_issue_580(self):
 
 
         lin_mod = linearize_constraint([x % 2 <= 0], supported={"mul", "sum", "wsum"})
-        self.assertEqual(str(lin_mod), '[IV8 <= 0, sum([2, -1] * [IV9, IV10]) == 0, sum([1, -1] * [IV8, IV11]) == 0, sum([1, 1, -1] * [IV10, IV8, x]) == 0]')
+        self.assertEqual(str(lin_mod), '[IV7 <= 0, sum([2, -1] * [IV8, IV9]) == 0, sum([1, 1, -1] * [IV9, IV7, x]) == 0]')
         self.assertTrue(cp.Model(lin_mod).solve())
         self.assertIn(x.value(), {2, 4}) # can never be < 0
 

From 5767b32e6d08e55da8f074b8b61b6e3cc9049900 Mon Sep 17 00:00:00 2001
From: Ignace Bleukx <ignace.bleukx@kuleuven.be>
Date: Fri, 23 May 2025 18:47:36 +0200
Subject: [PATCH 39/39] Fix eval comparison (#683)

* add failing test

* fix numpy comparison

* add tests for booleans too

* check of numpy bools
---
 cpmpy/expressions/utils.py |  5 ++++
 tests/test_expressions.py  | 56 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/cpmpy/expressions/utils.py b/cpmpy/expressions/utils.py
index 5eb79b1fd..5ac6cb463 100644
--- a/cpmpy/expressions/utils.py
+++ b/cpmpy/expressions/utils.py
@@ -157,6 +157,11 @@ def eval_comparison(str_op, lhs, rhs):
 
         Especially useful in decomposition and transformation functions that already involve a comparison.
     """
+    if isinstance(lhs, (np.integer, np.bool_)):
+        lhs = int(lhs)
+    if isinstance(rhs, (np.integer, np.bool_)):
+        rhs = int(rhs)
+
     if str_op == '==':
         return lhs == rhs
     elif str_op == '!=':
diff --git a/tests/test_expressions.py b/tests/test_expressions.py
index 49e067cea..73f749f68 100644
--- a/tests/test_expressions.py
+++ b/tests/test_expressions.py
@@ -5,8 +5,8 @@
 from cpmpy.exceptions import IncompleteFunctionError
 from cpmpy.expressions import *
 from cpmpy.expressions.variables import NDVarArray
-from cpmpy.expressions.core import Operator, Expression
-from cpmpy.expressions.utils import get_bounds, argval
+from cpmpy.expressions.core import Comparison, Operator, Expression
+from cpmpy.expressions.utils import eval_comparison, get_bounds, argval
 
 class TestComparison(unittest.TestCase):
     def test_comps(self):
@@ -650,5 +650,57 @@ def test_dict(self):
         assert d[self.y] == "y"
         assert d[self.z] == "z"
 
+        
+class TestUtils(unittest.TestCase):
+
+    def test_eval_comparison(self):
+        x = intvar(0,10, name="x")
+
+        for comp in ["==", "!=", "<", "<=", ">", ">="]:
+            expr = eval_comparison(comp, x, 5)
+            self.assertIsInstance(expr, Comparison)
+            self.assertEqual(str(expr.args[0]), "x")
+            self.assertEqual(expr.args[1], 5) # should always put the constant on the right
+
+            expr = eval_comparison(comp, 5, x)
+            self.assertIsInstance(expr, Comparison)
+            self.assertEqual(str(expr.args[0]), "x")
+            self.assertEqual(expr.args[1], 5) # should always put the constant on the right
+
+            # now, also check with numpy
+            expr = eval_comparison(comp, x, np.int64(5))
+            self.assertIsInstance(expr, Comparison)
+            self.assertEqual(str(expr.args[0]), "x")
+            self.assertEqual(expr.args[1], 5) # should always put the constant on the right
+
+            expr = eval_comparison(comp, np.int64(5), x)
+            self.assertIsInstance(expr, Comparison)
+            self.assertEqual(str(expr.args[0]), "x")
+            self.assertEqual(expr.args[1], 5) # should always put the constant on the right
+
+
+            # also with Boolean constants
+
+            expr = eval_comparison(comp, x, True)
+            self.assertIsInstance(expr, Comparison)
+            self.assertEqual(str(expr.args[0]), "x")
+            self.assertEqual(expr.args[1], True) # should always put the constant on the right
+
+            expr = eval_comparison(comp, True, x)
+            self.assertIsInstance(expr, Comparison)
+            self.assertEqual(str(expr.args[0]), "x")
+            self.assertEqual(expr.args[1], True) # should always put the constant on the right
+
+            # now, also check with numpy
+            expr = eval_comparison(comp, x, np.bool_(True))
+            self.assertIsInstance(expr, Comparison)
+            self.assertEqual(str(expr.args[0]), "x")
+            self.assertEqual(expr.args[1], True) # should always put the constant on the right
+
+            expr = eval_comparison(comp, np.bool_(True), x)
+            self.assertIsInstance(expr, Comparison)
+            self.assertEqual(str(expr.args[0]), "x")
+            self.assertEqual(expr.args[1], True) # should always put the constant on the right
+
 if __name__ == '__main__':
     unittest.main()