Public access to global state for numpy.random

I would like to be able to write code that can generate reproducible random numbers either by seeding a local RandomState or by falling back to the global state if a seed is not provided. This turns out to be more difficult than expected, despite being a common pattern. A number of libraries have implented the following function:

def check_random_state(seed):
    """Turn seed into a np.random.RandomState instance
    Parameters
    ----------
    seed : None | int | instance of RandomState
        If seed is None, return the RandomState singleton used by np.random.
        If seed is an int, return a new RandomState instance seeded with seed.
        If seed is already a RandomState instance, return it.
        Otherwise raise ValueError.
    """
    if seed is None or seed is np.random:
        return np.random.mtrand._rand
    if isinstance(seed, numbers.Integral):
        return np.random.RandomState(seed)
    if isinstance(seed, np.random.RandomState):
        return seed
    raise ValueError('%r cannot be used to seed a numpy.random.RandomState'
                     ' instance' % seed)

I believe this code originated in scikit-learn, and has since been propagated into scipy and, if you search on google, several other projects.

There is one problem with this approach, which is that the default behavior is to use np.random.mtrand._rand. That is to say, it depends on access to a private numpy object.

I think there are two implications here:

1. Given the widespread public usage of this private object, I’d suggest adding a comment to mtrand indicating that this is (for better or worse) a functionally public API, in that changing it would break a lot of projects.
2. Numpy itself could formally support such a usecase: a. Minimally, this could take the form of exposing the global RandomState as part of the public API. Then, downstream packages would need only make a simple change to check_random_state that would eliminate the risk of using a private object. b. Alternatively, numpy itself could add a similar convenience function that offers one-stop-shopping for a reproducible RandomState.

[rkern]

Yes, we definitely talked about it and decided to deliberately not expose it for the first release. Since this is a very new pattern (to our community), we wanted to see some use first, build some trust in the algorithm and implementation, and then lift it up in the API when there was visible demand for it. Thank you, @albertcthomas for doing exactly the kind of exploration and feedback that we needed.

At the moment, the SeedSequence is stored on the BitGenerator. It’s nominally private, but for exploration purposes, you can access it like so:

>>> rg = np.random.default_rng()
>>> rg.bit_generator._seed_seq
SeedSequence(
    entropy=156559746268636088056780713359175458950,
)

[rkern]

1. This usage is indeed documented as officially blessed. I’m ambivalent about making it more prominent in the documentation (e.g. documenting _rand explicitly in the numpy.random documentation) as I don’t want to encourage its use outside of functions like that. And I don’t particularly care to spend much more effort on the use of the old RNG system.

@seberg I would recommend just using default_rng() in pretty much exactly the same manner as check_random_state(). I do not really recommend spawning profligately at the head of every RNG-using API. Generally, trying to stick to one RNG per process/thread is still a good idea.