Clean up a bunch of docs.

[dunshire.git] / dunshire / games.py

diff --git a/dunshire/games.py b/dunshire/games.py
index 19b2f5b34276275258e4ccd0bcd9b9b143e7608c..e9ae21dd9fca7803ce0f67d5ba60f3d3555419c7 100644 (file)
--- a/dunshire/games.py
+++ b/dunshire/games.py
@@ -179,11 +179,15 @@ class SymmetricLinearGame:
     ----------
 
     L : list of list of float
-        A matrix represented as a list of ROWS. This representation
-        agrees with (for example) SageMath and NumPy, but not with CVXOPT
-        (whose matrix constructor accepts a list of columns).
-
-    K : :class:`SymmetricCone`
+        A matrix represented as a list of **rows**. This representation
+        agrees with (for example) `SageMath <http://www.sagemath.org/>`_
+        and `NumPy <http://www.numpy.org/>`_, but not with CVXOPT (whose
+        matrix constructor accepts a list of columns). In reality, ``L``
+        can be any iterable type of the correct length; however, you
+        should be extremely wary of the way we interpret anything other
+        than a list of rows.
+
+    K : dunshire.cones.SymmetricCone
         The symmetric cone instance over which the game is played.
 
     e1 : iterable float
@@ -461,8 +465,8 @@ class SymmetricLinearGame:
         The payoff operator takes pairs of strategies to a real
         number. For example, if player one's strategy is :math:`x` and
         player two's strategy is :math:`y`, then the associated payoff
-        is :math:`\left\langle L\left(x\right),y \right\rangle` \in
-        \mathbb{R}. Here, :math:`L` denotes the same linear operator as
+        is :math:`\left\langle L\left(x\right),y \right\rangle \in
+        \mathbb{R}`. Here, :math:`L` denotes the same linear operator as
         :meth:`L`. This method computes the payoff given the two
         players' strategies.
 
@@ -580,7 +584,7 @@ class SymmetricLinearGame:
         r"""
         Return the matrix ``A`` used in our CVXOPT construction.
 
-        This matrix :math`A` appears on the right-hand side of :math:`Ax
+        This matrix :math:`A` appears on the right-hand side of :math:`Ax
         = b` in the statement of the CVXOPT conelp program.
 
         .. warning::
@@ -593,7 +597,7 @@ class SymmetricLinearGame:
 
         matrix
             A ``1``-by-``(1 + self.dimension())`` row vector. Its first
-            entry is zero, and the rest are the entries of ``e2``.
+            entry is zero, and the rest are the entries of :meth:`e2`.
 
         Examples
         --------
@@ -672,7 +676,7 @@ class SymmetricLinearGame:
         -------
 
         matrix
-            A ``self.dimension()``-by-``1`` column vector.
+            A :meth:`dimension`-by-``1`` column vector.
 
         Examples
         --------
@@ -819,9 +823,9 @@ class SymmetricLinearGame:
         -------
 
         dict
-            A dictionary with two keys, 'x' and 's', which contain the
-            vectors of the same name in the CVXOPT primal problem
-            formulation.
+            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
@@ -854,9 +858,9 @@ class SymmetricLinearGame:
         -------
 
         dict
-            A dictionary with two keys, 'y' and 'z', which contain the
-            vectors of the same name in the CVXOPT dual problem
-            formulation.
+            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
@@ -914,19 +918,19 @@ class SymmetricLinearGame:
 
     def tolerance_scale(self, solution):
         r"""
-        Return a scaling factor that should be applied to ``ABS_TOL``
+        Return a scaling factor that should be applied to :const:`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.
+        When performing certain comparisons, the default tolerance
+        :const:`ABS_TOL` may not be appropriate. For example, if we expect
+        ``x`` and ``y`` to be within :const:`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
+        The returned scaling factor found from the inner product
+        mentioned above is
 
         .. math::
 
@@ -957,7 +961,7 @@ class SymmetricLinearGame:
         -------
 
         float
-            A scaling factor to be multiplied by ``ABS_TOL`` when
+            A scaling factor to be multiplied by :const:`ABS_TOL` when
             making comparisons involving solutions of this game.
 
         Examples