X-Git-Url: http://gitweb.michael.orlitzky.com/?a=blobdiff_plain;f=dunshire%2Fgames.py;h=951c7f4bc16088e4b82cc91cb90eb41c9e90db5f;hb=37d44f04834d61eb3c089b52e4ca7cdd75253520;hp=07a70b0a2b651a40c207d5d3bcdfd807d55f92df;hpb=0b6e486f52b6c42f78ba408543be0cc4b66fada7;p=dunshire.git

diff --git a/dunshire/games.py b/dunshire/games.py
index 07a70b0..951c7f4 100644
--- a/dunshire/games.py
+++ b/dunshire/games.py
@@ -220,8 +220,7 @@ class SymmetricLinearGame:
                [ 1],
           e2 = [ 1]
                [ 2]
-               [ 3],
-          Condition((L, K, e1, e2)) = 31.834...
+               [ 3]
 
     Lists can (and probably should) be used for every argument::
 
@@ -239,8 +238,7 @@ class SymmetricLinearGame:
           e1 = [ 1]
                [ 1],
           e2 = [ 1]
-               [ 1],
-          Condition((L, K, e1, e2)) = 1.707...
+               [ 1]
 
     The points ``e1`` and ``e2`` can also be passed as some other
     enumerable type (of the correct length) without much harm, since
@@ -262,8 +260,7 @@ class SymmetricLinearGame:
           e1 = [ 1]
                [ 1],
           e2 = [ 1]
-               [ 1],
-          Condition((L, K, e1, e2)) = 1.707...
+               [ 1]
 
     However, ``L`` will always be intepreted as a list of rows, even
     if it is passed as a :class:`cvxopt.base.matrix` which is
@@ -284,8 +281,7 @@ class SymmetricLinearGame:
           e1 = [ 1]
                [ 1],
           e2 = [ 1]
-               [ 1],
-          Condition((L, K, e1, e2)) = 6.073...
+               [ 1]
         >>> L = cvxopt.matrix(L)
         >>> print(L)
         [ 1  3]
@@ -300,8 +296,7 @@ class SymmetricLinearGame:
           e1 = [ 1]
                [ 1],
           e2 = [ 1]
-               [ 1],
-          Condition((L, K, e1, e2)) = 6.073...
+               [ 1]
 
     """
     def __init__(self, L, K, e1, e2):
@@ -335,8 +330,7 @@ class SymmetricLinearGame:
               '  L = {:s},\n' \
               '  K = {!s},\n' \
               '  e1 = {:s},\n' \
-              '  e2 = {:s},\n' \
-              '  Condition((L, K, e1, e2)) = {:f}.'
+              '  e2 = {:s}'
         indented_L = '\n      '.join(str(self.L()).splitlines())
         indented_e1 = '\n       '.join(str(self.e1()).splitlines())
         indented_e2 = '\n       '.join(str(self.e2()).splitlines())
@@ -344,8 +338,7 @@ class SymmetricLinearGame:
         return tpl.format(indented_L,
                           str(self.K()),
                           indented_e1,
-                          indented_e2,
-                          self.condition())
+                          indented_e2)
 
 
     def L(self):
@@ -731,7 +724,7 @@ class SymmetricLinearGame:
         return CartesianProduct(self._K, self._K)
 
     def _h(self):
-        """
+        r"""
         Return the ``h`` vector used in our CVXOPT construction.
 
         The ``h`` vector appears on the right-hand side of :math:`Gx + s
@@ -773,7 +766,7 @@ class SymmetricLinearGame:
 
     @staticmethod
     def b():
-        """
+        r"""
         Return the ``b`` vector used in our CVXOPT construction.
 
         The vector ``b`` appears on the right-hand side of :math:`Ax =
@@ -848,19 +841,82 @@ class SymmetricLinearGame:
 
     def _L_specnorm(self):
         """
-        Compute the spectral norm of ``L`` and cache it.
+        Compute the spectral norm of :meth:`L` and cache it.
+
+        The spectral norm of the matrix :meth:`L` is used in a few
+        places. Since it can be expensive to compute, we want to cache
+        its value. That is not possible in :func:`specnorm`, which lies
+        outside of a class, so this is the place to do it.
+
+        Returns
+        -------
+
+        float
+            A nonnegative real number; the largest singular value of
+            the matrix :meth:`L`.
+
         """
         if self._L_specnorm_value is None:
             self._L_specnorm_value = specnorm(self.L())
         return self._L_specnorm_value
 
+
     def tolerance_scale(self, solution):
-        # Don't return anything smaller than 1... we can't go below
-        # out "minimum tolerance."
+        r"""
+        Return a scaling factor that should be applied to ``ABS_TOL``
+        for this game.
+
+        When performing certain comparisons, the default tolernace
+        ``ABS_TOL`` may not be appropriate. For example, if we expect
+        ``x`` and ``y`` to be within ``ABS_TOL`` of each other, than the
+        inner product of ``L*x`` and ``y`` can be as far apart as the
+        spectral norm of ``L`` times the sum of the norms of ``x`` and
+        ``y``. Such a comparison is made in :meth:`solution`, and in
+        many of our unit tests.
+
+        The returned scaling factor found from the inner product mentioned
+        above is
+
+        .. math::
+
+            \left\lVert L \right\rVert_{2}
+            \left( \left\lVert \bar{x} \right\rVert
+                   + \left\lVert \bar{y} \right\rVert
+            \right),
+
+        where :math:`\bar{x}` and :math:`\bar{y}` are optimal solutions
+        for players one and two respectively. This scaling factor is not
+        formally justified, but attempting anything smaller leads to
+        test failures.
+
+        .. warning::
+
+            Optimal solutions are not unique, so the scaling factor
+            obtained from ``solution`` may not work when comparing other
+            solutions.
+
+        Parameters
+        ----------
+
+        solution : Solution
+            A solution of this game, used to obtain the norms of the
+            optimal strategies.
+
+        Returns
+        -------
+
+        float
+            A scaling factor to be multiplied by ``ABS_TOL`` when
+            making comparisons involving solutions of this game.
+
+        """
         norm_p1_opt = norm(solution.player1_optimal())
         norm_p2_opt = norm(solution.player2_optimal())
         scale = self._L_specnorm()*(norm_p1_opt + norm_p2_opt)
-        return max(1, scale/2.0)
+
+        # Don't return anything smaller than 1... we can't go below
+        # out "minimum tolerance."
+        return max(1, scale)
 
 
     def solution(self):
@@ -1162,8 +1218,7 @@ class SymmetricLinearGame:
                    [ 3],
               e2 = [ 1]
                    [ 1]
-                   [ 1],
-              Condition((L, K, e1, e2)) = 44.476...
+                   [ 1]
 
         """
         # We pass ``self.L()`` right back into the constructor, because