X-Git-Url: http://gitweb.michael.orlitzky.com/?a=blobdiff_plain;ds=sidebyside;f=dunshire%2Fgames.py;h=ea7a64f6b8e6451a808b464494c11e9be9f0de78;hb=24f8a8f6dcac63ba5446e6cb5808d0143c540479;hp=19b2f5b34276275258e4ccd0bcd9b9b143e7608c;hpb=fca2dba7c55f8eb55462c8376d56266792701de1;p=dunshire.git
diff --git a/dunshire/games.py b/dunshire/games.py
index 19b2f5b..ea7a64f 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.
@@ -489,7 +493,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 +501,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 +583,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 +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
--------
@@ -618,7 +622,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 +665,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 +678,7 @@ class SymmetricLinearGame:
-------
matrix
- A ``self.dimension()``-by-``1`` column vector.
+ A :meth:`dimension`-by-``1`` column vector.
Examples
--------
@@ -698,7 +704,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 +735,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 +778,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 +829,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 +864,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 +924,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 +969,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 +1007,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 +1246,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
-------