L : list of list of float
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
+ agrees with (for example) `SageMath <https://www.sagemath.org/>`_
+ and `NumPy <https://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
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
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]
>>> 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
"""
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
+ <https://cvxopt.org/userguide/coneprog.html#linear-cone-programs>`_.
.. warning::
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
+ <https://cvxopt.org/userguide/coneprog.html#linear-cone-programs>`_.
.. warning::
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
+ <https://cvxopt.org/userguide/coneprog.html#linear-cone-programs>`_.
.. warning::
"""
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
+ <https://cvxopt.org/userguide/coneprog.html#linear-cone-programs>`_
+ takes place.
Returns
-------
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
+ <https://cvxopt.org/userguide/coneprog.html#linear-cone-programs>`_.
.. warning::
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
+ <https://cvxopt.org/userguide/coneprog.html#linear-cone-programs>`_.
This method is static because the dimensions and entries of
``b`` are known beforehand, and don't depend on any other
def tolerance_scale(self, solution):
r"""
- Return a scaling factor that should be applied to :const:`ABS_TOL`
- for this game.
+
+ 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:`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.
+ :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
-------
float
- A scaling factor to be multiplied by :const:`ABS_TOL` when
+ A scaling factor to be multiplied by
+ :const:`dunshire.options.ABS_TOL` when
making comparisons involving solutions of this game.
Examples
Returns
-------
- :class:`Solution`
+ Solution
A :class:`Solution` object describing the game's value and
the optimal strategies of both players.
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
-------