8000 DOC, API: improve the C-API/Cython documentation and interfaces for random by mattip · Pull Request #15007 · numpy/numpy · GitHub
[go: up one dir, main page]
Skip to content

DOC, API: improve the C-API/Cython documentation and interfaces for random #15007

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Dec 3, 2019
Merged

DOC, API: improve the C-API/Cython documentation and interfaces for random #15007

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
16e8059
DOC: improve the C-API/Cython documentation for random
mattip Nov 29, 2019
bcd950f
DOC, TST: refactor CFFI test, add file names to documentation
mattip Nov 29, 2019
a2acfa6
API: rename functions in distributions.c,h
mattip Nov 29, 2019
aeaee5e
DOC: sphinx does not like breaking function declarations over lines
mattip Nov 29, 2019
2b791a5
API: revert changes to standard_t, cauchy
mattip Nov 30, 2019
b2f2700
DOC: fixes from review
mattip Dec 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
API: rename functions in distributions.c,h
  • Loading branch information
@mattip
mattip committed Nov 29, 2019
commit a2acfa6f2f99207fff87f19170cb4260b775d086
12 changes: 2 additions & 10 deletions doc/source/reference/random/c-api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,10 +69,6 @@ The functions are named with the following cconventions:

.. c:function:: void random_standard_exponential_fill(bitgen_t *bitgen_state, npy_intp cnt, double *out)

.. c:function:: double random_standard_exponential_zig(bitgen_t *bitgen_state)

.. c:function:: void random_standard_exponential_zig_fill(bitgen_t *bitgen_state, npy_intp cnt, double *out)

.. c:function:: double random_standard_normal(bitgen_t* bitgen_state)

.. c:function:: void random_standard_normal_fill(bitgen_t *bitgen_state, npy_intp count, double *out)
Expand All @@ -87,12 +83,8 @@ The functions are named with the following cconventions:

.. c:function:: float random_standard_exponential_f(bitgen_t *bitgen_state)

.. c:function:: float random_standard_exponential_zig_f(bitgen_t *bitgen_state)

.. c:function:: void random_standard_exponential_fill_f(bitgen_t *bitgen_state, npy_intp cnt, float *out)

.. c:function:: void random_standard_exponential_zig_fill_f(bitgen_t *bitgen_state, npy_intp cnt, float *out)

.. c:function:: float random_standard_normal_f(bitgen_t* bitgen_state)

.. c:function:: float random_standard_gamma_f(bitgen_t *bitgen_state, float shape)
Expand All @@ -112,7 +104,7 @@ The functions are named with the following cconventions:

.. c:function:: double random_f(bitgen_t *bitgen_state, double dfnum, double dfden)

.. c:function:: double random_standard_cauchy(bitgen_t *bitgen_state)
.. c:function:: double random_cauchy(bitgen_t *bitgen_state)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it already matches the name at the Python level, please leave it as such.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reverting the cauchy and random_t changes.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mattip I think you forgot to push the revert commit here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch. fixing.


.. c:function:: double random_pareto(bitgen_t *bitgen_state, double a)

Expand All @@ -130,7 +122,7 @@ The functions are named with the following cconventions:

.. c:function:: double random_rayleigh(bitgen_t *bitgen_state, double mode)

.. c:function:: double random_standard_t(bitgen_t *bitgen_state, double df)
.. c:function:: double random_student_t(bitgen_t *bitgen_state, double df)

.. c:function:: double random_noncentral_chisquare(bitgen_t *bitgen_state, double df,
double nonc)
Expand Down
10 changes: 4 additions & 6 deletions numpy/core/include/numpy/random/distributions.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,12 +71,10 @@ DECLDIR uint64_t random_uint(bitgen_t *bitgen_state);

DECLDIR double random_standard_exponential(bitgen_t *bitgen_state);
DECLDIR float random_standard_exponential_f(bitgen_t *bitgen_state);
DECLDIR double random_standard_exponential_zig(bitgen_t *bitgen_state);
DECLDIR float random_standard_exponential_zig_f(bitgen_t *bitgen_state);
DECLDIR void random_standard_exponential_fill(bitgen_t *, npy_intp, double *);
DECLDIR void random_standard_exponential_fill_f(bitgen_t *, npy_intp, float *);
DECLDIR void random_standard_exponential_zig_fill(bitgen_t *, npy_intp, double *);
DECLDIR void random_standard_exponential_zig_fill_f(bitgen_t *, npy_intp, float *);
DECLDIR void random_standard_exponential_inv_fill(bitgen_t *, npy_intp, double *);
DECLDIR void random_standard_exponential_inv_fill_f(bitgen_t *, npy_intp, float *);

DECLDIR double random_standard_normal(bitgen_t *bitgen_state);
DECLDIR float random_standard_normal_f(bitgen_t *bitgen_state);
Expand All @@ -95,7 +93,7 @@ DECLDIR double random_uniform(bitgen_t *bitgen_state, double lower, double range
DECLDIR double random_beta(bitgen_t *bitgen_state, double a, double b);
DECLDIR double random_chisquare(bitgen_t *bitgen_state, double df);
DECLDIR double random_f(bitgen_t *bitgen_state, double dfnum, double dfden);
DECLDIR double random_standard_cauchy(bitgen_t *bitgen_state);
DECLDIR double random_cauchy(bitgen_t *bitgen_state);
DECLDIR double random_pareto(bitgen_t *bitgen_state, double a);
DECLDIR double random_weibull(bitgen_t *bitgen_state, double a);
DECLDIR double random_power(bitgen_t *bitgen_state, double a);
Expand All @@ -104,7 +102,7 @@ DECLDIR double random_gumbel(bitgen_t *bitgen_state, double loc, double scale);
DECLDIR double random_logistic(bitgen_t *bitgen_state, double loc, double scale);
DECLDIR double random_lognormal(bitgen_t *bitgen_state, double mean, double sigma);
DECLDIR double random_rayleigh(bitgen_t *bitgen_state, double mode);
DECLDIR double random_standard_t(bitgen_t *bitgen_state, double df);
DECLDIR double random_student_t(bitgen_t *bitgen_state, double df);
DECLDIR double random_noncentral_chisquare(bitgen_t *bitgen_state, double df,
double nonc);
DECLDIR double random_noncentral_f(bitgen_t *bitgen_state, double dfnum,
Expand Down
26 changes: 12 additions & 14 deletions numpy/random/_generator.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,20 +54,18 @@ cdef extern from "numpy/random/distributions.h":
double random_standard_uniform(bitgen_t *bitgen_state) nogil
void random_standard_uniform_fill(bitgen_t* bitgen_state, np.npy_intp cnt, double *out) nogil
double random_standard_exponential(bitgen_t *bitgen_state) nogil
double random_standard_exponential_f(bitgen_t *bitgen_state) nogil
void random_standard_exponential_fill(bitgen_t *bitgen_state, np.npy_intp cnt, double *out) nogil
double random_standard_exponential_zig(bitgen_t *bitgen_state) nogil
void random_standard_exponential_zig_fill(bitgen_t *bitgen_state, np.npy_intp cnt, double *out) nogil
void random_standard_exponential_fill_f(bitgen_t *bitgen_state, np.npy_intp cnt, double *out) nogil
void random_standard_exponential_inv_fill(bitgen_t *bitgen_state, np.npy_intp cnt, double *out) nogil
void random_standard_exponential_inv_fill_f(bitgen_t *bitgen_state, np.npy_intp cnt, double *out) nogil
double random_standard_normal(bitgen_t* bitgen_state) nogil
void random_standard_normal_fill(bitgen_t *bitgen_state, np.npy_intp count, double *out) nogil
void random_standard_normal_fill_f(bitgen_t *bitgen_state, np.npy_intp count, float *out) nogil
double random_standard_gamma(bitgen_t *bitgen_state, double shape) nogil

float random_standard_uniform_f(bitgen_t *bitgen_state) nogil
void random_standard_uniform_fill_f(bitgen_t* bitgen_state, np.npy_intp cnt, float *out) nogil
float random_standard_exponential_f(bitgen_t *bitgen_state) nogil
float random_standard_exponential_zig_f(bitgen_t *bitgen_state) nogil
void random_standard_exponential_fill_f(bitgen_t *bitgen_state, np.npy_intp cnt, float *out) nogil
void random_standard_exponential_zig_fill_f(bitgen_t *bitgen_state, np.npy_intp cnt, float *out) nogil
float random_standard_normal_f(bitgen_t* bitgen_state) nogil
float random_standard_gamma_f(bitgen_t *bitgen_state, float shape) nogil

Expand All @@ -86,7 +84,7 @@ cdef extern from "numpy/random/distributions.h":
double random_beta(bitgen_t *bitgen_state, double a, double b) nogil
double random_chisquare(bitgen_t *bitgen_state, double df) nogil
double random_f(bitgen_t *bitgen_state, double dfnum, double dfden) nogil
double random_standard_cauchy(bitgen_t *bitgen_state) nogil
double random_cauchy(bitgen_t *bitgen_state) nogil
double random_pareto(bitgen_t *bitgen_state, double a) nogil
double random_weibull(bitgen_t *bitgen_state, double a) nogil
double random_power(bitgen_t *bitgen_state, double a) nogil
Expand All @@ -95,7 +93,7 @@ cdef extern from "numpy/random/distributions.h":
double random_logistic(bitgen_t *bitgen_state, double loc, double scale) nogil
double random_lognormal(bitgen_t *bitgen_state, double mean, double sigma) nogil
double random_rayleigh(bitgen_t *bitgen_state, double mode) nogil
double random_standard_t(bitgen_t *bitgen_state, double df) nogil
double random_student_t(bitgen_t *bitgen_state, double df) nogil
double random_noncentral_chisquare(bitgen_t *bitgen_state, double df,
double nonc) nogil
double random_noncentral_f(bitgen_t *bitgen_state, double dfnum,
Expand Down Expand Up @@ -459,14 +457,14 @@ cdef class Generator:
key = np.dtype(dtype).name
if key == 'float64':
if method == u'zig':
return double_fill(&random_standard_exponential_zig_fill, &self._bitgen, size, self.lock, out)
else:
return double_fill(&random_standard_exponential_fill, &self._bitgen, size, self.lock, out)
else:
return double_fill(&random_standard_exponential_inv_fill, &self._bitgen, size, self.lock, out)
elif key == 'float32':
if method == u'zig':
return float_fill(&random_standard_exponential_zig_fill_f, &self._bitgen, size, self.lock, out)
else:
return float_fill(&random_standard_exponential_fill_f, &self._bitgen, size, self.lock, out)
else:
return float_fill(&random_standard_exponential_inv_fill_f, &self._bitgen, size, self.lock, out)
else:
raise TypeError('Unsupported dtype "%s" for standard_exponential'
% key)
Expand Down Expand Up @@ -1697,7 +1695,7 @@ cdef class Generator:
>>> plt.show()

"""
return cont(&random_standard_cauchy, &self._bitgen, size, self.lock, 0,
return cont(&random_cauchy, &self._bitgen, size, self.lock, 0,
0.0, '', CONS_NONE, 0.0, '', CONS_NONE, 0.0, '', CONS_NONE, None)

def standard_t(self, df, size=None):
Expand Down Expand Up @@ -1788,7 +1786,7 @@ cdef class Generator:
probability of about 99% of being true.

"""
return cont(&random_standard_t, &self._bitgen, size, self.lock, 1,
return cont(&random_student_t, &self._bitgen, size, self.lock, 1,
df, 'df', CONS_POSITIVE,
0, '', CONS_NONE,
0, '', CONS_NONE,
Expand Down
85 changes: 39 additions & 46 deletions numpy/random/src/distributions/distributions.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,19 +41,7 @@ void random_standard_uniform_fill_f(bitgen_t *bitgen_state, npy_intp cnt, float
}
}

double random_standard_exponential(bitgen_t *bitgen_state) {
return -log(1.0 - next_double(bitgen_state));
}

void random_standard_exponential_fill(bitgen_t * bitgen_state, npy_intp cnt, double * out)
{
npy_intp i;
for (i = 0; i < cnt; i++) {
out[i] = random_standard_exponential(bitgen_state);
}
}

static double standard_exponential_zig_unlikely(bitgen_t *bitgen_state,
static double standard_exponential_unlikely(bitgen_t *bitgen_state,
uint8_t idx, double x) {
if (idx == 0) {
/* Switch to 1.0 - U to avoid log(0.0), see GH 13361 */
Expand All @@ -63,11 +51,11 @@ static double standard_exponential_zig_unlikely(bitgen_t *bitgen_state,
exp(-x)) {
return x;
} else {
return random_standard_exponential_zig(bitgen_state);
return random_standard_exponential(bitgen_state);
}
}

double random_standard_exponential_zig(bitgen_t *bitgen_state) {
double random_standard_exponential(bitgen_t *bitgen_state) {
uint64_t ri;
uint8_t idx;
double x;
Expand All @@ -79,30 +67,18 @@ double random_standard_exponential_zig(bitgen_t *bitgen_state) {
if (ri < ke_double[idx]) {
return x; /* 98.9% of the time we return here 1st try */
}
return standard_exponential_zig_unlikely(bitgen_state, idx, x);
}

void random_standard_exponential_zig_fill(bitgen_t * bitgen_state, npy_intp cnt, double * out)
{
npy_intp i;
for (i = 0; i < cnt; i++) {
out[i] = random_standard_exponential_zig(bitgen_state);
}
}

float random_standard_exponential_f(bitgen_t *bitgen_state) {
return -logf(1.0f - next_float(bitgen_state));
return standard_exponential_unlikely(bitgen_state, idx, x);
}

void random_standard_exponential_fill_f(bitgen_t * bitgen_state, npy_intp cnt, float * out)
void random_standard_exponential_fill(bitgen_t * bitgen_state, npy_intp cnt, double * out)
{
npy_intp i;
for (i = 0; i < cnt; i++) {
out[i] = random_standard_exponential_f(bitgen_state);
out[i] = random_standard_exponential(bitgen_state);
}
}

static float standard_exponential_zig_unlikely_f(bitgen_t *bitgen_state,
static float standard_exponential_unlikely_f(bitgen_t *bitgen_state,
uint8_t idx, float x) {
if (idx == 0) {
/* Switch to 1.0 - U to avoid log(0.0), see GH 13361 */
Expand All @@ -112,11 +88,11 @@ static float standard_exponential_zig_unlikely_f(bitgen_t *bitgen_state,
expf(-x)) {
return x;
} else {
return random_standard_exponential_zig_f(bitgen_state);
return random_standard_exponential_f(bitgen_state);
}
}

float random_standard_exponential_zig_f(bitgen_t *bitgen_state) {
float random_standard_exponential_f(bitgen_t *bitgen_state) {
uint32_t ri;
uint8_t idx;
float x;
Expand All @@ -128,17 +104,34 @@ float random_standard_exponential_zig_f(bitgen_t *bitgen_state) {
if (ri < ke_float[idx]) {
return x; /* 98.9% of the time we return here 1st try */
}
return standard_exponential_zig_unlikely_f(bitgen_state, idx, x);
return standard_exponential_unlikely_f(bitgen_state, idx, x);
}

void random_standard_exponential_fill_f(bitgen_t * bitgen_state, npy_intp cnt, float * out)
{
npy_intp i;
for (i = 0; i < cnt; i++) {
out[i] = random_standard_exponential_f(bitgen_state);
}
}

void random_standard_exponential_inv_fill(bitgen_t * bitgen_state, npy_intp cnt, double * out)
{
npy_intp i;
for (i = 0; i < cnt; i++) {
out[i] = -log(1.0 - next_double(bitgen_state));
}
}

void random_standard_exponential_zig_fill_f(bitgen_t * bitgen_state, npy_intp cnt, float * out)
void random_standard_exponential_inv_fill_f(bitgen_t * bitgen_state, npy_intp cnt, float * out)
{
npy_intp i;
for (i = 0; i < cnt; i++) {
out[i] = random_standard_exponential_zig_f(bitgen_state);
out[i] = -log(1.0 - next_float(bitgen_state));
}
}


double random_standard_normal(bitgen_t *bitgen_state) {
uint64_t r;
int sign;
Expand Down Expand Up @@ -228,13 +221,13 @@ double random_standard_gamma(bitgen_t *bitgen_state,
double U, V, X, Y;

if (shape == 1.0) {
return random_standard_exponential_zig(bitgen_state);
return random_standard_exponential(bitgen_state);
} else if (shape == 0.0) {
return 0.0;
} else if (shape < 1.0) {
for (;;) {
U = next_double(bitgen_state);
V = random_standard_exponential_zig(bitgen_state);
V = random_standard_exponential(bitgen_state);
if (U <= 1.0 - shape) {
X = pow(U, 1. / shape);
if (X <= V) {
Expand Down Expand Up @@ -274,13 +267,13 @@ float random_standard_gamma_f(bitgen_t *bitgen_state,
float U, V, X, Y;

if (shape == 1.0f) {
return random_standard_exponential_zig_f(bitgen_state);
return random_standard_exponential_f(bitgen_state);
} else if (shape == 0.0) {
return 0.0;
} else if (shape < 1.0f) {
for (;;) {
U = next_float(bitgen_state);
V = random_standard_exponential_zig_f(bitgen_state);
V = random_standard_exponential_f(bitgen_state);
if (U <= 1.0f - shape) {
X = powf(U, 1.0f / shape);
if (X <= V) {
Expand Down Expand Up @@ -391,7 +384,7 @@ double random_normal(bitgen_t *bitgen_state, double loc, double scale) {
}

double random_exponential(bitgen_t *bitgen_state, double scale) {
return scale * random_standard_exponential_zig(bitgen_state);
return scale * random_standard_exponential(bitgen_state);
}

double random_uniform(bitgen_t *bitgen_state, double lower, double range) {
Expand Down Expand Up @@ -450,23 +443,23 @@ double random_f(bitgen_t *bitgen_state, double dfnum, double dfden) {
(random_chisquare(bitgen_state, dfden) * dfnum));
}

double random_standard_cauchy(bitgen_t *bitgen_state) {
double random_cauchy(bitgen_t *bitgen_state) {
return random_standard_normal(bitgen_state) / random_standard_normal(bitgen_state);
}

double random_pareto(bitgen_t *bitgen_state, double a) {
return exp(random_standard_exponential_zig(bitgen_state) / a) - 1;
return exp(random_standard_exponential(bitgen_state) / a) - 1;
}

double random_weibull(bitgen_t *bitgen_state, double a) {
if (a == 0.0) {
return 0.0;
}
return pow(random_standard_exponential_zig(bitgen_state), 1. / a);
return pow(random_standard_exponential(bitgen_state), 1. / a);
}

double random_power(bitgen_t *bitgen_state, double a) {
return pow(1 - exp(-random_standard_exponential_zig(bitgen_state)), 1. / a);
return pow(1 - exp(-random_standard_exponential(bitgen_state)), 1. / a);
}

double random_laplace(bitgen_t *bitgen_state, double loc, double scale) {
Expand Down Expand Up @@ -514,7 +507,7 @@ double random_rayleigh(bitgen_t *bitgen_state, double mode) {
return mode * sqrt(-2.0 * log(1.0 - next_double(bitgen_state)));
}

double random_standard_t(bitgen_t *bitgen_state, double df) {
double random_student_t(bitgen_t *bitgen_state, double df) {
double num, denom;

num = random_standard_normal(bitgen_state);
Expand Down
0