1C API for random
2----------------
3
4.. currentmodule:: numpy.random
5
6Access to various distributions below is available via Cython or C-wrapper
7libraries like CFFI. All the functions accept a :c:type:`bitgen_t` as their
8first argument.  To access these from Cython or C, you must link with the
9``npyrandom`` library which is part of the NumPy distribution, located in
10``numpy/random/lib``.
11
12
13.. c:type:: bitgen_t
14
15    The :c:type:`bitgen_t` holds the current state of the BitGenerator and
16    pointers to functions that return standard C types while advancing the
17    state.
18
19    .. code-block:: c
20
21        struct bitgen:
22            void *state
23            npy_uint64 (*next_uint64)(void *st) nogil
24            uint32_t (*next_uint32)(void *st) nogil
25            double (*next_double)(void *st) nogil
26            npy_uint64 (*next_raw)(void *st) nogil
27
28        ctypedef bitgen bitgen_t
29
30See :doc:`extending` for examples of using these functions.
31
32The functions are named with the following conventions:
33
34- "standard" refers to the reference values for any parameters. For instance
35  "standard_uniform" means a uniform distribution on the interval ``0.0`` to
36  ``1.0``
37
38- "fill" functions will fill the provided ``out`` with ``cnt`` values.
39
40- The functions without "standard" in their name require additional parameters
41  to describe the distributions.
42
43- ``zig`` in the name are based on a ziggurat lookup algorithm is used instead
44  of calculating the ``log``, which is significantly faster. The non-ziggurat
45  variants are used in corner cases and for legacy compatibility.
46
47
48.. c:function:: double random_standard_uniform(bitgen_t *bitgen_state)
49
50.. c:function:: void random_standard_uniform_fill(bitgen_t* bitgen_state, npy_intp cnt, double *out)
51
52.. c:function:: double random_standard_exponential(bitgen_t *bitgen_state)
53
54.. c:function:: void random_standard_exponential_fill(bitgen_t *bitgen_state, npy_intp cnt, double *out)
55
56.. c:function:: double random_standard_normal(bitgen_t* bitgen_state)
57
58.. c:function:: void random_standard_normal_fill(bitgen_t *bitgen_state, npy_intp count, double *out)
59
60.. c:function:: void random_standard_normal_fill_f(bitgen_t *bitgen_state, npy_intp count, float *out)
61
62.. c:function:: double random_standard_gamma(bitgen_t *bitgen_state, double shape)
63
64.. c:function:: float random_standard_uniform_f(bitgen_t *bitgen_state)
65
66.. c:function:: void random_standard_uniform_fill_f(bitgen_t* bitgen_state, npy_intp cnt, float *out)
67
68.. c:function:: float random_standard_exponential_f(bitgen_t *bitgen_state)
69
70.. c:function:: void random_standard_exponential_fill_f(bitgen_t *bitgen_state, npy_intp cnt, float *out)
71
72.. c:function:: float random_standard_normal_f(bitgen_t* bitgen_state)
73
74.. c:function:: float random_standard_gamma_f(bitgen_t *bitgen_state, float shape)
75
76.. c:function:: double random_normal(bitgen_t *bitgen_state, double loc, double scale)
77
78.. c:function:: double random_gamma(bitgen_t *bitgen_state, double shape, double scale)
79
80.. c:function:: float random_gamma_f(bitgen_t *bitgen_state, float shape, float scale)
81
82.. c:function:: double random_exponential(bitgen_t *bitgen_state, double scale)
83
84.. c:function:: double random_uniform(bitgen_t *bitgen_state, double lower, double range)
85
86.. c:function:: double random_beta(bitgen_t *bitgen_state, double a, double b)
87
88.. c:function:: double random_chisquare(bitgen_t *bitgen_state, double df)
89
90.. c:function:: double random_f(bitgen_t *bitgen_state, double dfnum, double dfden)
91
92.. c:function:: double random_standard_cauchy(bitgen_t *bitgen_state)
93
94.. c:function:: double random_pareto(bitgen_t *bitgen_state, double a)
95
96.. c:function:: double random_weibull(bitgen_t *bitgen_state, double a)
97
98.. c:function:: double random_power(bitgen_t *bitgen_state, double a)
99
100.. c:function:: double random_laplace(bitgen_t *bitgen_state, double loc, double scale)
101
102.. c:function:: double random_gumbel(bitgen_t *bitgen_state, double loc, double scale)
103
104.. c:function:: double random_logistic(bitgen_t *bitgen_state, double loc, double scale)
105
106.. c:function:: double random_lognormal(bitgen_t *bitgen_state, double mean, double sigma)
107
108.. c:function:: double random_rayleigh(bitgen_t *bitgen_state, double mode)
109
110.. c:function:: double random_standard_t(bitgen_t *bitgen_state, double df)
111
112.. c:function:: double random_noncentral_chisquare(bitgen_t *bitgen_state, double df, double nonc)
113.. c:function:: double random_noncentral_f(bitgen_t *bitgen_state, double dfnum, double dfden, double nonc)
114.. c:function:: double random_wald(bitgen_t *bitgen_state, double mean, double scale)
115
116.. c:function:: double random_vonmises(bitgen_t *bitgen_state, double mu, double kappa)
117
118.. c:function:: double random_triangular(bitgen_t *bitgen_state, double left, double mode, double right)
119
120.. c:function:: npy_int64 random_poisson(bitgen_t *bitgen_state, double lam)
121
122.. c:function:: npy_int64 random_negative_binomial(bitgen_t *bitgen_state, double n, double p)
123
124.. c:type:: binomial_t
125
126    .. code-block:: c
127
128        typedef struct s_binomial_t {
129          int has_binomial; /* !=0: following parameters initialized for binomial */
130          double psave;
131          RAND_INT_TYPE nsave;
132          double r;
133          double q;
134          double fm;
135          RAND_INT_TYPE m;
136          double p1;
137          double xm;
138          double xl;
139          double xr;
140          double c;
141          double laml;
142          double lamr;
143          double p2;
144          double p3;
145          double p4;
146        } binomial_t;
147
148
149.. c:function:: npy_int64 random_binomial(bitgen_t *bitgen_state, double p, npy_int64 n, binomial_t *binomial)
150
151.. c:function:: npy_int64 random_logseries(bitgen_t *bitgen_state, double p)
152
153.. c:function:: npy_int64 random_geometric_search(bitgen_t *bitgen_state, double p)
154
155.. c:function:: npy_int64 random_geometric_inversion(bitgen_t *bitgen_state, double p)
156
157.. c:function:: npy_int64 random_geometric(bitgen_t *bitgen_state, double p)
158
159.. c:function:: npy_int64 random_zipf(bitgen_t *bitgen_state, double a)
160
161.. c:function:: npy_int64 random_hypergeometric(bitgen_t *bitgen_state, npy_int64 good, npy_int64 bad, npy_int64 sample)
162
163.. c:function:: npy_uint64 random_interval(bitgen_t *bitgen_state, npy_uint64 max)
164
165.. c:function:: void random_multinomial(bitgen_t *bitgen_state, npy_int64 n, npy_int64 *mnix, double *pix, npy_intp d, binomial_t *binomial)
166
167.. c:function:: int random_multivariate_hypergeometric_count(bitgen_t *bitgen_state, npy_int64 total, size_t num_colors, npy_int64 *colors, npy_int64 nsample, size_t num_variates, npy_int64 *variates)
168
169.. c:function:: void random_multivariate_hypergeometric_marginals(bitgen_t *bitgen_state, npy_int64 total, size_t num_colors, npy_int64 *colors, npy_int64 nsample, size_t num_variates, npy_int64 *variates)
170
171Generate a single integer
172
173.. c:function:: npy_int64 random_positive_int64(bitgen_t *bitgen_state)
174
175.. c:function:: npy_int32 random_positive_int32(bitgen_t *bitgen_state)
176
177.. c:function:: npy_int64 random_positive_int(bitgen_t *bitgen_state)
178
179.. c:function:: npy_uint64 random_uint(bitgen_t *bitgen_state)
180
181
182Generate random uint64 numbers in closed interval [off, off + rng].
183
184.. c:function:: npy_uint64 random_bounded_uint64(bitgen_t *bitgen_state, npy_uint64 off, npy_uint64 rng, npy_uint64 mask, bool use_masked)
185
186