From: Michael Orlitzky <michael@orlitzky.com>
Date: Tue, 15 Nov 2016 15:57:49 +0000 (-0500)
Subject: Add missing examples for two methods and use math for equations.
X-Git-Tag: 0.1.0~9
X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=fca2dba7c55f8eb55462c8376d56266792701de1;p=dunshire.git

Add missing examples for two methods and use math for equations.
---

diff --git a/dunshire/games.py b/dunshire/games.py
index 6ab420d..19b2f5b 100644
--- a/dunshire/games.py
+++ b/dunshire/games.py
@@ -577,11 +577,11 @@ class SymmetricLinearGame:
 
 
     def A(self):
-        """
+        r"""
         Return the matrix ``A`` used in our CVXOPT construction.
 
-        This matrix ``A``  appears on the right-hand side of ``Ax = b``
-        in the statement of the CVXOPT conelp program.
+        This matrix :math`A` appears on the right-hand side of :math:`Ax
+        = b` in the statement of the CVXOPT conelp program.
 
         .. warning::
 
@@ -617,8 +617,8 @@ class SymmetricLinearGame:
         r"""
         Return the matrix ``G`` used in our CVXOPT construction.
 
-        Thus matrix ``G`` appears on the left-hand side of ``Gx + s = h``
-        in the statement of the CVXOPT conelp program.
+        Thus matrix :math:`G` appears on the left-hand side of :math:`Gx
+        + s = h` in the statement of the CVXOPT conelp program.
 
         .. warning::
 
@@ -656,11 +656,12 @@ class SymmetricLinearGame:
 
 
     def c(self):
-        """
+        r"""
         Return the vector ``c`` used in our CVXOPT construction.
 
-        The column vector ``c``  appears in the objective function
-        value ``<c,x>`` in the statement of the CVXOPT conelp program.
+        The column vector :math:`c` appears in the objective function
+        value :math:`\left\langle c,x \right\rangle` in the statement of
+        the CVXOPT conelp program.
 
         .. warning::
 
@@ -697,8 +698,7 @@ class SymmetricLinearGame:
         """
         Return the cone ``C`` used in our CVXOPT construction.
 
-        The cone ``C`` is the cone over which the conelp program takes
-        place.
+        This is the cone over which the conelp program takes place.
 
         Returns
         -------
@@ -727,7 +727,7 @@ class SymmetricLinearGame:
         r"""
         Return the ``h`` vector used in our CVXOPT construction.
 
-        The ``h`` vector appears on the right-hand side of :math:`Gx + s
+        The :math:`h` vector appears on the right-hand side of :math:`Gx + s
         = h` in the statement of the CVXOPT conelp program.
 
         .. warning::
@@ -893,6 +893,19 @@ class SymmetricLinearGame:
             A nonnegative real number; the largest singular value of
             the matrix :meth:`L`.
 
+        Examples
+        --------
+
+            >>> from dunshire import *
+            >>> from dunshire.matrices import specnorm
+            >>> L = [[1,2],[3,4]]
+            >>> K = NonnegativeOrthant(2)
+            >>> e1 = [1,1]
+            >>> e2 = e1
+            >>> SLG = SymmetricLinearGame(L,K,e1,e2)
+            >>> specnorm(SLG.L()) == SLG._L_specnorm()
+            True
+
         """
         if self._L_specnorm_value is None:
             self._L_specnorm_value = specnorm(self.L())
@@ -947,6 +960,23 @@ class SymmetricLinearGame:
             A scaling factor to be multiplied by ``ABS_TOL`` when
             making comparisons involving solutions of this game.
 
+        Examples
+        --------
+
+        The spectral norm of ``L`` in this case is around ``5.464``, and
+        the optimal strategies both have norm one, so we expect the
+        tolerance scale to be somewhere around ``2 * 5.464``, or
+        ``10.929``::
+
+            >>> from dunshire import *
+            >>> L = [[1,2],[3,4]]
+            >>> K = NonnegativeOrthant(2)
+            >>> e1 = [1,1]
+            >>> e2 = e1
+            >>> SLG = SymmetricLinearGame(L,K,e1,e2)
+            >>> SLG.tolerance_scale(SLG.solution())
+            10.929...
+
         """
         norm_p1_opt = norm(solution.player1_optimal())
         norm_p2_opt = norm(solution.player2_optimal())
@@ -1172,12 +1202,14 @@ class SymmetricLinearGame:
         # same. Even if CVXOPT bails out due to numerical difficulty,
         # it will have some candidate points in mind. If those
         # candidates are good enough, we take them. We do the same
-        # check (perhaps pointlessly so) for "optimal" results.
+        # check for "optimal" results.
         #
         # First we check that the primal/dual objective values are
-        # close enough (one could be low by ABS_TOL, the other high by
-        # it) because otherwise CVXOPT might return "unknown" and give
-        # us two points in the cone that are nowhere near optimal.
+        # close enough because otherwise CVXOPT might return "unknown"
+        # and give us two points in the cone that are nowhere near
+        # optimal. And in fact, we need to ensure that they're close
+        # for "optimal" results, too, because we need to know how
+        # lenient to be in our testing.
         #
         if abs(p1_value - p2_value) > self.tolerance_scale(soln)*ABS_TOL:
             printing.options['dformat'] = DEBUG_FLOAT_FORMAT