src/dunshire/errors.py

   1 """
   2 Errors that can occur when solving a linear game.
   3 """
   4
   5 from cvxopt import matrix
   6
   7
   8 def _pretty_format_dict(dictionary):
   9     """
  10     Return a pretty-formatted string representation of a dictionary
  11     containing CVXOPT matrices.
  12
  13     The dictionary is also sorted so that it can be tested repeatably.
  14
  15     Examples
  16     --------
  17
  18         >>> d = {'foo': 1.234, 'bar': matrix([1,2,3])}
  19         >>> print(_pretty_format_dict(d))
  20         bar:
  21           [ 1]
  22           [ 2]
  23           [ 3]
  24         foo: 1.234
  25
  26     """
  27     result = ''
  28     for (key, value) in sorted(dictionary.items()):
  29         if isinstance(value, matrix):
  30             # Display matrices on their own lines, indented.
  31             result += '{:s}:'.format(key)
  32             colvec = '\n{!s}'.format(value)
  33             result += '\n  '.join(colvec.splitlines())
  34             result += '\n'
  35         else:
  36             result += '{:s}: {!s}\n'.format(key, value)
  37
  38     return result.rstrip('\n') # Kills trailing newlines on matrices.
  39
  40
  41 class GameUnsolvableException(Exception):
  42     """
  43     An exception raised when a game cannot be solved.
  44
  45     Every linear game has a solution. If we can't solve the conic
  46     program associated with a linear game, then something is wrong with
  47     either the model or the input, and this exception should be raised.
  48
  49     Parameters
  50     ----------
  51
  52     solution_dict : dict
  53         The solution dictionary returned from the failed cone program.
  54
  55     Examples
  56     --------
  57
  58        >>> d = {'residual as dual infeasibility certificate': None,
  59        ...      'y': matrix([1,1]),
  60        ...      'dual slack': 8.779496368228267e-10,
  61        ...      'z': matrix([1,1,0,0]),
  62        ...      's': None,
  63        ...      'primal infeasibility': None,
  64        ...      'status': 'primal infeasible',
  65        ...      'dual infeasibility': None,
  66        ...      'relative gap': None,
  67        ...      'iterations': 5,
  68        ...      'primal slack': None,
  69        ...      'x': None,
  70        ...      'dual objective': 1.0,
  71        ...      'primal objective': None,
  72        ...      'gap': None,
  73        ...      'residual as primal infeasibility certificate': 3.986246886102996e-09}
  74        >>> print(GameUnsolvableException(d))
  75        Solution failed with result "primal infeasible."
  76        CVXOPT returned:
  77          dual infeasibility: None
  78          dual objective: 1.0
  79          dual slack: 8.779496368228267e-10
  80          gap: None
  81          iterations: 5
  82          primal infeasibility: None
  83          primal objective: None
  84          primal slack: None
  85          relative gap: None
  86          residual as dual infeasibility certificate: None
  87          residual as primal infeasibility certificate: 3.986246886102996e-09
  88          s: None
  89          status: primal infeasible
  90          x: None
  91          y:
  92            [ 1]
  93            [ 1]
  94          z:
  95            [ 1]
  96            [ 1]
  97            [ 0]
  98            [ 0]
  99     """
 100     def __init__(self, solution_dict):
 101         """
 102         Create a new GameUnsolvableException object.
 103         """
 104         super().__init__()
 105         self._solution_dict = solution_dict
 106
 107
 108     def __str__(self):
 109         """
 110         Return a string representation of this exception.
 111
 112         The returned representation highlights the "status" field of the
 113         CVXOPT dictionary, since that should explain what went
 114         wrong. The full CVXOPT solution dictionary is included after the
 115         status.
 116         """
 117         tpl = 'Solution failed with result "{:s}."\n' \
 118               'CVXOPT returned:\n  {!s}'
 119         cvx_lines = _pretty_format_dict(self._solution_dict).splitlines()
 120         cvx_str = '\n  '.join(cvx_lines) # Indent the whole dict by two spaces.
 121         return tpl.format(self._solution_dict['status'], cvx_str)