Module docplex.cp.solution

This module contains the different elements that represent a solution resulting from the solve of a model.

This module implements the following object classes to represent solution elements:

• CpoIntVarSolution: solution of an integer variable,
• CpoIntervalVarSolution: solution of an interval variable,
• CpoSequenceVarSolution: solution of a sequence variable,
• CpoStateFunctionSolution: solution of a state function, and
• CpoModelSolution: aggregation of all individual model element solutions,

and the following ones to represent results:

• CpoSolveResult: result of a model solve, including a solution to the model (if any) plus other technical information (solve details, log, etc)
• CpoRefineConflictResult: result of an invocation of the conflict refiner.

The solution objects (CpoModelSolution, CpoIntVarSolution, etc) can be used in multiple ways:

• To represent a complete (fully instantiated) solution, where each model has a unique fixed value, as returned by a successful model solve.
• To represent a partial model solution, that is proposed as a solve starting point (see docplex.cp.model.CpoModel.set_starting_point()) In this case, not all variables are present in the solution, and some of them may be partially instantiated.
• To represent a partial model solution that is returned by the solver as result of calling method docplex.cp.solver.solver.CpoSolver.propagate().

Detailed description

docplex.cp.solution.ALL_FAIL_STATUSES = ('Unknown', 'SearchHasFailedNormally', 'SearchHasNotFailed', 'SearchStoppedByAbort', 'SearchStoppedByException', 'SearchStoppedByExit', 'SearchStoppedByLabel', 'SearchStoppedByLimit', 'SearchCompleted')

List of all possible fail statuses

docplex.cp.solution.ALL_SOLVE_STATUSES = ('Unknown', 'Infeasible', 'Feasible', 'Optimal', 'JobAborted', 'JobFailed')

List of all possible search statuses

class docplex.cp.solution.CpoIntVarSolution(name, value)

Bases: docplex.cp.solution.CpoVarSolution

This class represents a solution to an integer variable.

The solution can be:

• complete when the value is a single integer,
• partial when the value is a domain, set of multiple values.

A domain is a list of discrete integer values and/or intervals of values represented by a tuple containing interval min and max values (included).

For example, following are valid domains for an integer variable:

• 7 (complete solution)
• (1, 2, 4, 9)
• (2, 3, (5, 7), 9, (11, 13))

Constructor:

Parameters:

• name – Variable name
• value – Variable value, or domain if not completely instantiated

get_value()

Gets the value of the variable.

Returns:Variable value (integer), or domain (list of integers or intervals)

class docplex.cp.solution.CpoIntervalVarSolution(name, presence=None, start=None, end=None, size=None)

Bases: docplex.cp.solution.CpoVarSolution

This class represents a solution to an interval variable.

The solution can be complete if all attribute values are integers, or partial if at least one of them is an interval expressed as a tuple.

get_end()

Gets the interval end.

Returns:Interval end value, or domain (tuple (min, max)) if not fully instantiated

get_length()

Gets the interval length.

Returns:Interval length value, or domain (tuple (min, max)) if not fully instantiated

get_size()

Gets the interval size.

Returns:Interval size value, or domain (tuple (min, max)) if not fully instantiated

get_start()

Gets the interval start.

Returns:Interval start value, or domain (tuple (min, max)) if not fully instantiated

get_value()

Gets the interval variable value as a tuple (start, end, size), or () if absent.

If the variable is absent, then the result is an empty tuple.

If the variable is fully instantiated, the result is a tuple of 3 integers (start, end, size). The variable length, easy to compute as end - start, can also be retrieved by calling get_length().

If the variable is partially instantiated, the result is a tuple (start, end, size, length) where each individual value can be an integer or an interval expressed as a tuple.

Returns:Interval variable value as a tuple.

is_absent()

Check if the interval is absent.

Returns:True if interval is absent.

is_optional()

Check if the interval is optional.

Returns:True if interval is optional.

is_present()

Check if the interval is present.

Returns:True if interval is present.

class docplex.cp.solution.CpoModelSolution

Bases: object

This class represents a solution to a model. It contains the solutions of model variables plus the value of objective, if any.

Each variable solution is accessed with its name and its value is either CpoIntVarSolution, CpoIntervalVarSolution, CpoSequenceVarSolution or CpoStateFunctionSolution depending on the type of the variable.

The solution can be:

• complete, if each variable is assigned to a single value,
• partial if not all variables are defined, or if some variables are defined with domains that are not restricted to a single value.

An instance of this class may be created explicitly by the programmer of the model to express a starting point that can be passed to the model to optimize its solve (see docplex.cp.model.CpoModel.set_starting_point() for details).

add_integer_var_solution(name, value)

Add a new integer variable solution from its name and value..

The solution can be complete if the value is a single integer, or partial if the value is a domain, given as a list of integers or intervals expressed as tuples.

Parameters:

• name – Variable name
• value – Variable value, or domain if not completely instantiated

add_interval_var_solution(name, presence=None, start=None, end=None, size=None)

Add a new interval variable solution.

The solution can be complete if all attribute values are integers, or partial if at least one of them is an interval expressed as a tuple.

Parameters:

• name – Name of the variable.
• presence – Presence indicator (true for present, false for absent, None for undetermined). Default is None.
• start – Value of start, or tuple representing the start range
• end – Value of end, or tuple representing the end range
• size – Value of size, or tuple representing the size range

add_var_solution(vsol)

Add a solution to a variable to this model solution.

Parameters:vsol – Variable solution (object of a class extending CpoVarSolution)

get_all_var_solutions()

Gets the list of all variable solutions from this model solution.

Returns:List of all variable solutions (class extending CpoVarSolution).

get_objective_values()

Gets the numeric values of all objectives.

If the solution is partial, each objective value may be an interval expressed as a tuple (min, max)

Returns:Array of objective values, None if none.

get_value(name)

Gets the value of a variable.

This method first find the variable with get_var_solution() and, if exists, returns the result of a call to the method get_value() on this variable.

The result depends on the type of the variable. For details, please consult documentation of methods:

• CpoIntVarSolution.get_value()
• CpoIntervalVarSolution.get_value()
• CpoSequenceVarSolution.get_value()
• CpoStateFunctionSolution.get_value()

Parameters:name – Variable name, or model variable descriptor. Returns:Variable value, None if variable is not found.

get_var_solution(name)

Gets a variable solution from this model solution.

Parameters:name – Variable name or variable expression. Returns:Variable solution (class extending CpoVarSolution), None if variable not found

print_solution(out=None)

Prints the solution on a given output.

If the given output is a string, it is considered as a file name that is opened by this method using ‘utf-8’ encoding.

Parameters:out – Target output stream or output file, standard output if not given.

class docplex.cp.solution.CpoRefineConflictResult(model)

Bases: docplex.cp.solution.CpoRunResult

This class represents the result of a call to the conflict refiner.

A conflict is a subset of the constraints and/or variables of the model which are mutually contradictory.

The conflict refiner first examines the full infeasible model to identify portions of the conflict that it can remove. By this process of refinement, the conflict refiner arrives at a minimal conflict. A minimal conflict is usually smaller than the full infeasible model and thus makes infeasibility analysis easier. 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. If a model happens to include multiple independent causes of infeasibility, then it may be necessary for the user to repair one such cause and then repeat the diagnosis with further conflict analysis.

get_all_member_constraints()

Returns the list of all constraints that are certainly member of the conflict.

Returns:List of model constraints (class CpoExpr) certainly member of the conflict.

get_all_member_variables()

Returns the list of all variables that are certainly member of the conflict.

Returns:List of model variables (class CpoIntVar or CpoIntervalVar) certainly member of the conflict.

get_all_possible_constraints()

Returns the list of all constraints that are possibly member of the conflict.

Returns:List of model constraints (class CpoExpr) possibly member of the conflict.

get_all_possible_variables()

Returns the list of all variables that are possibly member of the conflict.

Returns:List of model variables (class CpoIntVar or CpoIntervalVar) possibly member of the conflict.

is_conflict()

Checks if this descriptor contains a valid conflict.

Returns:True if there is a conflict, False otherwise.

print_conflict(out=None)

Prints this conflict on a given output.

If the given output is a string, it is considered as a file name that is opened by this method using ‘utf-8’ encoding.

Parameters:out – Target output stream or output file, standard output if not given.

class docplex.cp.solution.CpoRunResult

Bases: object

This class is an abstract class extended by classes representing the result of a call to the solver.

get_solver_log()

Gets the log of the solver.

Returns:Solver log as a string, None if unknown.

class docplex.cp.solution.CpoSequenceVarSolution(name, lvars)

Bases: docplex.cp.solution.CpoVarSolution

This class represents a solution to a sequence variable.

Constructor:

Parameters:lvars – List of interval variable solutions that are in this sequence (objects CpoIntervalVarSolution).

get_interval_variables()

Gets the list of CpoIntervalVarSolution in this sequence.

Returns:List of CpoIntervalVarSolution in this sequence.

get_value()

Gets the list of CpoIntervalVarSolution in this sequence.

Returns:List of CpoIntervalVarSolution in this sequence.

class docplex.cp.solution.CpoSolveResult(model)

Bases: docplex.cp.solution.CpoRunResult

This class represents the result of a call to the solve of a model.

It contains the following elements:

• solve status,
• solver parameters,
• solver information
• output log
• solution, if any (class CpoModelSolution)

If this result contains a solution, the methods implemented in the class CpoModelSolution to access solution elements are available directly from this class.

Constructor:

Parameters:model – Related model

get_all_var_solutions()

Gets the list of all variable solutions from this model solution.

Returns:List of all variable solutions (class CpoVarSolution).

get_fail_status()

Gets the solving fail status.

Returns:Fail status, element of the global list ALL_FAIL_STATUSES.

get_info(name, default=None)

Gets a particular information attribute.

Parameters:

• name – Name of the information to get
• default – (optional) Default value if not found. None by default.

Returns:

Information attribute value, None if not found.

get_infos()

Gets the complete dictionary of information attributes.

Returns:Dictionary of information attributes, None if undefined.

get_number_of_constraints()

Gets the number of constraints in the model.

Returns:Number of constraints.

get_number_of_integer_vars()

Gets the number of integer variables in the model.

Returns:Number of integer variables.

get_number_of_interval_vars()

Gets the number of interval variables in the model.

Returns:Number of interval variables.

get_number_of_sequence_vars()

Gets the number of sequence variables in the model.

Returns:Number of sequence variables.

get_objective_values()

Gets the numeric values of all objectives.

Returns:Array of all objective values, None if none.

get_parameter(name, default=None)

Get a particular solving parameter.

Parameters:

• name – Name of the parameter to get
• default – (optional) Default value if not found. None by default.

Returns:

Parameter value, default value if not found.

get_parameters()

Gets the complete dictionary of solving parameters.

Returns:Solving parameters (object of class CpoParameters), None if undefined.

get_solve_status()

Gets the solve status.

Returns:Solve status, element of the global list ALL_SOLVE_STATUSES.

get_solve_time()

Gets the solve time required for this solution.

Returns:(float) Solve time in seconds.

get_value(name)

Gets the value of a variable.

For IntVar, value is an integer. For IntervalVar, value is a tuple (start, end, size), () if absent. For SequenceVar, value is list of interval variable solutions. For StateFunction, value is list of steps.

Parameters:name – Variable name, or model variable descriptor. Returns:Variable value, None if variable is not found.

get_var_solution(name)

Gets a variable solution from this model solution.

Parameters:name – Variable name or variable expression. Returns:Variable solution (class CpoVarSolution), None if not found.

is_solution()

Checks if this descriptor contains a valid solution to the problem.

A solution is present if the solve status is ‘Feasible’ or ‘Optimal’. Optimality of the solution should be tested using method is_solution_optimal().

Returns:True if there is a solution.

is_solution_optimal()

Checks if this descriptor contains an optimal solution to the problem.

Returns:True if there is a solution that is optimal.

print_solution(out=None)

Prints the solution on a given output.

If the given output is a string, it is considered as a file name that is opened by this method using ‘utf-8’ encoding.

Parameters:out – Target output stream or output file, standard output if not given.

class docplex.cp.solution.CpoStateFunctionSolution(name, steps)

Bases: docplex.cp.solution.CpoVarSolution

This class represents a solution to a step function.

A solution to a step function is represented by a list of steps. A step is a triplet (start, end, value) that gives the value of the function on the interval [start, end).

Constructor:

Parameters:steps – List of function steps represented as tuples (start, end, value).

get_function_steps()

Gets the list of function steps.

Returns:List of function steps. Each step is a tuple (start, end, value).

get_value()

Gets the list of function steps. Identical to get_function_steps().

Returns:List of function steps.

class docplex.cp.solution.CpoVarSolution(name)

Bases: object

This class is a super class of all classes representing a solution to a variable.

Constructor:

Parameters:name – Variable name, or object providing a name with a function get_name() or an attribute ‘name’.

get_name()

Gets the name of the variable.

Returns:Name of the variable.

get_value()

Gets the variable value. This method is overloaded by each class extending this class.

Returns:Value of the variable, represented according to its semantic (see specific variable documentation).