Added doc for strict flag.

[Thrandis]

Fixes #2651

Is this example enough, or shall I make something with more infos, examples, use cases,...

Cesar

[nouiz]

Can you specify if this cause scan grad speed up, scan optimization speed up or scan execution speed up? All of them?

[memimo]

Format wise, if you compiled it with sphinx locally without any error and warning, then it should be good.
But from user perspective, I couldn't quite understand the use case of the flag and have to go and read the original discussion. Maybe if emphasizing the speed up in the first sentence would make it more clear. And also what happens if I don't set this flag but still pass the shared variables as non sequences?

[Thrandis]

Yeah, I agree that it is not really clear. The problem is that there is a lot of different use case. Here are some:

x = T.vector()
W = theano.sared()

# Function with x and W as arguments
def f1(x, W):
    return T.dot(W, x)

# Function without W as argument
def f2(x):
    return T.dot(W, x)

# Here it is ok:
theano.scan(fn=f1, sequences=x, non_sequences=W)
# Here theano complains that f1 takes 2 arguments as input, and only one was provided:
theano.scan(fn=f1, sequences=x)
# Here it is fine:
theano.scan(fn=f2, sequences=x)
# Here it crashes, because strict=True and W was not provided:
theano.scan(fn=f2, sequences=x, strict=True)
# Here it is fine, and the right way to do it:
theano.scan(fn=f1, sequences=x, non_sequences=W, strict=True)

All in all we should say that the best practice is:
1. If you use shared variables inside a function, pass them as argument;
2. When using scan, pass those shared variables as non_sequences, and use strict=True for faster optimization and computation.

This should be the "official" way of using scan. Am I right?
Shall I put something like that in the doc?

[carriepl]

One thing though, it's not using strict=True that makes it faster, it's passing the shared variables as non-sequences. Strict mode only ensures that you did that so it's a convenient way for not forgetting to do it by accident.

[Thrandis]

Oh it's a good point actually! I will rephrase the whole thing tomorrow.

[Thrandis]

So I changed a bit the way the strict flag is presented: Now it is better integrated with the previous Gibbs smapling example.

[memimo]

Thanks, this is much more clear! If @carriepl approves too, it should be ready for merge.

[carriepl]

I like it. I think it's clear, well explained and it stresses the point that even though you can rely on scan to figure out the shared variables to use, you really ought to pass them as non-sequences yourself.

I don't really have any improvement to suggest. Good work.