From: Michael Orlitzky <michael@orlitzky.com>
Date: Sun, 13 Nov 2016 20:08:19 +0000 (-0500)
Subject: Add missing docs for two SymmetricLinearGame methods.
X-Git-Tag: 0.1.0~27
X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=687820b6a899842773f79bc1c830458b65de2ad3;p=dunshire.git

Add missing docs for two SymmetricLinearGame methods.
---

diff --git a/dunshire/games.py b/dunshire/games.py
index 07a70b0..a0c5227 100644
--- a/dunshire/games.py
+++ b/dunshire/games.py
@@ -731,7 +731,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 +773,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 +848,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):