knows how to solve a linear game.
"""
-# These few are used only for tests.
-from math import sqrt
-from random import randint, uniform
-from unittest import TestCase
-
-# These are mostly actually needed.
from cvxopt import matrix, printing, solvers
-from cones import CartesianProduct, IceCream, NonnegativeOrthant
-from errors import GameUnsolvableException
-from matrices import append_col, append_row, identity, inner_product, norm
-import options
+from .cones import CartesianProduct
+from .errors import GameUnsolvableException
+from .matrices import append_col, append_row, identity
+from . import options
printing.options['dformat'] = options.FLOAT_FORMAT
solvers.options['show_progress'] = options.VERBOSE
Examples
--------
- >>> from cones import NonnegativeOrthant
+ >>> from dunshire import *
>>> K = NonnegativeOrthant(3)
>>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]]
>>> e1 = [1,1,1]
Lists can (and probably should) be used for every argument::
- >>> from cones import NonnegativeOrthant
+ >>> from dunshire import *
>>> K = NonnegativeOrthant(2)
>>> L = [[1,0],[0,1]]
>>> e1 = [1,1]
>>> import cvxopt
>>> import numpy
- >>> from cones import NonnegativeOrthant
+ >>> from dunshire import *
>>> K = NonnegativeOrthant(2)
>>> L = [[1,0],[0,1]]
>>> e1 = cvxopt.matrix([1,1])
otherwise indexed by columns::
>>> import cvxopt
- >>> from cones import NonnegativeOrthant
+ >>> from dunshire import *
>>> K = NonnegativeOrthant(2)
>>> L = [[1,2],[3,4]]
>>> e1 = [1,1]
This example is computed in Gowda and Ravindran in the section
"The value of a Z-transformation"::
- >>> from cones import NonnegativeOrthant
+ >>> from dunshire import *
>>> K = NonnegativeOrthant(3)
>>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]]
>>> e1 = [1,1,1]
The value of the following game can be computed using the fact
that the identity is invertible::
- >>> from cones import NonnegativeOrthant
+ >>> from dunshire import *
>>> K = NonnegativeOrthant(3)
>>> L = [[1,0,0],[0,1,0],[0,0,1]]
>>> e1 = [1,2,3]
# what happened.
soln_dict = solvers.conelp(c, G, h, C.cvxopt_dims(), A, b)
+ # The optimal strategies are named ``p`` and ``q`` in the
+ # background documentation, and we need to extract them from
+ # the CVXOPT ``x`` and ``z`` variables. The objective values
+ # :math:`nu` and :math:`omega` can also be found in the CVXOPT
+ # ``x`` and ``y`` variables; however, they're stored
+ # conveniently as separate entries in the solution dictionary.
p1_value = -soln_dict['primal objective']
p2_value = -soln_dict['dual objective']
p1_optimal = soln_dict['x'][1:]
Examples
--------
- >>> from cones import NonnegativeOrthant
+ >>> from dunshire import *
>>> K = NonnegativeOrthant(3)
>>> L = [[1,-5,-15],[-1,2,-3],[-12,-15,1]]
>>> e1 = [1,1,1]
self._K,
self._e2,
self._e1)
-
-
-
-def _random_square_matrix(dims):
- """
- Generate a random square (``dims``-by-``dims``) matrix,
- represented as a list of rows. This is used only by the
- :class:`SymmetricLinearGameTest` class.
- """
- return [[uniform(-10, 10) for i in range(dims)] for j in range(dims)]
-
-
-def _random_orthant_params():
- """
- Generate the ``L``, ``K``, ``e1``, and ``e2`` parameters for a
- random game over the nonnegative orthant. This is only used by
- the :class:`SymmetricLinearGameTest` class.
- """
- ambient_dim = randint(1, 10)
- K = NonnegativeOrthant(ambient_dim)
- e1 = [uniform(0.5, 10) for idx in range(K.dimension())]
- e2 = [uniform(0.5, 10) for idx in range(K.dimension())]
- L = _random_square_matrix(K.dimension())
- return (L, K, e1, e2)
-
-
-def _random_icecream_params():
- """
- Generate the ``L``, ``K``, ``e1``, and ``e2`` parameters for a
- random game over the ice cream cone. This is only used by
- the :class:`SymmetricLinearGameTest` class.
- """
- # Use a minimum dimension of two to avoid divide-by-zero in
- # the fudge factor we make up later.
- ambient_dim = randint(2, 10)
- K = IceCream(ambient_dim)
- e1 = [1] # Set the "height" of e1 to one
- e2 = [1] # And the same for e2
-
- # If we choose the rest of the components of e1,e2 randomly
- # between 0 and 1, then the largest the squared norm of the
- # non-height part of e1,e2 could be is the 1*(dim(K) - 1). We
- # need to make it less than one (the height of the cone) so
- # that the whole thing is in the cone. The norm of the
- # non-height part is sqrt(dim(K) - 1), and we can divide by
- # twice that.
- fudge_factor = 1.0 / (2.0*sqrt(K.dimension() - 1.0))
- e1 += [fudge_factor*uniform(0, 1) for idx in range(K.dimension() - 1)]
- e2 += [fudge_factor*uniform(0, 1) for idx in range(K.dimension() - 1)]
- L = _random_square_matrix(K.dimension())
-
- return (L, K, e1, e2)
-
-
-class SymmetricLinearGameTest(TestCase):
- """
- Tests for the SymmetricLinearGame and Solution classes.
- """
- def assert_within_tol(self, first, second):
- """
- Test that ``first`` and ``second`` are equal within our default
- tolerance.
- """
- self.assertTrue(abs(first - second) < options.ABS_TOL)
-
-
- def assert_norm_within_tol(self, first, second):
- """
- Test that ``first`` and ``second`` vectors are equal in the
- sense that the norm of their difference is within our default
- tolerance.
- """
- self.assert_within_tol(norm(first - second), 0)
-
-
- def assert_solution_exists(self, L, K, e1, e2):
- """
- Given the parameters needed to construct a SymmetricLinearGame,
- ensure that that game has a solution.
- """
- G = SymmetricLinearGame(L, K, e1, e2)
- soln = G.solution()
-
- # The matrix() constructor assumes that ``L`` is a list of
- # columns, so we transpose it to agree with what
- # SymmetricLinearGame() thinks.
- L_matrix = matrix(L).trans()
- expected = inner_product(L_matrix*soln.player1_optimal(),
- soln.player2_optimal())
- self.assert_within_tol(soln.game_value(), expected)
-
-
- def test_solution_exists_orthant(self):
- """
- Every linear game has a solution, so we should be able to solve
- every symmetric linear game over the NonnegativeOrthant. Pick
- some parameters randomly and give it a shot. The resulting
- optimal solutions should give us the optimal game value when we
- apply the payoff operator to them.
- """
- (L, K, e1, e2) = _random_orthant_params()
- self.assert_solution_exists(L, K, e1, e2)
-
-
- def test_solution_exists_icecream(self):
- """
- Like :meth:`test_solution_exists_nonnegative_orthant`, except
- over the ice cream cone.
- """
- (L, K, e1, e2) = _random_icecream_params()
- self.assert_solution_exists(L, K, e1, e2)
-
-
- def test_negative_value_z_operator(self):
- """
- Test the example given in Gowda/Ravindran of a Z-matrix with
- negative game value on the nonnegative orthant.
- """
- K = NonnegativeOrthant(2)
- e1 = [1, 1]
- e2 = e1
- L = [[1, -2], [-2, 1]]
- G = SymmetricLinearGame(L, K, e1, e2)
- self.assertTrue(G.solution().game_value() < -options.ABS_TOL)
-
-
- def assert_scaling_works(self, L, K, e1, e2):
- """
- Test that scaling ``L`` by a nonnegative number scales the value
- of the game by the same number.
- """
- # Make ``L`` a matrix so that we can scale it by alpha. Its
- # random, so who cares if it gets transposed.
- L = matrix(L)
- game1 = SymmetricLinearGame(L, K, e1, e2)
- value1 = game1.solution().game_value()
-
- alpha = uniform(0.1, 10)
- game2 = SymmetricLinearGame(alpha*L, K, e1, e2)
- value2 = game2.solution().game_value()
- self.assert_within_tol(alpha*value1, value2)
-
-
- def test_scaling_orthant(self):
- """
- Test that scaling ``L`` by a nonnegative number scales the value
- of the game by the same number over the nonnegative orthant.
- """
- (L, K, e1, e2) = _random_orthant_params()
- self.assert_scaling_works(L, K, e1, e2)
-
-
- def test_scaling_icecream(self):
- """
- The same test as :meth:`test_nonnegative_scaling_orthant`,
- except over the ice cream cone.
- """
- (L, K, e1, e2) = _random_icecream_params()
- self.assert_scaling_works(L, K, e1, e2)
-
-
- def assert_translation_works(self, L, K, e1, e2):
- """
- Check that translating ``L`` by alpha*(e1*e2.trans()) increases
- the value of the associated game by alpha.
- """
- e1 = matrix(e1, (K.dimension(), 1))
- e2 = matrix(e2, (K.dimension(), 1))
- game1 = SymmetricLinearGame(L, K, e1, e2)
- soln1 = game1.solution()
- value1 = soln1.game_value()
- x_bar = soln1.player1_optimal()
- y_bar = soln1.player2_optimal()
-
- # Make ``L`` a CVXOPT matrix so that we can do math with
- # it. Note that this gives us the "correct" representation of
- # ``L`` (in agreement with what G has), but COLUMN indexed.
- alpha = uniform(-10, 10)
- L = matrix(L).trans()
- tensor_prod = e1*e2.trans()
-
- # Likewise, this is the "correct" representation of ``M``, but
- # COLUMN indexed...
- M = L + alpha*tensor_prod
-
- # so we have to transpose it when we feed it to the constructor.
- game2 = SymmetricLinearGame(M.trans(), K, e1, e2)
- value2 = game2.solution().game_value()
-
- self.assert_within_tol(value1 + alpha, value2)
-
- # Make sure the same optimal pair works.
- self.assert_within_tol(value2, inner_product(M*x_bar, y_bar))
-
-
- def test_translation_orthant(self):
- """
- Test that translation works over the nonnegative orthant.
- """
- (L, K, e1, e2) = _random_orthant_params()
- self.assert_translation_works(L, K, e1, e2)
-
-
- def test_translation_icecream(self):
- """
- The same as :meth:`test_translation_orthant`, except over the
- ice cream cone.
- """
- (L, K, e1, e2) = _random_icecream_params()
- self.assert_translation_works(L, K, e1, e2)
-
-
- def assert_opposite_game_works(self, L, K, e1, e2):
- """
- Check the value of the "opposite" game that gives rise to a
- value that is the negation of the original game. Comes from
- some corollary.
- """
- e1 = matrix(e1, (K.dimension(), 1))
- e2 = matrix(e2, (K.dimension(), 1))
- game1 = SymmetricLinearGame(L, K, e1, e2)
-
- # Make ``L`` a CVXOPT matrix so that we can do math with
- # it. Note that this gives us the "correct" representation of
- # ``L`` (in agreement with what G has), but COLUMN indexed.
- L = matrix(L).trans()
-
- # Likewise, this is the "correct" representation of ``M``, but
- # COLUMN indexed...
- M = -L.trans()
-
- # so we have to transpose it when we feed it to the constructor.
- game2 = SymmetricLinearGame(M.trans(), K, e2, e1)
-
- soln1 = game1.solution()
- x_bar = soln1.player1_optimal()
- y_bar = soln1.player2_optimal()
- soln2 = game2.solution()
-
- self.assert_within_tol(-soln1.game_value(), soln2.game_value())
-
- # Make sure the switched optimal pair works.
- self.assert_within_tol(soln2.game_value(),
- inner_product(M*y_bar, x_bar))
-
-
- def test_opposite_game_orthant(self):
- """
- Test the value of the "opposite" game over the nonnegative
- orthant.
- """
- (L, K, e1, e2) = _random_orthant_params()
- self.assert_opposite_game_works(L, K, e1, e2)
-
-
- def test_opposite_game_icecream(self):
- """
- Like :meth:`test_opposite_game_orthant`, except over the
- ice-cream cone.
- """
- (L, K, e1, e2) = _random_icecream_params()
- self.assert_opposite_game_works(L, K, e1, e2)
-
-
- def assert_orthogonality(self, L, K, e1, e2):
- """
- Two orthogonality relations hold at an optimal solution, and we
- check them here.
- """
- game = SymmetricLinearGame(L, K, e1, e2)
- soln = game.solution()
- x_bar = soln.player1_optimal()
- y_bar = soln.player2_optimal()
- value = soln.game_value()
-
- # Make these matrices so that we can compute with them.
- L = matrix(L).trans()
- e1 = matrix(e1, (K.dimension(), 1))
- e2 = matrix(e2, (K.dimension(), 1))
-
- ip1 = inner_product(y_bar, L*x_bar - value*e1)
- self.assert_within_tol(ip1, 0)
-
- ip2 = inner_product(value*e2 - L.trans()*y_bar, x_bar)
- self.assert_within_tol(ip2, 0)
-
-
- def test_orthogonality_orthant(self):
- """
- Check the orthgonality relationships that hold for a solution
- over the nonnegative orthant.
- """
- (L, K, e1, e2) = _random_orthant_params()
- self.assert_orthogonality(L, K, e1, e2)
-
-
- def test_orthogonality_icecream(self):
- """
- Check the orthgonality relationships that hold for a solution
- over the ice-cream cone.
- """
- (L, K, e1, e2) = _random_icecream_params()
- self.assert_orthogonality(L, K, e1, e2)
-
-
- def test_positive_operator_value(self):
- """
- Test that a positive operator on the nonnegative orthant gives
- rise to a a game with a nonnegative value.
-
- This test theoretically applies to the ice-cream cone as well,
- but we don't know how to make positive operators on that cone.
- """
- (L, K, e1, e2) = _random_orthant_params()
-
- # Make the entries of ``L`` nonnegative... this makes it a
- # positive operator on ``K``.
- L = [[abs(entry) for entry in row] for row in L]
-
- game = SymmetricLinearGame(L, K, e1, e2)
- self.assertTrue(game.solution().game_value() >= -options.ABS_TOL)