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