More documentation and comments in test cases.

theano/tensor/tests/test_basic.py

@@ -1795,28 +1795,38 @@ class TestInversePermutation(unittest.TestCase):
         utt.seed_rng()
 
     def test_dim1(self):
+        """Test the inversion of one permutation (int vector)"""
         p = ivector()
         inv = inverse_permutation(p)
         f_inverse = function([p], inv)
 
+        # Generate a random permutation
         rng = numpy.random.RandomState(utt.fetch_seed())
         p_val = rng.permutation(10)
         inv_val = f_inverse(p_val)
 
+        # Check that the inverse of the inverse is the original permutation
         assert numpy.all(f_inverse(inv_val) == p_val)
+        # Check that permutation(inverse) == inverse(permutation) = identity
         assert numpy.all(p_val[inv_val] == numpy.arange(10))
         assert numpy.all(inv_val[p_val] == numpy.arange(10))
 
     def test_dim2(self):
+        """Test the inversion of several permutation at a time"""
+        # Each row of p is a different permutation to inverse
         p = imatrix()
         inv = inverse_permutation(p)
         f_inverse = function([p], inv)
 
         rng = numpy.random.RandomState(utt.fetch_seed())
+        # Generate 10 random permutations
         p_val = numpy.asarray([rng.permutation(10) for i in range(7)])
         inv_val = f_inverse(p_val)
 
+        # Check that the inverse of the inverse is the original permutation list
         assert numpy.all(f_inverse(inv_val) == p_val)
+        # Check that, for each permutation,
+        # permutation(inverse) == inverse(permutation) = identity
         for p_row, i_row in zip(p_val, inv_val):
             assert numpy.all(p_row[i_row] == numpy.arange(10))
             assert numpy.all(i_row[p_row] == numpy.arange(10))
@@ -1827,6 +1837,7 @@ class TestReorderRowElements(unittest.TestCase):
         utt.seed_rng()
 
     def test_1_1(self):
+        """Test ReorderRowElements(vector, vector)"""
         input = vector()
         p = ivector()
         out = reorder_row_elements(input, p)
@@ -1837,15 +1848,18 @@ class TestReorderRowElements(unittest.TestCase):
         p_val = rng.permutation(5)
         out_val = reorder(input_val, p_val)
 
+        # Should be equivalent to advanced indexing
         out_bis = input_val[p_val]
         assert numpy.all(out_val == out_bis)
 
         # Verify gradient
         def reorder_fixed(s_input):
+            """Auxiliary op defined to get rid of gradient wrt p_val"""
             return reorder_row_elements(s_input, p_val)
         utt.verify_grad(reorder_fixed, [input_val])
 
     def test_2_1(self):
+        """Test broadcasting in ReorderRowElements(matrix, vector)"""
         input = matrix()
         p = ivector()
         out = reorder_row_elements(input, p)
@@ -1856,15 +1870,18 @@ class TestReorderRowElements(unittest.TestCase):
         p_val = rng.permutation(5)
         out_val = reorder(input_val, p_val)
 
+        # The same permutation should be applied to every row of the input matrix.
         out_bis = numpy.asarray([row[p_val] for row in input_val])
         assert numpy.all(out_val == out_bis)
 
         # Verify gradient
         def reorder_fixed(s_input):
+            """Auxiliary op defined to get rid of gradient wrt p_val"""
             return reorder_row_elements(s_input, p_val)
         utt.verify_grad(reorder_fixed, [input_val])
 
     def test_2_2(self):
+        """Test ReorderRowElements(matrix, matrix)"""
         input = matrix()
         p = imatrix()
         out = reorder_row_elements(input, p)
@@ -1875,11 +1892,14 @@ class TestReorderRowElements(unittest.TestCase):
         p_val = numpy.asarray([rng.permutation(5) for i in range(3)])
         out_val = reorder(input_val, p_val)
 
+        # Each row of p contains a permutation to apply to the corresponding
+        # row of input
         out_bis = numpy.asarray([i_row[p_row] for i_row, p_row in zip(input_val, p_val)])
         assert numpy.all(out_val == out_bis)
 
         # Verify gradient
         def reorder_fixed(s_input):
+            """Auxiliary op defined to get rid of gradient wrt p_val"""
             return reorder_row_elements(s_input, p_val)
         utt.verify_grad(reorder_fixed, [input_val])
 

theano/tensor/tests/test_randomstreams.py

@@ -139,12 +139,18 @@ class T_RandomStreams(unittest.TestCase):
         assert m.random is m.m2.random
 
     def test_ndim(self):
+        """Test that the behaviour of 'ndim' optional parameter"""
+        # 'ndim' is an optional integer parameter, specifying the length
+        # of the 'shape', placed as first argument.
+
+        # ndim not specified, OK
         m1 = Module()
         m1.random = RandomStreams(234)
         m1.fn = Method([], m1.random.uniform((2,2)))
         made1 = m1.make()
         made1.random.initialize()
 
+        # ndim specified, consistent with shape, OK
         m2 = Module()
         m2.random = RandomStreams(234)
         m2.fn = Method([], m2.random.uniform(2, (2,2)))
@@ -155,6 +161,7 @@ class T_RandomStreams(unittest.TestCase):
         val2 = made2.fn()
         assert numpy.all(val1 == val2)
 
+        # ndim specified, inconsistent with shape, should raise ValueError
         m3 = Module()
         m3.random = RandomStreams(234)
         m3.fn = Method([], m3.random.uniform(1, (2,2)))
@@ -163,6 +170,8 @@ class T_RandomStreams(unittest.TestCase):
         self.assertRaises(ValueError, made3.fn)
 
     def test_uniform(self):
+        """Test that RandomStreams.uniform generates the same results as numpy"""
+        # Check over two calls to see if the random state is correctly updated.
         m = Module()
         m.random = RandomStreams(234)
         m.fn = Method([], m.random.uniform((2,2), -1, 1))
@@ -186,6 +195,8 @@ class T_RandomStreams(unittest.TestCase):
         assert numpy.all(fn_val1 == numpy_val1)
 
     def test_normal(self):
+        """Test that RandomStreams.normal generates the same results as numpy"""
+        # Check over two calls to see if the random state is correctly updated.
         m = Module()
         m.random = RandomStreams(234)
         m.fn = Method([], m.random.normal((2,2), -1, 2))
@@ -204,6 +215,8 @@ class T_RandomStreams(unittest.TestCase):
         assert numpy.all(fn_val1 == numpy_val1)
 
     def test_random_integers(self):
+        """Test that RandomStreams.random_integers generates the same results as numpy"""
+        # Check over two calls to see if the random state is correctly updated.
         m = Module()
         m.random = RandomStreams(234)
         m.fn = Method([], m.random.random_integers((20,20), -5, 5))
@@ -222,6 +235,8 @@ class T_RandomStreams(unittest.TestCase):
         assert numpy.all(fn_val1 == numpy_val1)
 
     def test_permutation(self):
+        """Test that RandomStreams.uniform generates the same results as numpy"""
+        # Check over two calls to see if the random state is correctly updated.
         m = Module()
         m.random = RandomStreams(234)
         m.fn = Method([], m.random.permutation((20,), 10))
@@ -233,6 +248,8 @@ class T_RandomStreams(unittest.TestCase):
 
         rng_seed = numpy.random.RandomState(234).randint(2**30)
         rng = numpy.random.RandomState(int(rng_seed)) #int() is for 32bit
+
+        # rng.permutation outputs one vector at a time, so we iterate.
         numpy_val0 = numpy.asarray([rng.permutation(10) for i in range(20)])
         numpy_val1 = numpy.asarray([rng.permutation(10) for i in range(20)])
 
@@ -240,6 +257,8 @@ class T_RandomStreams(unittest.TestCase):
         assert numpy.all(fn_val1 == numpy_val1)
 
     def test_multinomial(self):
+        """Test that RandomStreams.multinomial generates the same results as numpy"""
+        # Check over two calls to see if the random state is correctly updated.
         m = Module()
         m.random = RandomStreams(234)
         m.fn = Method([], m.random.multinomial((20,20), 1, [0.1]*10))
@@ -258,6 +277,12 @@ class T_RandomStreams(unittest.TestCase):
         assert numpy.all(fn_val1 == numpy_val1)
 
     def test_shuffle_row_elements(self):
+        """Test that RandomStreams.shuffle_row_elements generates the right results"""
+        # Check over two calls to see if the random state is correctly updated.
+
+        # On matrices, for each row, the elements of that row should be shuffled.
+        # Note that this differs from numpy.random.shuffle, where all the elements
+        # of the matrix are shuffled.
         mm = Module()
         mm.random = RandomStreams(234)
         m_input = tensor.dmatrix()
@@ -288,6 +313,8 @@ class T_RandomStreams(unittest.TestCase):
         assert numpy.all(numpy_mval0 == fn_mval0)
         assert numpy.all(numpy_mval1 == fn_mval1)
 
+        # On vectors, the behaviour is the same as numpy.random.shuffle,
+        # except that it does not work in place, but returns a shuffled vector.
         vm = Module()
         vm.random = RandomStreams(234)
         v_input = tensor.dvector()
@@ -305,6 +332,8 @@ class T_RandomStreams(unittest.TestCase):
         print numpy_vval
         assert numpy.all(numpy_vval == fn_vval)
 
+        # Trying to shuffle a vector with function that should shuffle
+        # matrices, or vice versa, raises a TypeError
         self.assertRaises(TypeError, vmade.f, in_mval)
         self.assertRaises(TypeError, mmade.f, in_vval)
 

theano/tensor/tests/test_raw_random.py

@@ -95,9 +95,15 @@ class T_random_function(unittest.TestCase):
         rf2 = random_function(numpy.random.RandomState.uniform, 'float64', -2.0, 2.0)
         rng_R = random_state_type()
 
+        # ndim is an optional argument indicating the length of the 'shape'
+        # ndim not specified, OK
         post_out4,      out4    =   rf2(rng_R, (4,))
+
+        # ndim specified, consistent with shape, OK
         post_out1_4,    out1_4  =   rf2(rng_R, 1, (4,))
         post_out2_4_4,  out2_4_4=   rf2(rng_R, 2, (4, 4))
+
+        # ndim specified, but not compatible with shape
         post_out2_4,    out2_4  =   rf2(rng_R, 2, (4,))
 
         f_ok = compile.function(
@@ -109,17 +115,24 @@ class T_random_function(unittest.TestCase):
                 [out2_4],
                 accept_inplace=True)
 
+        # The correct cases should execute properly
         o4, o1_4, o2_4_4 = f_ok()
 
+        # Check the sanity of the answers
         self.assertTrue(numpy.allclose(o4, o1_4))
         self.assertTrue(numpy.allclose(o4, o2_4_4[0]))
+
+        # The incorrect case should raise ValueError
         self.assertRaises(ValueError, f_no)
 
     def test_random_function_ndim_added(self):
         """Test that random_function helper function accepts ndim_added as keyword argument"""
-        # On a uniform distribution, ndim_added=-1 means that the shape
-        # provided should be one dimension bigger, and its last value
-        # will be ignored
+        # If using numpy's uniform distribution, ndim_added should be 0,
+        # because the shape provided as argument is the output shape.
+        # Specifying a different ndim_added will change the Op's output ndim,
+        # so numpy.uniform will produce a result of incorrect shape,
+        # and a ValueError should be raised.
+
         uni_1 = random_function(numpy.random.RandomState.uniform, 'float64', -2.0, 2.0, ndim_added=1)
         uni_0 = random_function(numpy.random.RandomState.uniform, 'float64', -2.0, 2.0, ndim_added=0)
         uni_m1 = random_function(numpy.random.RandomState.uniform, 'float64', -2.0, 2.0, ndim_added=-1)
@@ -164,7 +177,10 @@ class T_random_function(unittest.TestCase):
         self.assertTrue(numpy.allclose(u01, u02[0]))
 
     def test_uniform(self):
+        """Test that raw_random.uniform generates the same results as numpy."""
+        # Check over two calls to see if the random state is correctly updated.
         rng_R = random_state_type()
+        # Use non-default parameters
         post_r, out = uniform(rng_R, (4,), -2.0, 2.0)
 
         f = compile.function(
@@ -184,7 +200,11 @@ class T_random_function(unittest.TestCase):
         self.assertTrue(numpy.allclose(val1, numpy_val1))
 
     def test_binomial(self):
+        """Test that raw_random.binomial generates the same results as numpy."""
+        # Check over two calls to see if the random state is correctly updated.
         rng_R = random_state_type()
+        # Use non-default parameters, and larger dimensions because of
+        # the integer nature of the result
         post_r, bin = binomial(rng_R, (7,12), 5, 0.8)
 
         f = compile.function(
@@ -204,7 +224,10 @@ class T_random_function(unittest.TestCase):
         self.assertTrue(numpy.all(val1 == numpy_val1))
 
     def test_normal(self):
+        """Test that raw_random.normal generates the same results as numpy."""
+        # Check over two calls to see if the random state is correctly updated.
         rng_R = random_state_type()
+        # Use non-default parameters
         post_r, out = normal(rng_R, (2,3), 4.0, 2.0)
 
         f = compile.function(
@@ -224,7 +247,11 @@ class T_random_function(unittest.TestCase):
         self.assertTrue(numpy.allclose(val1, numpy_val1))
 
     def test_random_integers(self):
+        """Test that raw_random.random_integers generates the same results as numpy."""
+        # Check over two calls to see if the random state is correctly updated.
         rng_R = random_state_type()
+        # Use non-default parameters, and larger dimensions because of
+        # the integer nature of the result
         post_r, out = random_integers(rng_R, (11,8), -3, 16)
 
         f = compile.function(
@@ -244,6 +271,13 @@ class T_random_function(unittest.TestCase):
         self.assertTrue(numpy.allclose(val1, numpy_val1))
 
     def test_permutation_helper(self):
+        """Test that raw_random.permutation_helper generates the same results as numpy,
+        and that the 'ndim_added' keyword behaves correctly."""
+        # permutation_helper needs "ndim_added=1", because its output
+        # is one dimension more than its "shape" argument (and there's
+        # no way to determine that automatically).
+        # Check the working case, over two calls to see if the random
+        # state is correctly updated.
         rf = RandomFunction(permutation_helper, tensor.imatrix, 8, ndim_added=1)
         rng_R = random_state_type()
         post_r, out = rf(rng_R, (7,), 8)
@@ -255,6 +289,8 @@ class T_random_function(unittest.TestCase):
         numpy_rng = numpy.random.RandomState(55)
         val0 = f()
         val1 = f()
+        # numpy_rng.permutation outputs one vector at a time,
+        # so we call it iteratively to generate all the samples.
         numpy_val0 = numpy.asarray([numpy_rng.permutation(8) for i in range(7)])
         numpy_val1 = numpy.asarray([numpy_rng.permutation(8) for i in range(7)])
         print val0
@@ -264,6 +300,8 @@ class T_random_function(unittest.TestCase):
         self.assertTrue(numpy.all(val0 == numpy_val0))
         self.assertTrue(numpy.all(val1 == numpy_val1))
 
+        # This call lacks "ndim_added=1", so ndim_added defaults to 0.
+        # A ValueError should be raised.
         rf0 = RandomFunction(permutation_helper, tensor.imatrix, 8)
         post_r0, out0 = rf0(rng_R, (7,), 8)
         f0 = compile.function(
@@ -271,6 +309,7 @@ class T_random_function(unittest.TestCase):
                 [out0], accept_inplace=True)
         self.assertRaises(ValueError, f0)
 
+        # Here, ndim_added is 2 instead of 1. A ValueError should be raised.
         rf2 = RandomFunction(permutation_helper, tensor.imatrix, 8, ndim_added=2)
         post_r2, out2 = rf2(rng_R, (7,), 8)
         f2 = compile.function(
@@ -279,6 +318,7 @@ class T_random_function(unittest.TestCase):
         self.assertRaises(ValueError, f2)
 
     def test_permutation(self):
+        """Test that raw_random.permutation generates the same results as numpy."""
         rng_R = random_state_type()
         post_r, out = permutation(rng_R, (9,), 6)
         f = compile.function(
@@ -286,6 +326,9 @@ class T_random_function(unittest.TestCase):
                 [out], accept_inplace=True)
 
         numpy_rng = numpy.random.RandomState(55)
+        # Check over two calls to see if the random state is correctly updated.
+        # numpy_rng.permutation outputs one vector at a time,
+        # so we call it iteratively to generate all the samples.
         val0 = f()
         val1 = f()
         numpy_val0 = numpy.asarray([numpy_rng.permutation(6) for i in range(9)])
@@ -298,6 +341,8 @@ class T_random_function(unittest.TestCase):
         self.assertTrue(numpy.all(val1 == numpy_val1))
 
     def test_multinomial(self):
+        """Test that raw_random.multinomial generates the same results as numpy."""
+        # Check over two calls to see if the random state is correctly updated.
         rng_R = random_state_type()
         post_r, out = multinomial(rng_R, (7,3), 6, [0.2]*5)