diff --git a/docs/source/consistency_propagators.rst b/docs/source/consistency_propagators.rst index 93224ed..acddb0a 100644 --- a/docs/source/consistency_propagators.rst +++ b/docs/source/consistency_propagators.rst @@ -7,7 +7,7 @@ Consistency algorithms ********************** NuCS relies on :ref:`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 ########################### diff --git a/docs/source/index.rst b/docs/source/index.rst index 77866a9..6f3e8ec 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -32,4 +32,5 @@ Contents installation variables_domains consistency_propagators + solvers_heuristics reference diff --git a/docs/source/reference.rst b/docs/source/reference.rst index 737afd9..14c7cb7 100644 --- a/docs/source/reference.rst +++ b/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: ******** diff --git a/docs/source/solvers_heuristics.rst b/docs/source/solvers_heuristics.rst new file mode 100644 index 0000000..4c11cf1 --- /dev/null +++ b/docs/source/solvers_heuristics.rst @@ -0,0 +1,48 @@ +###################### +Solvers and heuristics +###################### + +******* +Solvers +******* + +NuCS comes with some pre-defined :ref:`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 ` 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) + + diff --git a/nucs/solvers/backtrack_solver.py b/nucs/solvers/backtrack_solver.py index ac7664d..6a13295 100644 --- a/nucs/solvers/backtrack_solver.py +++ b/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