[API change] Making the seeding more intuitive.

[gabrieldemarmiesse]

After a lot of thinking, here is my proposal for the new seeding setup.

Fixes #432
Fixes #586
Fixes part of #610 #193

My take here is:

We add too little value compared to a manual seeding done by the user and passed through the config. In the end, it requires a lot of documentation and engineering for a very simple result: Seeding when the experiment starts and get some seeds here and there. This can be done in a couple of lines by the user, and will be much more explicit and clear. We can encourage users to put their seed in the config so that it's saved and can be changed from the command line.

This is only a couples of LOC for the user, but a lot less LOC for sacred. This should prepare the ground to make something simpler for the config as mentioned in #610.

Of course this is a big breaking change. Because of this, we'll use the strategy of the global flag to avoid users shooting themselves in the foot.

I'm not sure the PR actually works if the flag is set to False. The doc isn't updated. This PR serves as a base for discussion about the behavior that we want.

We provide two things:

• Helper functions to set the seeds of common libraries, those are often one liners, but we offer a common api and avoid the cognitive workload of looking into those libraries. Those could be removed since they're really simple, it can be discussed, we add very little value:

import sacred.random
sacred.random.set_python_random_seed(44)
sacred.random.set_numpy_seed(44)
sacred.random.set_tensorflow_seed(44)
sacred.random.set_torch_seed(44)

• We offer a context manager/function decorator, which can isolate the piece of code/function from the rest of the code by saving and reloading random states. This enables local seeding. Example:

import sacred.random

@sacred.random.save_numpy_random_state
def my_function()
      sacred.random.set_numpy_seed(84) # this has no effect on the code outside the function

with sacred.random.save_torch_random_state():
      # sample distributions with torch here without affecting the random state of the program.
      # you can even use a local seed with sacred.randomness.set_torch_seed.

[gabrieldemarmiesse]

I realised that my understanding of libraries producing random numbers is really bad haha, let's close that for now and I'll come up with a better proposal later on.

[Qwlouse]

Now I am curious, what it is that you discovered, that made you write this.
I don't necessarily agree with this proposal, but it does seem reasonable to me. So if you found a problem, I'd be interested to learn about it.

[gabrieldemarmiesse]

Basically, I didn't know that there was a way to generate random numbers without touching the global seed. RandomStates should be encouraged because touching the global random seed isn't thread safe. Furthermore, you can't know if some other libraries will mess up the global random state without your knowledge. See #573. In the end, to allow isolation, we should use random numbers generators, like it is currently done in the sacred API. One thing I'd like to change though, is the automatic seeding. Touching a global variable without explicit user approval can lead to some unexpected results if the user skip this part of the docs.