Coverage for picos/settings.py: 82.98%

1# ------------------------------------------------------------------------------ 

2# Copyright (C) 2020 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"""Contains global settings for PICOS. 

20 

21All settings can be set via environment variables using the ``PICOS_`` prefix, 

22e.g. ``PICOS_SOLVER_WHITELIST='["cvxopt", "glpk"]' ./application.py`` would set 

23:data:`SOLVER_WHITELIST` to ``["cvxopt", "glpk"]`` for this execution of 

24``application.py`` only. :func:`Safe evaluation <ast.literal_eval>` is used to 

25convert the given value to a Python object. 

26 

27Applications that use PICOS may assign to these settings directly (silently 

28overwriting any environment variable) but libraries that depend on PICOS should 

29not do so as this would affect also applications and other libraries that use 

30both PICOS and the library making the modificaiton. 

31""" 

32 

33import os 

34import sys 

35from ast import literal_eval 

36 

37from .apidoc import api_end, api_start 

38 

39_API_START = api_start(globals()) 

40# ------------------------------- 

41 

42 

43SOLVER_WHITELIST = [] 

44"""A list of names of solvers; PICOS considers all others not available.""" 

45 

46SOLVER_BLACKLIST = [] 

47"""A list of names of solvers that PICOS considers to be not available.""" 

48 

49NONFREE_SOLVERS = True 

50"""Whether PICOS may perform solution search with proprietary solvers.""" 

51 

52LICENSE_WARNINGS = True 

53"""Let solvers ignore verbosity settings to print licensing related warnings. 

54 

55License warnings are only printed if both :data:`LICENSE_WARNINGS` and the 

56solution search option :ref:`license_warnings <option_license_warnings>` are set 

57to true, or if the verbosity setting allows solver output in general. 

58""" 

59 

60RETURN_SOLUTION = True 

61"""Whether :meth:`~.Problem.solve` returns a :class:`~.solution.Solution`.""" 

62 

63INTERNAL_OPTIONS = {"solver": "cvxopt"} 

64"""Solution search options used whenever PICOS solves a problem internally. 

65 

66By default, this limits the solver used to CVXOPT for reproducibility and to 

67avoid licensing issues when non-free solvers are installed. 

68 

69This setting is given as a dictionary. For keys and possible values see 

70:class:`~picos.Options`. 

71""" 

72 

73DEFAULT_CHARSET = "unicode" 

74"""Default charset to use for :mod:`console output <picos.glyphs>`. 

75 

76Can be any of ``"ascii"``, ``"latin1"`` or ``"unicode"`` (default). 

77 

78Note that applications can change the charset at any time using the respective 

79function in the :mod:`~picos.glyphs` module. 

80""" 

81 

82RELATIVE_HERMITIANNESS_TOLERANCE = 1e-10 

83r"""Relative tolerance used when checking whether a matrix is hermitian. 

84 

85A matrix :math:`A \in \mathbb{C}^{n \times n}` is considered numerically 

86hermitian if 

87 

88.. math:: 

89 

90 \max_{1 \leq i, j \leq n} |(A - A^H)_{ij}| 

91 \leq 

92 \varepsilon \max_{1 \leq i, j \leq n} |A_{ij}| 

93 

94where :math:`\varepsilon` is this tolerance. 

95""" 

96 

97RELATIVE_SEMIDEFINITENESS_TOLERANCE = 1e-10 

98r"""Relative tolerance used when checking if a matrix is positive semidefinite. 

99 

100A hermitian matrix :math:`A \in \mathbb{C}^{n \times n}` is considered 

101numerically positive semidefinite if 

102 

103.. math:: 

104 

105 \min \operatorname{eigvals}(A) 

106 \geq 

107 -\varepsilon \max \left( \{ 1 \} \cup \operatorname{eigvals}(A) \right) 

108 

109where :math:`\varepsilon` is this tolerance. 

110""" 

111 

112ABSOLUTE_INTEGRALITY_TOLERANCE = 1e-4 

113"""Absolute tolerance used to validate integrality of integral variables.""" 

114 

115WARN_MISSING_DOCSTRINGS = False 

116"""Whether to warn about missing docstrings for top level objects in a module. 

117 

118Must be set via an environment variable to have an effect. 

119""" 

120 

121PREFER_GUROBI_MATRIX_INTERFACE = True 

122"""Whether to prefer Gurobi's matrix interface when it is available. 

123 

124This default can be overwritten by the :ref:`gurobi_matint 

125<option_gurobi_matint>` solver option. 

126""" 

127 

128UNRELIABLE_STRATEGIES = False 

129"""Whether to pass solvers problems that they are known to struggle with. 

130 

131This allows all problem/solver combinations that are skipped by "PICOS' choice". 

132""" 

133 

134 

135# -------------------------------------- 

136__all__ = api_end(_API_START, globals()) 

137 

138 

139_THIS = sys.modules[__name__] 

140_ENV_PREFIX = "PICOS_" 

141 

142 

143# Modify settings given by the environment. 

144for key, value in os.environ.items(): 

145 key = key.upper() 

146 

147 if not key.startswith(_ENV_PREFIX): 

148 continue 

149 

150 setting = key.split(_ENV_PREFIX, 1)[1] 

151 

152 if setting not in __all__: 

153 raise AttributeError( 

154 "The setting '{}' referenced by the environment variable '{}' is " 

155 "not known to PICOS.".format(setting, key)) 

156 

157 try: 

158 value = literal_eval(value) 

159 except Exception as error: 

160 raise ValueError( 

161 "The value '{}' of the environment variable '{}' could not be " 

162 "parsed as a Python literal.".format(value, key)) from error 

163 

164 setattr(_THIS, setting, value)