picos.solvers.solver

Backend for solver interface implementations.

Outline

Classes

Solver

Base class for an interface to an optimization solver.

Exceptions

ConflictingOptionsError	Two solver options are in conflict.
DependentOptionError	A solver option is invalid due to another option not being set.
OptionError	Base class for solver option related errors.
OptionValueError	A solver option has an invalid value.
ProblemUpdateError	Changes to the problem could not be forward to the solver.
SolverError	Base class for solver-specific exceptions.
UnsupportedOptionError	The solver does not support an option.

Classes

Solver

class picos.solvers.solver.Solver(problem)

Bases: abc.ABC

Base class for an interface to an optimization solver.

__init__(problem)

Instanciate a solver interface with an optimization problem.

An exception is raised when the solver is not available on the user’s platform. No exception is raised when the problem type is not supported as the problem is first imported when a solution is requested.

Solver implementations are supposed to also implement __init__, but with problem as its only positional argument, and using super to provide fixed values for this method’s additional parameters.

Parameters

problem (Problem) – A PICOS optimization problem.

classmethod available(verbose=False)

Whether the solver is properly installed on the system.

abstract classmethod default_penalty()

Report the default penalty for the solver.

See Options for the scale.

execute()

Solve the problem and return the solution.

Returns picos.Solution or list(picos.Solution)

A solution object or list thereof.

external_problem()

Return the external (PICOS) problem represenation.

internal_problem()

Return the solver’s internal problem represenation.

abstract classmethod is_free()

Report whether the solver is free software.

This allows users to prevent PICOS from using non-free solvers at all, including for internal use, via the NONFREE_SOLVERS setting.

abstract classmethod names()

Returns a triple (name, display_name, long_display_name).

classmethod penalty(options)

Report solver penalty given an Options object.

classmethod predict(footprint)

Return the solver class.

This mimics the behavior of Reformulation.predict so that solvers can be the last pipeline node in a reformulation strategy.

reset()

A shorthand for reset_problem.

This is defined for consistency with Reformulation.reset.

abstract reset_problem()

Reset the solver’s internal problem representation and related data.

Method implementations are supposed to

• set int to None (after performing any garbage collection), and

• reset all additional problem metadata to the state it had after __init__, in particular the data stored for _update_problem.

Solver implementations should not call reset_problem directly, except from within __init__ if this is convenient.

The user may call this method at any time if they wish to solve the problem from scratch.

abstract classmethod supports(footprint)

Whether a type of problem, given by footprint, is supported.

The default implementation ensures that all reformulations required by user’s choice have been performed before the problem is handed to the solver. Solver implementations are thus required to incorporate it.

abstract classmethod test_availability()

Raise an exception if the solver is not installed on the system.

Checks whether the solver is installed on the system, and raises an appropriate exception (usually ModuleNotFoundError or ImportError) if not. Does not return anything.

verbosity()

Return the problem’s current verbosity level.

property display_name

Short display name of the solver.

property ext

The “external” (input) problem.

property long_display_name

Long display name of the solver.

property name

Keyword string of the solver.

Exceptions

ConflictingOptionsError

exception picos.solvers.solver.ConflictingOptionsError

Bases: picos.solvers.solver.OptionError

Two solver options are in conflict.

Raised by implementations of _solve to signal to the user that two options they specified cannot be used in conjunction.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)

Create and return a new object. See help(type) for accurate signature.

DependentOptionError

exception picos.solvers.solver.DependentOptionError

Bases: picos.solvers.solver.OptionError

A solver option is invalid due to another option not being set.

Raised by implementations of _solve to signal to the user that an option they specified needs another option to also be set.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)

Create and return a new object. See help(type) for accurate signature.

OptionError

exception picos.solvers.solver.OptionError

Bases: picos.solvers.solver.SolverError

Base class for solver option related errors.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)

Create and return a new object. See help(type) for accurate signature.

OptionValueError

exception picos.solvers.solver.OptionValueError

Bases: picos.solvers.solver.OptionError, ValueError

A solver option has an invalid value.

Raised by implementations of _solve to signal to the user that they have set an option to an invalid value.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)

Create and return a new object. See help(type) for accurate signature.

ProblemUpdateError

exception picos.solvers.solver.ProblemUpdateError

Bases: picos.solvers.solver.SolverError

Changes to the problem could not be forward to the solver.

Raised by implementations of _update_problem to signal to the method _load_problem that the problem needs to be re-imported.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)

Create and return a new object. See help(type) for accurate signature.

SolverError

exception picos.solvers.solver.SolverError

Bases: Exception

Base class for solver-specific exceptions.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)

Create and return a new object. See help(type) for accurate signature.

UnsupportedOptionError

exception picos.solvers.solver.UnsupportedOptionError

Bases: picos.solvers.solver.OptionError

The solver does not support an option.

Raised by implementations of _solve to signal to the user that an option they specified is not supported by the solver or the requested sub-solver, or in conjunction with the given problem type or with another option. If the option is valid but not supported by PICOS, then NotImplementedError should be raised instead. The exception is only raised if the strictOptions option is set, otherwise a warning is printed.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__new__(**kwargs)

Create and return a new object. See help(type) for accurate signature.