utilities

Utilities to Support Random Operations and Generating Vectors and Matrices

quantecon.random.utilities.draw(cdf, size=None, rng=None)

Generate a random sample according to the cumulative distribution given by cdf. JIT-compiled by Numba in nopython mode.

Parameters:

cdfarray_like(float, ndim=1)

Array containing the cumulative distribution.

sizescalar(int), optional(default=None)

Size of the sample. If an integer is supplied, an ndarray of size independent draws is returned; otherwise, a single draw is returned as a scalar.

rngnp.random.Generator, optional(default=None)

Random number generator to draw from. Must be a np.random.Generator or None; in particular, integer seeds and np.random.RandomState are not accepted. If None, the global random state is used (see Notes).

Returns:

scalar(int) or ndarray(int, ndim=1)

Notes

draw is intended primarily for use inside jit-compiled functions. Pass a np.random.Generator as rng whenever the draws should be reproducible; the generator is consumed in place, so its state advances across successive calls.

rng accepts only None or a Generator because Numba’s nopython mode can neither construct a generator from a seed nor represent np.random.RandomState. A jit-compiled caller passing anything else gets a compile-time numba.TypingError. Build a generator outside any jit-compiled function with np.random.default_rng(seed) and pass it in.

If rng is None, a jit-compiled caller draws from Numba’s own internal random state, which is seeded by calling np.random.seed inside a jit-compiled function; seeding NumPy’s global random state from Python has no effect on it.

A single Generator must not be shared across the iterations of a numba.prange loop. Its state is updated in place, so concurrent iterations race and can consume the same underlying random number; the draws are then neither reproducible nor independent. Give each iteration its own generator, spawned with Generator.spawn outside the jit-compiled function – spawn itself cannot be called in nopython mode.

Examples

>>> import numpy as np
>>> import quantecon as qe
>>> cdf = np.cumsum([0.4, 0.6])
>>> rng = np.random.default_rng(1234)
>>> qe.random.draw(cdf, 10, rng=rng)
array([1, 0, 1, 0, 0, 0, 0, 0, 1, 0])
>>> qe.random.draw(cdf, rng=np.random.default_rng(1234))
np.int64(1)

Inside a jit-compiled function:

>>> from numba import njit
>>> @njit
... def draw_jitted(cdf, size, rng):
...     return qe.random.draw(cdf, size, rng)
>>> draw_jitted(cdf, 5, np.random.default_rng(1234))
array([1, 0, 1, 0, 0])

quantecon.random.utilities.ol_draw(cdf, size=None, rng=None)

quantecon.random.utilities.probvec(m, k, random_state=None, parallel=True)

Return m randomly sampled probability vectors of dimension k.

Parameters:

mscalar(int)

Number of probability vectors.

kscalar(int)

Dimension of each probability vectors.

random_stateint or np.random.RandomState/Generator, optional

Random seed (integer) or np.random.RandomState or Generator instance to set the initial state of the random number generator for reproducibility. If None, a randomly initialized RandomState is used.

parallelbool(default=True)

Whether to use multi-core CPU (parallel=True) or single-threaded CPU (parallel=False). (Internally the code is executed through Numba.guvectorize.)

Returns:

xndarray(float, ndim=2)

Array of shape (m, k) containing probability vectors as rows.

Examples

>>> import numpy as np
>>> import quantecon as qe
>>> rng = np.random.default_rng(1234)
>>> qe.random.probvec(2, 3, random_state=rng)
array([[0.38019574, 0.59650403, 0.02330023],
       [0.26169242, 0.66155381, 0.07675377]])

quantecon.random.utilities.sample_without_replacement(n, k, num_trials=None, random_state=None)

Randomly choose k integers without replacement from 0, …, n-1.

Parameters:

nscalar(int)

Number of integers, 0, …, n-1, to sample from.

kscalar(int)

Number of integers to sample.

num_trialsscalar(int), optional(default=None)

Number of trials.

random_stateint or np.random.RandomState/Generator, optional

Random seed (integer) or np.random.RandomState or Generator instance to set the initial state of the random number generator for reproducibility. If None, a randomly initialized RandomState is used.

Returns:

resultndarray(int, ndim=1 or 2)

Array of shape (k,) if num_trials is None, or of shape (num_trials, k) otherwise, (each row of) which contains k unique random elements chosen from 0, …, n-1.

Examples

>>> import numpy as np
>>> import quantecon as qe
>>> rng = np.random.default_rng(1234)
>>> qe.random.sample_without_replacement(5, 3, random_state=rng)
array([4, 1, 2])
>>> rng = np.random.default_rng(1234)
>>> qe.random.sample_without_replacement(5, 3, num_trials=4,
...                                      random_state=rng)
array([[4, 1, 2],
       [1, 4, 0],
       [1, 4, 2],
       [1, 4, 3]])