From: Michael Orlitzky Date: Wed, 16 Nov 2016 01:12:53 +0000 (-0500) Subject: A bunch more doc fixes. X-Git-Tag: 0.1.0~2 X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=0274de467062ab29d2a41d2a91ec0b28fcd95c8d;p=dunshire.git A bunch more doc fixes. --- diff --git a/dunshire/games.py b/dunshire/games.py index 7dd2806..ea7a64f 100644 --- a/dunshire/games.py +++ b/dunshire/games.py @@ -924,16 +924,18 @@ class SymmetricLinearGame: 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 @@ -967,7 +969,8 @@ class SymmetricLinearGame: ------- 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 @@ -1004,7 +1007,7 @@ class SymmetricLinearGame: Returns ------- - :class:`Solution` + Solution A :class:`Solution` object describing the game's value and the optimal strategies of both players. diff --git a/dunshire/matrices.py b/dunshire/matrices.py index a5a02e9..f35827d 100644 --- a/dunshire/matrices.py +++ b/dunshire/matrices.py @@ -18,8 +18,11 @@ def append_col(left, right): Parameters ---------- - left, right : matrix - The two matrices to append to one another. + left : matrix + The "original" matrix, the one that will wind up on the left. + + right : matrix + The matrix to be appended on the right of ``left``. Returns ------- @@ -57,8 +60,11 @@ def append_row(top, bottom): Parameters ---------- - top, bottom : matrix - The two matrices to append to one another. + top : matrix + The "original" matrix, the one that will wind up on top. + + bottom : matrix + The matrix to be appended below ``top``. Returns ------- @@ -265,8 +271,11 @@ def inner_product(vec1, vec2): Parameters ---------- - vec1, vec2 : matrix - The two vectors whose inner product you want. + vec1 : matrix + The first vector, whose inner product with ``vec2`` you want. + + vec2 : matrix + The second vector, whose inner product with ``vec1`` you want. Returns ------- @@ -346,7 +355,7 @@ def specnorm(mat): Return the spectral norm of a matrix. The spectral norm of a matrix is its largest singular value, and it - corresponds to the operator norm induced by the vector ``2``-norm. + corresponds to the operator norm induced by the vector Euclidean norm. Parameters ---------- diff --git a/dunshire/options.py b/dunshire/options.py index 9b3ddc3..a66abb7 100644 --- a/dunshire/options.py +++ b/dunshire/options.py @@ -18,7 +18,7 @@ philosophers. DEBUG_FLOAT_FORMAT = '%.20f' """ The float output format to use when something goes wrong. If we need to -produce a random test case, for example, then we need all of the digits +reproduce a random test case, for example, then we need all of the digits of the things involved. If we try to recreate the problem using only, say, the first seven digits of each number, then the resulting game might not reproduce the failure. @@ -26,7 +26,5 @@ might not reproduce the failure. FLOAT_FORMAT = '%.7f' """ -The default output format for floating point numbers. It has been -chosen to match the ``ABS_TOL``, in the sense that if ``x != y``, -then they would not appear different when printed. +The default output format for floating point numbers. """ diff --git a/test/__init__.py b/test/__init__.py index 2e23a7c..8c0de9e 100644 --- a/test/__init__.py +++ b/test/__init__.py @@ -46,8 +46,8 @@ def build_suite(doctests=True): def run_suite(suite): """ - Run all of the unit and doctests for the ``dunshire`` and ``test`` - packages. + Run all of the unit and doctests for the :mod:`dunshire` and + :mod:`test` packages. """ runner = TextTestRunner(verbosity=1) return runner.run(suite) diff --git a/test/matrices_test.py b/test/matrices_test.py index e755f31..69f9da9 100644 --- a/test/matrices_test.py +++ b/test/matrices_test.py @@ -1,5 +1,5 @@ """ -Unit tests for the functions in the ``matrices`` module. +Unit tests for the functions in the :mod:`dunshire.matrices` module. """ from copy import deepcopy @@ -36,7 +36,7 @@ class AppendColTest(TestCase): class AppendRowTest(TestCase): """ - Tests for the :func:`append_row` function. + Tests for the :func:`dunshire.matrices.append_row` function. """ def test_new_dimensions(self): @@ -58,7 +58,7 @@ class AppendRowTest(TestCase): class EigenvaluesTest(TestCase): """ - Tests for the :func:`eigenvalues` function. + Tests for the :func:`dunshire.matrices.eigenvalues` function. """ def test_eigenvalues_input_not_clobbered(self): @@ -82,8 +82,9 @@ class EigenvaluesTest(TestCase): def test_eigenvalues_of_symmat_are_real(self): """ A real symmetric matrix has real eigenvalues, so if we start - with a symmetric matrix, then the two functions :func:`eigenvalues` - and :func:`eigenvalues_re` should agree on it. + with a symmetric matrix, then the two functions + :func:`dunshire.matrices.eigenvalues` and + :func:`dunshire.matrices.eigenvalues_re` should agree on it. """ mat = random_matrix(random_natural()) symmat = mat + mat.trans() @@ -103,20 +104,21 @@ class EigenvaluesTest(TestCase): class EigenvaluesRealPartTest(TestCase): """ - Tests for the :func:`eigenvalues_re` function. + Tests for the :func:`dunshire.matrices.eigenvalues_re` function. """ def test_eigenvalues_re_input_not_clobbered(self): """ - The eigenvalue functions provided by CVXOPT/LAPACK like to - overwrite the matrices that you pass into them as - arguments. This test makes sure that our :func:`eigenvalues_re` - function does not do the same. + The eigenvalue functions provided by CVXOPT/LAPACK like + to overwrite the matrices that you pass into them as + arguments. This test makes sure that our + :func:`dunshire.matrices.eigenvalues_re` function does not do + the same. We use a ``deepcopy`` here in case the ``copy`` used in the - :func:`eigenvalues_re` function is insufficient. If ``copy`` didn't - work and this test used it too, then this test would pass when - it shouldn't. + :func:`dunshire.matrices.eigenvalues_re` function is + insufficient. If ``copy`` didn't work and this test used it too, + then this test would pass when it shouldn't. """ mat = random_matrix(random_natural()) mat_copy = deepcopy(mat) @@ -134,14 +136,15 @@ class EigenvaluesRealPartTest(TestCase): class InnerProductTest(TestCase): """ - Tests for the :func:`inner_product` function. + Tests for the :func:`dunshire.matrices.inner_product` function. """ def test_inner_product_with_self_is_norm_squared(self): """ - Ensure that the func:`inner_product` and :func:`norm` functions - are compatible by checking that the square of the norm of a - vector is its inner product with itself. + Ensure that the func:`dunshire.matrices.inner_product` and + :func:`dunshire.matrices.norm` functions are compatible by + checking that the square of the norm of a vector is its inner + product with itself. """ vec = random_matrix(random_natural(), 1) actual = inner_product(vec, vec) @@ -151,7 +154,7 @@ class InnerProductTest(TestCase): class NormTest(TestCase): """ - Tests for the :func:`norm` function. + Tests for the :func:`dunshire.matrices.norm` function. """ def test_norm_is_nonnegative(self): @@ -164,7 +167,7 @@ class NormTest(TestCase): class ConditionNumberTest(TestCase): """ - Tests for the :func:`condition_number` function. + Tests for the :func:`dunshire.matrices.condition_number` function. """ def test_condition_number_ge_one(self): diff --git a/test/randomgen.py b/test/randomgen.py index 8c3c863..bfc70f3 100644 --- a/test/randomgen.py +++ b/test/randomgen.py @@ -33,8 +33,8 @@ def random_scalar(): ------- float - A random real number between ``-RANDOM_MAX`` and ``RANDOM_MAX``, - inclusive. + A random real number between negative and positive + :const:`RANDOM_MAX`, inclusive. Examples -------- @@ -54,8 +54,8 @@ def random_nn_scalar(): ------- float - A random nonnegative real number between zero and ``RANDOM_MAX``, - inclusive. + A random nonnegative real number between zero and + :const:`RANDOM_MAX`, inclusive. Examples -------- @@ -75,7 +75,8 @@ def random_natural(): ------- int - A random natural number between ``1`` and ``RANDOM_MAX`` inclusive. + A random natural number between ``1`` and :const:`RANDOM_MAX`, + inclusive. Examples -------- @@ -105,8 +106,8 @@ def random_matrix(row_count, column_count=None): ------- matrix - A new matrix whose entries are random floats chosen uniformly from - the interval ``[-RANDOM_MAX, RANDOM_MAX]``. + A new matrix whose entries are random floats chosen uniformly + between negative and positive :const:`RANDOM_MAX`. Examples -------- @@ -188,7 +189,7 @@ def random_diagonal_matrix(dims): matrix A new matrix whose diagonal entries are random floats chosen - using func:`random_scalar` and whose off-diagonal entries are + using :func:`random_scalar` and whose off-diagonal entries are zero. Examples @@ -271,7 +272,7 @@ def random_lyapunov_like_icecream(dims): 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 ``[-RANDOM_MAX, RANDOM_MAX]``. + between negative and positive :const:`RANDOM_MAX`. References ---------- @@ -310,7 +311,7 @@ def random_orthant_game(): We generate each of ``L``, ``K``, ``e1``, and ``e2`` randomly within the constraints of the nonnegative orthant, and then construct a game from them. The process is repeated until we generate a game with - a condition number under ``MAX_COND``. + a condition number under :const:`MAX_COND`. Returns ------- @@ -345,7 +346,7 @@ def random_icecream_game(): We generate each of ``L``, ``K``, ``e1``, and ``e2`` randomly within the constraints of the ice-cream cone, and then construct a game from them. The process is repeated until we generate a game with a - condition number under ``MAX_COND``. + condition number under :const:`MAX_COND`. Returns ------- @@ -394,14 +395,17 @@ def random_ll_orthant_game(): to have a :func:`random_diagonal_matrix` as its operator. Such things are Lyapunov-like on the nonnegative orthant. That process is repeated until the condition number of the resulting game is within - ``MAX_COND``. + :const:`MAX_COND`. Returns ------- SymmetricLinearGame - A random game over some nonnegative orthant whose ``payoff`` method - is based on a Lyapunov-like ``L`` operator. + + A random game over some nonnegative orthant whose + :meth:`dunshire.games.SymmetricLinearGame.payoff` method is + based on a Lyapunov-like + :meth:`dunshire.games.SymmetricLinearGame.L` operator. Examples -------- @@ -432,14 +436,16 @@ def random_ll_icecream_game(): We first construct a :func:`random_icecream_game` and then modify it to have a :func:`random_lyapunov_like_icecream` operator. That process is repeated until the condition number of the resulting game - is within ``MAX_COND``. + is within :const:`MAX_COND`. Returns ------- SymmetricLinearGame - A random game over some ice-cream cone whose ``payoff`` method - is based on a Lyapunov-like ``L`` operator. + A random game over some ice-cream cone whose + :meth:`dunshire.games.SymmetricLinearGame.payoff` method + is based on a Lyapunov-like + :meth:`dunshire.games.SymmetricLinearGame.L` operator. Examples -------- @@ -471,14 +477,16 @@ def random_positive_orthant_game(): We first construct a :func:`random_orthant_game` and then modify it to have a :func:`random_nonnegative_matrix` as its operator. That process is repeated until the condition number of the resulting game - is within ``MAX_COND``. + is within :const:`MAX_COND`. Returns ------- SymmetricLinearGame - A random game over some nonnegative orthant whose ``payoff`` method - is based on a positive ``L`` operator. + A random game over some nonnegative orthant whose + :meth:`dunshire.games.SymmetricLinearGame.payoff` method + is based on a positive + :meth:`dunshire.games.SymmetricLinearGame.L` operator. Examples --------