X-Git-Url: https://gitweb.michael.orlitzky.com/?a=blobdiff_plain;f=dunshire%2Fgames.py;h=6ed36c3963fe34b902c04d8f5fc3e25662c491e5;hb=ff9a508f946f02c9c8896ebadccf2a44525a52a9;hp=19b2f5b34276275258e4ccd0bcd9b9b143e7608c;hpb=fca2dba7c55f8eb55462c8376d56266792701de1;p=dunshire.git diff --git a/dunshire/games.py b/dunshire/games.py index 19b2f5b..6ed36c3 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 @@ -245,12 +249,11 @@ class SymmetricLinearGame: there is no row/column ambiguity:: >>> import cvxopt - >>> import numpy >>> from dunshire import * >>> K = NonnegativeOrthant(2) >>> L = [[1,0],[0,1]] >>> e1 = cvxopt.matrix([1,1]) - >>> e2 = numpy.matrix([1,1]) + >>> e2 = (1,1) >>> G = SymmetricLinearGame(L, K, e1, e2) >>> print(G) The linear game (L, K, e1, e2) where @@ -461,8 +464,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. @@ -489,7 +492,6 @@ class SymmetricLinearGame: strategies:: >>> from dunshire import * - >>> from dunshire.options import ABS_TOL >>> K = NonnegativeOrthant(3) >>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]] >>> e1 = [1,1,1] @@ -498,7 +500,7 @@ class SymmetricLinearGame: >>> soln = SLG.solution() >>> x_bar = soln.player1_optimal() >>> y_bar = soln.player2_optimal() - >>> abs(SLG.payoff(x_bar, y_bar) - soln.game_value()) < ABS_TOL + >>> SLG.payoff(x_bar, y_bar) == soln.game_value() True """ @@ -580,8 +582,9 @@ 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 - = 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:: @@ -593,7 +596,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 -------- @@ -618,7 +621,8 @@ class SymmetricLinearGame: Return the matrix ``G`` used in our CVXOPT construction. Thus matrix :math:`G` appears on the left-hand side of :math:`Gx - + s = h` in the statement of the CVXOPT conelp program. + + s = h` in the `statement of the CVXOPT conelp program + `_. .. warning:: @@ -660,8 +664,9 @@ class SymmetricLinearGame: Return the vector ``c`` used in our CVXOPT construction. 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. + value :math:`\left\langle c,x \right\rangle` in the `statement + of the CVXOPT conelp program + `_. .. warning:: @@ -672,7 +677,7 @@ class SymmetricLinearGame: ------- matrix - A ``self.dimension()``-by-``1`` column vector. + A :meth:`dimension`-by-``1`` column vector. Examples -------- @@ -698,7 +703,9 @@ class SymmetricLinearGame: """ Return the cone ``C`` used in our CVXOPT construction. - This is the cone over which the conelp program takes place. + This is the cone over which the `CVXOPT conelp program + `_ + takes place. Returns ------- @@ -727,8 +734,9 @@ class SymmetricLinearGame: r""" Return the ``h`` vector used in our CVXOPT construction. - The :math:`h` vector appears on the right-hand side of :math:`Gx + s - = h` in the statement of the CVXOPT conelp program. + The :math:`h` vector appears on the right-hand side of :math:`Gx + + s = h` in the `statement of the CVXOPT conelp program + `_. .. warning:: @@ -769,8 +777,9 @@ class SymmetricLinearGame: r""" Return the ``b`` vector used in our CVXOPT construction. - The vector ``b`` appears on the right-hand side of :math:`Ax = - b` in the statement of the CVXOPT conelp program. + The vector :math:`b` appears on the right-hand side of :math:`Ax + = b` in the `statement of the CVXOPT conelp program + `_. This method is static because the dimensions and entries of ``b`` are known beforehand, and don't depend on any other @@ -819,9 +828,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 +863,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 +923,21 @@ class SymmetricLinearGame: def tolerance_scale(self, solution): 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 + + Return a scaling factor that should be applied to + :const:`dunshire.options.ABS_TOL` for this game. + + When performing certain comparisons, the default tolerance + :const:`dunshire.options.ABS_TOL` may not be appropriate. For + example, if we expect ``x`` and ``y`` to be within + :const:`dunshire.options.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 +968,8 @@ class SymmetricLinearGame: ------- float - A scaling factor to be multiplied by ``ABS_TOL`` when + A scaling factor to be multiplied by + :const:`dunshire.options.ABS_TOL` when making comparisons involving solutions of this game. Examples @@ -994,7 +1006,7 @@ class SymmetricLinearGame: Returns ------- - :class:`Solution` + Solution A :class:`Solution` object describing the game's value and the optimal strategies of both players. @@ -1233,8 +1245,12 @@ class SymmetricLinearGame: can show up. We define the condition number of this game to be the average of the condition numbers of ``G`` and ``A`` in the CVXOPT construction. If the condition number of this game is - high, then you can expect numerical difficulty (such as - :class:`PoorScalingException`). + high, you can problems like :class:`PoorScalingException`. + + Random testing shows that a condition number of around ``125`` + is about the best that we can solve reliably. However, the + failures are intermittent, and you may get lucky with an + ill-conditioned game. Returns -------