Module docplex.cp.model

This module contains principally the class CpoModel that handles all the elements that compose a CPO model:

• the variables of the domain (integer variables, interval variables, sequence variables and state functions),
• the constraints of the model,
• optional objective value(s),
• optional search phases,
• optional starting point (available for CPO solver release greater or equal to 12.7.0).

The different model expressions and elements are created using services provided by modules:

• docplex.cp.expression for the simple expression elements,
• docplex.cp.modeler to build complex expressions and constraints using the specialized CPO functions.

Detailed description

class docplex.cp.model.CpoModel(name=None, sfile=None)

Bases: object

This class is the Python container of a CPO model.

Constructor.

Parameters:

• name – Model name, None for automatic (source file name).
• sfile – Source file, None for automatic.

add(expr)

Adds a CP expression to the model.

This method adds a CP expression to the model. All the variables that are used by this expression are automatically added to the model.

The order in which expressions are added to the model is preserved when it is submitted for solving.

Parameters:expr – Expression to add. Raises:CpoException in case of error.

add_search_phase(phase)

Add a search phase to the list of search phases

Parameters:phase – Phase to add to the list

check_equivalence(other)

Checks that this model is equivalent to another.

Variables and expressions are compared, but not names that may differ because of automatic naming.

Parameters:other – Other model to compare with. Raises:Exception if models are not equivalent

equals(other)

Checks if this model is equal to another.

Parameters:other – Other model to compare with. Returns:True if models are identical, False otherwise.

export_as_cpo(out=None, **kwargs)

Exports/prints the model in the standard CPO file format.

Parameters:out – Target output, stream or file name. Default is sys.stdout.

Optional args:

context: Global solving context. If not given, context is the default context that is set in config.py. params: Solving parameters (CpoParameters) that overwrites those in solving context add_source_location: Add source location into generated text length_for_alias: Minimum name length to use shorter alias instead (others): All other context parameters that can be changed

get_all_expressions()

Gets the list of all model expressions

Returns:List of model expressions Each expression is a tuple (expr, loc, root) where loc is a tuple (source_file, line).

get_all_variables()

Gets the list of all model variables.

Returns:List of model variables.

get_cpo_string(**kwargs)

Compiles the model in CPO file format into a string.

Parameters:

• context – Global solving context. If not given, context is the default context that is set in config.py.
• params – Solving parameters (CpoParameters) that overwrites those in solving context
• add_source_location – Add source location into generated text
• length_for_alias – Minimum name length to use shorter alias instead
• (others) – All other context parameters that can be changed

Returns:

String containing the model.

get_expression(name)

Gets an expression from its name (expression or variable).

Parameters:name – Name of the expression. Returns:Expression, None if not found.

get_format_version()

Gets the version of the CPO format

Returns:String containing the version of the CPO format. None for default.

get_modeling_duration()

Get the time spent in modeling.

This time is computes as difference between the last time an expression has been added and the model object creation time.

Returns:Modeling duration in seconds

get_name()

Gets the name of the model.

Returns:Name of the model (file name with no path or extension).

get_optimization_expression()

Gets the optimization expression (maximization or minimization).

Returns:Optimization expression, None if satisfaction problem.

get_search_phases()

Get the list of search phases.

Returns:List of search phases (pairs (expression, location)), [] if none.

get_source_file()

Gets the name of the source file from which model has been created.

Returns:Python source file name.

get_starting_point()

Get the model starting point

Returns:Model starting point, None if none

print_information(out=None)

Prints model information.

Parameters:out – Output stream or file name, default is sys.stdout.

propagate(**kwargs)

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 method creates a new CpoSolver with given arguments, and then call its method propagate.

The class docplex.cp.solver.solver.CpoSolver contains the actual implementation of this method, but also some others functions allowing to invoke more specialized functions. An advanced programming may require to explicitly create a CpoSolver instead of calling function at model level. Please refer to this class for more details.

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

Parameters:

• 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.

Returns:

Propagation result (object of class CpoSolveResult)

Raises:

• docplex.cp.utils.CpoNotSupportedException – if method not available in the solver agent.
• docplex.cp.utils.CpoException – (or derived) if error.

refine_conflict(**kwargs)

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 method creates a new CpoSolver with given arguments, and then call its method refine_conflict.

The class docplex.cp.solver.solver.CpoSolver contains the actual implementation of this method, but also some others functions allowing to invoke more specialized functions. An advanced programming may require to explicitly create a CpoSolver instead of calling function at model level. Please refer to this class for more details.

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

Parameters:

• 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.

Returns:

List of constraints that cause the conflict (object of class CpoRefineConflictResult)

Raises:

• docplex.cp.utils.CpoNotSupportedException – if method not available in the solver agent.
• docplex.cp.utils.CpoException – (or derived) if error.

remove(expr)

Remove an expression from the model.

This method removes from the model the first occurrence of the expression given as parameter. It does not remove the expression if it used as sub-expression of another expression.

Parameters:expr – Expression to remove. Returns:True if expression has been removed, False if not found

set_search_phases(phases)

Set a list of search phases

Parameters:phases – Array of search phases, or single phase

set_starting_point(stpoint)

Set a model starting point.

A starting point specifies a (possibly partial) solution that could be used by CP Optimizer to start the search.

Starting point is available for CPO solver release greater or equal to 12.7.0.

Parameters:stpoint – Starting point, object of class CpoModelSolution

solve(**kwargs)

Solves the model.

This method solves the model using the appropriate solver according to the optional parameters and/or configuration attributes.

This method creates a new CpoSolver with given arguments, and then calls its method solve().

The class docplex.cp.solver.solver.CpoSolver contains the actual implementation of this method, but also some others functions allowing to invoke more specialized functions. An advanced programming may require to explicitly create a CpoSolver instead of calling function at model level. Please refer to this class for more details.

Parameters:

• 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.

Returns:

Model solve result (object of class CpoSolveResult).

Raises:

docplex.cp.utils.CpoException – (or derived) if error.