docplex.mp.solution module¶

class
docplex.mp.solution.
SolutionPool
[source]¶ Bases:
object
Solutions pools as returned by Model.populate()This class is not to be instantiated by users, only used after returned by Model.populate.
Instances of this class can be used like lists. They are fully iterable, and accessible by index.
See also

describe_objectives
()[source]¶ Prints statistical information about poolobjective values.
Relies on the stats property.

export_as_sol
(path=None, basename=None, **kwargs)[source]¶ Exports the solution pool as a SOL file.
Parameters:  basename – Controls the basename with which the solution is printed. Accepts None, a plain string, or a string format. If None, the model name is used. If passed a plain string, the string is used in place of the model’s name. If passed a string format (either with %s or {0}), this format is used to format the model name to produce the basename of the written file.
 path – A path to write the file, expects a string path or None.
Can be a directory, in which case the basename
that was computed with the basename argument is appended to the directory to produce
the file.
If given a full path, the path is directly used to write the file, and
the basename argument is not used.
If passed None, the output directory will be
tempfile.gettempdir()
.
Returns: The path to which the solutions from the pool are written, or None if an error occured.

mean_objective_value
¶ This property returns the mean objective value in the pool.

size
¶ Returns the number of solutions in the pool.
Returns:

stats
¶ Returns statistics about pool objective values.
Returns: a tuple of floats containing (in this order:  number of solutions (same as len()  mean objective value  standard deviation  minimum objective value  median objective value  maximum objective value Note
if pool is empty returns dummy values, only the first value (len of 0) is valid.


class
docplex.mp.solution.
SolveSolution
(model, var_value_map=None, obj=None, blended_obj_by_priority=None, name=None, solved_by=None, keep_zeros=True)[source]¶ Bases:
object
The
SolveSolution
class holds the result of a solve.
add_var_value
(var_key, value)[source]¶ Adds a new (variable, value) pair to this solution.
Parameters:  var_key – A decision variable (
docplex.mp.dvar.Var
) or a variable name (string).  value (number) – The value of the variable in the solution.
 var_key – A decision variable (

as_df
(name_key='name', value_key='value')[source]¶ Converts the solution to a pandas dataframe with two columns: variable name and values
Parameters:  name_key – column name for variable names. Default is ‘name’
 value_key – cilumn name for values., Default is ‘value’.
Returns: a pandas dataframe, if pandas is present.
New in version 2.15

check_as_mip_start
(strong_check=False)[source]¶ Checks that this solution is a valid MIP start.
 To be valid, it must have:
 at least one discrete variable (integer or binary), and
 the values for decision variables should be consistent with the type.
Returns: True if this solution is a valid MIP start. Return type: Boolean

contains
(dvar)[source]¶ Checks whether or not a decision variable is mentioned in the solution.
This predicate can also be used in the form var in solution, because the
__contains_()
method has been redefined for this purpose.Parameters: dvar ( docplex.mp.dvar.Var
) – The variable to check.Returns: True if the variable is mentioned in the solution. Return type: Boolean

export
(file_or_filename, format='json', **kwargs)[source]¶ Export this solution.
Parameters:  file_or_filename – If
file_or_filename
is a string, this argument contains the filename to write to. If this is a file object, this argument contains the file object to write to.  format – A string, the name of format to use. Possible values are:  “json”  “mst”: the MST cplex format for MIP starts  “xml”: same as MST
 kwargs – additional kwargs passed to the actual exporter
 file_or_filename – If

export_as_json_string
(**kwargs)[source]¶ Returns the solution as a string in JSON format.
Returns: a string. New in version 2.10

export_as_mst
(path=None, basename=None, write_level=<WriteLevel.Auto: 0>, **kwargs)[source]¶ Exports a solution to a file in CPLEX mst format.
Parameters:  basename – Controls the basename with which the solution is printed. Accepts None, a plain string, or a string format. If None, the model’s name is used. If passed a plain string, the string is used in place of the model’s name. If passed a string format (either with %s or {0}), this format is used to format the model name to produce the basename of the written file.
 path – A path to write the file, expects a string path or None.
Can be a directory, in which case the basename
that was computed with the basename argument is appended to the directory to produce
the file.
If given a full path, the path is directly used to write the file, and
the basename argument is not used.
If passed None, the output directory will be
tempfile.gettempdir()
.  write_level – an enumerated value which controls which variables are printed. The default is WriteLevel.Auto, which prints the values of all discrete variables. This parameter also accepts the number values of the corresponding CPLEX parameters (1 for AllVars, 2 for DiscreteVars, 3 for NonZeroVars, 4 for NonZeroDiscreteVars)
Returns: The full path of the file, when successful, else None
Examples
Assuming the solution has the name “prob”:
sol.export_as_mst()
will write file prob.mst in a temporary directory.sol.export_as_mst(write_level=WriteLevel.ALlvars)
will write file prob.mst in a temporary directory, and will print all variables in the problem.
sol.export_as_mst(path="c:/temp/myprob1.mst")
will write file “c:/temp/myprob1.mst”.sol.export_as_mst(basename="my_%s_mipstart", path ="z:/home/")
will write “z:/home/my_prob_mipstart.mst”.Note
The complete description of MST format is found here:
See also

export_as_sol
(path=None, basename=None, **kwargs)[source]¶ Exports a solution to a file in CPLEX SOL format.
SOL format is valid for all types of solutions, LP or MIP, but cannot be used for warm starts.
Arguments are identical to the method
export_as_mst()
Note: The complete description of SOL format is found here: https://www.ibm.com/support/knowledgecenter/SSSA5P_20.1.0/ilog.odms.cplex.help/CPLEX/FileFormats/topics/SOL.html
See also
docplex.mp.model.SolveSolution.export_as_mst()

classmethod
from_file
(filename, mdl)[source]¶  Builds solution(s) from a SOL file.
 Assumes filename is in CPLEX SOL format, reference: https://www.ibm.com/support/knowledgecenter/SSSA5P_20.1.0/ilog.odms.cplex.help/CPLEX/FileFormats/topics/SOL.html
Returns: a list of solution objects, read from the file, or None, if an error occured.

get_blended_objective_value_by_priority
()[source]¶ Gets the blended objective value (or list of blended objectives value) by priority level as defined in the solution. When the objective value has not been defined, a special value NO_SOLUTION is returned. To check whether the objective has been set, use
has_objective()
.Returns: The value of the objective (or list of values for multiobjective) as defined by the solution. Return type: float or list(float)

get_cuts
()[source]¶ Returns the number of cuts under the form of a dict(type > number).
Returns: the number of cuts under the form of a dict(type > number). Empty dict if CPLEX is not present.

get_dual_values
(lcts)[source]¶ Returns the dual values of a sequence of linear constraints.
Note: the model must a pure LP: no integer or binary variable, no piecewise, no SOS. The model must also be solved successfully before calling this method.
Parameters: lcts – a sequence of linear constraints. Returns: a sequence of float numbers

get_num_cuts
(cut_type)[source]¶ Returns the number of cuts for a specific type.
Parameters: cut_type – a cut type. Returns: the number of cuts associated to this type of cut. 0 if CPLEX is not present

get_objective_value
()[source]¶ Gets the objective value (or list of objectives value) as defined in the solution. When the objective value has not been defined, a special value NO_SOLUTION is returned. To check whether the objective has been set, use
has_objective()
.Returns: The value of the objective (or list of values for multiobjective) as defined by the solution. Return type: float or list(float)

get_reduced_costs
(dvars)[source]¶ Returns the reduced costs for a variable iterable.
Note: the model must a pure LP: no integer or binary variable, no piecewise, no SOS. The model must also be solved successfully before calling this method.
Parameters: dvars – a sequence of variables. Returns: a list of float numbers, in the same order as the variable sequence.

get_sensitivity
(dvars)[source]¶ Returns the sensitivity values for a variable iterable.
Note: The model must be solved successfully before calling this method.
Parameters: dvars – a sequence of variables. Returns: a list of tuples, in the same order as the variable sequence. Each tuple contains 3 tuples: the lower lower_bounds, the upper_bounds and the objective For example [((1e+20, 2.5), (3.0, 5.0), (1e+20, 2.0), (0.0, 4.0)), ((1e+20, 2.5), (3.0, 5.0), (1e+20, 2.0), (0.0, 4.0))]

get_slacks
(cts)[source]¶ Return the slack values for a sequence of constraints.
Slack values are available for linear, quadratic and indicator constraints. The model must be solved successfully before calling this method.
Parameters: cts – a sequence of constraints. Returns: a list of float values, in the same order as the constraints.

get_status
(ct)[source]¶ Returns the status of a linear constraint in the solution.
Returns 1 if the constraint is satisfied, else returns 0. This is particularly useful when using the status variable of constraints.
Parameters: ct – A linear constraint Returns: a number (1 or 0)

get_value
(arg)[source]¶ Gets the value of a variable or an expression in a solution. If the variable is not mentioned in the solution, the method returns 0 and does not raise an exception. Note that this method can also be used as
solution[arg]()
because the__getitem__()
method has been overloaded.Parameters: arg – A decision variable ( docplex.mp.dvar.Var
), a variable name (a string), or an expression.Returns: The value of the variable in the solution. Return type: float

get_value_df
(var_dict, value_column_name=None, key_column_names=None)[source]¶ Returns values of a dicitonary of variables, as a pandas dataframe.
If pandas is not present, returns a dicitonary of columns.
Parameters:  var_dict – the dicitonary of variables, as created by Model.xx_var_dict
 value_column_name – an optional string to name the value column. Default is ‘value’
 key_column_names – an optional list of strings to name th ekeys of the dicitonary. If not present, keys are named ‘k1’, ‘k2’, …
Returns: a pandas DataFrame, if pandas is present.

get_value_dict
(var_dict, keep_zeros=True, precision=1e06)[source]¶ Converts a dictionary of variables to a dictionary of solutions
Assuming var_dict is a dictionary of variables (for example, as returned by Model.integer_var_dict(), returns a dictionary with the same keys and as values the solution values of the variables.
Parameters:  var_dict – a dictionary of decision variables.
 keep_zeros – an optional flag to keep zero values (default is True)
 precision – an optional precision, used to filter small nonzero values. The default is 1e6.
Returns: A dictionary from variable keys to solution values (floats).

get_value_list
(dvars)[source]¶ Gets the value of a sequence of variables in a solution. If a variable is not mentioned in the solution, the method assumes a 0 value.
Parameters: dvars – an ordered sequence of decision variables. Returns: A list of float values, in the same order as the variable sequence. Return type: list

has_objective
()[source]¶ Checks whether or not the objective has been set.
Returns: True if the solution defines an objective value. Return type: Boolean

is_empty
()[source]¶ Checks whether the solution is empty.
Returns: True if the solution is empty; in other words, the solution has no defined objective and no variable value. Return type: Boolean

is_feasible_solution
(tolerance=1e06, silent=True)¶ Returns True if the solution is feasible.
This method checks that solution values for variables are compatible for their types and bounds. It also checks that all constraints are satisfied, within the tolerance.
Parameters:  tolerance – a float number used to check satisfaction; default is 1e6.
 silent – optional flag. If False, prints which variable (or constraint) causes the solution to be invalid. default is True.
Returns: True if the solution is valid, within the tolerance value.
New in version 2.13

is_valid_solution
(tolerance=1e06, silent=True)[source]¶ Returns True if the solution is feasible.
This method checks that solution values for variables are compatible for their types and bounds. It also checks that all constraints are satisfied, within the tolerance.
Parameters:  tolerance – a float number used to check satisfaction; default is 1e6.
 silent – optional flag. If False, prints which variable (or constraint) causes the solution to be invalid. default is True.
Returns: True if the solution is valid, within the tolerance value.
New in version 2.13

iter_var_values
()[source]¶ Iterates over the (variable, value) pairs in the solution.
Returns: A dictstyle iterator which returns a twocomponent tuple (variable, value) for all variables mentioned in the solution. Return type: iterator

iter_variables
()[source]¶ Iterates over all variables mentioned in the solution.
Returns: An iterator object over all variables mentioned in the solution. Return type: iterator

kpi_value_by_name
(name, match_case=False)[source]¶ Returns the solution value of a KPI from its name.
Parameters:  name (string) – The string to be matched.
 match_case (boolean) – If True, looks for a caseexact match, else ignores case. Default is False.
Returns: The value of the KPI, evaluated in the solution.
Note
This method raises an error when the string does not match any KPI in the model.
 See:
func: docplex.mp.model.kpi_by_name

model
¶ This property returns the model associated with the solution.

multi_objective_values
¶ This property is used to get the list of objective values of the solution. In case of single objective this property returns the value for the objective as a singleton list
When the objective value has not been defined, a special value NO_SOLUTION is returned. To check whether the objective has been set, use
has_objective()
.

name
¶ This property allows to get/set a name on the solution.
In some cases , it might be interesting to build different solutions for the same model, in this case, use the name property to distinguish them.

number_of_var_values
¶ This property returns the number of variable/value pairs stored in this solution.

objective_value
¶ This property is used to get the objective value of the solution. In case of multiobjective this property returns the value for the first objective
When the objective value has not been defined, a special value NO_SOLUTION is returned. To check whether the objective has been set, use
has_objective()
.

print_mst
(outs=None, **kwargs)[source]¶ Writes the solution in MST format in an output stream (default is sys.out)

set_objective_value
(obj)[source]¶ Sets the objective value (or list of values for multiobjective) of the solution.
Parameters:  obj (float or list(float)) – The value of the objective (or list of values for multiobjective) in
 solution. (the) –

size
¶ This property returns the number of variable/value pairs stored in this solution.

slack_value
(ct, error='raise')[source]¶ Return the slack value for a constraint.
Slack values are available for linear, quadratic and indicator constraints. The model must be solved successfully before calling this method.
Parameters: ct – a constraint. Returns: the float value.

solve_details
¶ This property returns the solve_details associated with the solution,if any.
Note
This property returns an instance of solve details if the solution is the result of a solve operation. If the solution has been created by API, this property returns None
See also
Returns: an instance of SolveDetails, or None.

solved_by
¶ Returns a string indicating how the solution was produced.
 If the solution was created by a program, this field returns None.
 If the solution originated from a local CPLEX solve, this method returns the string ‘cplex_local’.
 If the solution originated from a DOcplexcloud solve, this method returns ‘cplex_cloud’.
Returns: A string, or None.

update
(var_values_iterable)[source]¶ Updates the solution from a dictionary. Keys can be either strings, interpreted as variable names, or variables; values are the new values for the variable.
This method returns nothing, only performs a side effect on the solution object.
Parameters: var_values_iterable – a dictionary of keys, values.
