Better error message when missing dimension in initial value in Scan

theano/scan_module/scan_op.py

@@ -215,14 +215,36 @@ class Scan(PureOp):
                  " does not match the number of inputs given to scan.")
         new_inputs = [inputs[0]]
         # assert dtype is consistent
-        err_msg1 = ('When compiling the inner function of scan the '
-                    'following error has been encountered: The '
+        err_msg1 = ('When compiling the inner function of scan (the '
+                    'function called by scan in each of its iterations) '
+                    'the following error has been encountered: The '
                     '%s %s (argument number %d) has dtype '
-                    '%s and %d dimension(s). The corresponding slice %s '
-                    'however has dtype %s and %d dimension(s) (it should '
-                    'have the same dtype and one fewer dimensions). This '
-                    'should never happen, please '
-                    'report to theano-dev mailing list'
+                    '%s and %d dimension(s). The corresponding slice '
+                    'in the inner function of scan %s '
+                    'however has dtype %s and %d dimension(s). This '
+                    'slice in the inner function of scan should '
+                    'have the same dtype and one fewer dimension in its '
+                    'leading dimension compared to its corresponding '
+                    'slice in the initial state (outputs_info in scan '
+                    'nomenclature). For example, if the inner function '
+                    'of scan returns a vector of dimensionality d and '
+                    'scan uses the values of the previous time-step, then '
+                    'the initial state in scan should be a matrix of '
+                    'dimensionality (1, d). The first dimension of this '
+                    'matrix corresponds to the number of previous time-steps'
+                    'that scan uses in each of its iterations. If for '
+                    'example scan uses up to 3 previous time-step values, '
+                    'the initial matrix should have dimensionality of (3, d). '
+                    'In order to solve this issue if the two slices currently '
+                    'have the same dimensionality, you can increase the first '
+                    'dimension of the initial state in scan by using '
+                    'dimshuffle or shape_padleft. As an exmaple, if you only '
+                    'use the values of the previous time-step and the '
+                    'corresponding variable in the inner function of scan '
+                    'returns a vector, then use v.dimshuffle(\'x\', 0) or '
+                    'theano.tensor.shape_padleft(v, n_ones=1) for vector v in '
+                    'the initial state of scan to change it from a vector to '
+                    'a matrix. '
                    )
         err_msg2 = ('When compiling the inner function of scan the '
                     'following error has been encountered: The '
@@ -231,13 +253,34 @@ class Scan(PureOp):
                     'has dtype %s, while the result of the inner function '
                     '(`fn`) has dtype %s. This can happen if the inner '
                     'function of scan results in an upcast or downcast.')
-        err_msg3 = ('When compiling the inner function of scan the '
-                    'following error has been encountered: The '
+        err_msg3 = ('When compiling the inner function of scan (the '
+                    'function called by scan in each of its iterations) '
+                    'the following error has been encountered: The '
                     'initial state (`outputs_info` in scan nomenclature) '
                     'of variable %s (argument number %d) has %d dimension(s), '
-                    'while the result of the inner function (`fn`) has %d '
-                    'dimension(s) (should be one less than the initial '
-                    'state).')
+                    'while the corresponding slice in the result of the inner '
+                    'function of scan (`fn`) has %d dimension(s) (it should '
+                    'be one less than the initial state). '
+                    'For example, if the inner function '
+                    'of scan returns a vector of dimensionality d and '
+                    'scan uses the values of the previous time-step, then '
+                    'the initial state in scan should be a matrix of '
+                    'dimensionality (1, d). The first dimension of this '
+                    'matrix corresponds to the number of previous time-steps'
+                    'that scan uses in each of its iterations. If for '
+                    'example scan uses up to 3 previous time-step values, '
+                    'the initial matrix should have dimensionality of (3, d). '
+                    'In order to solve this issue if the two slices currently '
+                    'have the same dimensionality, you can increase the first '
+                    'dimension of the initial state in scan by using '
+                    'dimshuffle or shape_padleft. As an exmaple, if you only '
+                    'use the values of the previous time-step and the '
+                    'corresponding variable in the inner function of scan '
+                    'returns a vector, then use v.dimshuffle(\'x\', 0) or '
+                    'theano.tensor.shape_padleft(v, n_ones=1) for vector v in '
+                    'the initial state of scan to change it from a vector to '
+                    'a matrix. '
+                   )
 
         def format(var, as_var):
             """ This functions ensures that ``out`` has the same dtype as