Add some more docs for the player[12]_start() methods.

[dunshire.git] / dunshire / games.py

diff --git a/dunshire/games.py b/dunshire/games.py
index 951c7f4bc16088e4b82cc91cb90eb41c9e90db5f..6ab420d1b0c26cc6de561caf85629bae28f0462a 100644 (file)
--- a/dunshire/games.py
+++ b/dunshire/games.py
@@ -613,7 +613,7 @@ class SymmetricLinearGame:
 
 
 
-    def _G(self):
+    def G(self):
         r"""
         Return the matrix ``G`` used in our CVXOPT construction.
 
@@ -640,7 +640,7 @@ class SymmetricLinearGame:
             >>> e1 = [1,2,3]
             >>> e2 = [1,1,1]
             >>> SLG = SymmetricLinearGame(L, K, e1, e2)
-            >>> print(SLG._G())
+            >>> print(SLG.G())
             [  0.0000000  -1.0000000   0.0000000   0.0000000]
             [  0.0000000   0.0000000  -1.0000000   0.0000000]
             [  0.0000000   0.0000000   0.0000000  -1.0000000]
@@ -655,7 +655,7 @@ class SymmetricLinearGame:
                           append_col(self.e1(), -self.L()))
 
 
-    def _c(self):
+    def c(self):
         """
         Return the vector ``c`` used in our CVXOPT construction.
 
@@ -682,7 +682,7 @@ class SymmetricLinearGame:
             >>> e1 = [1,2,3]
             >>> e2 = [1,1,1]
             >>> SLG = SymmetricLinearGame(L, K, e1, e2)
-            >>> print(SLG._c())
+            >>> print(SLG.c())
             [-1.0000000]
             [ 0.0000000]
             [ 0.0000000]
@@ -723,7 +723,7 @@ class SymmetricLinearGame:
         """
         return CartesianProduct(self._K, self._K)
 
-    def _h(self):
+    def h(self):
         r"""
         Return the ``h`` vector used in our CVXOPT construction.
 
@@ -750,7 +750,7 @@ class SymmetricLinearGame:
             >>> e1 = [1,2,3]
             >>> e2 = [1,1,1]
             >>> SLG = SymmetricLinearGame(L, K, e1, e2)
-            >>> print(SLG._h())
+            >>> print(SLG.h())
             [0.0000000]
             [0.0000000]
             [0.0000000]
@@ -809,17 +809,32 @@ class SymmetricLinearGame:
         Return a feasible starting point for player one.
 
         This starting point is for the CVXOPT formulation and not for
-        the original game. The basic premise is that if you normalize
-        :meth:`e2`, then you get a point in :meth:`K` that makes a unit
-        inner product with :meth:`e2`. We then get to choose the primal
-        objective function value such that the constraint involving
-        :meth:`L` is satisfied.
+        the original game. The basic premise is that if you scale
+        :meth:`e2` by the reciprocal of its squared norm, then you get a
+        point in :meth:`K` that makes a unit inner product with
+        :meth:`e2`. We then get to choose the primal objective function
+        value such that the constraint involving :meth:`L` is satisfied.
+
+        Returns
+        -------
+
+        dict
+            A dictionary with two keys, 'x' and 's', which contain the
+            vectors of the same name in the CVXOPT primal problem
+            formulation.
+
+            The vector ``x`` consists of the primal objective function
+            value concatenated with the strategy (for player one) that
+            achieves it. The vector ``s`` is essentially a dummy
+            variable, and is computed from the equality constraing in
+            the CVXOPT primal problem.
+
         """
         p = self.e2() / (norm(self.e2()) ** 2)
         dist = self.K().ball_radius(self.e1())
         nu = - self._L_specnorm()/(dist*norm(self.e2()))
         x = matrix([nu, p], (self.dimension() + 1, 1))
-        s = - self._G()*x
+        s = - self.G()*x
 
         return {'x': x, 's': s}
 
@@ -827,6 +842,29 @@ class SymmetricLinearGame:
     def player2_start(self):
         """
         Return a feasible starting point for player two.
+
+        This starting point is for the CVXOPT formulation and not for
+        the original game. The basic premise is that if you scale
+        :meth:`e1` by the reciprocal of its squared norm, then you get a
+        point in :meth:`K` that makes a unit inner product with
+        :meth:`e1`. We then get to choose the dual objective function
+        value such that the constraint involving :meth:`L` is satisfied.
+
+        Returns
+        -------
+
+        dict
+            A dictionary with two keys, 'y' and 'z', which contain the
+            vectors of the same name in the CVXOPT dual problem
+            formulation.
+
+            The ``1``-by-``1`` vector ``y`` consists of the dual
+            objective function value. The last :meth:`dimension` entries
+            of the vector ``z`` contain the strategy (for player two)
+            that achieves it. The remaining entries of ``z`` are
+            essentially dummy variables, computed from the equality
+            constraint in the CVXOPT dual problem.
+
         """
         q = self.e1() / (norm(self.e1()) ** 2)
         dist = self.K().ball_radius(self.e2())
@@ -1074,9 +1112,9 @@ class SymmetricLinearGame:
         """
         try:
             opts = {'show_progress': False}
-            soln_dict = solvers.conelp(self._c(),
-                                       self._G(),
-                                       self._h(),
+            soln_dict = solvers.conelp(self.c(),
+                                       self.G(),
+                                       self.h(),
                                        self.C().cvxopt_dims(),
                                        self.A(),
                                        self.b(),
@@ -1186,7 +1224,7 @@ class SymmetricLinearGame:
         1.809...
 
         """
-        return (condition_number(self._G()) + condition_number(self.A()))/2
+        return (condition_number(self.G()) + condition_number(self.A()))/2
 
 
     def dual(self):