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 the OPTION_OBJS tuple.

__init__(name, argType, default, description, check=lambda x: ...)[source]¶

Initialize an Option.

See OPTIONS.

static __new__(cls, *args, **kwargs)[source]¶: Create a blank Option to be filled in by copy.

copy()[source]¶: Return an independent copy of the option.

is_default()[source]¶: Whether the option has its default value.

reset()[source]¶: Reset the option to its default value.

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 shell-style 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"] = 1e-6

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 ➥ cplex_vmconfig ➥ cvxopt_kktreg ➥ cvxopt_kktsolver ➥ dualize ➥ duals ➥ gurobi_matint ➥ gurobi_params ➥ hotstart ➥ integrality_tol ➥ license_warnings ➥ lp_node_method ➥ lp_root_method ➥ markowitz_tol ➥ max_footprints ➥ max_fsb_nodes ➥ max_iterations ➥ mosek_basic_sol ➥ mosek_params ➥ mosek_server ➥ mskfsn_params ➥ osqp_params ➥ penalty_cplex ➥ penalty_cvxopt ➥ penalty_ecos ➥ penalty_glpk ➥ penalty_gurobi ➥ penalty_mosek ➥ penalty_mskfsn ➥ penalty_osqp ➥ 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	`1e-06`	Absolute optimality tolerance for branch-and-bound 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	`1e-08`	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	`1e-08`	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 1-norm, 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	`1e-08`	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 their `apply` method.
assume_conic	`True`	Determines how `ConicQuadraticConstraint` instances, which correspond to nonconvex constraints of the form $x^TQx + p^Tx + q \leq (a^Tx + b)(c^Tx + d)$ with $x^TQx + p^Tx + q$ representable as a squared norm, are processed: `True` strengthens them into convex conic constraints by assuming the additional constraints $a^Tx + b \geq 0$ and $c^Tx + d \geq 0$ . `False` takes them verbatim and also considers solutions with $(a^Tx + b) < 0$ or $(c^Tx + d) < 0$ . This requires a solver that accepts nonconvex quadratic constraints. Warning `ConicQuadraticConstraint` are also used in the case of $Q = 0$ . For instance, $x^2 \geq 1$ is effectively ransformed to $x \geq 1$ if this is `True`.
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 field `bounds_monitor` of the dictionary returned by `solve`.
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 $5$ .
cplex_upr_bnd_limit	`None`	Tells CPLEX to stop MIP optimization if an upper bound above this value is found.
cplex_vmconfig	`None`	Load a CPLEX virtual machine configuration file.
cvxopt_kktreg	`1e-09`	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	`None`	The KKT solver used by CVXOPT internally. See CVXOPT’s guide on exploiting structure. `None` denotes PICOS’ choice: Try first with the faster `"chol"`, then with the more reliable `"ldl"` 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. `True` will raise an exception if no optimal dual solution is found. `None` will accept and apply also incomplete, infeasible or suboptimal dual solutions. `False` will not ask for a dual solution and throw away any dual solution returned by the solver.
gurobi_matint	`None`	Whether to use Gurobi’s matrix interface. This requires Gurobi 9 or later and SciPy. `None` with `PREFER_GUROBI_MATRIX_INTERFACE` enabled means use it if possible. `None` with that setting disabled behaves like `False`.
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 $25$ .
hotstart	`False`	Tells the solver to start from the (partial) solution that is stored in the `variables` assigned to the problem.
integrality_tol	`1e-05`	Integrality tolerance. A number $x \in \mathbb{R}$ is considered integral if $\min_{z \in \mathbb{Z}}{\|x - z\|}$ 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 non-root 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 branch-and-bound 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_basic_sol	`False`	Return a basic solution when solving LPs with MOSEK (Optimizer).
mosek_params	`{}`	A dictionary of MOSEK (Optimizer) parameters to be set after general options are passed and before the search is started. See the list of MOSEK (Optimizer) 8.1 parameters.
mosek_server	`None`	Address of a MOSEK remote optimization server to use. This option affects both MOSEK (Optimizer) and MOSEK (Fusion).
mskfsn_params	`{}`	A dictionary of MOSEK (Fusion) parameters to be set after general options are passed and before the search is started. See the list of MOSEK (Fusion) 8.1 parameters.
osqp_params	`{}`	A dictionary of OSQP parameters to be set after general options are passed and before the search is started. See the list of OSQP parameters.
penalty_cplex	`0.0`	Penalty for using the CPLEX solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
penalty_cvxopt	`1.0`	Penalty for using the CVXOPT solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
penalty_ecos	`1.0`	Penalty for using the ECOS solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
penalty_glpk	`1.0`	Penalty for using the GLPK solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
penalty_gurobi	`0.0`	Penalty for using the GUROBI solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
penalty_mosek	`0.0`	Penalty for using the MOSEK solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
penalty_mskfsn	`0.5`	Penalty for using the MSKFSN solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
penalty_osqp	`2.0`	Penalty for using the OSQP solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
penalty_scip	`1.0`	Penalty for using the SCIP solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
penalty_smcp	`2.0`	Penalty for using the SMCP solver. If solver $A$ has a penalty of $p$ and solver $B$ has a larger penality of $p + x$ , then $B$ is be chosen over $A$ only if the problem as passed to $A$ would be $10^x$ times larger as when passed to $B$ .
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 of `Solution` objects instead of just a single one. `None` lets the solver return only the best solution.
primals	`True`	Whether to request a primal solution. `True` will raise an exception if no optimal primal solution is found. `None` will accept and apply also incomplete, infeasible or suboptimal primal solutions. `False` will not ask for a primal solution and throw away any primal solution returned by the solver.
rel_bnb_opt_tol	`0.0001`	Relative optimality tolerance for branch-and-bound 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	`1e-08`	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	`1e-08`	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	`1e-08`	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 $1$ . `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 $4$ .
solver	`None`	The solver to use. See also the global settings `SOLVER_BLACKLIST`, `SOLVER_WHITELIST` and `NONFREE_SOLVERS`. `None` to let PICOS choose. `"cplex"` for `CPLEXSolver`. `"cvxopt"` for `CVXOPTSolver`. `"ecos"` for `ECOSSolver`. `"glpk"` for `GLPKSolver`. `"gurobi"` for `GurobiSolver`. `"mosek"` for `MOSEKSolver`. `"mskfsn"` for `MOSEKFusionSolver`. `"osqp"` for `OSQPSolver`. `"scip"` for `SCIPSolver`. `"smcp"` for `SMCPSolver`. 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 branch-and-bound 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.

__eq__(other)[source]¶: Report whether two sets of options are equal.

__init__(**options)[source]¶: Create a default option set and set the given options on top.

static __new__(cls, *args, **kwargs)[source]¶: Create an empty options set.

copy()[source]¶: Return an independent copy of the current options set.

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.

updated(**options)[source]¶: Return a modified copy.

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 multi-line 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 returns False, then the argument is rejected. The default function rejects exactly None. Supplying None instead of a function accepts all arguments (in particular, accepts None).

Default value

[('abs_bnb_opt_tol',
  <class 'float'>,
  1e-06,
  '\n'
  '        Absolute optimality tolerance for branch-and-bound 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 0x7efe6bf1af80>,
 <picos.modeling.options.Option object at 0x7efe6bf1b220>,
 <picos.modeling.options.Option object at 0x7efe6bf1b250>,
 <picos.modeling.options.Option object at 0x7efe6bf1b280>,
...

Fork me on GitLab