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 

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

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

62 

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

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

65 

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

67:class:`~picos.Options`. 

68""" 

69 

70DEFAULT_CHARSET = "unicode" 

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

72 

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

74 

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

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

77""" 

78 

79RELATIVE_HERMITIANNESS_TOLERANCE = 1e-10 

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

81 

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

83hermitian if 

84 

85.. math:: 

86 

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

88 \leq 

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

90 

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

92""" 

93 

94RELATIVE_SEMIDEFINITENESS_TOLERANCE = 1e-10 

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

96 

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

98numerically positive semidefinite if 

99 

100.. math:: 

101 

102 \min \operatorname{eigvals}(A) 

103 \geq 

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

105 

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

107""" 

108 

109ABSOLUTE_INTEGRALITY_TOLERANCE = 1e-4 

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

111 

112WARN_MISSING_DOCSTRINGS = False 

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

114 

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

116""" 

117 

118 

119# -------------------------------------- 

120__all__ = api_end(_API_START, globals()) 

121 

122 

123_THIS = sys.modules[__name__] 

124_ENV_PREFIX = "PICOS_" 

125 

126 

127# Modify settings given by the environment. 

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

129 key = key.upper() 

130 

131 if not key.startswith(_ENV_PREFIX): 

132 continue 

133 

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

135 

136 if setting not in __all__: 

137 raise AttributeError( 

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

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

140 

141 try: 

142 value = literal_eval(value) 

143 except Exception as error: 

144 raise ValueError( 

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

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

147 

148 setattr(_THIS, setting, value)