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)

Bases: docplex.mp.progress.SolutionListener

A subclass of SolutionListener, which calls a function at each intermediate solution.

No exception is caught.

notify_solution(sol)

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)

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)

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.

publish(kpi_dict)

This method is called at each improving solution, with a dictionay of name, values.

Parameters:kpi_dict – a dicitonary of names and KPi values, computed on the intermediate solution.

class docplex.mp.progress.KpiPrinter(model, clock=<ProgressClock.Gap: 7>, absdiff=None, reldiff=None, kpi_format='* ItCnt={3:d} KPI: {1:<{0}} = ')

Bases: docplex.mp.progress.KpiListener

publish(kpi_dict)

This method is called at each improving solution, with a dictionay of name, values.

Parameters:kpi_dict – a dicitonary of names and KPi values, computed on the intermediate solution.

class docplex.mp.progress.ProgressClock

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

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)

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)

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()

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)

Bases: docplex.mp.progress._AbstractProgressListener

The base class for progress listeners.

abort()

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)

The method called when solve is finished on a model.

The status is the solve status from the solve() method

notify_progress(progress_data)

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)

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()

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)

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)

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()

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)

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.

iter_solutions()

Returns an iterator on the stored solutions

notify_solution(sol)

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()

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)

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)

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()

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.