API: restructure and document numpy.random C-API (#14604)

* API: restructure and document numpy.random C-API

* DOC: fix bad reference

* API: ship, document, and start to test numpy.random C-API examples

* API, DOC, TST: fix tests, refactor documentation to include snippets

* BUILD: move public headers to numpy/core/include/numpy/random

* TST: ignore DeprecationWarnings in setuptools and numba

* DOC: document the C-API as used from Cython

1 files changed, 19 insertions, 15 deletions

diff --git a/numpy/random/examples/cython/extending_distributions.pyx b/numpy/random/examples/cython/extending_distributions.pyx
index 3cefec97e..d17da45c1 100644
--- a/numpy/random/examples/cython/extending_distributions.pyx
+++ b/numpy/random/examples/cython/extending_distributions.pyx
@@ -1,21 +1,23 @@
 #!/usr/bin/env python
 #cython: language_level=3
 """
-This file shows how the distributions that are accessed through
-distributions.pxd can be used Cython code.
+This file shows how the to use a BitGenerator to create a distribution.
 """
 import numpy as np
 cimport numpy as np
 cimport cython
 from cpython.pycapsule cimport PyCapsule_IsValid, PyCapsule_GetPointer
-from numpy.random.common cimport *
-from numpy.random.distributions cimport random_gauss_zig
+from numpy.random._bit_generator cimport bitgen_t
 from numpy.random import PCG64
 
 
 @cython.boundscheck(False)
 @cython.wraparound(False)
-def normals_zig(Py_ssize_t n):
+def uniforms(Py_ssize_t n):
+    """ Create an array of `n` uniformly distributed doubles.
+    A 'real' distribution would want to process the values into
+    some non-uniform distribution
+    """
     cdef Py_ssize_t i
     cdef bitgen_t *rng
     cdef const char *capsule_name = "BitGenerator"
@@ -23,21 +25,25 @@ def normals_zig(Py_ssize_t n):
 
     x = PCG64()
     capsule = x.capsule
+    # Optional check that the capsule if from a BitGenerator
     if not PyCapsule_IsValid(capsule, capsule_name):
         raise ValueError("Invalid pointer to anon_func_state")
+    # Cast the pointer
     rng = <bitgen_t *> PyCapsule_GetPointer(capsule, capsule_name)
-    random_values = np.empty(n)
-    # Best practice is to release GIL and acquire the lock
+    random_values = np.empty(n, dtype='float64')
     with x.lock, nogil:
         for i in range(n):
-            random_values[i] = random_gauss_zig(rng)
+            # Call the function
+            random_values[i] = rng.next_double(rng.state)
     randoms = np.asarray(random_values)
-    return randoms
 
+    return randoms
+ 
+# cython example 2
 
 @cython.boundscheck(False)
 @cython.wraparound(False)
-def uniforms(Py_ssize_t n):
+def uint16_uniforms(Py_ssize_t n):
     cdef Py_ssize_t i
     cdef bitgen_t *rng
     cdef const char *capsule_name = "BitGenerator"
@@ -45,15 +51,13 @@ def uniforms(Py_ssize_t n):
 
     x = PCG64()
     capsule = x.capsule
-    # Optional check that the capsule if from a BitGenerator
     if not PyCapsule_IsValid(capsule, capsule_name):
         raise ValueError("Invalid pointer to anon_func_state")
-    # Cast the pointer
     rng = <bitgen_t *> PyCapsule_GetPointer(capsule, capsule_name)
-    random_values = np.empty(n)
+    random_values = np.empty(n, dtype='uint32')
+    # Best practice is to release GIL and acquire the lock
     with x.lock, nogil:
         for i in range(n):
-            # Call the function
-            random_values[i] = rng.next_double(rng.state)
+            random_values[i] = rng.next_uint32(rng.state)
     randoms = np.asarray(random_values)
     return randoms