docplex.mp.solution module

class docplex.mp.solution.SolutionPool

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

docplex.mp.model.Model.populate()

describe_objectives()

Prints statistical information about poolobjective values.

Relies on the stats property.

export_as_sol(path=None, basename=None, **kwargs)

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)

Bases: object

The SolveSolution class holds the result of a solve.

add_var_value(var_key, value)

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.

as_df(name_key='name', value_key='value')

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)

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

clear()

Clears all solve result data.

All data related to the model are left unchanged.

contains(dvar)

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)

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

export_as_json_string(**kwargs)

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)

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:

https://www.ibm.com/support/knowledgecenter/SSSA5P_20.1.0/ilog.odms.cplex.help/CPLEX/FileFormats/topics/MST.html

See also

docplex.mp.constants.WriteLevel

export_as_sol(path=None, basename=None, **kwargs)

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)

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

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 multi-objective) as defined by the solution. Return type:float or list(float)

get_cuts()

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)

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)

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

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 multi-objective) as defined by the solution. Return type:float or list(float)

get_reduced_costs(dvars)

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)

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)

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)

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)

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)

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=1e-06)

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 non-zero values. The default is 1e-6.

Returns:

A dictionary from variable keys to solution values (floats).

get_value_list(dvars)

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

get_values(var_seq)

Same as get_value_list

has_objective()

Checks whether or not the objective has been set.

Returns:True if the solution defines an objective value. Return type:Boolean

is_empty()

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=1e-06, 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 1e-6.
• 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=1e-06, 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 1e-6.
• 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()

Iterates over the (variable, value) pairs in the solution.

Returns:A dict-style iterator which returns a two-component tuple (variable, value) for all variables mentioned in the solution. Return type:iterator

iter_variables()

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)

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 case-exact 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 multi-objective 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)

Writes the solution in MST format in an output stream (default is sys.out)

set_objective_value(obj)

Sets the objective value (or list of values for multi-objective) of the solution.

Parameters:

• obj (float or list(float)) – The value of the objective (or list of values for multi-objective) in
• solution. (the) –

size

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

slack_value(ct, error='raise')

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

docplex.mp.sdetails.SolveDetails

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)

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.