document solvers and heuristics

docs/source/consistency_propagators.rst

@@ -7,7 +7,7 @@ Consistency algorithms
 **********************
 
 NuCS relies on :ref:`consistency algorithms <consistency_algorithms>`.
-A bound-consistency algorithm is provided, custom consistency algorithm can be used instead.
+A bound-consistency algorithm is provided, a custom consistency algorithm can be used instead.
 
 Bound consistency algorithm
 ###########################

docs/source/index.rst

@@ -32,4 +32,5 @@ Contents
    installation
    variables_domains
    consistency_propagators
+   solvers_heuristics
    reference

docs/source/reference.rst

@@ -400,6 +400,40 @@ NUCS provides the following functions for reducing a shared domain.
    :rtype: int
 
 
+.. _solvers:
+
+*******
+Solvers
+*******
+
+NuCS comes with the following solvers.
+
+
+.. py:module:: nucs.solvers.backtrack_solver
+.. py:function:: nucs.solvers.backtrack_solver.__init__(problem, consistency_alg_idx, var_heuristic_idx, dom_heuristic_idx, stack_max_height)
+
+   A backtrack-based solver.
+
+   :param problem: the problem to be solved
+   :type problem: Problem
+   :param consistency_alg_idx: the index of the consistency algorithm
+   :type consistency_alg_idx: int
+   :param var_heuristic_idx: the index of the heuristic for selecting a variable/domain
+   :type var_heuristic_idx: int
+   :param dom_heuristic_idx: the index of the heuristic for reducing a domain
+   :type dom_heuristic_idx: int
+   :param stack_max_height: the maximal height of the choice point stack
+   :type stack_max_height: int
+
+.. py:module:: nucs.solvers.multiprocessing_solver
+.. py:function:: nucs.solvers.multiprocessing_solver.__init__(solvers)
+
+   A solver relying on the multiprocessing package. This solver delegates resolution to a set of solvers.
+
+   :param solvers: the solvers used in different processes
+   :type solvers: List[BacktrackSolver]
+
+
 .. _examples:
 
 ********

docs/source/solvers_heuristics.rst

@@ -0,0 +1,48 @@
+######################
+Solvers and heuristics
+######################
+
+*******
+Solvers
+*******
+
+NuCS comes with some pre-defined :ref:`solvers <solvers>`.
+
+Backtracking-based solver
+#########################
+NuCS provides :mod:`nucs.solvers.backtrack_solver` which is the main solver.
+
+Multiprocessing-based solver
+############################
+NuCS also provides :mod:`nucs.solvers.multiprocessing_solver` which relies on the Python :code:`multiprocessing` package.
+
+This solver is used by the launcher of the :mod:`nucs.examples.queens.queens_problem`.
+
+.. code-block:: python
+   :linenos:
+
+   problem = QueensProblem(args.n)
+   problems = problem.split(args.processors, 0)  # creates n-subproblems by splitting the domain of the first variable
+   solver = MultiprocessingSolver([BacktrackSolver(problem) for problem in problems])
+   solver.solve_all()
+
+
+**********
+Heuristics
+**********
+
+NuCS comes with some pre-defined :ref:`heuristics <heuristics>` and makes it possible to design custom heuristics.
+
+Custom heuristics
+#################
+NuCS makes it possible to define and use custom heuristics.
+
+A heuristic needs to be registered before it is used.
+The following code registers the :code:`SPLIT_LOW` heuristic.
+
+.. code-block:: python
+   :linenos:
+
+   DOM_HEURISTIC_SPLIT_LOW = register_dom_heuristic(split_low_dom_heuristic)
+
+

nucs/solvers/backtrack_solver.py

@@ -83,7 +83,7 @@ def __init__(
     ):
         """
         Inits the solver.
-        :param problem: the problem
+        :param problem: the problem to be solved
         :param consistency_alg_idx: the index of the consistency algorithm
         :param var_heuristic_idx: the index of the heuristic for selecting a variable/domain
         :param dom_heuristic_idx: the index of the heuristic for reducing a domain