From fca2dba7c55f8eb55462c8376d56266792701de1 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Tue, 15 Nov 2016 10:57:49 -0500 Subject: [PATCH] Add missing examples for two methods and use math for equations. --- dunshire/games.py | 62 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 15 deletions(-) diff --git a/dunshire/games.py b/dunshire/games.py index 6ab420d..19b2f5b 100644 --- a/dunshire/games.py +++ b/dunshire/games.py @@ -577,11 +577,11 @@ class SymmetricLinearGame: def A(self): - """ + r""" Return the matrix ``A`` used in our CVXOPT construction. - This matrix ``A`` appears on the right-hand side of ``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:: @@ -617,8 +617,8 @@ class SymmetricLinearGame: r""" Return the matrix ``G`` used in our CVXOPT construction. - Thus matrix ``G`` appears on the left-hand side of ``Gx + s = h`` - in the statement of the CVXOPT conelp program. + Thus matrix :math:`G` appears on the left-hand side of :math:`Gx + + s = h` in the statement of the CVXOPT conelp program. .. warning:: @@ -656,11 +656,12 @@ class SymmetricLinearGame: def c(self): - """ + r""" Return the vector ``c`` used in our CVXOPT construction. - The column vector ``c`` appears in the objective function - value ```` in the statement of the CVXOPT conelp program. + 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. .. warning:: @@ -697,8 +698,7 @@ class SymmetricLinearGame: """ Return the cone ``C`` used in our CVXOPT construction. - The cone ``C`` is the cone over which the conelp program takes - place. + This is the cone over which the conelp program takes place. Returns ------- @@ -727,7 +727,7 @@ class SymmetricLinearGame: r""" Return the ``h`` vector used in our CVXOPT construction. - The ``h`` vector appears on the right-hand side of :math:`Gx + s + The :math:`h` vector appears on the right-hand side of :math:`Gx + s = h` in the statement of the CVXOPT conelp program. .. warning:: @@ -893,6 +893,19 @@ class SymmetricLinearGame: A nonnegative real number; the largest singular value of the matrix :meth:`L`. + Examples + -------- + + >>> from dunshire import * + >>> from dunshire.matrices import specnorm + >>> L = [[1,2],[3,4]] + >>> K = NonnegativeOrthant(2) + >>> e1 = [1,1] + >>> e2 = e1 + >>> SLG = SymmetricLinearGame(L,K,e1,e2) + >>> specnorm(SLG.L()) == SLG._L_specnorm() + True + """ if self._L_specnorm_value is None: self._L_specnorm_value = specnorm(self.L()) @@ -947,6 +960,23 @@ class SymmetricLinearGame: A scaling factor to be multiplied by ``ABS_TOL`` when making comparisons involving solutions of this game. + Examples + -------- + + The spectral norm of ``L`` in this case is around ``5.464``, and + the optimal strategies both have norm one, so we expect the + tolerance scale to be somewhere around ``2 * 5.464``, or + ``10.929``:: + + >>> from dunshire import * + >>> L = [[1,2],[3,4]] + >>> K = NonnegativeOrthant(2) + >>> e1 = [1,1] + >>> e2 = e1 + >>> SLG = SymmetricLinearGame(L,K,e1,e2) + >>> SLG.tolerance_scale(SLG.solution()) + 10.929... + """ norm_p1_opt = norm(solution.player1_optimal()) norm_p2_opt = norm(solution.player2_optimal()) @@ -1172,12 +1202,14 @@ class SymmetricLinearGame: # same. Even if CVXOPT bails out due to numerical difficulty, # it will have some candidate points in mind. If those # candidates are good enough, we take them. We do the same - # check (perhaps pointlessly so) for "optimal" results. + # check for "optimal" results. # # First we check that the primal/dual objective values are - # close enough (one could be low by ABS_TOL, the other high by - # it) because otherwise CVXOPT might return "unknown" and give - # us two points in the cone that are nowhere near optimal. + # close enough because otherwise CVXOPT might return "unknown" + # and give us two points in the cone that are nowhere near + # optimal. And in fact, we need to ensure that they're close + # for "optimal" results, too, because we need to know how + # lenient to be in our testing. # if abs(p1_value - p2_value) > self.tolerance_scale(soln)*ABS_TOL: printing.options['dformat'] = DEBUG_FLOAT_FORMAT -- 2.43.2