--- /dev/null
+"""
+Unit tests for the :class:`SymmetricLinearGame` class.
+"""
+
+from math import sqrt
+from random import randint, uniform
+from unittest import TestCase
+
+from cvxopt import matrix
+from dunshire.cones import NonnegativeOrthant, IceCream
+from dunshire.games import SymmetricLinearGame
+from dunshire.matrices import (append_col, append_row, eigenvalues_re,
+ identity, inner_product)
+from dunshire import options
+
+
+def random_matrix(dims):
+ """
+ Generate a random square matrix.
+
+ Parameters
+ ----------
+
+ dims : int
+ The number of rows/columns you want in the returned matrix.
+
+ Returns
+ -------
+
+ matrix
+ A new matrix whose entries are random floats chosen uniformly from
+ the interval [-10, 10].
+
+ Examples
+ --------
+
+ >>> A = random_matrix(3)
+ >>> A.size
+ (3, 3)
+
+ """
+ return matrix([[uniform(-10, 10) for i in range(dims)]
+ for j in range(dims)])
+
+
+def random_nonnegative_matrix(dims):
+ """
+ Generate a random square matrix with nonnegative entries.
+
+ Parameters
+ ----------
+
+ dims : int
+ The number of rows/columns you want in the returned matrix.
+
+ Returns
+ -------
+
+ matrix
+ A new matrix whose entries are random floats chosen uniformly from
+ the interval [0, 10].
+
+ Examples
+ --------
+
+ >>> A = random_nonnegative_matrix(3)
+ >>> A.size
+ (3, 3)
+ >>> all([entry >= 0 for entry in A])
+ True
+
+ """
+ L = random_matrix(dims)
+ return matrix([abs(entry) for entry in L], (dims, dims))
+
+
+def random_diagonal_matrix(dims):
+ """
+ Generate a random square matrix with zero off-diagonal entries.
+
+ These matrices are Lyapunov-like on the nonnegative orthant, as is
+ fairly easy to see.
+
+ Parameters
+ ----------
+
+ dims : int
+ The number of rows/columns you want in the returned matrix.
+
+ Returns
+ -------
+
+ matrix
+ A new matrix whose diagonal entries are random floats chosen
+ uniformly from the interval [-10, 10] and whose off-diagonal
+ entries are zero.
+
+ Examples
+ --------
+
+ >>> A = random_diagonal_matrix(3)
+ >>> A.size
+ (3, 3)
+ >>> A[0,1] == A[0,2] == A[1,0] == A[2,0] == A[1,2] == A[2,1] == 0
+ True
+
+ """
+ return matrix([[uniform(-10, 10)*int(i == j) for i in range(dims)]
+ for j in range(dims)])
+
+
+def random_skew_symmetric_matrix(dims):
+ """
+ Generate a random skew-symmetrix matrix.
+
+ Parameters
+ ----------
+
+ dims : int
+ The number of rows/columns you want in the returned matrix.
+
+ Returns
+ -------
+
+ matrix
+ A new skew-matrix whose strictly above-diagonal entries are
+ random floats chosen uniformly from the interval [-10, 10].
+
+ Examples
+ --------
+
+ >>> A = random_skew_symmetric_matrix(3)
+ >>> A.size
+ (3, 3)
+
+ >>> from dunshire.matrices import norm
+ >>> A = random_skew_symmetric_matrix(randint(1, 10))
+ >>> norm(A + A.trans()) < options.ABS_TOL
+ True
+
+ """
+ strict_ut = [[uniform(-10, 10)*int(i < j) for i in range(dims)]
+ for j in range(dims)]
+
+ strict_ut = matrix(strict_ut, (dims, dims))
+ return strict_ut - strict_ut.trans()
+
+
+def random_lyapunov_like_icecream(dims):
+ r"""
+ Generate a random matrix Lyapunov-like on the ice-cream cone.
+
+ The form of these matrices is cited in Gowda and Tao
+ [GowdaTao]_. The scalar ``a`` and the vector ``b`` (using their
+ notation) are easy to generate. The submatrix ``D`` is a little
+ trickier, but it can be found noticing that :math:`C + C^{T} = 0`
+ for a skew-symmetric matrix :math:`C` implying that :math:`C + C^{T}
+ + \left(2a\right)I = \left(2a\right)I`. Thus we can stick an
+ :math:`aI` with each of :math:`C,C^{T}` and let those be our
+ :math:`D,D^{T}`.
+
+ Parameters
+ ----------
+
+ dims : int
+ The dimension of the ice-cream cone (not of the matrix you want!)
+ on which the returned matrix should be Lyapunov-like.
+
+ Returns
+ -------
+
+ matrix
+ A new matrix, Lyapunov-like on the ice-cream cone in ``dims``
+ dimensions, whose free entries are random floats chosen uniformly
+ from the interval [-10, 10].
+
+ References
+ ----------
+
+ .. [GowdaTao] M. S. Gowda and J. Tao. On the bilinearity rank of a
+ proper cone and Lyapunov-like transformations. Mathematical
+ Programming, 147:155-170, 2014.
+
+ Examples
+ --------
+
+ >>> L = random_lyapunov_like_icecream(3)
+ >>> L.size
+ (3, 3)
+ >>> x = matrix([1,1,0])
+ >>> s = matrix([1,-1,0])
+ >>> abs(inner_product(L*x, s)) < options.ABS_TOL
+ True
+
+ """
+ a = matrix([uniform(-10, 10)], (1, 1))
+ b = matrix([uniform(-10, 10) for idx in range(dims-1)], (dims-1, 1))
+ D = random_skew_symmetric_matrix(dims-1) + a*identity(dims-1)
+ row1 = append_col(a, b.trans())
+ row2 = append_col(b, D)
+ return append_row(row1, row2)
+
+
+def random_orthant_params():
+ """
+ Generate the ``L``, ``K``, ``e1``, and ``e2`` parameters for a
+ random game over the nonnegative orthant.
+ """
+ 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_matrix(K.dimension())
+ return (L, K, matrix(e1), matrix(e2))
+
+
+def random_icecream_params():
+ """
+ Generate the ``L``, ``K``, ``e1``, and ``e2`` parameters for a
+ random game over the ice-cream cone.
+ """
+ # 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_matrix(K.dimension())
+
+ return (L, K, matrix(e1), matrix(e2))
+
+
+# Tell pylint to shut up about the large number of methods.
+class SymmetricLinearGameTest(TestCase): # pylint: disable=R0904
+ """
+ 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_solution_exists(self, L, K, e1, e2):
+ """
+ Given the parameters needed to construct a SymmetricLinearGame,
+ ensure that that game has a solution.
+ """
+ # The matrix() constructor assumes that ``L`` is a list of
+ # columns, so we transpose it to agree with what
+ # SymmetricLinearGame() thinks.
+ G = SymmetricLinearGame(L.trans(), K, e1, e2)
+ soln = G.solution()
+
+ expected = inner_product(L*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.
+ """
+ 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.
+ """
+ # We need to use ``L`` later, so make sure we transpose it
+ # before passing it in as a column-indexed matrix.
+ game1 = SymmetricLinearGame(L.trans(), K, e1, e2)
+ soln1 = game1.solution()
+ value1 = soln1.game_value()
+ x_bar = soln1.player1_optimal()
+ y_bar = soln1.player2_optimal()
+
+ alpha = uniform(-10, 10)
+ tensor_prod = e1*e2.trans()
+
+ # 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.
+ """
+ # We need to use ``L`` later, so make sure we transpose it
+ # before passing it in as a column-indexed matrix.
+ game1 = SymmetricLinearGame(L.trans(), K, e1, e2)
+
+ # 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.
+ """
+ # We need to use ``L`` later, so make sure we transpose it
+ # before passing it in as a column-indexed matrix.
+ game = SymmetricLinearGame(L.trans(), K, e1, e2)
+ soln = game.solution()
+ x_bar = soln.player1_optimal()
+ y_bar = soln.player2_optimal()
+ value = soln.game_value()
+
+ 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.
+ """
+ (K, e1, e2) = random_orthant_params()[1:]
+ L = random_nonnegative_matrix(K.dimension())
+
+ game = SymmetricLinearGame(L, K, e1, e2)
+ self.assertTrue(game.solution().game_value() >= -options.ABS_TOL)
+
+
+ def assert_lyapunov_works(self, L, K, e1, e2):
+ """
+ Check that Lyapunov games act the way we expect.
+ """
+ game = SymmetricLinearGame(L, K, e1, e2)
+ soln = game.solution()
+
+ # We only check for positive/negative stability if the game
+ # value is not basically zero. If the value is that close to
+ # zero, we just won't check any assertions.
+ eigs = eigenvalues_re(L)
+ if soln.game_value() > options.ABS_TOL:
+ # L should be positive stable
+ positive_stable = all([eig > -options.ABS_TOL for eig in eigs])
+ self.assertTrue(positive_stable)
+ elif soln.game_value() < -options.ABS_TOL:
+ # L should be negative stable
+ negative_stable = all([eig < options.ABS_TOL for eig in eigs])
+ self.assertTrue(negative_stable)
+
+ # The dual game's value should always equal the primal's.
+ dualsoln = game.dual().solution()
+ self.assert_within_tol(dualsoln.game_value(), soln.game_value())
+
+
+ def test_lyapunov_orthant(self):
+ """
+ Test that a Lyapunov game on the nonnegative orthant works.
+ """
+ (K, e1, e2) = random_orthant_params()[1:]
+ L = random_diagonal_matrix(K.dimension())
+
+ self.assert_lyapunov_works(L, K, e1, e2)
+
+
+ def test_lyapunov_icecream(self):
+ """
+ Test that a Lyapunov game on the ice-cream cone works.
+ """
+ (K, e1, e2) = random_icecream_params()[1:]
+ L = random_lyapunov_like_icecream(K.dimension())
+
+ self.assert_lyapunov_works(L, K, e1, e2)
projects / dunshire.git / commitdiff