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)

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)

Notify that the solve is ended.

Parameters:solver – Originator CPO solver (object of class CpoSolver)

result_found(solver, msol)

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

start_solve(solver)

Notify that the solve is started.

Parameters:solver – Originator CPO solver (object of class CpoSolver)

class docplex.cp.solver.solver_listener.CpoSolverListener

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)

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

end_operation(solver, op)

Notify that an operation is terminated.

Parameters:

• solver – Originator CPO solver (object of class CpoSolver)
• op – Operation that is terminated, in constants OPERATION_*

end_refine_conflict(solver)

Notify that the refine conflict is ended.

Parameters:solver – Originator CPO solver (object of class CpoSolver)

end_solve(solver)

Notify that the solve is ended.

Parameters:solver – Originator CPO solver (object of class CpoSolver)

new_log_data(solver, data)

Signal a new piece of log data.

Parameters:

• solver – Originator CPO solver (object of class CpoSolver)
• data – New log data as a string

new_result(solver, result)

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

result_found(solver, sres)

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

Notify the listener that the solver object has been created.

Parameters:solver – Originator CPO solver (object of class CpoSolver)

start_operation(solver, op)

Notify that an operation is started.

Parameters:

• solver – Originator CPO solver (object of class CpoSolver)
• op – Operation that is started, in constants OPERATION_*

start_refine_conflict(solver)

Notify that the refine conflict is started.

Parameters:solver – Originator CPO solver (object of class CpoSolver)

start_solve(solver)

Notify that the solve is started.

Parameters:solver – Originator CPO solver (object of class CpoSolver)

class docplex.cp.solver.solver_listener.DelayListener(delay)

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)

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

class docplex.cp.solver.solver_listener.LogSolverListener(prefix='')

Bases: docplex.cp.solver.solver_listener.CpoSolverListener

Solve listener that just log listener events.

New in version 2.8.

end_operation(solver, op)

Notify that an operation is terminated.

Parameters:

• solver – Originator CPO solver (object of class CpoSolver)
• op – Operation that is terminated, in constants OPERATION_*

new_result(solver, result)

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

Notify the listener that the solver object has been created.

Parameters:solver – Originator CPO solver (object of class CpoSolver)

start_operation(solver, op)

Notify that an operation is started.

Parameters:

• solver – Originator CPO solver (object of class CpoSolver)
• op – Operation that is started, in constants OPERATION_*

class docplex.cp.solver.solver_listener.SolverProgressPanelListener(parse_log=False)

Bases: docplex.cp.solver.solver_listener.CpoSolverListener