move param_combinations to cpmpy.solvers.utils

Author: tias

cpmpy/solvers/__init__.py

@@ -23,9 +23,17 @@
 
         CPM_ortools
         CPM_pysat
+
+    =================
+    List of functions
+    =================
+    .. autosummary::
+        :nosignatures:
+
+        param_combinations
 """
 
-from .utils import builtin_solvers, get_supported_solvers
+from .utils import builtin_solvers, get_supported_solvers, param_combinations
 from .ortools import CPM_ortools
 from .pysat import CPM_pysat
 # from minizinc import CPMpyMiniZinc # closed for maintenance

cpmpy/solvers/utils.py

@@ -17,6 +17,7 @@
         :nosignatures:
 
         get_supported_solvers
+        param_combinations
 """
 
 #from .minizinc import CPMpyMiniZinc # closed for maintenance
@@ -31,5 +32,37 @@ def get_supported_solvers():
     """
     return [sv for sv in builtin_solvers if sv.supported()]
 
+def param_combinations(all_params, remaining_keys=None, cur_params=None):
+    """
+        Recursively yield all combinations of param values
+
+        For example usage, see `examples/advanced/hyperparameter_search.py`
+
+        - all_params is a dict of {key: list} items, e.g.:
+            {'val': [1,2], 'opt': [True,False]}
+
+        - output is an generator over all {key:value} combinations
+          of the keys and values. For the example above:
+          generator([{'val':1,'opt':True},{'val':1,'opt':False},{'val':2,'opt':True},{'val':2,'opt':False}])
+    """
+    if remaining_keys is None or cur_params is None:
+        # init
+        remaining_keys = list(all_params.keys())
+        cur_params = dict()
+
+    cur_key = remaining_keys[0]
+    myresults = [] # (runtime, cur_params)
+    for cur_value in all_params[cur_key]:
+        cur_params[cur_key] = cur_value
+        if len(remaining_keys) == 1:
+            # terminal, return copy
+            yield dict(cur_params)
+        else:
+            # recursive call
+            yield from param_combinations(all_params, 
+                            remaining_keys=remaining_keys[1:],
+                            cur_params=cur_params)
+
+
 # Order matters! first is default, then tries second, etc...
 builtin_solvers=[CPM_ortools,CPM_pysat]

docs/solver_parameters.md

@@ -29,16 +29,19 @@ s.solve(num_search_workers=8, log_search_progress=True)
 ## Hyperparameter search across different parameters
 Because CPMpy offers programmatic access to the solver API, hyperparameter search can be straightforwardly done with little overhead between the calls.
 
-The full example is in [examples/advanced/hyperparameter_search.py](examples/advanced/hyperparameter_search.py), here is a relevant excrept:
+The cpmpy.solvers module has a helper function `param_combinations` that generates all parameter combinations of an input, which can then be looped over.
+
+The example is in [examples/advanced/hyperparameter_search.py](examples/advanced/hyperparameter_search.py), the key part is:
 
 ```python
+    from cpmpy.solvers import CPM_ortools, param_combinations
+
     params = {'cp_model_probing_level': [0,1,2,3],
               'linearization_level': [0,1,2],
               'symmetry_level': [0,1,2]}
 
-    configs = gridsearch(model, CPM_ortools, params)
-
-    best = configs[0]
-    print("Best config:", best[1])
-    print("    with runtime:", round(best[0],2))
+    for params in param_combinations(all_params):
+        s = CPM_ortools(model)
+        s.solve(**params)
+        print(s.status().runtime, "seconds for config", params)
 ```

examples/advanced/hyperparameter_search.py

@@ -5,7 +5,7 @@
 """
 import sys
 from cpmpy import *
-from cpmpy.solvers import CPM_ortools
+from cpmpy.solvers import CPM_ortools, param_combinations
 from cpmpy.transformations.flatten_model import flatten_model
 
 def main():
@@ -45,36 +45,6 @@ def main():
     # With default parameters: 0.13
 
 
-def param_combinations(all_params, remaining_keys=None, cur_params=None):
-    """
-        Recursively yield all combinations of param values
-
-        - all_params is a dict of {key: list} items, e.g.:
-            {'val': [1,2], 'opt': [True,False]}
-
-        - output is an generator over all {key:value} combinations
-          of the keys and values. For the example above:
-          generator([{'val':1,'opt':True},{'val':1,'opt':False},{'val':2,'opt':True},{'val':2,'opt':False}])
-    """
-    if remaining_keys is None or cur_params is None:
-        # init
-        remaining_keys = list(all_params.keys())
-        cur_params = dict()
-
-    cur_key = remaining_keys[0]
-    myresults = [] # (runtime, cur_params)
-    for cur_value in all_params[cur_key]:
-        cur_params[cur_key] = cur_value
-        if len(remaining_keys) == 1:
-            # terminal, return copy
-            yield dict(cur_params)
-        else:
-            # recursive call
-            yield from param_combinations(all_params, 
-                            remaining_keys=remaining_keys[1:],
-                            cur_params=cur_params)
-
-
 
 def nqueens(n=8):
     """ N-queens problem