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 

121 

122# -------------------------------------- 

123__all__ = api_end(_API_START, globals()) 

124 

125 

126_THIS = sys.modules[__name__] 

127_ENV_PREFIX = "PICOS_" 

128 

129 

130# Modify settings given by the environment. 

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

132 key = key.upper() 

133 

134 if not key.startswith(_ENV_PREFIX): 

135 continue 

136 

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

138 

139 if setting not in __all__: 

140 raise AttributeError( 

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

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

143 

144 try: 

145 value = literal_eval(value) 

146 except Exception as error: 

147 raise ValueError( 

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

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

150 

151 setattr(_THIS, setting, value)