picos.modeling.options¶
Optimization solver parameter handling.
Classes

class
picos.modeling.options.
Option
(*args, **kwargs)[source]¶ Bases:
object
Optimization solver option.
A single option that affects how a
Problem
is solved.An initial instance of this class is built from each entry of the
OPTIONS
table to obtain theOPTION_OBJS
tuple.
__init__
(name, argType, default, description, check=<function Option.<lambda>>)[source]¶ Initialize an
Option
.See
OPTIONS
.

property
value
¶


class
picos.modeling.options.
Options
(*args, **kwargs)[source]¶ Bases:
object
Collection of optimization solver options.
A collection of options that affect how a
Problem
is solved.Problem.options
is an instance of this class.The options can be accessed as an attribute or as an item. The latter approach supports Unix shellstyle wildcard characters:
>>> import picos >>> P = picos.Problem() >>> P.options.verbosity = 2 >>> P.options["primals"] = False >>> # Set all absolute tolerances at once. >>> P.options["abs_*_tol"] = 1e6
There are two corresponding ways to reset an option to its default value:
>>> del P.options.verbosity >>> P.options.reset("primals", "*_tol")
Options can also be passed as a keyword argument sequence when the
Problem
is created and whenever a solution is searched:>>> # Use default options except for verbosity. >>> P = picos.Problem(verbosity = 1) >>> x = P.add_variable("x", lower = 0); P.set_objective("min", x) >>> # Only for the next search: Don't be verbose anyway. >>> solution = P.solve(solver = "cvxopt", verbosity = 0)
Available Options
Jump to option: ➥ abs_bnb_opt_tol ➥ abs_dual_fsb_tol ➥ abs_ipm_opt_tol ➥ abs_prim_fsb_tol ➥ ad_hoc_solver ➥ apply_solution ➥ assume_conic ➥ cplex_bnd_monitor ➥ cplex_lwr_bnd_limit ➥ cplex_params ➥ cplex_upr_bnd_limit ➥ cvxopt_kktreg ➥ cvxopt_kktsolver ➥ dualize ➥ duals ➥ gurobi_params ➥ hotstart ➥ integrality_tol ➥ license_warnings ➥ lp_node_method ➥ lp_root_method ➥ markowitz_tol ➥ max_footprints ➥ max_fsb_nodes ➥ max_iterations ➥ mosek_params ➥ mskfsn_params ➥ penalty_cplex ➥ penalty_cvxopt ➥ penalty_ecos ➥ penalty_glpk ➥ penalty_gurobi ➥ penalty_mosek ➥ penalty_mskfsn ➥ penalty_scip ➥ penalty_smcp ➥ pool_abs_gap ➥ pool_rel_gap ➥ pool_size ➥ primals ➥ rel_bnb_opt_tol ➥ rel_dual_fsb_tol ➥ rel_ipm_opt_tol ➥ rel_prim_fsb_tol ➥ scip_params ➥ solver ➥ strict_options ➥ timelimit ➥ treememory ➥ verbosity ➥ verify_prediction
Option
Default
Description
abs_bnb_opt_tol
1e06
Absolute optimality tolerance for branchandbound solution strategies to mixed integer problems.
A solution is optimal if the absolute difference between the objective function value of the current best integer solution and the current best bound obtained from a continuous relaxation is smaller than this value.
None
lets the solver use its own default value.abs_dual_fsb_tol
1e08
Absolute dual problem feasibility tolerance.
A dual solution is feasible if some norm over the vector of dual constraint violations is smaller than this value.
Serves as an optimality criterion for the Simplex algorithm.
None
lets the solver use its own default value.abs_ipm_opt_tol
1e08
Absolute optimality tolerance for interior point methods.
Depending on the solver, a fesible primal/dual solution pair is considered optimal if this value upper bounds either
the absolute difference between the primal and dual objective values, or
the violation of the complementary slackness condition.
The violation is computed as some norm over the vector that contains the products of each constraint’s slack with its corresponding dual value. If the norm is the 1norm, then the two conditions are equal. Otherwise they can differ by a factor that depends on the number and type of constraints.
None
lets the solver use its own default value.abs_prim_fsb_tol
1e08
Absolute primal problem feasibility tolerance.
A primal solution is feasible if some norm over the vector of primal constraint violations is smaller than this value.
None
lets the solver use its own default value.ad_hoc_solver
None
The solver to use as a
Solver
subclass.This allows solver implementations to be shipped independent of PICOS.
If set, takes precedence over solver.
apply_solution
True
Whether to immediately apply the solution returned by a solver to the problem’s variables and constraints.
If multiple solutions are returned by the solver, then the first one will be applied. If this is
False
, then solutions can be applied manually via theirapply
method.assume_conic
True
Determines how
ConicQuadraticConstraint
instances, which correspond to nonconvex constraints of the form with representable as a squared norm, are processed:True
strengthens them into convex conic constraints by assuming the additional constraints and .False
takes them verbatim and also considers solutions with or . This requires a solver that accepts nonconvex quadratic constraints.
Warning
ConicQuadraticConstraint
are also used in the case of . For instance, is effectively ransformed to if this isTrue
.cplex_bnd_monitor
False
Tells CPLEX to store information about the evolution of the bounds during the MIP solution search process. At the end of the computation, a list of triples
(time, lowerbound, upperbound)
will be provided in the fieldbounds_monitor
of the dictionary returned bysolve
.cplex_lwr_bnd_limit
None
Tells CPLEX to stop MIP optimization if a lower bound below this value is found.
cplex_params
{}
A dictionary of CPLEX parameters to be set after general options are passed and before the search is started.
For example,
{"mip.limits.cutpasses": 5}
limits the number of cutting plane passes when solving the root node to .cplex_upr_bnd_limit
None
Tells CPLEX to stop MIP optimization if an upper bound above this value is found.
cvxopt_kktreg
1e09
The KKT solver regularization term used by CVXOPT internally.
This is an undocumented feature of CVXOPT, see here.
End of 2020, this option only affected the LDL KKT solver.
None
denotes CVXOPT’s default value.cvxopt_kktsolver
'ldl'
The KKT solver used by CVXOPT internally.
See CVXOPT’s guide on exploiting structure.
None
denotes CVXOPT’s default KKT solver.dualize
False
Whether to dualize the problem as part of the solution strategy.
This can sometimes lead to a significant solution search speedup.
duals
None
Whether to request a dual solution.
gurobi_params
{}
A dictionary of Gurobi parameters to be set after general options are passed and before the search is started.
For example,
{"NodeLimit": 25}
limits the number of nodes visited by the MIP optimizer to .hotstart
False
Tells the solver to start from the (partial) solution that is stored in the
variables
assigned to the problem.integrality_tol
1e05
Integrality tolerance.
A number is considered integral if is at most this value.
None
lets the solver use its own default value.license_warnings
True
Whether solvers are allowed to ignore the verbosity option to print licensing related warnings.
See also the global setting
LICENSE_WARNINGS
.lp_node_method
None
Algorithm used to solve continuous linear problems at nonroot nodes of the branching tree built when solving mixed integer programs.
None
lets PICOS or the solver select it for you."psimplex"
for Primal Simplex."dsimplex"
for Dual Simplex."interior"
for the interior point method.
lp_root_method
None
Algorithm used to solve continuous linear problems, including the root relaxation of mixed integer problems.
None
lets PICOS or the solver select it for you."psimplex"
for Primal Simplex."dsimplex"
for Dual Simplex."interior"
for the interior point method.
markowitz_tol
None
Markowitz threshold used in the Simplex algorithm.
None
lets the solver use its own default value.max_footprints
1024
Maximum number of different predicted problem formulations (footprints) to consider before deciding on a formulation and solver to use.
None
lets PICOS exhaust all reachable problem formulations.max_fsb_nodes
None
Maximum number of feasible solution nodes visited for branchandbound solution strategies.
None
means no limit.Note
If you want to obtain all feasible solutions that the solver encountered, use the pool_size option.
max_iterations
None
Maximum number of iterations allowed for iterative solution strategies.
None
means no limit.mosek_params
{}
A dictionary of MOSEK (Optimizer) parameters to be set after general options are passed and before the search is started.
mskfsn_params
{}
A dictionary of MOSEK (Fusion) parameters to be set after general options are passed and before the search is started.
penalty_cplex
0.0
Penalty for using the CPLEX solver.
If solver has a penalty of and solver has a larger penality of , then is be chosen over only if the problem as passed to would be times larger as when passed to .
penalty_cvxopt
1.0
Penalty for using the CVXOPT solver.
If solver has a penalty of and solver has a larger penality of , then is be chosen over only if the problem as passed to would be times larger as when passed to .
penalty_ecos
1.0
Penalty for using the ECOS solver.
If solver has a penalty of and solver has a larger penality of , then is be chosen over only if the problem as passed to would be times larger as when passed to .
penalty_glpk
1.0
Penalty for using the GLPK solver.
If solver has a penalty of and solver has a larger penality of , then is be chosen over only if the problem as passed to would be times larger as when passed to .
penalty_gurobi
0.0
Penalty for using the GUROBI solver.
If solver has a penalty of and solver has a larger penality of , then is be chosen over only if the problem as passed to would be times larger as when passed to .
penalty_mosek
0.0
Penalty for using the MOSEK solver.
If solver has a penalty of and solver has a larger penality of , then is be chosen over only if the problem as passed to would be times larger as when passed to .
penalty_mskfsn
0.5
Penalty for using the MSKFSN solver.
If solver has a penalty of and solver has a larger penality of , then is be chosen over only if the problem as passed to would be times larger as when passed to .
penalty_scip
1.0
Penalty for using the SCIP solver.
If solver has a penalty of and solver has a larger penality of , then is be chosen over only if the problem as passed to would be times larger as when passed to .
penalty_smcp
2.0
Penalty for using the SMCP solver.
If solver has a penalty of and solver has a larger penality of , then is be chosen over only if the problem as passed to would be times larger as when passed to .
pool_abs_gap
None
Discards solutions from the solution pool as soon as a better solution is found that beats it by the given absolute objective function gap.
None
is the solver’s choice, which may be never discard.pool_rel_gap
None
Discards solutions from the solution pool as soon as a better solution is found that beats it by the given relative objective function gap.
None
is the solver’s choice, which may be never discard.pool_size
None
Maximum number of mixed integer feasible solutions returned.
If this is not
None
,solve
returns a list ofSolution
objects instead of just a single one.None
lets the solver return only the best solution.primals
True
Whether to request a primal solution.
rel_bnb_opt_tol
0.0001
Relative optimality tolerance for branchandbound solution strategies to mixed integer problems.
Like abs_bnb_opt_tol, but the difference is divided by a convex combination of the absolute values of the two objective function values.
None
lets the solver use its own default value.rel_dual_fsb_tol
1e08
Relative dual problem feasibility tolerance.
Like abs_dual_fsb_tol, but the norm is divided by the norm of the constraints’ right hand side vector. (See rel_prim_fsb_tol for exceptions.)
Serves as an optimality criterion for the Simplex algorithm.
None
lets the solver use its own default value.rel_ipm_opt_tol
1e08
Relative optimality tolerance for interior point methods.
Like abs_ipm_opt_tol, but the suboptimality measure is divided by a convex combination of the absolute primal and dual objective function values.
None
lets the solver use its own default value.rel_prim_fsb_tol
1e08
Relative primal problem feasibility tolerance.
Like abs_prim_fsb_tol, but the norm is divided by the norm of the constraints’ right hand side vector.
If the norm used is some nested norm (e.g. the maximum over the norms of the equality and inequality violations), then solvers might divide the inner violation norms by the respective right hand side inner norms (see e.g. CVXOPT).
To prevent that the right hand side vector norm is zero (or small), solvers would either add some small constant or use a fixed lower bound, which may be as large as .
None
lets the solver use its own default value.scip_params
{}
A dictionary of SCIP parameters to be set after general options are passed and before the search is started.
For example,
{"lp/threads": 4}
sets the number of threads to solve LPs with to .solver
None
The solver to use.
See also the global settings
SOLVER_BLACKLIST
,SOLVER_WHITELIST
andNONFREE_SOLVERS
.None
to let PICOS choose."cplex"
forCPLEXSolver
."cvxopt"
forCVXOPTSolver
."ecos"
forECOSSolver
."glpk"
forGLPKSolver
."gurobi"
forGurobiSolver
."mosek"
forMOSEKSolver
."mskfsn"
forMOSEKFusionSolver
."scip"
forSCIPSolver
."smcp"
forSMCPSolver
.
This option is ignored when ad_hoc_solver is set.
Note
picos.available_solvers()
returns a list of names of solvers that are available at runtime.strict_options
False
Whether unsupported general options will raise an
UnsupportedOptionError
exception, instead of printing a warning.timelimit
None
Maximum number of seconds spent searching for a solution.
None
means no limit.treememory
None
Bound on the memory used by the branchandbound tree, in Megabytes.
None
means no limit.verbosity
0
Verbosity level.
1
attempts to suppress all output, even errros.0
only generates warnings and errors.1
generates standard informative output.2
or larger prints additional information for debugging purposes.
verify_prediction
True
Whether PICOS should validate that problem reformulations produce a problem that matches their predicted outcome.
If a mismatch is detected, a
RuntimeError
is thrown as there is a chance that it is caused by a bug in the reformulation, which could affect the correctness of the solution. By disabling this option you are able to retrieve a correct solution given that the error is only in the prediction, and given that the solution strategy remains valid for the actual outcome.
help
(*options)[source]¶ Print text describing selected options.
 Parameters
options – The names of the options to describe, may contain wildcard characters.

reset
(*options)[source]¶ Reset all or a selection of options to their default values.
 Parameters
options – The names of the options to reset, may contain wildcard characters. If no name is given, all options are reset.

self_or_updated
(**options)[source]¶ Return either a modified copy or self, depending on given options.

update
(**options)[source]¶ Set multiple options at once.
This method is called with the keyword arguments supplied to the
Options
constructor, so the following two are the same:>>> import picos >>> a = picos.Options(verbosity = 1, primals = False) >>> b = picos.Options() >>> b.update(verbosity = 1, primals = False) >>> a == b True
 Parameters
options – A parameter sequence of options to set.

property
nondefaults
¶ A dictionary mapping option names to nondefault values.
 Example
>>> from picos import Options >>> o = Options() >>> o.verbosity = 2 >>> o.nondefaults {'verbosity': 2} >>> Options(**o.nondefaults) == o True
Objects

picos.modeling.options.
OPTIONS
¶ The table of available solver options.
Each entry is a tuple representing a single solver option. The tuple’s entries are, in order:
Name of the option. Must be a valid Python attribute name.
The option’s argument type. Will be cast on any argument that is not already an instance of the type, except for
None
.The option’s default value. Must already be of the proper type, or
None
, and must pass the optional check.The option’s description, which is used as part of the docstring of
Options
. In the case of a multiline text, leading and trailing empty lines as well as the overall indentation are ignored.Optional: A boolean function used on every argument that passes the type conversion (so either an argument of the proper type, or
None
). If the function returnsFalse
, then the argument is rejected. The default function rejects exactlyNone
. SupplyingNone
instead of a function accepts all arguments (in particular, acceptsNone
).
 Default value
[('abs_bnb_opt_tol', <class 'float'>, 1e06, '\n' ' Absolute optimality tolerance for branchandbound solution ' 'strategies\n' ' to mixed integer problems.\n' '\n' ' A solution is optimal if the absolute...

picos.modeling.options.
OPTION_OBJS
¶ The initial solver options as
Option
objects. Default value
(<picos.modeling.options.Option object at 0x7fbe57004220>, <picos.modeling.options.Option object at 0x7fbe57004850>, <picos.modeling.options.Option object at 0x7fbe570048b0>, <picos.modeling.options.Option object at 0x7fbe57004880>, ...