Module docplex.cp.solver.solver

This module implements appropriate software to solve a CPO model represented by a docplex.cp.model.CpoModel object.

It implements the following object classes:

• CpoSolver contains the public interface allowing to make solving requests with a model.
• CpoSolverAgent is an abstract class that is extended by the actual implementation(s) of the solving functions.

The CpoSolver identifies and creates the required CpoSolverAgent depending on the configuration parameter context.solver.agent’ that contains the name of the agent to be used. This name is used to access the configuration context *context.solver.<agent> that contains the details about this agent.

For example, the default configuration refers to docloud as default solver agent, to solve model using DOcplexcloud services. This means that at least following configuration elements must be set:

context.solver.agent = 'docloud'
context.solver.docloud.url = <URL of the service>
context.solver.docloud.key = <Access key of the service>

The different methods that can be called on a CpoSolver object are:

• solve() simply solve the model and returns a solve result, if any. For convenience reason, this method is also directly available on the CpoModel object (docplex.cp.model.CpoModel.solve()).
• search_next() and end_search() allows to iterate on different solutions of the model.
• refine_conflict() calls the conflict refiner that identifies a minimal conflict for the infeasibility of the model.
• propagate() calls the propagation that communicates the domain reduction of a decision variable to all of the constraints that are stated over this variable.

Except solve(), these functions are only available with a local solver with release greater or equal to 12.7.0. When a method is not available, an exception CpoNotSupportedException is raised.

If the methods search_next() and end_search() are available in the underlying solver agent, the CpoSolver object can acts as an iterator. All solutions can be retrieved using a loop like:

solver = CpoSolver(mdl)
for sol in solver:
    sol.print_solution()

A such solution iteration can be interrupted at any time by calling end_search() that returns a fail solution including the last solve status.

Detailed description

class docplex.cp.solver.solver.CpoSolver(model, **kwargs)

Bases: object

This class represents the public API of the object allowing to solve a CPO model.

It create the appropriate CpoSolverAgent that actually implements solving functions, depending on the value of the configuration parameter context.solver.agent.

Constructor:

Parameters:model – Model to solve

Optional args:

context: Complete solving context. If not given, context is the default context that is set in config.py. params: Solving parameters (CpoParameters) that overwrite those in the solving context url: URL of the DOcplexcloud service that overwrites the one defined in the solving context. key: Authentication key of the DOcplexcloud service that overwrites the one defined in the solving context. (others): All other context parameters that can be changed.

end_search()

End current search.

This function is available only with local CPO solver with release number greater or equal to 12.7.0.

Returns:Last (fail) model solution with last solve information (type CpoModelSolution) Raises:CpoNotSupportedException – if method not available in the solver agent.

get_last_solution()

Get the last solution returned by this solver

Returns:Last solution returned by this solver

next()

For solution iteration, get the next available solution.

This function is available only with local CPO solver with release number greater or equal to 12.7.0.

Returns:Next model solution (object of class CpoModelSolution)

propagate()

This method invokes the propagation on the current model.

Constraint propagation is the process of communicating the domain reduction of a decision variable to all of the constraints that are stated over this variable. This process can result in more domain reductions. These domain reductions, in turn, are communicated to the appropriate constraints. This process continues until no more variable domains can be reduced or when a domain becomes empty and a failure occurs. An empty domain during the initial constraint propagation means that the model has no solution.

The result is a object of class CpoSolveResult, the same than the one returned by solve() method. However, variable domains may not be completely defined.

This function is available only with local CPO solver with release number greater or equal to 12.7.0.

Returns:Propagation result (object of class CpoSolveResult) Raises:CpoNotSupportedException – method not available in this solver agent.

refine_conflict()

This method identifies a minimal conflict for the infeasibility of the current model.

Given an infeasible model, the conflict refiner can identify conflicting constraints and variable domains within the model to help you identify the causes of the infeasibility. In this context, a conflict is a subset of the constraints and/or variable domains of the model which are mutually contradictory. Since the conflict is minimal, removal of any one of these constraints will remove that particular cause for infeasibility. There may be other conflicts in the model; consequently, repair of a given conflict does not guarantee feasibility of the remaining model.

Conflict refiner is controled by the following parameters (that can be set at CpoSolver creation):

• ConflictRefinerBranchLimit
• ConflictRefinerFailLimit
• ConflictRefinerIterationLimit
• ConflictRefinerOnVariables
• ConflictRefinerTimeLimit

that are described in module docplex.cp.parameters.

Note that the general TimeLimit parameter is used as a limiter for each conflict refiner iteration, but the global limitation in time must be set using ConflictRefinerTimeLimit that is infinite by default.

This function is available only with local CPO solver with release number greater or equal to 12.7.0.

Returns:List of constraints that cause the conflict (object of class CpoRefineConflictResult) Raises:CpoNotSupportedException – if method not available in the solver agent.

search_next()

Get the next available solution.

This function is available only with local CPO solver with release number greater or equal to 12.7.0.

Returns:Next model solution (object of class CpoModelSolution) Raises:CpoNotSupportedException – if method not available in the solver agent.

solve()

Solve the model

This function solves the model using CP Optimizer’s built-in strategy. The built-in strategy is determined by setting the parameter SearchType (see docplex.cp.parameters). If the model contains an objective, then the optimal solution with respect to the objective will be calculated. Otherwise, a solution satisfying all problem constraints will be calculated.

The function returns an object of the class CpoSolveResult (see docplex.cp.solution) that contains the solution if exists, plus different information on the solving process.

Returns:Model solution (object of class CpoSolveResult) Raises:docplex.cp.utils.CpoException (or derived) if error.

class docplex.cp.solver.solver.CpoSolverAgent(model, params, context)

Bases: object

This class is an abstract class that must be extended by every solver agent that intend to be called by CpoSolver to solve a CPO model.

Constructor

Parameters:

• model – Model to solve
• params – Solving parameters
• context – Solver agent context

Raises:

CpoException if jar file does not exists

end()

End solver agent and release all resources.

end_search()

End current search.

Returns:Last (fail) solve result with last solve information (type CpoSolveResult) Raises:CpoNotSupportedException – method not available in this solver agent.

propagate()

This method invokes the propagation on the current model.

Constraint propagation is the process of communicating the domain reduction of a decision variable to all of the constraints that are stated over this variable. This process can result in more domain reductions. These domain reductions, in turn, are communicated to the appropriate constraints. This process continues until no more variable domains can be reduced or when a domain becomes empty and a failure occurs. An empty domain during the initial constraint propagation means that the model has no solution.

The result is a object of class CpoSolveResult, the same than the one returned by solve() method. However, in this case, variable domains may not be completely defined.

Returns:Propagation result (object of class CpoSolveResult) Raises:CpoNotSupportedException – method not available in this solver agent.

refine_conflict()

This method identifies a minimal conflict for the infeasibility of the current model.

Given an infeasible model, the conflict refiner can identify conflicting constraints and variable domains within the model to help you identify the causes of the infeasibility. In this context, a conflict is a subset of the constraints and/or variable domains of the model which are mutually contradictory. Since the conflict is minimal, removal of any one of these constraints will remove that particular cause for infeasibility. There may be other conflicts in the model; consequently, repair of a given conflict does not guarantee feasibility of the remaining model.

Returns:Conflict result (object of class CpoRefineConflictResult) Raises:CpoNotSupportedException – method not available in this solver agent.

search_next()

Search the next available solution.

Returns:Next solve result (object of class CpoSolveResult) Raises:CpoNotSupportedException – method not available in this solver agent.

solve()

Solve the model

Returns:Model solve result (object of class CpoSolveResult) Raises:CpoNotSupportedException – method not available in this solver agent.

start_search()

Start a new search. Solutions are retrieved using method search_next().

Raises:CpoNotSupportedException – method not available in this solver agent.