Module docplex.cp.solver.solver_listener¶
This module defines the class CpoSolverListener
that allows to be warned about different steps of the solve.
Any number of listeners can be added to a solver using the method docplex.cp.solver.solver.CpoSolver.add_listener()
.
Listeners can also be added on the model object using docplex.cp.model.CpoModel.add_listener()
This module also defines some default useful listeners:
AutoStopListener
: Listener that stops the solve if configurable conditions are reached.DelayListener
: Utility listener that waits some time at each solution found.SolverProgressPanelListener
: implements a progress panel that appears when the solve is started. This panel is based on the package Tkinter that is available only in Python 2.7.14 and Python 3.X.
All these listeners are effective if the model provides multiple solutions. They are then more adapted to optimization problems.
To be able to process multiple solutions, the model should be solved:
 using the solution iterator given by method
docplex.cp.model.CpoModel.start_search()
, or using the method
docplex.cp.model.CpoModel.solve()
but setting the parameter context.solver.solve_with_search_next to True.
New in version 2.8.
Detailed description¶

class
docplex.cp.solver.solver_listener.
AutoStopListener
(qsc_time=None, qsc_sols=None, min_sols=0, max_sols=None)[source]¶ Bases:
docplex.cp.solver.solver_listener.CpoSolverListener
Solver listener that aborts a search when a predefined criteria is reached.
New in version 2.8.
Constructor
Create a new solver listener that aborts the solve if defined criteria are reached.
Parameters:  min_sols – Minimun number of solutions to be found before stopping the solve
 max_sols – Maximum number of solutions after which solve is stopped
 qsc_time – Quiesce time limit. Max time, in seconds, after which solver is stopped if no new solution is found.
 qsc_sols – Quiesce time limit expressed as a number of solutions. Actual quiesce time limit is computed as this value multiplied by the average time between solutions.

end_solve
(solver)[source]¶ Notify that the solve is ended.
Parameters: solver – Originator CPO solver (object of class CpoSolver
)

result_found
(solver, msol)[source]¶ Signal that a solve result has been found.
This method is called every time a result is provided by the solver. The result, in particular the last one, may not contain any solution. This should be checked calling method sres.is_solution().
This method replaces deprecated method solution_found() that is confusing as result may possibly not contain a solution to the model.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  sres – Solve result, object of class
CpoSolveResult
 solver – Originator CPO solver (object of class

class
docplex.cp.solver.solver_listener.
CpoSolverListener
[source]¶ Bases:
object
Solve listener to be warned about different solving steps.
This class is an ‘abstract’ class that must be extended by actual listener implementation. It implements methods that are called to be warned about noticeable solving steps.
These methods are all taking the source solver as first argument. There are:
solver_created()
signals the solver has just been created,start_operation()
signals the start of a solve operation,end_operation()
signals the end of a solve operation,new_result()
notifies about a new result,new_log_data()
notifies about a new piece of log data.
For a more specialized notification, the following methods are also implemented (here empty), called by the default implementation of the methods listed above (except solver_created). This means that, if the methods above are overwritten, the following methods may never be called, except if the new implementation calls for super().
start_solve()
signals that a solve operation is started,end_solve()
signals that a solve operation is ended,result_found()
notifies a new solve result,start_refine_conflict()
signals that a refine_conflict operation is started,end_refine_conflict()
signals that a refine_conflict operation is ended,conflict_found()
notifies about the result of a refine_conflict.

conflict_found
(solver, cflct)[source]¶ Signal that a conflict result has been found.
This method is called when a conflict result is found by the solver when method refine_conflict() is called.
Note that the conflict result may contain no conflict.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  cflct – Conflict descriptor, object of class
CpoRefineConflictResult
 solver – Originator CPO solver (object of class

end_operation
(solver, op)[source]¶ Notify that an operation is terminated.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  op – Operation that is terminated, in constants OPERATION_*
 solver – Originator CPO solver (object of class

end_refine_conflict
(solver)[source]¶ Notify that the refine conflict is ended.
Parameters: solver – Originator CPO solver (object of class CpoSolver
)

end_solve
(solver)[source]¶ Notify that the solve is ended.
Parameters: solver – Originator CPO solver (object of class CpoSolver
)

new_log_data
(solver, data)[source]¶ Signal a new piece of log data.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  data – New log data as a string
 solver – Originator CPO solver (object of class

new_result
(solver, result)[source]¶ Signal that a new result has been found.
Depending on the operation in progress, result object may be:
 an object of class
CpoSolveResult
if operation is a solve,  an object of class
CpoRefineConflictResult
if the operation is a refine_conflict.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  result – New result that has been found
 an object of class

result_found
(solver, sres)[source]¶ Signal that a solve result has been found.
This method is called every time a result is provided by the solver. The result, in particular the last one, may not contain any solution. This should be checked calling method sres.is_solution().
This method replaces deprecated method solution_found() that is confusing as result may possibly not contain a solution to the model.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  sres – Solve result, object of class
CpoSolveResult
 solver – Originator CPO solver (object of class

solver_created
(solver)[source]¶ Notify the listener that the solver object has been created.
Parameters: solver – Originator CPO solver (object of class CpoSolver
)

start_operation
(solver, op)[source]¶ Notify that an operation is started.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  op – Operation that is started, in constants OPERATION_*
 solver – Originator CPO solver (object of class

class
docplex.cp.solver.solver_listener.
DelayListener
(delay)[source]¶ Bases:
docplex.cp.solver.solver_listener.CpoSolverListener
Solver listener that waits a given delay after each solution.
New in version 2.8.
Constructor
Create a new solver listener that waits a given delay after each solution.
Parameters: delay – Wait delay in seconds 
result_found
(solver, msol)[source]¶ Signal that a solve result has been found.
This method is called every time a result is provided by the solver. The result, in particular the last one, may not contain any solution. This should be checked calling method sres.is_solution().
This method replaces deprecated method solution_found() that is confusing as result may possibly not contain a solution to the model.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  sres – Solve result, object of class
CpoSolveResult
 solver – Originator CPO solver (object of class


class
docplex.cp.solver.solver_listener.
LogSolverListener
(prefix='')[source]¶ Bases:
docplex.cp.solver.solver_listener.CpoSolverListener
Solve listener that just log listener events.
New in version 2.8.

end_operation
(solver, op)[source]¶ Notify that an operation is terminated.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  op – Operation that is terminated, in constants OPERATION_*
 solver – Originator CPO solver (object of class

new_result
(solver, result)[source]¶ Signal that a new result has been found.
Parameters:  solver – Originator CPO solver (object of class
CpoSolver
)  result – New result that has been found
 solver – Originator CPO solver (object of class
