diff options
Diffstat (limited to 'numpy/random/_generator.pyx')
| -rw-r--r-- | numpy/random/_generator.pyx | 94 |
1 files changed, 88 insertions, 6 deletions
diff --git a/numpy/random/_generator.pyx b/numpy/random/_generator.pyx index da66c1cac..a30d116c2 100644 --- a/numpy/random/_generator.pyx +++ b/numpy/random/_generator.pyx @@ -238,6 +238,64 @@ cdef class Generator: """ return self._bit_generator + def spawn(self, int n_children): + """ + spawn(n_children) + + Create new independent child generators. + + See :ref:`seedsequence-spawn` for additional notes on spawning + children. + + .. versionadded:: 1.25.0 + + Parameters + ---------- + n_children : int + + Returns + ------- + child_generators : list of Generators + + Raises + ------ + TypeError + When the underlying SeedSequence does not implement spawning. + + See Also + -------- + random.BitGenerator.spawn, random.SeedSequence.spawn : + Equivalent method on the bit generator and seed sequence. + bit_generator : + The bit generator instance used by the generator. + + Examples + -------- + Starting from a seeded default generator: + + >>> # High quality entropy created with: f"0x{secrets.randbits(128):x}" + >>> entropy = 0x3034c61a9ae04ff8cb62ab8ec2c4b501 + >>> rng = np.random.default_rng(entropy) + + Create two new generators for example for parallel executation: + + >>> child_rng1, child_rng2 = rng.spawn(2) + + Drawn numbers from each are independent but derived from the initial + seeding entropy: + + >>> rng.uniform(), child_rng1.uniform(), child_rng2.uniform() + (0.19029263503854454, 0.9475673279178444, 0.4702687338396767) + + It is safe to spawn additional children from the original ``rng`` or + the children: + + >>> more_child_rngs = rng.spawn(20) + >>> nested_spawn = child_rng1.spawn(20) + + """ + return [type(self)(g) for g in self._bit_generator.spawn(n_children)] + def random(self, size=None, dtype=np.float64, out=None): """ random(size=None, dtype=np.float64, out=None) @@ -380,6 +438,22 @@ cdef class Generator: out : ndarray or scalar Drawn samples from the parameterized exponential distribution. + Examples + -------- + A real world example: Assume a company has 10000 customer support + agents and the average time between customer calls is 4 minutes. + + >>> n = 10000 + >>> time_between_calls = np.random.default_rng().exponential(scale=4, size=n) + + What is the probability that a customer will call in the next + 4 to 5 minutes? + + >>> x = ((time_between_calls < 5).sum())/n + >>> y = ((time_between_calls < 4).sum())/n + >>> x-y + 0.08 # may vary + References ---------- .. [1] Peyton Z. Peebles Jr., "Probability, Random Variables and @@ -2560,7 +2634,7 @@ cdef class Generator: >>> b = [] >>> for i in range(1000): ... a = 10. + rng.standard_normal(100) - ... b.append(np.product(a)) + ... b.append(np.prod(a)) >>> b = np.array(b) / np.min(b) # scale values to be positive >>> count, bins, ignored = plt.hist(b, 100, density=True, align='mid') @@ -3533,8 +3607,8 @@ cdef class Generator: generalization of the one-dimensional normal distribution to higher dimensions. Such a distribution is specified by its mean and covariance matrix. These parameters are analogous to the mean - (average or "center") and variance (standard deviation, or "width," - squared) of the one-dimensional normal distribution. + (average or "center") and variance (the squared standard deviation, + or "width") of the one-dimensional normal distribution. Parameters ---------- @@ -3611,6 +3685,12 @@ cdef class Generator: nonnegative-definite). Otherwise, the behavior of this method is undefined and backwards compatibility is not guaranteed. + This function internally uses linear algebra routines, and thus results + may not be identical (even up to precision) across architectures, OSes, + or even builds. For example, this is likely if ``cov`` has multiple equal + singular values and ``method`` is ``'svd'`` (default). In this case, + ``method='cholesky'`` may be more robust. + References ---------- .. [1] Papoulis, A., "Probability, Random Variables, and Stochastic @@ -4247,7 +4327,7 @@ cdef class Generator: Raises ------ ValueError - If any value in ``alpha`` is less than or equal to zero + If any value in ``alpha`` is less than zero Notes ----- @@ -4326,8 +4406,8 @@ cdef class Generator: alpha_arr = <np.ndarray>np.PyArray_FROMANY( alpha, np.NPY_DOUBLE, 1, 1, np.NPY_ARRAY_ALIGNED | np.NPY_ARRAY_C_CONTIGUOUS) - if np.any(np.less_equal(alpha_arr, 0)): - raise ValueError('alpha <= 0') + if np.any(np.less(alpha_arr, 0)): + raise ValueError('alpha < 0') alpha_data = <double*>np.PyArray_DATA(alpha_arr) if size is None: @@ -4803,6 +4883,8 @@ def default_rng(seed=None): ----- If ``seed`` is not a `BitGenerator` or a `Generator`, a new `BitGenerator` is instantiated. This function does not manage a default global instance. + + See :ref:`seeding_and_entropy` for more information about seeding. Examples -------- |