docplex.mp.progress module¶
This package contains classes to monitor the progress of a MIP solve.
This abstract class defines protocol methods, which are called from within CPLEX’s MIP search algorithm.
Progress listeners are based on CPLEX’s MIPInfoCallback, and work only with a local installation of CPLEX, not on Cplexcloud.
At each node, all progress listeners attached to the model receive progress data
through a notify_progress method, with an instance of ProgressData
.
This named tuple class contains information about solve time, objective value,
best bound, gap and nodes, but no variable values.
The base class for progress listeners is ProgressListener
.
DOcplex provides concrete sub-classes to handle basic cases, but
you may also create your own sub-class of ProgressListener
to suit your needs.
Each instance of ProgressListener
must be attached to a model to receive events during
a MIP solve., using Model.add_progress_listener.
An example of such a progress listener is TextProgressListener
,
which prints a message to stdout in a format similar to CPLEX log, each time it receives a progress data.
If you need to get the values of variables in an intermediate solution,
you should sub-class from class SolutionListener
.
In this case, the notify_solution()
method will be called
each time CPLEX finds a valid intermediate solution, with an instance of docplex.mp.solution.SolveSolution
.
Listeners are called from within CPLEX code, with its own frequency. It may occur that listeners are
called with no real progress in either the objective or the best bound. To help you chose what kind
of calls you are really interested in, DOcplex uses the enumerated class Objective
filters all calls but those where the objective has improved.
To summarize, listeners are called from within CPLEX’s MIP search algorithm, when the clock you have chosen accepts the call. All listeners are created with a clock argument that controls which calls they accept.
When a listener accepts a call, its method notify_progress()
is called with the current progress data.
See TextProgressListener
as an example of a simple progress listener.
In addition, if the listener derives from SolutionListener
, its method notify_solution()
is also called
with the intermediate solution, passed as an instance of docplex.mp.solution.SolveSolution
.
See SolutionRecorder
as an example of solution listener
-
class
docplex.mp.progress.
FunctionalSolutionListener
(solution_fn, clock=<ProgressClock.Gap: 7>, absdiff=None, reldiff=None)[source]¶ Bases:
docplex.mp.progress.SolutionListener
A subclass of SolutionListener, which calls a function at each intermediate solution.
No exception is caught.
-
notify_solution
(sol)[source]¶ Generic method to be redefined by custom listeners to handle intermediate solutions. This method is called by the CPLEX search with an intermediate solution.
Parameters: sol – an instance of docplex.mp.solution.SolveSolution
Note: as this method is called at each node of the MIP search, it may happen that several calls are made with an identical solution, that is, different object instances, but sharing the same variable values.
-
-
class
docplex.mp.progress.
KpiListener
(model, clock=<ProgressClock.Gap: 7>, absdiff=None, reldiff=None)[source]¶ Bases:
docplex.mp.progress.SolutionListener
A refinement of SolutionListener, which computes KPIs at each intermediate solution.
Calls the publish method with a dicitonary of KPIs. Defaul tis to do nothing.
This listener listens to the Gap clock.
-
notify_solution
(sol)[source]¶ Generic method to be redefined by custom listeners to handle intermediate solutions. This method is called by the CPLEX search with an intermediate solution.
Parameters: sol – an instance of docplex.mp.solution.SolveSolution
Note: as this method is called at each node of the MIP search, it may happen that several calls are made with an identical solution, that is, different object instances, but sharing the same variable values.
-
-
class
docplex.mp.progress.
KpiPrinter
(model, clock=<ProgressClock.Gap: 7>, absdiff=None, reldiff=None, kpi_format='* ItCnt={3:d} KPI: {1:<{0}} = ')[source]¶
-
class
docplex.mp.progress.
ProgressClock
[source]¶ Bases:
enum.Enum
This enumerated class controls the type of events a listener listens to.
The possible values are (in order of decreasing call frequency).
- All: the listener listens to all calls from CPLEX.
- BestBound: listen to changes in best bound, not necessarily with a solution present.
- Solutions: listen to all intermediate solutions, not necessarily impriving.
- Nothing prevents being called several times with an identical solution.
- Gap: listen to intermediate solutions, where either objective or best bound has improved.
- Objective: listen to intermediate solutions, where the solution objective has improved.
To determine whether objective or best bound have improved (or not), see the numerical parameters absdiff and reldiff in :class:ProgressListener and all its descendant classes.
New in version 2.10
-
class
docplex.mp.progress.
ProgressData
[source]¶ Bases:
docplex.mp.progress._TProgressData
A named tuple class to hold progress data, as reeived from CPLEX.
-
has_incumbent
¶ a boolean, indicating whether an incumbent solution is available (or not), at the moment the listener is called.
-
current_objective
¶ contains the current objective, if an incumbent is available, else None.
-
best_bound
¶ The current best bound as reported by the solver.
-
mip_gap
¶ the gap between the best integer objective and the objective of the best node remaining; available if an incumbent is available.
-
current_nb_nodes
¶ the current number of nodes.
-
current_nb_iterations
¶ the current number of iterations.
-
remaining_nb_nodes
¶ the remaining number of nodes.
-
time
¶ the elapsed time since solve started.
-
det_time
¶ the deterministic time since solve started.
-
-
class
docplex.mp.progress.
ProgressDataRecorder
(clock=<ProgressClock.Gap: 7>, absdiff=None, reldiff=None)[source]¶ Bases:
docplex.mp.progress.ProgressListener
A specialized class of ProgressListener, which collects all ProgressData it receives.
-
iter_recorded
¶ Returns an iterator on stored progress data
Returns: an iterator.
-
notify_progress
(progress_data)[source]¶ This method is called from within the solve with a ProgressData instance.
Parameters: progress_data – an instance of ProgressData
containing data about the current point in the search tree.
-
notify_start
()[source]¶ This methods is called on all attached listeners at the beginning of a solve().
When writing a custom listener, this method is used to restore internal data which can be modified during solve. Always call the superclass notify_start before adding specific code in a sub-class.
-
recorded
¶ Returns a copy of the recorded data.
Returns:
-
-
class
docplex.mp.progress.
ProgressListener
(clock_arg=<ProgressClock.All: 0>, absdiff=None, reldiff=None)[source]¶ Bases:
docplex.mp.progress._AbstractProgressListener
The base class for progress listeners.
-
abort
()[source]¶ Aborts the CPLEX search.
This method tells CPLEX to stop the MIP search. You may use this method in a custom progress listener to stop the search based on your own criteria (for example, when improvements in gap is consistently below a minimum threshold).
Note
This method should be called from within a
notify_progress()
method call, otherwise it will have no effect.
-
clock
¶ Returns the clock of the listener.
Returns: an instance of ProgressClock
-
current_progress_data
¶ This property return the current progress data, if any.
Returns the latest progress data, if at least one has been received.
Returns: an instance of :class:~ProgressData` or None.
-
notify_end
(status, objective)[source]¶ The method called when solve is finished on a model.
The status is the solve status from the solve() method
-
notify_progress
(progress_data)[source]¶ This method is called from within the solve with a ProgressData instance.
Parameters: progress_data – an instance of ProgressData
containing data about the current point in the search tree.
-
notify_solution
(s)[source]¶ Redefine this method to handle an intermediate solution from the callback.
Parameters: s – solution Note
if you need to access runtime information (time, gap, number of nodes), use
SolutionListener.current_progress_data()
, which contains the latest priogress information as a tuple.
-
notify_start
()[source]¶ This methods is called on all attached listeners at the beginning of a solve().
When writing a custom listener, this method is used to restore internal data which can be modified during solve. Always call the superclass notify_start before adding specific code in a sub-class.
-
-
class
docplex.mp.progress.
SolutionListener
(clock=<ProgressClock.Solutions: 1>, absdiff=None, reldiff=None)[source]¶ Bases:
docplex.mp.progress.ProgressListener
The base class for listeners that work on intermediate solutions.
To define a custom behavior for a subclass of this class, you need to redefine notify_solution. The current progress data is available from the current_progress_data property.
-
notify_solution
(sol)[source]¶ Generic method to be redefined by custom listeners to handle intermediate solutions. This method is called by the CPLEX search with an intermediate solution.
Parameters: sol – an instance of docplex.mp.solution.SolveSolution
Note: as this method is called at each node of the MIP search, it may happen that several calls are made with an identical solution, that is, different object instances, but sharing the same variable values.
-
notify_start
()[source]¶ This methods is called on all attached listeners at the beginning of a solve().
When writing a custom listener, this method is used to restore internal data which can be modified during solve. Always call the superclass notify_start before adding specific code in a sub-class.
-
-
class
docplex.mp.progress.
SolutionRecorder
(clock=<ProgressClock.Gap: 7>, absdiff=None, reldiff=None)[source]¶ Bases:
docplex.mp.progress.SolutionListener
A specialized implementation of
SolutionListener
, which stores –all– intermediate solutions.As the listener might be called at different times with identical incumbent values, thus the list of solutions list might well contain identical solutions.
-
notify_solution
(sol)[source]¶ Redefintion of the generic notify_solution method, called by CPLEX. For this class, appends the intermediate solution to the list of stored solutions.
-
notify_start
()[source]¶ Redefinition of the generic notify_start() method to clear all data modified by solve(). In this case, clears the list of solutions.
-
number_of_solutions
¶ Returns the number of stored solutions.
-
-
class
docplex.mp.progress.
TextProgressListener
(clock=<ProgressClock.Gap: 7>, gap_fmt=None, obj_fmt=None, absdiff=None, reldiff=None)[source]¶ Bases:
docplex.mp.progress.ProgressListener
- A simple implementation of Progress Listener, which prints messages to stdout,
- in the manner of the CPLEX log.
Parameters: - clock – an enumerated value of type :class:ProgressClock which defines the frequency of the listener.
- absdiff – a float value which controls the minimum absolute change for objective or best bound values
- reldiff – a float value which controls the minimum absolute change for objective or best bound values.
Note
The default behavior is to listen to an improvement in either the objective or best bound, each being improved by either an absolute value change of at least absdiff, or a relative change of at least reldiff.
-
notify_progress
(progress_data)[source]¶ This method is called from within the solve with a ProgressData instance.
Parameters: progress_data – an instance of ProgressData
containing data about the current point in the search tree.
-
notify_start
()[source]¶ This methods is called on all attached listeners at the beginning of a solve().
When writing a custom listener, this method is used to restore internal data which can be modified during solve. Always call the superclass notify_start before adding specific code in a sub-class.