From: Michael Orlitzky Date: Tue, 1 Nov 2016 22:25:23 +0000 (-0400) Subject: Enable docs for the new test modules and clean them up. X-Git-Tag: 0.1.0~85 X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=17055c563e53d29a6e72195b335e0c00f846cf78;p=dunshire.git Enable docs for the new test modules and clean them up. --- diff --git a/doc/source/developer-api.rst b/doc/source/developer-api.rst index aa7898f..39d2611 100644 --- a/doc/source/developer-api.rst +++ b/doc/source/developer-api.rst @@ -52,6 +52,22 @@ test module :undoc-members: :show-inheritance: +test.matrices_test +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: test.matrices_test + :members: + :undoc-members: + :show-inheritance: + +test.randomgen +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: test.randomgen + :members: + :undoc-members: + :show-inheritance: + test.symmetric_linear_game_test module ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/test/randomgen.py b/test/randomgen.py index afe0dae..395408c 100644 --- a/test/randomgen.py +++ b/test/randomgen.py @@ -23,12 +23,14 @@ properties within reason. def random_scalar(): """ - Generate a random scalar in ``[-RANDOM_MAX, RANDOM_MAX]``. + Generate a random scalar. Returns ------- float + A random real number between ``-RANDOM_MAX`` and ``RANDOM_MAX``, + inclusive. Examples -------- @@ -42,12 +44,14 @@ def random_scalar(): def random_nn_scalar(): """ - Generate a random nonnegative scalar in ``[0, RANDOM_MAX]``. + Generate a random nonnegative scalar. Returns ------- float + A random nonnegative real number between zero and ``RANDOM_MAX``, + inclusive. Examples -------- @@ -61,13 +65,13 @@ def random_nn_scalar(): def random_natural(): """ - Generate a random natural number between ``1 and RANDOM_MAX`` - inclusive. + Generate a random natural number. Returns ------- int + A random natural number between ``1`` and ``RANDOM_MAX`` inclusive. Examples -------- @@ -98,7 +102,7 @@ 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]. + the interval ``[-RANDOM_MAX, RANDOM_MAX]``. Examples -------- @@ -263,7 +267,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]. + from the interval ``[-RANDOM_MAX, RANDOM_MAX]``. References ---------- @@ -297,12 +301,19 @@ def random_lyapunov_like_icecream(dims): def random_orthant_game(): """ - Generate the ``L``, ``K``, ``e1``, and ``e2`` parameters for a - random game over the nonnegative orthant, and return the - corresponding :class:`SymmetricLinearGame`. + Generate a random game over the nonnegative orthant. + + 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``. + + Returns + ------- + + SymmetricLinearGame + A random game over some nonnegative orthant. - We keep going until we generate a game with a condition number under - MAX_COND. """ ambient_dim = random_natural() + 1 K = NonnegativeOrthant(ambient_dim) @@ -319,12 +330,19 @@ def random_orthant_game(): def random_icecream_game(): """ - Generate the ``L``, ``K``, ``e1``, and ``e2`` parameters for a - random game over the ice-cream cone, and return the corresponding - :class:`SymmetricLinearGame`. + Generate a random game over the ice-cream cone. + + 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``. + + Returns + ------- + + SymmetricLinearGame + A random game over some ice-cream cone. - We keep going until we generate a game with a condition number under - MAX_COND. """ # Use a minimum dimension of two to avoid divide-by-zero in # the fudge factor we make up later. @@ -361,6 +379,14 @@ def random_ll_orthant_game(): things are Lyapunov-like on the nonnegative orthant. That process is repeated until the condition number of the resulting game is within ``MAX_COND``. + + Returns + ------- + + SymmetricLinearGame + A random game over some nonnegative orthant whose ``payoff`` method + is based on a Lyapunov-like ``L`` operator. + """ G = random_orthant_game() L = random_diagonal_matrix(G._K.dimension()) @@ -385,6 +411,14 @@ def random_ll_icecream_game(): 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``. + + Returns + ------- + + SymmetricLinearGame + A random game over some ice-cream cone whose ``payoff`` method + is based on a Lyapunov-like ``L`` operator. + """ G = random_icecream_game() L = random_lyapunov_like_icecream(G._K.dimension()) @@ -410,6 +444,14 @@ def random_positive_orthant_game(): 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``. + + Returns + ------- + + SymmetricLinearGame + A random game over some nonnegative orthant whose ``payoff`` method + is based on a positive ``L`` operator. + """ G = random_orthant_game() @@ -431,15 +473,18 @@ def random_nn_scaling(G): """ Scale the given game by a random nonnegative amount. + We re-attempt the scaling with a new random number until the + resulting scaled game has an acceptable condition number. + Parameters ---------- - G : :class:`SymmetricLinearGame` + G : SymmetricLinearGame The game that you would like to scale. Returns ------- - (float, :class:`SymmetricLinearGame`) + (float, SymmetricLinearGame) A pair containing the both the scaling factor and the new scaled game. """ @@ -458,15 +503,18 @@ def random_translation(G): """ Translate the given game by a random amount. + We re-attempt the translation with new random scalars until the + resulting translated game has an acceptable condition number. + Parameters ---------- - G : :class:`SymmetricLinearGame` + G : SymmetricLinearGame The game that you would like to translate. Returns ------- - (float, :class:`SymmetricLinearGame`) + (float, SymmetricLinearGame) A pair containing the both the translation distance and the new scaled game.