Coverage for picos/modeling/quicksolve.py: 100.00%

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# ------------------------------------------------------------------------------ 

18 

19"""Functions to quickly solve a problem.""" 

20 

21from . import Problem 

22from ..apidoc import api_end, api_start 

23 

24_API_START = api_start(globals()) 

25# ------------------------------- 

26 

27 

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 "-" 

33 

34 return \ 

35 """{capital} a scalar expression subject to constraints. 

36 

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. 

41 

42 :param ~picos.expressions.Expression function: 

43 The objective function to {lower}. 

44 

45 :param list(~picos.constraints.Constraint) subject_to: 

46 A collection of constraints to obey. 

47 

48 :param options: 

49 A keyword argument sequence of solver options to use. See 

50 :class:`~picos.Options`. 

51 

52 :returns: 

53 The optimum value, as computed from an applied solution. 

54 

55 :raises ~picos.SolutionFailure: 

56 See :meth:`~.problem.Problem.solve`. 

57 

58 :Example: 

59 

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) 

68 

69 

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 

76 

77 

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 

84 

85 

86minimize.__doc__ = _make_doc(minimize=True) 

87maximize.__doc__ = _make_doc(minimize=False) 

88 

89 

90def find_assignment(subject_to=[], **options): 

91 """Find a feasible variable assignment. 

92 

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>`. 

96 

97 :param list(~picos.constraints.Constraint) subject_to: 

98 A collection of constraints to obey. 

99 

100 :param options: 

101 A keyword argument sequence of solver options to use. See 

102 :class:`~picos.Options`. 

103 

104 :returns: 

105 Nothing. Check the concerned variables' :attr:`values 

106 <.valuable.Valuable.value>`. 

107 

108 :raises ~picos.SolutionFailure: 

109 See :meth:`~.problem.Problem.solve`. 

110 

111 :Example: 

112 

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() 

128 

129 

130# -------------------------------------- 

131__all__ = api_end(_API_START, globals())