From ffbc6b15e3269ef71fa6400889d358c2c5de5a20 Mon Sep 17 00:00:00 2001 From: Robert Kern Date: Thu, 27 Jun 2019 01:10:18 -0700 Subject: DOC: Expand on the recommendations. --- doc/source/reference/random/performance.rst | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) (limited to 'doc/source') diff --git a/doc/source/reference/random/performance.rst b/doc/source/reference/random/performance.rst index 3e5c20e3a..7121129d4 100644 --- a/doc/source/reference/random/performance.rst +++ b/doc/source/reference/random/performance.rst @@ -7,7 +7,27 @@ Performance Recommendation ************** -The recommended generator for single use is :class:`~PCG64`. +The recommended generator for general use is :class:`~pcg64.PCG64`. It is +statistically high quality, full-featured, and fast on most platforms, but +somewhat slow when compiled for 32-bit processes. + +:class:`~philox.Philox` is fairly slow, but its statistical properties have +very high quality, and it is easy to get assuredly-independent stream by using +unique keys. If that is the style you wish to use for parallel streams, or you +are porting from another system that uses that style, then +:class:`~philox.Philox` is your choice. + +:class:`~sfc64.SFC64` is statistically high quality and very fast. However, it +lacks jumpability. If you are not using that capability and want lots of speed, +even on 32-bit processes, this is your choice. + +:class:`~mt19937.MT19937` `fails some statistical tests`_ and is not especially +fast compared to modern PRNGs. For these reasons, we mostly do not recommend +using it on its own, only through the legacy `~mtrand.RandomState` for +reproducing old results. That said, it has a very long history as a default in +many systems. + +.. _`fails some statistical tests`: https://www.iro.umontreal.ca/~lecuyer/myftp/papers/testu01.pdf Timings ******* @@ -44,7 +64,7 @@ The column labeled MT19973 is used the same 32-bit generator as The next table presents the performance in percentage relative to values -generated by the legagy generator, `RandomState(MT19937())`. The overall +generated by the legacy generator, `RandomState(MT19937())`. The overall performance was computed using a geometric mean. .. csv-table:: -- cgit v1.2.1