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.

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 0x7f4ee14597b0>,
 <picos.modeling.options.Option object at 0x7f4ee1459a50>,
 <picos.modeling.options.Option object at 0x7f4ee1459a80>,
 <picos.modeling.options.Option object at 0x7f4ee1459ab0>,
...