diff options
author | Robert Kern <robert.kern@gmail.com> | 2018-06-16 21:32:53 -0700 |
---|---|---|
committer | Robert Kern <robert.kern@gmail.com> | 2018-06-16 21:32:53 -0700 |
commit | 15af58f7b1358d430a1af3c12f34a5024735d072 (patch) | |
tree | 25d39f263bf15c7d039736babb4e3132cf5085c4 | |
parent | 3aa5ff809201089a5679ab321d9360ab00dd42fa (diff) | |
download | numpy-15af58f7b1358d430a1af3c12f34a5024735d072.tar.gz |
NEP: Clarify duration of requirements.
-rw-r--r-- | doc/neps/nep-0019-rng-policy.rst | 47 |
1 files changed, 26 insertions, 21 deletions
diff --git a/doc/neps/nep-0019-rng-policy.rst b/doc/neps/nep-0019-rng-policy.rst index cd4800961..a2cc80262 100644 --- a/doc/neps/nep-0019-rng-policy.rst +++ b/doc/neps/nep-0019-rng-policy.rst @@ -206,27 +206,32 @@ state underneath them. It can be hard to categorize and count API usages consistently and usefully, but a very common usage is in unit tests where many of the problems of global state are less likely. -The initial release of the new PRNG subsystem MUST leave these convenience -functions as aliases to the methods on a global ``RandomState`` that is -initialized with a Mersenne Twister basic RNG object. A call to -``numpy.random.seed()`` will be forwarded to that basic RNG object. In order -to allow certain workarounds, it MUST be possible to replace the basic RNG -underneath the global ``RandomState`` with any other basic RNG object (we leave -the precise API details up to the new subsystem). Calling ``numpy.random.seed()`` -thereafter SHOULD just pass the given seed to the current basic RNG object and -not attempt to reset the basic RNG to the Mersenne Twister. The global -``RandomState`` instance MUST be accessible by the name -``numpy.random.mtrand._rand``: Robert Kern long ago promised ``scikit-learn`` -that this name would be stable. Whoops. - -The set of ``numpy.random.*`` convenience functions SHALL remain the same as -they currently are. They SHALL be aliases to the ``RandomState`` methods and -not the new less-stable distributions class (``RandomGenerator``, in the -examples above). Users who want to get the fastest, best distributions can -follow best practices and instantiate generator objects explicitly. - -After we have experience with the new PRNG subsystem, we can and should revisit -these issues in future NEPs. +This NEP does not propose removing these functions or changing them to use the +less-stable ``RandomGenerator`` distribution implementations. Future NEPs +might. + +Specifically, the initial release of the new PRNG subsystem SHALL leave these +convenience functions as aliases to the methods on a global ``RandomState`` +that is initialized with a Mersenne Twister basic RNG object. A call to +``numpy.random.seed()`` will be forwarded to that basic RNG object. In +addition, the global ``RandomState`` instance MUST be accessible in this +initial release by the name ``numpy.random.mtrand._rand``: Robert Kern long ago +promised ``scikit-learn`` that this name would be stable. Whoops. + +In order to allow certain workarounds, it MUST be possible to replace the basic +RNG underneath the global ``RandomState`` with any other basic RNG object (we +leave the precise API details up to the new subsystem). Calling +``numpy.random.seed()`` thereafter SHOULD just pass the given seed to the +current basic RNG object and not attempt to reset the basic RNG to the Mersenne +Twister. The set of ``numpy.random.*`` convenience functions SHALL remain the +same as they currently are. They SHALL be aliases to the ``RandomState`` +methods and not the new less-stable distributions class (``RandomGenerator``, +in the examples above). Users who want to get the fastest, best distributions +can follow best practices and instantiate generator objects explicitly. + +This NEP does not propose that these requirements remain in perpetuity. After +we have experience with the new PRNG subsystem, we can and should revisit these +issues in future NEPs. Alternatives |