Coverage for picos/modeling/quicksolve.py: 100.00%
28 statements
« prev ^ index » next coverage.py v6.5.0, created at 2023-03-26 07:46 +0000
« prev ^ index » next coverage.py v6.5.0, created at 2023-03-26 07:46 +0000
1# ------------------------------------------------------------------------------
2# Copyright (C) 2019 Maximilian Stahlberg
3#
4# This file is part of PICOS.
5#
6# PICOS is free software: you can redistribute it and/or modify it under the
7# terms of the GNU General Public License as published by the Free Software
8# Foundation, either version 3 of the License, or (at your option) any later
9# version.
10#
11# PICOS is distributed in the hope that it will be useful, but WITHOUT ANY
12# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
13# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
14#
15# You should have received a copy of the GNU General Public License along with
16# this program. If not, see <http://www.gnu.org/licenses/>.
17# ------------------------------------------------------------------------------
19"""Functions to quickly solve a problem."""
21from . import Problem
22from ..apidoc import api_end, api_start
24_API_START = api_start(globals())
25# -------------------------------
28def _make_doc(minimize):
29 """Create the docstring for :func:`minimize` and :func:`maximize`."""
30 lower = "minimize" if minimize else "maximize"
31 capital = lower.capitalize()
32 sign = "" if minimize else "-"
34 return \
35 """{capital} a scalar expression subject to constraints.
37 Internally, this creates a :class:`~.problem.Problem`, :meth:`sets an
38 objective <.problem.Problem.set_objective>`, :meth:`adds constraints
39 <.problem.Problem.add_list_of_constraints>`, performs a :meth:`solution
40 search <.problem.Problem.solve>` and returns an optimum value found.
42 :param ~picos.expressions.Expression function:
43 The objective function to {lower}.
45 :param list(~picos.constraints.Constraint) subject_to:
46 A collection of constraints to obey.
48 :param options:
49 A keyword argument sequence of solver options to use. See
50 :class:`~picos.Options`.
52 :returns:
53 The optimum value, as computed from an applied solution.
55 :raises ~picos.SolutionFailure:
56 See :meth:`~.problem.Problem.solve`.
58 :Example:
60 >>> from picos import {lower}, RealVariable
61 >>> x = RealVariable("x")
62 >>> p = {lower}({sign}x**2, [(x - 2)**2 <= x - 2], solver="cvxopt")
63 >>> round(p, 5)
64 {sign}4.0
65 >>> round(x, 5)
66 2.0
67 """.format(capital=capital, lower=lower, sign=sign)
70def minimize(function, subject_to = [], **options): # noqa
71 P = Problem(**options)
72 P.set_objective("min", function)
73 P.add_list_of_constraints(subject_to)
74 P.solve()
75 return P.value
78def maximize(function, subject_to = [], **options): # noqa
79 P = Problem(**options)
80 P.set_objective("max", function)
81 P.add_list_of_constraints(subject_to)
82 P.solve()
83 return P.value
86minimize.__doc__ = _make_doc(minimize=True)
87maximize.__doc__ = _make_doc(minimize=False)
90def find_assignment(subject_to=[], **options):
91 """Find a feasible variable assignment.
93 Internally, this creates a :class:`~.problem.Problem`, :meth:`adds
94 constraints <.problem.Problem.add_list_of_constraints>` and performs a
95 :meth:`solution search <.problem.Problem.solve>`.
97 :param list(~picos.constraints.Constraint) subject_to:
98 A collection of constraints to obey.
100 :param options:
101 A keyword argument sequence of solver options to use. See
102 :class:`~picos.Options`.
104 :returns:
105 Nothing. Check the concerned variables' :attr:`values
106 <.valuable.Valuable.value>`.
108 :raises ~picos.SolutionFailure:
109 See :meth:`~.problem.Problem.solve`.
111 :Example:
113 >>> from picos import find_assignment, RealVariable
114 >>> x = RealVariable("x")
115 >>> values = find_assignment([x**2 + 1 <= x], solver="cvxopt")
116 ... # doctest: +ELLIPSIS
117 Traceback (most recent call last):
118 ...
119 picos.modeling.problem.SolutionFailure: Code 3: ...
120 >>> x.value
121 >>> find_assignment([x**2 + 0.25 <= x], solver="cvxopt")
122 >>> round(x.value, 5)
123 0.5
124 """
125 P = Problem(**options)
126 P.add_list_of_constraints(subject_to)
127 P.solve()
130# --------------------------------------
131__all__ = api_end(_API_START, globals())