Coverage for picos/settings.py : 74.19%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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# ------------------------------------------------------------------------------
19"""Contains global settings for PICOS.
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.
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"""
33import os
34import sys
35from ast import literal_eval
37from .apidoc import api_end, api_start
39_API_START = api_start(globals())
40# -------------------------------
43SOLVER_WHITELIST = []
44"""A list of names of solvers; PICOS considers all others not available."""
46SOLVER_BLACKLIST = []
47"""A list of names of solvers that PICOS considers to be not available."""
49NONFREE_SOLVERS = True
50"""Whether PICOS may perform solution search with proprietary solvers."""
52LICENSE_WARNINGS = True
53"""Let solvers ignore verbosity settings to print licensing related warnings.
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"""
60INTERNAL_OPTIONS = {"solver": "cvxopt"}
61"""Solution search options used whenever PICOS solves a problem internally.
63By default, this limits the solver used to CVXOPT for reproducibility and to
64avoid licensing issues when non-free solvers are installed.
66This setting is given as a dictionary. For keys and possible values see
67:class:`~picos.Options`.
68"""
70DEFAULT_CHARSET = "unicode"
71"""Default charset to use for :mod:`console output <picos.glyphs>`.
73Can be any of ``"ascii"``, ``"latin1"`` or ``"unicode"`` (default).
75Note that applications can change the charset at any time using the respective
76function in the :mod:`~picos.glyphs` module.
77"""
79RELATIVE_HERMITIANNESS_TOLERANCE = 1e-10
80r"""Relative tolerance used when checking whether a matrix is hermitian.
82A matrix :math:`A \in \mathbb{C}^{n \times n}` is considered numerically
83hermitian if
85.. math::
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}|
91where :math:`\varepsilon` is this tolerance.
92"""
94RELATIVE_SEMIDEFINITENESS_TOLERANCE = 1e-10
95r"""Relative tolerance used when checking if a matrix is positive semidefinite.
97A hermitian matrix :math:`A \in \mathbb{C}^{n \times n}` is considered
98numerically positive semidefinite if
100.. math::
102 \min \operatorname{eigvals}(A)
103 \geq
104 -\varepsilon \max \left( \{ 1 \} \cup \operatorname{eigvals}(A) \right)
106where :math:`\varepsilon` is this tolerance.
107"""
109ABSOLUTE_INTEGRALITY_TOLERANCE = 1e-4
110"""Absolute tolerance used to validate integrality of integral variables."""
112WARN_MISSING_DOCSTRINGS = False
113"""Whether to warn about missing docstrings for top level objects in a module.
115Must be set via an environment variable to have an effect.
116"""
119# --------------------------------------
120__all__ = api_end(_API_START, globals())
123_THIS = sys.modules[__name__]
124_ENV_PREFIX = "PICOS_"
127# Modify settings given by the environment.
128for key, value in os.environ.items():
129 key = key.upper()
131 if not key.startswith(_ENV_PREFIX):
132 continue
134 setting = key.split(_ENV_PREFIX, 1)[1]
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))
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
148 setattr(_THIS, setting, value)