from cvxopt import matrix, printing, solvers
from .cones import CartesianProduct
from .errors import GameUnsolvableException, PoorScalingException
-from .matrices import append_col, append_row, condition_number, identity
+from .matrices import (append_col, append_row, condition_number, identity,
+ inner_product)
from . import options
printing.options['dformat'] = options.FLOAT_FORMAT
-solvers.options['show_progress'] = options.VERBOSE
-
class Solution:
"""
if not self._e2 in K:
raise ValueError('the point e2 must lie in the interior of K')
- # Cached result of the self._zero() method.
- self._zero_col = None
def __str__(self):
self.condition())
+ def L(self):
+ """
+ Return the matrix ``L`` passed to the constructor.
+
+ Returns
+ -------
+
+ matrix
+ The matrix that defines this game's :meth:`payoff` operator.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]]
+ >>> e1 = [1,1,1]
+ >>> e2 = [1,2,3]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG.L())
+ [ 1 -5 -15]
+ [ -1 2 -3]
+ [-12 -15 1]
+ <BLANKLINE>
+
+ """
+ return self._L
+
+
+ def K(self):
+ """
+ Return the cone over which this game is played.
+
+ Returns
+ -------
+
+ SymmetricCone
+ The :class:`SymmetricCone` over which this game is played.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]]
+ >>> e1 = [1,1,1]
+ >>> e2 = [1,2,3]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG.K())
+ Nonnegative orthant in the real 3-space
+
+ """
+ return self._K
+
+
+ def e1(self):
+ """
+ Return player one's interior point.
+
+ Returns
+ -------
+
+ matrix
+ The point interior to :meth:`K` affiliated with player one.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]]
+ >>> e1 = [1,1,1]
+ >>> e2 = [1,2,3]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG.e1())
+ [ 1]
+ [ 1]
+ [ 1]
+ <BLANKLINE>
+
+ """
+ return self._e1
+
+
+ def e2(self):
+ """
+ Return player two's interior point.
+
+ Returns
+ -------
+
+ matrix
+ The point interior to :meth:`K` affiliated with player one.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]]
+ >>> e1 = [1,1,1]
+ >>> e2 = [1,2,3]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG.e2())
+ [ 1]
+ [ 2]
+ [ 3]
+ <BLANKLINE>
+
+ """
+ return self._e2
+
+
+ def payoff(self, strategy1, strategy2):
+ r"""
+ Return the payoff associated with ``strategy1`` and ``strategy2``.
+
+ 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
+ :meth:`L`. This method computes the payoff given the two
+ players' strategies.
+
+ Parameters
+ ----------
+
+ strategy1 : matrix
+ Player one's strategy.
+
+ strategy2 : matrix
+ Player two's strategy.
+
+ Returns
+ -------
+
+ float
+ The payoff for the game when player one plays ``strategy1``
+ and player two plays ``strategy2``.
+
+ Examples
+ --------
+
+ The value of the game should be the payoff at the optimal
+ 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]
+ >>> e2 = [1,1,1]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> 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
+ True
+
+ """
+ return inner_product(self.L()*strategy1, strategy2)
+
+
+ def dimension(self):
+ """
+ Return the dimension of this game.
+
+ The dimension of a game is not needed for the theory, but it is
+ useful for the implementation. We define the dimension of a game
+ to be the dimension of its underlying cone. Or what is the same,
+ the dimension of the space from which the strategies are chosen.
+
+ Returns
+ -------
+
+ int
+ The dimension of the cone :meth:`K`, or of the space where
+ this game is played.
+
+ Examples
+ --------
+
+ The dimension of a game over the nonnegative quadrant in the
+ plane should be two (the dimension of the plane)::
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(2)
+ >>> L = [[1,-5],[-1,2]]
+ >>> e1 = [1,1]
+ >>> e2 = [1,4]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> SLG.dimension()
+ 2
+
+ """
+ return self.K().dimension()
+
+
def _zero(self):
"""
Return a column of zeros that fits ``K``.
This is used in our CVXOPT construction.
+
+ .. warning::
+
+ It is not safe to cache any of the matrices passed to
+ CVXOPT, because it can clobber them.
+
+ Returns
+ -------
+
+ matrix
+ A ``self.dimension()``-by-``1`` column vector of zeros.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = identity(3)
+ >>> e1 = [1,1,1]
+ >>> e2 = e1
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG._zero())
+ [0.0000000]
+ [0.0000000]
+ [0.0000000]
+ <BLANKLINE>
+
"""
- if self._zero_col is None:
- # Cache it, it's constant.
- self._zero_col = matrix(0, (self._K.dimension(), 1), tc='d')
- return self._zero_col
+ return matrix(0, (self.dimension(), 1), tc='d')
def _A(self):
This matrix ``A`` appears on the right-hand side of ``Ax = b``
in the statement of the CVXOPT conelp program.
+
+ .. warning::
+
+ It is not safe to cache any of the matrices passed to
+ CVXOPT, because it can clobber them.
+
+ Returns
+ -------
+
+ matrix
+ A ``1``-by-``(1 + self.dimension())`` row vector. Its first
+ entry is zero, and the rest are the entries of ``e2``.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[1,1,1],[1,1,1],[1,1,1]]
+ >>> e1 = [1,1,1]
+ >>> e2 = [1,2,3]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG._A())
+ [0.0000000 1.0000000 2.0000000 3.0000000]
+ <BLANKLINE>
+
"""
- return matrix([0, self._e2], (1, self._K.dimension() + 1), 'd')
+ return matrix([0, self._e2], (1, self.dimension() + 1), 'd')
+
def _G(self):
r"""
Return the matrix ``G`` used in our CVXOPT construction.
- Thus matrix ``G``that appears on the left-hand side of ``Gx + s = h``
+ Thus matrix ``G`` appears on the left-hand side of ``Gx + s = h``
in the statement of the CVXOPT conelp program.
+
+ .. warning::
+
+ It is not safe to cache any of the matrices passed to
+ CVXOPT, because it can clobber them.
+
+ Returns
+ -------
+
+ matrix
+ A ``2*self.dimension()``-by-``(1 + self.dimension())`` matrix.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[4,5,6],[7,8,9],[10,11,12]]
+ >>> e1 = [1,2,3]
+ >>> e2 = [1,1,1]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG._G())
+ [ 0.0000000 -1.0000000 0.0000000 0.0000000]
+ [ 0.0000000 0.0000000 -1.0000000 0.0000000]
+ [ 0.0000000 0.0000000 0.0000000 -1.0000000]
+ [ 1.0000000 -4.0000000 -5.0000000 -6.0000000]
+ [ 2.0000000 -7.0000000 -8.0000000 -9.0000000]
+ [ 3.0000000 -10.0000000 -11.0000000 -12.0000000]
+ <BLANKLINE>
+
"""
- I = identity(self._K.dimension())
- return append_row(append_col(self._zero(), -I),
+ identity_matrix = identity(self.dimension())
+ return append_row(append_col(self._zero(), -identity_matrix),
append_col(self._e1, -self._L))
- def solution(self):
+ def _c(self):
"""
- Solve this linear game and return a :class:`Solution`.
+ Return the vector ``c`` used in our CVXOPT construction.
+
+ The column vector ``c`` appears in the objective function
+ value ``<c,x>`` in the statement of the CVXOPT conelp program.
+
+ .. warning::
+
+ It is not safe to cache any of the matrices passed to
+ CVXOPT, because it can clobber them.
+
+ Returns
+ -------
+
+ matrix
+ A ``self.dimension()``-by-``1`` column vector.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[4,5,6],[7,8,9],[10,11,12]]
+ >>> e1 = [1,2,3]
+ >>> e2 = [1,1,1]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG._c())
+ [-1.0000000]
+ [ 0.0000000]
+ [ 0.0000000]
+ [ 0.0000000]
+ <BLANKLINE>
+
+ """
+ return matrix([-1, self._zero()])
+
+
+ def _C(self):
+ """
+ Return the cone ``C`` used in our CVXOPT construction.
+
+ The cone ``C`` is the cone over which the conelp program takes
+ place.
+
+ Returns
+ -------
+
+ CartesianProduct
+ The cartesian product of ``K`` with itself.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[4,5,6],[7,8,9],[10,11,12]]
+ >>> e1 = [1,2,3]
+ >>> e2 = [1,1,1]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG._C())
+ Cartesian product of dimension 6 with 2 factors:
+ * Nonnegative orthant in the real 3-space
+ * Nonnegative orthant in the real 3-space
+
+ """
+ return CartesianProduct(self._K, self._K)
+
+ def _h(self):
+ """
+ Return the ``h`` vector used in our CVXOPT construction.
+
+ The ``h`` vector appears on the right-hand side of :math:`Gx + s
+ = h` in the statement of the CVXOPT conelp program.
+
+ .. warning::
+
+ It is not safe to cache any of the matrices passed to
+ CVXOPT, because it can clobber them.
+
+ Returns
+ -------
+
+ matrix
+ A ``2*self.dimension()``-by-``1`` column vector of zeros.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[4,5,6],[7,8,9],[10,11,12]]
+ >>> e1 = [1,2,3]
+ >>> e2 = [1,1,1]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG._h())
+ [0.0000000]
+ [0.0000000]
+ [0.0000000]
+ [0.0000000]
+ [0.0000000]
+ [0.0000000]
+ <BLANKLINE>
+
+ """
+
+ return matrix([self._zero(), self._zero()])
+
+
+ @staticmethod
+ def _b():
+ """
+ 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.
+
+ This method is static because the dimensions and entries of
+ ``b`` are known beforehand, and don't depend on any other
+ properties of the game.
+
+ .. warning::
+
+ It is not safe to cache any of the matrices passed to
+ CVXOPT, because it can clobber them.
+
+ Returns
+ -------
+
+ matrix
+ A ``1``-by-``1`` matrix containing a single entry ``1``.
+
+ Examples
+ --------
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[4,5,6],[7,8,9],[10,11,12]]
+ >>> e1 = [1,2,3]
+ >>> e2 = [1,1,1]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG._b())
+ [1.0000000]
+ <BLANKLINE>
+
+ """
+ return matrix([1], tc='d')
+
+
+ def _try_solution(self, tolerance):
+ """
+ Solve this linear game within ``tolerance``, if possible.
+
+ This private function is the one that does all of the actual
+ work for :meth:`solution`. This method accepts a ``tolerance``,
+ and what :meth:`solution` does is call this method twice with
+ two different tolerances. First it tries a strict tolerance, and
+ then it tries a looser one.
+
+ .. warning::
+
+ If you try to be smart and precompute the matrices used by
+ this function (the ones passed to ``conelp``), then you're
+ going to shoot yourself in the foot. CVXOPT can and will
+ clobber some (but not all) of its input matrices. This isn't
+ performance sensitive, so play it safe.
+
+ Parameters
+ ----------
+
+ tolerance : float
+ The absolute tolerance to pass to the CVXOPT solver.
Returns
-------
Examples
--------
- This example is computed in Gowda and Ravindran in the section
- "The value of a Z-transformation"::
+ This game can be solved easily, so the first attempt in
+ :meth:`solution` should succeed::
>>> from dunshire import *
+ >>> from dunshire.matrices import norm
+ >>> from dunshire.options import ABS_TOL
>>> K = NonnegativeOrthant(3)
>>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]]
>>> e1 = [1,1,1]
>>> e2 = [1,1,1]
>>> SLG = SymmetricLinearGame(L, K, e1, e2)
- >>> print(SLG.solution())
- Game value: -6.1724138
- Player 1 optimal:
- [ 0.551...]
- [-0.000...]
- [ 0.448...]
- Player 2 optimal:
- [0.448...]
- [0.000...]
- [0.551...]
-
- The value of the following game can be computed using the fact
- that the identity is invertible::
+ >>> s1 = SLG.solution()
+ >>> s2 = SLG._try_solution(options.ABS_TOL)
+ >>> abs(s1.game_value() - s2.game_value()) < ABS_TOL
+ True
+ >>> norm(s1.player1_optimal() - s2.player1_optimal()) < ABS_TOL
+ True
+ >>> norm(s1.player2_optimal() - s2.player2_optimal()) < ABS_TOL
+ True
+
+ This game cannot be solved with the default tolerance, but it
+ can be solved with a weaker one::
>>> from dunshire import *
- >>> K = NonnegativeOrthant(3)
- >>> L = [[1,0,0],[0,1,0],[0,0,1]]
- >>> e1 = [1,2,3]
- >>> e2 = [4,5,6]
- >>> SLG = SymmetricLinearGame(L, K, e1, e2)
- >>> print(SLG.solution())
- Game value: 0.0312500
+ >>> from dunshire.options import ABS_TOL
+ >>> L = [[ 0.58538005706658102767, 1.53764301129883040886],
+ ... [-1.34901059721452210027, 1.50121179114155500756]]
+ >>> K = NonnegativeOrthant(2)
+ >>> e1 = [1.04537193228494995623, 1.39699624965841895374]
+ >>> e2 = [0.35326554172108337593, 0.11795703527854853321]
+ >>> SLG = SymmetricLinearGame(L,K,e1,e2)
+ >>> print(SLG._try_solution(ABS_TOL / 10))
+ Traceback (most recent call last):
+ ...
+ dunshire.errors.GameUnsolvableException: Solution failed...
+ >>> print(SLG._try_solution(ABS_TOL))
+ Game value: 9.1100945
Player 1 optimal:
- [0.031...]
- [0.062...]
- [0.093...]
+ [-0.0000000]
+ [ 8.4776631]
Player 2 optimal:
- [0.125...]
- [0.156...]
- [0.187...]
+ [0.0000000]
+ [0.7158216]
"""
- # The cone "C" that appears in the statement of the CVXOPT
- # conelp program.
- C = CartesianProduct(self._K, self._K)
-
- # The column vector "b" that appears on the right-hand side of
- # Ax = b in the statement of the CVXOPT conelp program.
- b = matrix([1], tc='d')
-
- # The column vector "h" that appears on the right-hand side of
- # Gx + s = h in the statement of the CVXOPT conelp program.
- h = matrix([self._zero(), self._zero()])
-
- # The column vector "c" that appears in the objective function
- # value <c,x> in the statement of the CVXOPT conelp program.
- c = matrix([-1, self._zero()])
-
- # Actually solve the thing and obtain a dictionary describing
- # what happened.
try:
- soln_dict = solvers.conelp(c, self._G(), h,
- C.cvxopt_dims(), self._A(), b)
- except ValueError as e:
- if str(e) == 'math domain error':
+ opts = {'show_progress': options.VERBOSE, 'abstol': tolerance}
+ soln_dict = solvers.conelp(self._c(),
+ self._G(),
+ self._h(),
+ self._C().cvxopt_dims(),
+ self._A(),
+ self._b(),
+ options=opts)
+ except ValueError as error:
+ if str(error) == 'math domain error':
# Oops, CVXOPT tried to take the square root of a
# negative number. Report some details about the game
# rather than just the underlying CVXOPT crash.
raise PoorScalingException(self)
else:
- raise e
+ raise error
# The optimal strategies are named ``p`` and ``q`` in the
# background documentation, and we need to extract them from
p1_value = -soln_dict['primal objective']
p2_value = -soln_dict['dual objective']
p1_optimal = soln_dict['x'][1:]
- p2_optimal = soln_dict['z'][self._K.dimension():]
+ p2_optimal = soln_dict['z'][self.dimension():]
# The "status" field contains "optimal" if everything went
# according to plan. Other possible values are "primal
# value could be under the true optimal by ``ABS_TOL``
# and the dual value could be over by the same amount.
#
- if abs(p1_value - p2_value) > 2*options.ABS_TOL:
+ if abs(p1_value - p2_value) > tolerance:
raise GameUnsolvableException(self, soln_dict)
if (p1_optimal not in self._K) or (p2_optimal not in self._K):
raise GameUnsolvableException(self, soln_dict)
return Solution(p1_value, p1_optimal, p2_optimal)
+ def solution(self):
+ """
+ Solve this linear game and return a :class:`Solution`.
+
+ Returns
+ -------
+
+ :class:`Solution`
+ A :class:`Solution` object describing the game's value and
+ the optimal strategies of both players.
+
+ Raises
+ ------
+ GameUnsolvableException
+ If the game could not be solved (if an optimal solution to its
+ associated cone program was not found).
+
+ PoorScalingException
+ If the game could not be solved because CVXOPT crashed while
+ trying to take the square root of a negative number.
+
+ Examples
+ --------
+
+ This example is computed in Gowda and Ravindran in the section
+ "The value of a Z-transformation"::
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]]
+ >>> e1 = [1,1,1]
+ >>> e2 = [1,1,1]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG.solution())
+ Game value: -6.1724138
+ Player 1 optimal:
+ [ 0.551...]
+ [-0.000...]
+ [ 0.448...]
+ Player 2 optimal:
+ [0.448...]
+ [0.000...]
+ [0.551...]
+
+ The value of the following game can be computed using the fact
+ that the identity is invertible::
+
+ >>> from dunshire import *
+ >>> K = NonnegativeOrthant(3)
+ >>> L = [[1,0,0],[0,1,0],[0,0,1]]
+ >>> e1 = [1,2,3]
+ >>> e2 = [4,5,6]
+ >>> SLG = SymmetricLinearGame(L, K, e1, e2)
+ >>> print(SLG.solution())
+ Game value: 0.0312500
+ Player 1 optimal:
+ [0.031...]
+ [0.062...]
+ [0.093...]
+ Player 2 optimal:
+ [0.125...]
+ [0.156...]
+ [0.187...]
+
+ """
+ try:
+ # First try with a stricter tolerance. Who knows, it might
+ # work. If it does, we prefer that solution.
+ return self._try_solution(options.ABS_TOL / 10)
+
+ except (PoorScalingException, GameUnsolvableException):
+ # Ok, that didn't work. Let's try it with the default
+ # tolerance, and whatever happens, happens.
+ return self._try_solution(options.ABS_TOL)
+
+
def condition(self):
r"""
Return the condition number of this game.