Merge pull request #305 from ds4dm/feature-solve-iter

Feature solve iter

Author: AntoinePrv

dev/conda.yaml

@@ -23,7 +23,7 @@ dependencies:
 
   # Documentation
   - doxygen
-  - sphinx = 4.0
+  - sphinx = 4.4
   - breathe>=4.15
   - sphinx_rtd_theme
 

docs/discussion/seeding.rst

@@ -8,7 +8,7 @@ One such aspect is the solver randomness, which is controlled by its random seed
 
 This means that, by default, Ecole environment will generate different episodes (and in
 particular different initial states) after each new call to
-:py:meth:`~ecole.environment.EnvironmentComposer.reset`.
+:py:meth:`~ecole.environment.Environment.reset`.
 To do so, the environment keeps a :py:class:`~ecole.RandomGenerator` (random state)
 between episodes, and start a new episode by calling
 :py:meth:`~ecole.typing.Dynamics.set_dynamics_random_state` on the underlying

docs/howto/create-environments.rst

@@ -117,13 +117,114 @@ To do so, we will take parameters in the constructor.
        __Dynamics__ = SimpleBranchingDynamics
 
 
-The constructor arguments are forwarded from the :py:meth:`~ecole.environment.EnvironmentComposer.__init__` constructor:
+The constructor arguments are forwarded from the :py:meth:`~ecole.environment.Environment.__init__` constructor:
 
 .. testcode::
    :skipif: pyscipopt is None
 
    env = SimpleBranching(observation_function=None, disable_cuts=False)
 
-Similarily, extra arguments given to the environemnt :py:meth:`~ecole.environment.EnvironmentComposer.reset` and
-:py:meth:`~ecole.environment.EnvironmentComposer.step` are forwarded to the associated
+Similarily, extra arguments given to the environemnt :py:meth:`~ecole.environment.Environment.reset` and
+:py:meth:`~ecole.environment.Environment.step` are forwarded to the associated
 :py:class:`~ecole.typing.Dynamics` methods.
+
+Using Control Inversion
+-----------------------
+When using a traditional SCIP callback, the user has to add the callback to SCIP, call ``SCIPsolve``, and wait for the
+solving process to terminate.
+We say that *SCIP has the control*.
+This has some downsides, such a having to forward all the data the agent will use to the callback, making it harder to
+stop the solving process, and reduce interactivity.
+For instance when using a callback in a notebook, if the user forgot to fetch some data, then they have to re-execute
+the whole solving process.
+
+On the contrary, when using an Ecole environment such as :py:class:`~ecole.environment.Branching`, the environment
+pauses on every branch-and-bound node (*i.e.* every branchrule callback call) to let the user make a decision,
+or inspect the :py:class:`~ecole.scip.Model`.
+We say that the *user (or the agent) has the control*.
+To do so, we did not reconstruct the solving algorithm ``SCIPsolve`` to fit our needs.
+Rather, we have implemented a general *inversion of control* mechanism to let SCIP pause and be resumed on every
+callback call (using a form of *stackful coroutine*).
+We call this approach *iterative solving* and it runs exactly the same ``SCIPsolve`` algorithm, without noticable
+overhead, while perfectly forwarding all information available in the callback.
+
+To use this tool, the user start by calling :py:meth:`ecole.scip.Model.solve_iter`, with a set of call callback
+constructor arguments.
+Iterative solving will then add these callbacks, start solving, and return the first time that one of these callback
+is executed.
+The return value describes where the solving has stopped, and the parameters of the callback where it has stopped.
+This is the time for the user to perform whichever action they would have done in the callback.
+Solving can be resumed by calling :py:meth:`ecole.scip.Model.solve_iter_continue` with the
+:py:class:`ecole.scip.callback.Result` that would have been set in the callback.
+Solving is finished when one of the iterative solving function returns ``None``.
+The :py:class:`ecole.scip.Model` can safely be deleted an any time (SCIP termination is handled automatically).
+
+For instance, iterative solving an environement while pausing on branchrule and heuristic callbacks look like the
+following.
+
+.. testcode::
+
+   model = ecole.scip.Model.from_file("path/to/file")
+
+   # Start solving until the first pause, if any.
+   fcall = model.solve_iter(
+       # Stop on branchrule callback.
+       ecole.scip.callback.BranchruleConstructor(),
+       # Stop on heuristic callback after node.
+       ecole.scip.callback.HeuristicConstructor(timing_mask=ecole.scip.HeurTiming.AfterNode),
+   )
+   # While solving is not finished, `fcall` contains information about the current stop.
+   while fcall is not None:
+       # Solving stopped on a branchrule callback.
+       if isinstance(fcall, ecole.scip.callback.BranchruleCall):
+           # Perform some branching (through PyScipOpt).
+           ...
+           # Resume solving until next pause.
+           fcall = model.solve_iter_continue(ecole.scip.callback.Result.Branched)
+       # Solving stopped on a heurisitc callback.
+       elif isinstance(fcall, ecole.scip.callback.HeuristicCall):
+           # Return as no heuristic was performed (only data collection)
+           fcall = model.solve_iter_continue(ecole.scip.callback.Result.DidNotRun)
+
+See :py:class:`~ecole.scip.callback.BranchruleConstructor`, :py:class:`~ecole.scip.callback.HeuristicConstructor` for
+callback constructor parameters, as well as :py:class:`~ecole.scip.callback.BranchruleCall` and
+:py:class:`~ecole.scip.callback.BranchruleCall` for callbacks functions parameters passed by SCIP to the callback
+methods.
+
+.. note::
+
+   By default callback parameters such as ``priority``, ``frequency``, and ``max_depth`` taht control how when
+   the callback are evaluated by SCIP are set to run as often as possible.
+   However, it is entirely possible to run it with lower priority or frequency for create specific environments or
+   whatever other purpose.
+
+To create dynamics using iterative solving, one should call :py:meth:`ecole.scip.Model.solve_iter` in
+:py:meth:`~ecole.typing.Dynamics.reset_dynamics` and :py:meth:`ecole.scip.Model.solve_iter_continue` in
+:py:meth:`~ecole.typing.Dynamics.step_dynamics`.
+For instance, a branching environment could be created with the following dynamics.
+
+.. testcode::
+   :skipif: pyscipopt is None
+
+   class MyBranchingDynamics:
+       def __init__(self, pseudo_candidates=False, max_depth=ecole.scip.callback.max_depth_none):
+           self.pseudo_candidates = pseudo_candidates
+           self.max_depth = max_depth
+
+       def action_set(self, model):
+           if self.pseudo_candidates:
+               return model.as_pyscipopt().getPseudoBranchCands()
+           else:
+               return model.as_pyscipopt().getLPBranchCands()
+           return ...
+
+       def reset_dynamics(self, model):
+           fcall = model.solve_iter(
+               ecole.scip.callback.BranchruleConstructor(max_depth=self.max_depth)
+           )
+           return (fcall is None), self.action_set(model)
+
+       def step_dynamics(self, model, action):
+           model.as_pyscipopt().branchVar(action)
+           fcall = model.solve_iter_continue(ecole.scip.callback.Result.Branched)
+           return (fcall is None), self.action_set(model)

docs/howto/instances.rst

@@ -59,7 +59,7 @@ With an Environment
 -------------------
 The instance objects generated by :py:class:`~ecole.typing.InstanceGenerator`s,
 of type :py:class:`ecole.scip.Model`, can be passed directly to an environment's
-:py:meth:`~ecole.environment.EnvironmentComposer.reset` method.
+:py:meth:`~ecole.environment.Environment.reset` method.
 
 A typical example training over 1000 instances/episodes would look like:
 
@@ -78,7 +78,7 @@ A typical example training over 1000 instances/episodes would look like:
 
 .. note::
    The generated instance objects can be, in principle, modified between their generation and their usage in an environment
-   :py:meth:`~ecole.environment.EnvironmentComposer.reset` method. To keep code clean, however, we recommend that such modifications
+   :py:meth:`~ecole.environment.Environment.reset` method. To keep code clean, however, we recommend that such modifications
    be wrapped in a custom environment class. Details about custom environments :ref:`can be found here<create-new-environment>`.
 
 

docs/reference/scip-interface.rst

@@ -4,3 +4,31 @@ SCIP Interface
 Model
 -----
 .. autoclass:: ecole.scip.Model
+
+Callbacks
+---------
+Branchrule
+^^^^^^^^^^
+.. autoclass:: ecole.scip.callback.BranchruleConstructor
+.. autoclass:: ecole.scip.callback.BranchruleCall
+
+Heuristic
+^^^^^^^^^
+.. autoclass:: ecole.scip.callback.HeuristicConstructor
+.. autoclass:: ecole.scip.callback.HeuristicCall
+
+Utilities
+^^^^^^^^^
+.. autoattribute:: ecole.scip.callback.priority_max
+.. autoattribute:: ecole.scip.callback.max_depth_none
+.. autoattribute:: ecole.scip.callback.max_bound_distance_none
+.. autoattribute:: ecole.scip.callback.frequency_always
+.. autoattribute:: ecole.scip.callback.frequency_offset_none
+
+.. autoclass:: ecole.scip.callback.Result
+.. autoclass:: ecole.scip.callback.Type
+
+SCIP Data Types
+---------------
+.. autoclass:: ecole.scip.Stage
+.. autoclass:: ecole.scip.HeurTiming

libecole/CMakeLists.txt

@@ -5,7 +5,6 @@ add_library(
 	src/random.cpp
 	src/exception.cpp
 
-	src/utility/reverse-control.cpp
 	src/utility/chrono.cpp
 	src/utility/graph.cpp
 

libecole/include/ecole/dynamics/primal-search.hpp

@@ -6,7 +6,6 @@
 
 #include <nonstd/span.hpp>
 #include <scip/def.h>
-#include <scip/scip_heur.h>
 #include <scip/type_result.h>
 #include <xtensor/xtensor.hpp>
 
@@ -27,7 +26,7 @@ class ECOLE_EXPORT PrimalSearchDynamics : public DefaultSetDynamicsRandomState {
 
 	using DefaultSetDynamicsRandomState::set_dynamics_random_state;
 
-	ECOLE_EXPORT auto reset_dynamics(scip::Model& model) -> std::tuple<bool, ActionSet>;
+	ECOLE_EXPORT auto reset_dynamics(scip::Model& model) const -> std::tuple<bool, ActionSet>;
 
 	ECOLE_EXPORT auto step_dynamics(scip::Model& model, Action action) -> std::tuple<bool, ActionSet>;
 
@@ -38,7 +37,6 @@ class ECOLE_EXPORT PrimalSearchDynamics : public DefaultSetDynamicsRandomState {
 	int depth_stop;
 
 	unsigned int trials_spent = 0;        // to keep track of the number of trials during each search
-	SCIP_HEUR* heur = nullptr;            // to tell SCIP where primal solutions come from
 	SCIP_RESULT result = SCIP_DIDNOTRUN;  // the final result of each search (several trials)
 };
 

libecole/include/ecole/scip/callback.hpp

@@ -0,0 +1,83 @@
+#pragma once
+
+#include <tuple>
+#include <variant>
+
+#include <scip/type_timing.h>
+
+#include "ecole/utility/unreachable.hpp"
+
+/**
+ * Reverse callback tools.
+ *
+ * Helper tools for using reverse callback for iterative solving.
+ */
+namespace ecole::scip::callback {
+
+/** Type of rverse callback available. */
+enum struct Type { Branchrule, Heuristic };
+
+/** Return the name used for the reverse callback. */
+constexpr auto name(Type type) {
+	switch (type) {
+	case Type::Branchrule:
+		return "ecole::scip::StopLocation::Branchrule";
+	case Type::Heuristic:
+		return "ecole::scip::StopLocation::Heuristic";
+	default:
+		utility::unreachable();
+	}
+}
+
+constexpr inline int priority_max = 536870911;
+constexpr inline int max_depth_none = -1;
+constexpr inline double max_bound_distance_none = 1.0;
+constexpr inline int frequency_always = 1;
+constexpr inline int frequency_offset_none = 0;
+
+/** Parameter passed to create a reverse callback. */
+template <Type type> struct Constructor;
+
+/** Parameter passed to a reverse branchrule. */
+template <> struct Constructor<Type::Branchrule> {
+	int priority = priority_max;
+	int max_depth = max_depth_none;
+	double max_bound_distance = max_bound_distance_none;
+};
+using BranchruleConstructor = Constructor<Type::Branchrule>;
+
+/** Parameter passed to create a reverse heurisitc. */
+template <> struct Constructor<Type::Heuristic> {
+	int priority = priority_max;
+	int frequency = frequency_always;
+	int frequency_offset = frequency_offset_none;
+	int max_depth = max_depth_none;
+	SCIP_HEURTIMING timing_mask = SCIP_HEURTIMING_AFTERNODE;
+};
+using HeuristicConstructor = Constructor<Type::Heuristic>;
+
+using DynamicConstructor = std::variant<Constructor<Type::Branchrule>, Constructor<Type::Heuristic>>;
+
+/** Parameter given by SCIP to the callback function. */
+template <Type type> struct Call;
+
+/** Parameter given by SCIP to the branchrule function. */
+template <> struct Call<Type::Branchrule> {
+	/** The method of the Branchrule callback being called. */
+	enum struct Where { LP, External, Pseudo };
+
+	bool allow_add_constraints;
+	Where where;
+};
+using BranchruleCall = Call<Type::Branchrule>;
+
+/** Parameter given by SCIP to the heuristic functions. */
+template <> struct Call<Type::Heuristic> {
+	SCIP_HEURTIMING heuristic_timing;
+	bool node_infeasible;
+};
+using HeuristicCall = Call<Type::Heuristic>;
+
+using DynamicCall = std::variant<Call<Type::Branchrule>, Call<Type::Heuristic>>;
+
+}  // namespace ecole::scip::callback