Changed unittest seeding behaviour (in code and documentation)

doc/advanced/unittest.txt

@@ -252,13 +252,15 @@ following:
 >>>     def setUp(self):
 >>>         unittest_tools.seed_rng()
 >>>         # OR ... call with an explicit seed 
->>>         unittest_tools.seed_rng(234234)
+>>>         unittest_tools.seed_rng(234234) #use only if really necessary!
 
 The behaviour of seed_rng is as follows:
 
-* if the environment variable THEANO_UNITTEST_SEED is defined, it will be used to seed the random number generator (and override any seed provided by the user)
-* if THEANO_UNITTEST_SEED is not defined, the user-supplied seed will be used to seed the rng
-* if THEANO_UNITTEST_SEED is not defined and no seed is given, the rng will be seeded with a random seed.
+* If an explicit seed is given, it will be used for seending numpy's rng.
+* If not, it will try to get a seed from the THEANO_UNITTEST_SEED variable.
+* If THEANO_UNITTEST_SEED is set to "random", it will seed the rng. with None, which is equivalent to seeding with a random seed.
+* If THEANO_UNITTEST_SEED is not defined, it will use a default seed of 666.
+
 
 The main advantage of using unittest_tools.seed_rng is that it allows us to
 change the seed used in the unitests, without having to manually edit all the
@@ -267,13 +269,13 @@ changing the seed on every run (hence achieving a higher confidence that the
 variables are correct), while still making sure unittests are deterministic. 
 
 Users who prefer their unittests to be random (when run on their local machine)
-can simply undefine THEANO_UNITTEST_SEED.
+can simply set THEANO_UNITTEST_SEED to 'random'.
 
 Similarly, to provide a seed to numpy.random.RandomState, simply use:
 
 >>> rng = numpy.random.RandomState(unittest_tools.fetch_seed())
 >>> # OR providing an explicit seed
->>> rng = numpy.random.RandomState(unittest_tools.fetch_seed(1231))
+>>> rng = numpy.random.RandomState(unittest_tools.fetch_seed(1231)) #again not recommended
 
 Note that the ability to change the seed from one nosetest to another, is incompatible with the method of hard-coding the baseline variables (against which we compare the theano outputs). These must then be determined "algorithmically". Although this represents more work, the test suite will be better because of it.
 

doc/install.txt

@@ -155,8 +155,9 @@ automatic code generation, but that way is much, much slower.
 
 - `THEANO_UNITTEST_SEED`:
     An integer value specifying which seed should be used when
-    running unit tests.
-    Setting this value will make the unit tests deterministic.
+    running unit tests. If this variable is not defined, the seed will default
+    to 666. Users wishing for non-deterministic behaviour can set this
+    variable to 'random'.
 
 
 Mac

theano/tests/unittest_tools.py

@@ -4,7 +4,21 @@ import numpy
 import os, sys
 
 def fetch_seed(pseed=None):
-    seed = os.getenv("THEANO_UNITTEST_SEED", pseed)
+    """
+    Returns the seed to use for running the unit tests.
+    If an explicit seed is given, it will be used for seending numpy's rng.
+    If not, it will try to get a seed from the THEANO_UNITTEST_SEED variable.
+    If THEANO_UNITTEST_SEED is set to "random", it will seed the rng. with None,
+    which is equivalent to seeding with a random seed.
+    If THEANO_UNITTEST_SEED is not defined, it will use a default seed of 666.
+
+    Useful for seeding RandomState objects.
+    >>> rng = numpy.random.RandomState(unittest_tools.fetch_seed())
+    """
+     
+    seed = pseed or os.getenv("THEANO_UNITTEST_SEED", 666)
+    seed = None if seed=='random' else seed
+
     try:
         seed = int(seed) if seed else None
     except ValueError:
@@ -15,6 +29,10 @@ def fetch_seed(pseed=None):
     return seed
 
 def seed_rng(pseed=None):
+    """
+    Seeds numpy's random number generator with the value returned by fetch_seed.
+    Usage: unittest_tools.seed_rng()
+    """
 
     seed = fetch_seed(pseed)
     if pseed and pseed!=seed: