Coverage for picos/settings.py: 82.98%
47 statements
« prev ^ index » next coverage.py v6.5.0, created at 2023-02-15 14:21 +0000
« prev ^ index » next coverage.py v6.5.0, created at 2023-02-15 14:21 +0000
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"""
60RETURN_SOLUTION = True
61"""Whether :meth:`~.Problem.solve` returns a :class:`~.solution.Solution`."""
63INTERNAL_OPTIONS = {"solver": "cvxopt"}
64"""Solution search options used whenever PICOS solves a problem internally.
66By default, this limits the solver used to CVXOPT for reproducibility and to
67avoid licensing issues when non-free solvers are installed.
69This setting is given as a dictionary. For keys and possible values see
70:class:`~picos.Options`.
71"""
73DEFAULT_CHARSET = "unicode"
74"""Default charset to use for :mod:`console output <picos.glyphs>`.
76Can be any of ``"ascii"``, ``"latin1"`` or ``"unicode"`` (default).
78Note that applications can change the charset at any time using the respective
79function in the :mod:`~picos.glyphs` module.
80"""
82RELATIVE_HERMITIANNESS_TOLERANCE = 1e-10
83r"""Relative tolerance used when checking whether a matrix is hermitian.
85A matrix :math:`A \in \mathbb{C}^{n \times n}` is considered numerically
86hermitian if
88.. math::
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}|
94where :math:`\varepsilon` is this tolerance.
95"""
97RELATIVE_SEMIDEFINITENESS_TOLERANCE = 1e-10
98r"""Relative tolerance used when checking if a matrix is positive semidefinite.
100A hermitian matrix :math:`A \in \mathbb{C}^{n \times n}` is considered
101numerically positive semidefinite if
103.. math::
105 \min \operatorname{eigvals}(A)
106 \geq
107 -\varepsilon \max \left( \{ 1 \} \cup \operatorname{eigvals}(A) \right)
109where :math:`\varepsilon` is this tolerance.
110"""
112ABSOLUTE_INTEGRALITY_TOLERANCE = 1e-4
113"""Absolute tolerance used to validate integrality of integral variables."""
115WARN_MISSING_DOCSTRINGS = False
116"""Whether to warn about missing docstrings for top level objects in a module.
118Must be set via an environment variable to have an effect.
119"""
121PREFER_GUROBI_MATRIX_INTERFACE = True
122"""Whether to prefer Gurobi's matrix interface when it is available.
124This default can be overwritten by the :ref:`gurobi_matint
125<option_gurobi_matint>` solver option.
126"""
128UNRELIABLE_STRATEGIES = False
129"""Whether to pass solvers problems that they are known to struggle with.
131This allows all problem/solver combinations that are skipped by "PICOS' choice".
132"""
135# --------------------------------------
136__all__ = api_end(_API_START, globals())
139_THIS = sys.modules[__name__]
140_ENV_PREFIX = "PICOS_"
143# Modify settings given by the environment.
144for key, value in os.environ.items():
145 key = key.upper()
147 if not key.startswith(_ENV_PREFIX):
148 continue
150 setting = key.split(_ENV_PREFIX, 1)[1]
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))
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
164 setattr(_THIS, setting, value)