From 7d7775ac5300884e4e87fad322daa98469e3531c Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Tue, 15 Nov 2016 11:23:12 -0500 Subject: [PATCH] Clean up a bunch of docs. --- doc/source/user-api.rst | 6 ++--- dunshire/cones.py | 2 +- dunshire/games.py | 58 ++++++++++++++++++++++------------------- 3 files changed, 35 insertions(+), 31 deletions(-) diff --git a/doc/source/user-api.rst b/doc/source/user-api.rst index 22488f3..4627a41 100644 --- a/doc/source/user-api.rst +++ b/doc/source/user-api.rst @@ -1,9 +1,9 @@ User API Documentation --------------------------- -You should only need to work with two modules, ``dunshire.cones`` and -``dunshire.games``. For convenience, you can import everything from -the ``dunshire`` package, and it will re-export what you need. For +You should only need to work with two modules, :mod:`dunshire.cones` and +:mod:`dunshire.games`. For convenience, you can import everything from +the :mod:`dunshire` package, and it will re-export what you need. For example, .. testcode:: diff --git a/dunshire/cones.py b/dunshire/cones.py index 50c57e7..bc27640 100644 --- a/dunshire/cones.py +++ b/dunshire/cones.py @@ -734,7 +734,7 @@ class CartesianProduct(SymmetricCone): Returns ------- - tuple of :class:`SymmetricCone`. + tuple of SymmetricCone. The factors of this cartesian product. Examples diff --git a/dunshire/games.py b/dunshire/games.py index 19b2f5b..e9ae21d 100644 --- 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 `_ + and `NumPy `_, 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 -- 2.43.2