Add ability to pass another solver.

Closes #42

conference_scheduler/scheduler.py

@@ -12,7 +12,7 @@
 #   schedule: a generator for a list of ScheduledItem instances
 
 
-def solution(events, slots, objective_function=None, **kwargs):
+def solution(events, slots, objective_function=None, solver=None, **kwargs):
     """Setup up the ILP problem, submit it to pulp and return the solution
 
     Parameters
@@ -21,8 +21,12 @@ def solution(events, slots, objective_function=None, **kwargs):
             of resources.Event instances
         slots : list or tuple
             of resources.Slot instances
+        solve : pulp.solver
+            a pulp solver
         objective_function: callable
             from lp_problem.objective_functions
+        kwargs : keyword arguments
+            arguments for the objective function
 
     Returns
     -------
@@ -51,7 +55,7 @@ def solution(events, slots, objective_function=None, **kwargs):
         problem += objective_function(events=events, slots=slots, X=X,
                                       **kwargs)
 
-    status = problem.solve()
+    status = problem.solve(solver=solver)
     if status == 1:
         return (
             item for item, variable in X.items()
@@ -96,7 +100,7 @@ def array(events, slots, objective_function=None):
     )
 
 
-def schedule(events, slots, objective_function=None, **kwargs):
+def schedule(events, slots, objective_function=None, solver=None, **kwargs):
     """Compute the ILP solution and return it in schedule form
 
      Parameters
@@ -105,16 +109,20 @@ def schedule(events, slots, objective_function=None, **kwargs):
             of resources.Event instances
         slots : list or tuple
             of resources.Slot instances
+        solver : pulp.solver
+            a pulp solver
         objective_function : callable
             from lp_problem.objective_functions
+        kwargs : keyword arguments
+            arguments for the objective function
 
     Returns
     -------
         Generator
             of tuples of instances of resources.ScheduledItem
     """
     return solution_to_schedule(
-        solution(events, slots, objective_function, **kwargs),
+        solution(events, slots, objective_function, solver=solver, **kwargs),
         events, slots
     )
 

conference_scheduler/tests/test_scheduler.py

@@ -81,6 +81,10 @@ def test_unsolvable_raises_error(events):
         scheduler.solution(events, slots)
 
 
+def test_solver_recognised_by_pulp_raises_error(events, slots):
+    with pytest.raises(AttributeError):
+        scheduler.solution(events, slots, solver="Not a real solver")
+
 # Array form
 # Less testing needed here since it simply calls scheduler.solution and
 # converts the result to array form

docs/howtos/index.rst

@@ -1,4 +1,9 @@
 How tos
 =======
 
-TBD
+A number of specific instructions for particular things you might want to do:
+
+.. toctree::
+   :maxdepth: 2
+
+   use_different_solver.rst

docs/howtos/use_different_solver.rst

@@ -0,0 +1,17 @@
+Using different solvers
+=======================
+
+The `Pulp <https://pythonhosted.org/PuLP/index.html>`_ library is a Python
+interface to underlying solution engines. By default it comes packaged with `CBC
+<https://projects.coin-or.org/Cbc>`_
+
+It is however possible to use a number of other solvers (see the Pulp
+documentation for details) and these can be passed to the scheduler. For example
+here is how we would use the `GLPK <https://www.gnu.org/software/glpk/>`_
+solver for a given set of :code:`events` and :code:`slots`::
+
+    >>> scheduler.schedule(events=events, slots=slots, solver=pulp.GLPK()) # doctest: +SKIP
+
+Different solvers can have major impact on the performance of the scheduler.
+This can be an important consideration when scheduling large or highly
+constrained problems.