Clean up and document some of the new test code.

[dunshire.git] / test / randomgen.py

diff --git a/test/randomgen.py b/test/randomgen.py
index 6513440152d3e693618267d6b839faabaf8417f4..afe0dae25304b33e2f01e3fd2cb46ca824cc8771 100644 (file)
--- a/test/randomgen.py
+++ b/test/randomgen.py
@@ -79,15 +79,19 @@ def random_natural():
     return randint(1, RANDOM_MAX)
 
 
-def random_matrix(dims):
+def random_matrix(row_count, column_count=None):
     """
-    Generate a random square matrix.
+    Generate a random matrix.
 
     Parameters
     ----------
 
-    dims : int
-        The number of rows/columns you want in the returned matrix.
+    row_count : int
+        The number of rows you want in the returned matrix.
+
+    column_count: int
+        The number of columns you want in the returned matrix (default:
+        the same as ``row_count``).
 
     Returns
     -------
@@ -103,21 +107,31 @@ def random_matrix(dims):
         >>> A.size
         (3, 3)
 
+        >>> A = random_matrix(3,2)
+        >>> A.size
+        (3, 2)
+
     """
-    return matrix([[random_scalar()
-                    for _ in range(dims)]
-                   for _ in range(dims)])
+    if column_count is None:
+        column_count = row_count
+
+    entries = [random_scalar() for _ in range(row_count*column_count)]
+    return matrix(entries, (row_count, column_count))
 
 
-def random_nonnegative_matrix(dims):
+def random_nonnegative_matrix(row_count, column_count=None):
     """
-    Generate a random square matrix with nonnegative entries.
+    Generate a random matrix with nonnegative entries.
 
     Parameters
     ----------
 
-    dims : int
-        The number of rows/columns you want in the returned matrix.
+    row_count : int
+        The number of rows you want in the returned matrix.
+
+    column_count : int
+        The number of columns you want in the returned matrix (default:
+        the same as ``row_count``).
 
     Returns
     -------
@@ -134,10 +148,18 @@ def random_nonnegative_matrix(dims):
         >>> all([entry >= 0 for entry in A])
         True
 
+        >>> A = random_nonnegative_matrix(3,2)
+        >>> A.size
+        (3, 2)
+        >>> all([entry >= 0 for entry in A])
+        True
+
     """
-    return matrix([[random_nn_scalar()
-                    for _ in range(dims)]
-                   for _ in range(dims)])
+    if column_count is None:
+        column_count = row_count
+
+    entries = [random_nn_scalar() for _ in range(row_count*column_count)]
+    return matrix(entries, (row_count, column_count))
 
 
 def random_diagonal_matrix(dims):
@@ -280,7 +302,7 @@ def random_orthant_game():
     corresponding :class:`SymmetricLinearGame`.
 
     We keep going until we generate a game with a condition number under
-    5000.
+    MAX_COND.
     """
     ambient_dim = random_natural() + 1
     K = NonnegativeOrthant(ambient_dim)
@@ -300,6 +322,9 @@ 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`.
+
+    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.
@@ -330,6 +355,12 @@ def random_icecream_game():
 def random_ll_orthant_game():
     """
     Return a random Lyapunov game over some nonnegative orthant.
+
+    We first construct a :func:`random_orthant_game` and then modify it
+    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``.
     """
     G = random_orthant_game()
     L = random_diagonal_matrix(G._K.dimension())
@@ -349,6 +380,11 @@ def random_ll_orthant_game():
 def random_ll_icecream_game():
     """
     Return a random Lyapunov game over some ice-cream cone.
+
+    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``.
     """
     G = random_icecream_game()
     L = random_lyapunov_like_icecream(G._K.dimension())
@@ -366,6 +402,16 @@ def random_ll_icecream_game():
 
 
 def random_positive_orthant_game():
+    """
+    Return a random game over the nonnegative orthant with a positive
+    operator.
+
+    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``.
+    """
+
     G = random_orthant_game()
     L = random_nonnegative_matrix(G._K.dimension())
 
@@ -382,6 +428,21 @@ def random_positive_orthant_game():
 
 
 def random_nn_scaling(G):
+    """
+    Scale the given game by a random nonnegative amount.
+
+    Parameters
+    ----------
+
+    G : :class:`SymmetricLinearGame`
+        The game that you would like to scale.
+
+    Returns
+    -------
+    (float, :class:`SymmetricLinearGame`)
+        A pair containing the both the scaling factor and the new scaled game.
+
+    """
     alpha = random_nn_scalar()
     H = SymmetricLinearGame(alpha*G._L.trans(), G._K, G._e1, G._e2)
 
@@ -392,7 +453,24 @@ def random_nn_scaling(G):
 
     return (alpha, H)
 
+
 def random_translation(G):
+    """
+    Translate the given game by a random amount.
+
+    Parameters
+    ----------
+
+    G : :class:`SymmetricLinearGame`
+        The game that you would like to translate.
+
+    Returns
+    -------
+    (float, :class:`SymmetricLinearGame`)
+        A pair containing the both the translation distance and the new
+        scaled game.
+
+    """
     alpha = random_scalar()
     tensor_prod = G._e1 * G._e2.trans()
     M = G._L + alpha*tensor_prod