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 multi-objective) as defined by the solution. Return type: float or list(float)
-
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 multi-objective) as defined by the solution. Return type: float or list(float)
-
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=1e-06)[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 non-zero values. The default is 1e-6.
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=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)[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 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
()[source]¶ 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
()[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 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)[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 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.
-
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.
-