<div dir="ltr">Matti, Kevin and Robert -- thanks for putting this together! I am very excited about these long awaited improvements to numpy.random.<div><br></div><div>I have a number of concerns about the user facing API, starting with the names "Random Generator" and "Base Random Number Generator," which I suspect will be a source of confusion. In particular, the current docs seem to use the term "random number generator" interchangeably for both.</div><div><br></div><div>Rather than "base RNG", what about calling these classes a "random source" or "random stream"? In particular, I would suggest defining two Python classes:</div><div>- np.random.Generator as a less redundant name for what is currently called RandomGenerator</div><div>- np.random.Source or np.random.Stream as an abstract base class for what are currently called "base RNGs"</div><div><br></div><div>Even if we don't yet provide an API for defining sources of randomness outside of NumPy, a base class for sources of randomness is valuable because it clearly defines the shared interface.</div><div><br></div><div>There are also a couple of convenience attributes in the user-facing API that I would suggest refining:</div><div>- The "brng" attribute of RandomGenerator is not a very descriptive name. I would prefer "stream" or "source", or the more explicit "base_rng" if we stick with that term.</div><div>- I don't think we need the "generator" property on base RNG objects. It is fine to require writing np.random.Generator(base) instead. Looking at the implementation, .generator caches the RandomGenerator objects it creates on the base RNG, which creates a reference cycle. Yes, Python can garbage collect reference cycles, but this is still a muddled data model.</div><div><br></div><div>Finally, why do we expose the np.random.gen object? I thought part of the idea with the new API was to avoid global mutable state.</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Apr 18, 2019 at 7:20 AM Matti Picus <<a href="mailto:matti.picus@gmail.com" target="_blank">matti.picus@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Thanks to the work of Kevin Sheppard, Robert Kern and others, the branch <br>
to merge randomgen <a href="https://github.com/bashtage/randomgen" rel="noreferrer" target="_blank">https://github.com/bashtage/randomgen</a> into numpy is <br>
ready for final review.<br>
<br>
The branch is here <a href="https://github.com/numpy/numpy/pull/13163" rel="noreferrer" target="_blank">https://github.com/numpy/numpy/pull/13163</a>. It is <br>
fully backward compatible: numpy.random.mtrand, <br>
numpy.random.RandomState, and the various stateful distributions from <br>
RandomState available as numpy.random.* produce the same streams as the <br>
current versions. The branch is intended to implement NEP 19 <br>
<a href="https://www.numpy.org/neps/nep-0019-rng-policy.html" rel="noreferrer" target="_blank">https://www.numpy.org/neps/nep-0019-rng-policy.html</a><br>
<br>
<br>
The biggest change is that now there are a variety of random number <br>
generators available <br>
<a href="https://6722-908607-gh.circle-artifacts.com/0/home/circleci/repo/doc/build/html/reference/random/brng/index.html" rel="noreferrer" target="_blank">https://6722-908607-gh.circle-artifacts.com/0/home/circleci/repo/doc/build/html/reference/random/brng/index.html</a>, <br>
and a class numpy.random.RandomGenerator that can produce all the <br>
distributions from RandomState. A RandomGenerator instance is provided <br>
for convenience as numpy.random.gen<br>
<br>
<br>
Additional enhancements <br>
<a href="https://6722-908607-gh.circle-artifacts.com/0/home/circleci/repo/doc/build/html/reference/random/new-or-different.html" rel="noreferrer" target="_blank">https://6722-908607-gh.circle-artifacts.com/0/home/circleci/repo/doc/build/html/reference/random/new-or-different.html</a> <br>
allow convenient use of the new constructs in CFFI, Numba, Ctypes, and <br>
Cython.<br>
<br>
<br>
There are a few things to address before merging:<br>
<br>
- Review the new constructs and other APIS<br>
<br>
- Decide which BRNGs to include in the first release<br>
<br>
- Check that your packages still work with the new implementations. You <br>
can do this by creating a new virtualenv and installing numpy via pip <br>
install git+<a href="https://github.com/mattip/numpy.git@randomgen" rel="noreferrer" target="_blank">https://github.com/mattip/numpy.git@randomgen</a> <br>
<<a href="https://github.com/user/repo.git@branch" rel="noreferrer" target="_blank">https://github.com/user/repo.git@branch</a>><br>
<br>
<br>
We will try to have a final video call about the branch during the <br>
upcoming meeting May 10-11, more details will follow once we schedule <br>
the call. The goal is to merge it for the upcoming 1.17 release.<br>
<br>
<br>
The expectation is that this first merge will be followed by <br>
implementation and documentation tweaks and improvements, but we hope to <br>
get the major pieces in place as much as possible now.<br>
<br>
<br>
Matti<br>
<br>
<br>
Notes:<br>
<br>
<br>
Sorry for the long urls, they link to the generated documentation from <br>
CI. They may not be available a few weeks from now.<br>
<br>
There is a tracking issue for further work related to the PR <br>
numpy.random <a href="https://github.com/numpy/numpy/issues/13164" rel="noreferrer" target="_blank">https://github.com/numpy/numpy/issues/13164</a><br>
<br>
_______________________________________________<br>
NumPy-Discussion mailing list<br>
<a href="mailto:NumPy-Discussion@python.org" target="_blank">NumPy-Discussion@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/numpy-discussion" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/numpy-discussion</a><br>
</blockquote></div>