Table of Contents

Class Generator

Namespace
NumSharp
Assembly
NumSharp.dll

The modern NumPy random number container returned by np.random.default_rng.

public class Generator
Inheritance
Generator
Inherited Members

Remarks

Port of NumPy 2.4.2's numpy.random.Generator (numpy/random/_generator.pyx). Unlike the legacy NumPyRandom (RandomState, MT19937 + polar-method normal / inverse-CDF exponential / masked bounded integers), Generator draws from any BitGenerator — PCG64 by default, or PCG64DXSM, Philox, SFC64, MT19937 — and uses NumPy's newer algorithms — ziggurat normal/exponential and Lemire bounded integers — so its stream matches np.random.Generator(bit_generator) (and default_rng(seed)) bit-for-bit, not RandomState.

Every public drawing method holds the bit generator's lock while it consumes the stream, so one generator (or several over the same bit generator) can be shared between threads with NumPy's guarantee: each call is atomic with respect to the stream.

Constructors

Generator(BitGenerator)

Constructs a Generator over the given bit generator (NumPy's Generator(bit_generator)).

public Generator(BitGenerator bit_generator)

Parameters

bit_generator BitGenerator

The bit generator supplying the stream; its lock is shared with every other consumer. The name is NumPy's, so a named argument ports verbatim (new Generator(bit_generator: pcg)).

Exceptions

AttributeError

bit_generator is null — NumPy's 'NoneType' object has no attribute 'capsule' (its constructor reads bit_generator.capsule).

Fields

_poisson_lam_max

NumPy's Generator._poisson_lam_max: the largest lam the Poisson sampler accepts, <double>iinfo(int64).max - sqrt(iinfo(int64).max) * 10 (the same value RandomState exposes).

public const double _poisson_lam_max = 9.223372006484771E+18

Field Value

double

Properties

_bit_generator

The bit generator supplying this Generator's stream — NumPy's public Generator._bit_generator attribute (cdef public object _bit_generator), the same instance bit_generator returns.

public BitGenerator _bit_generator { get; }

Property Value

BitGenerator

Remarks

Read-only here: NumPy lets Python rebind the attribute, but its draws keep using the engine captured at construction (the bitgen_t copy), so rebinding it there only desynchronizes the two — nothing a caller can rely on.

bit_generator

The bit generator supplying this Generator's stream.

public BitGenerator bit_generator { get; }

Property Value

BitGenerator

Methods

ToString()

NumPy's str(Generator): the class name and the bit generator's name.

public override string ToString()

Returns

string

Generator(<bit generator name>), e.g. Generator(PCG64).

beta(NDArray, NDArray, Shape?)

Draw samples from a Beta distribution with array-valued, broadcast parameters.

public NDArray beta(NDArray a, NDArray b, Shape? size = null)

Parameters

a NDArray

Alpha, positive (NaN accepted and sampled). Null is Python's None (NaN on the broadcast path; a TypeError when every parameter is 0-d).

b NDArray

Beta, positive (NaN accepted). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape; a given size must be that shape or one the parameters broadcast into.

Returns

NDArray

The float64 draws; a 0-d array when every parameter is 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.beta.html
NumPy's cont_broadcast_2 over the modern random_beta, one call per output position with that position's (a, b): byte-identical to default_rng(seed).beta(a_arr, b_arr, size).

Exceptions

TypeError

A parameter's dtype does not cast to float64 under 'safe' (complex), or a None reaches the scalar path.

ValueError

An element of a (checked first) or b is not positive, or the shapes do not broadcast / the size is incompatible (NumPy's texts).

beta(double, double, Shape?)

Draw samples from a Beta distribution.

public NDArray beta(double a, double b, Shape? size = null)

Parameters

a double

Alpha, positive (> 0; NaN is accepted and samples NaN, as in NumPy).

b double

Beta, positive (> 0; NaN accepted).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws, in [0, 1].

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.beta.html
NumPy's modern random_beta: when both shapes are <= 1, Johnk's algorithm (with a log-space fallback when a power underflows, and a single-uniform 0/1 shortcut when both shapes are below 3e-103); otherwise the ratio of two standard gammas. Byte-identical to default_rng(seed).beta.

Exceptions

ValueError

a (a <= 0, checked first) or b is not positive.

binomial(NDArray, NDArray, Shape?)

Draw samples from a binomial distribution with array-valued, broadcast parameters.

public NDArray binomial(NDArray n, NDArray p, Shape? size = null)

Parameters

n NDArray

Number of trials, a non-negative INTEGER array (a float array is NumPy's safe-cast TypeError). Null is Python's None (a TypeError).

p NDArray

Probability of success, in [0, 1] (NaN rejected). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The int64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.binomial.html
NumPy's own broadcast loop over the modern random_binomial with this Generator's setup cache; an n == 0 or p == 0 position returns 0 without drawing. Byte-identical to NumPy.

Exceptions

TypeError

p (converted first) does not cast to float64 or n to int64 under 'safe', or a None reaches a conversion / the scalar path.

ValueError

In NumPy's order: an element of p outside [0, 1] or NaN, then of n negative; or the shapes do not broadcast / the size is incompatible (NumPy numbers p before n in the mismatch text).

binomial(long, double, Shape?)

Draw samples from a binomial distribution.

public NDArray binomial(long n, double p, Shape? size = null)

Parameters

n long

Number of trials, non-negative (a fractional count truncates, as NumPy's <int64_t>n).

p double

Probability of success, in [0, 1] (NaN rejected).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The int64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.binomial.html
NumPy's modern random_binomial: 0 without drawing for n == 0 or p == 0, the inversion sampler for n*min(p,1-p) <= 30 and BTPE above, over this Generator's own setup cache. Byte-identical to default_rng(seed).binomial.

Exceptions

ValueError

In NumPy's order: p outside [0, 1] or NaN (p < 0, p > 1 or p is NaN), then n negative (n < 0).

bytes(long)

Return random bytes.

public NDArray<byte> bytes(long length)

Parameters

length long

Number of random bytes.

Returns

NDArray<byte>

A 1-D NDArray<TDType> of byte (dtype uint8), length length — the NumSharp analogue of NumPy's bytes object.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.bytes.html
Byte-identical to NumPy: draws ceil(length/4) uint32 words from the bit generator (via the 32-bit buffered path), packs them little-endian, and truncates to length. As with bytes(long), the result is an unmanaged-backed NDArray<TDType>, so — matching NumPy's 64-bit npy_intp length — it is NOT capped at MaxLength and a request over 2 GiB still succeeds.

Exceptions

ValueError

length is below the smallest length NumPy accepts (negative dimensions are not allowed).

chisquare(NDArray, Shape?)

Draw samples from a chi-square distribution with array-valued, broadcast degrees of freedom.

public NDArray chisquare(NDArray df, Shape? size = null)

Parameters

df NDArray

Degrees of freedom, positive (NaN accepted). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is df's shape.

Returns

NDArray

The float64 draws; a 0-d array for a 0-d df and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.chisquare.html
2 * standard_gamma(df / 2) per position. Byte-identical to NumPy.

Exceptions

TypeError

df does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element is not positive (df <= 0), or the size is incompatible.

chisquare(double, Shape?)

Draw samples from a chi-square distribution.

public NDArray chisquare(double df, Shape? size = null)

Parameters

df double

Degrees of freedom, positive (> 0; NaN accepted and samples NaN).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.chisquare.html
NumPy's random_chisquare: 2 * random_standard_gamma(df / 2). Byte-identical to default_rng(seed).chisquare.

Exceptions

ValueError

df is not positive (df <= 0).

choice(NDArray, Shape?, bool, NDArray, int, bool)

Generates a random sample from a given array (or arange(a) when a is an integer population size).

public NDArray choice(NDArray a, Shape? size = null, bool replace = true, NDArray p = null, int axis = 0, bool shuffle = true)

Parameters

a NDArray

The population: a 0-d integer (or bool) array for arange(a), else the array sampled along axis.

size Shape?

Output shape; null is NumPy's size=None (one sample, the element/sub-array itself), () a 0-d request.

replace bool

Whether a population member may be drawn more than once.

p NDArray

Optional 1-D probabilities, one per population member; must sum to 1 within a tolerance tied to its float dtype.

axis int

The axis of a sampled along (Python-style negative indexing).

shuffle bool

Without replacement and without p: whether the selection is shuffled (false keeps Floyd's order).

Returns

NDArray

For an integer population, the int64 indices (0-d for size=None/()); otherwise a.take(indices, axis) — a single element (0-d) or one sub-array when size=None.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.choice.html
Byte-identical to NumPy on every sampling path: with replacement (uniform integers or the p-weighted CDF search), and without replacement (Floyd's algorithm / tail shuffle, or the weighted rounds). The whole call holds the bit generator's lock.

Exceptions

ValueError

A null a (NumPy's None: a must be a sequence or an integer, not <class 'NoneType'>) or a 0-d population that is not an integer; a non-positive population or an empty a with samples requested; a p that is not 1-D, has the wrong size, contains NaN or negatives, or does not sum to 1; a sample larger than the population without replacement; fewer non-zero probabilities than samples without replacement.

TypeError

p is 0-d (NumPy evaluates len(p) first).

IndexError

axis is outside [-a.ndim, a.ndim) (NumPy reads a.shape[axis]).

choice(long, Shape?, bool, NDArray, int, bool)

choice(int population, ...) convenience: draws from arange(a).

public NDArray choice(long a, Shape? size = null, bool replace = true, NDArray p = null, int axis = 0, bool shuffle = true)

Parameters

a long

The population size.

size Shape?

Output shape; null is NumPy's size=None (a 0-d int64 result).

replace bool

Whether an index may be drawn more than once.

p NDArray

Optional 1-D probabilities of length a.

axis int

Accepted for NumPy's signature and position — choice(a, size, replace, p, axis, shuffle) — and, as in NumPy, never read for an integer population (only an array's a.shape[axis] uses it).

shuffle bool

Without replacement and without p: whether the selection is shuffled.

Returns

NDArray

The int64 indices.

Remarks

The axis slot keeps a positional call aligned with NumPy's: without it the fifth positional argument would bind shuffle, where NumPy's fifth is axis.

Exceptions

ValueError

See choice(NDArray, Shape?, bool, NDArray, int, bool).

TypeError

p is 0-d.

dirichlet(NDArray, Shape?)

Draw samples from the Dirichlet distribution with the concentration given as a 1-D array.

public NDArray dirichlet(NDArray alpha, Shape? size = null)

Parameters

alpha NDArray

Concentration parameters, 1-D, any numeric dtype and layout (cast to float64).

size Shape?

Leading output shape. null (NumPy's None, the default) draws one vector.

Returns

NDArray

The float64 draws, shape (*size, k).

Remarks

NumPy's order: len(alpha) (fails for 0-d), then PyArray_FROMANY(alpha, NPY_DOUBLE, 1, 1), whose depth test precedes its safe-cast test — so a 2-D complex array reports the depth.

Exceptions

TypeError

alpha is null or 0-d (len() of unsized object), or complex (Cannot cast array data from dtype('complex128') to dtype('float64') according to the rule 'safe').

ValueError

alpha has more than one dimension (object too deep for desired array) or a negative element (alpha < 0).

dirichlet(double[], Shape?)

Draw samples from the Dirichlet distribution.

public NDArray dirichlet(double[] alpha, Shape? size = null)

Parameters

alpha double[]

Concentration parameters (length k, each non-negative; NaN accepted and samples NaN).

size Shape?

Leading output shape. null (NumPy's None, the default) draws one vector of shape (k,).

Returns

NDArray

The float64 draws, shape (*size, k); each row sums to 1.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.dirichlet.html
NumPy's Generator algorithm: when every alpha is below 0.1, the stick-breaking construction over random_beta (so all-tiny alphas never produce the 0/0 NaN of the gamma normalization); otherwise standard gammas normalized by the reciprocal of their sum. Unlike RandomState, zeros are allowed. Byte-identical to default_rng(seed).dirichlet.

Exceptions

TypeError

alpha is null (object of type 'NoneType' has no len()).

ValueError

An element of alpha is negative (alpha < 0).

exponential(NDArray, Shape?)

Draw samples from an exponential distribution with an array-valued, broadcast scale.

public NDArray exponential(NDArray scale, Shape? size = null)

Parameters

scale NDArray

The scale (1/rate); sign bit must be clear (-0.0 rejected), NaN propagates. Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is scale's shape.

Returns

NDArray

The float64 draws; a 0-d array for a 0-d scale and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.exponential.html
scale * standard_exponential() per position: the ziggurat exponentials are bulk-filled (one per value, whatever the scale) and scaled in place. Byte-identical to NumPy.

Exceptions

TypeError

scale does not cast to float64 under 'safe' (complex).

ValueError

An element is negative (scale < 0), or the size is incompatible.

exponential(double, Shape?)

Draw samples from an exponential distribution.

public NDArray exponential(double scale = 1, Shape? size = null)

Parameters

scale double

The scale parameter (1/rate); sign bit must be clear, NaN propagates.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.exponential.html
scale * standard_exponential() (ziggurat), byte-identical to NumPy.

Exceptions

ValueError

scale is negative, including -0.0 (NumPy's scale < 0).

f(NDArray, NDArray, Shape?)

Draw samples from an F distribution with array-valued, broadcast degrees of freedom.

public NDArray f(NDArray dfnum, NDArray dfden, Shape? size = null)

Parameters

dfnum NDArray

Numerator degrees of freedom, positive (NaN accepted). Null is Python's None.

dfden NDArray

Denominator degrees of freedom, positive (NaN accepted). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.f.html
NumPy's random_f per position, numerator first. Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element of dfnum (checked first) or dfden is not positive, or the shapes do not broadcast / the size is incompatible.

f(double, double, Shape?)

Draw samples from an F distribution.

public NDArray f(double dfnum, double dfden, Shape? size = null)

Parameters

dfnum double

Degrees of freedom in the numerator, positive (NaN accepted).

dfden double

Degrees of freedom in the denominator, positive (NaN accepted).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.f.html
NumPy's random_f: (chisquare(dfnum) * dfden) / (chisquare(dfden) * dfnum), the numerator drawn first. Byte-identical to default_rng(seed).f.

Exceptions

ValueError

dfnum (checked first) or dfden is not positive.

gamma(NDArray, NDArray, Shape?)

Draw samples from a Gamma distribution with array-valued, broadcast parameters.

public NDArray gamma(NDArray shape, NDArray scale = null, Shape? size = null)

Parameters

shape NDArray

The shape; sign bit must be clear, NaN propagates. Null is Python's None.

scale NDArray

The scale; sign bit must be clear, NaN propagates. Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.gamma.html
scale * standard_gamma(shape) per position (a zero shape returns 0 without drawing). Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element of shape (checked first) or scale is negative, or the shapes do not broadcast / the size is incompatible.

gamma(double, double, Shape?)

Draw samples from a Gamma distribution.

public NDArray gamma(double shape, double scale = 1, Shape? size = null)

Parameters

shape double

The shape parameter; sign bit must be clear (-0.0 rejected), NaN propagates.

scale double

The scale parameter (default 1); sign bit must be clear, NaN propagates.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

Exceptions

ValueError

shape or scale is negative (checked in that order).

geometric(NDArray, Shape?)

Draw samples from the geometric distribution with an array-valued, broadcast probability.

public NDArray geometric(NDArray p, Shape? size = null)

Parameters

p NDArray

The probability of success of an individual trial, in (0, 1]. Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is p's shape.

Returns

NDArray

The int64 draws (>= 1); a 0-d array for a 0-d p and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.geometric.html
The modern random_geometric per position: the CDF search (one uniform) for p >= 1/3, else the inversion over a ziggurat exponential. Both take their draws from one 64-bit read-ahead — a uniform is one 64-bit unit — and every value draws, so the read-ahead serves any mix. Byte-identical to NumPy.

Exceptions

TypeError

p does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element is outside (0, 1] or NaN, or the size is incompatible.

geometric(double, Shape?)

Draw samples from the geometric distribution.

public NDArray geometric(double p, Shape? size = null)

Parameters

p double

The probability of success of an individual trial, in (0, 1].

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The int64 draws (the trial of the first success, >= 1).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.geometric.html
NumPy's modern random_geometric: the CDF search for p >= 1/3, else the inversion ceil(-E / log1p(-p)) over a ziggurat exponential, clamped to INT64_MAX. Byte-identical to default_rng(seed).geometric.

Exceptions

ValueError

p is outside (0, 1] or NaN.

gumbel(NDArray, NDArray, Shape?)

Draw samples from a Gumbel distribution with array-valued, broadcast location and scale.

public NDArray gumbel(NDArray loc, NDArray scale = null, Shape? size = null)

Parameters

loc NDArray

The mode's location. Null is NumPy's default, 0.

scale NDArray

The scale, non-negative (-0.0 rejected; NaN accepted). Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

Exceptions

TypeError

A parameter does not cast to float64 under 'safe'.

ValueError

An element of scale is negative, or the shapes do not broadcast / the size is incompatible.

gumbel(double, double, Shape?)

Draw samples from a Gumbel distribution.

public NDArray gumbel(double loc = 0, double scale = 1, Shape? size = null)

Parameters

loc double

The location of the mode. Default 0.

scale double

The scale parameter, non-negative (-0.0 rejected; NaN accepted). Default 1.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.gumbel.html
NumPy's random_gumbel (shared with RandomState), one uniform per value.

Exceptions

ValueError

scale is negative (scale < 0).

hypergeometric(NDArray, NDArray, NDArray, Shape?)

Draw samples from a Hypergeometric distribution with array-valued, broadcast parameters.

public NDArray hypergeometric(NDArray ngood, NDArray nbad, NDArray nsample, Shape? size = null)

Parameters

ngood NDArray

Good selections, a non-negative INTEGER array below 10^9. Null is Python's None (a TypeError).

nbad NDArray

Bad selections, a non-negative integer array below 10^9.

nsample NDArray

Items sampled, 0 <= nsample <= ngood + nbad per position.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The int64 draws; a 0-d array when every parameter is 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.hypergeometric.html
The modern random_hypergeometric per position: HRUA (doubles) for 10 <= nsample <= ngood + nbad - 10, else the urn walk (32-bit words). A pre-walk classifies the positions: all HRUA reads doubles ahead, all drawing urns read words ahead, and any mix — whose 64-bit and buffered 32-bit draws interleave — or a draw-free urn position runs per draw. Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to int64 under 'safe' (floats, uint64, complex) or is None.

ValueError

In NumPy's order: an element of ngood or nbad at least 10^9; any ngood + nbad < nsample (whose whole-array arithmetic raises the ufunc broadcast error for mismatched shapes); then a negative ngood, nbad or nsample; or an incompatible size.

hypergeometric(long, long, long, Shape?)

Draw samples from a Hypergeometric distribution.

public NDArray hypergeometric(long ngood, long nbad, long nsample, Shape? size = null)

Parameters

ngood long

Number of ways to make a good selection, non-negative and below 10^9.

nbad long

Number of ways to make a bad selection, non-negative and below 10^9.

nsample long

Number of items sampled, 0 <= nsample <= ngood + nbad.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The int64 draws (good items in the sample).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.hypergeometric.html
NumPy's modern random_hypergeometric — a different algorithm from RandomState's: HRUA (with logfactorial) for 10 <= nsample <= ngood + nbad - 10, else an urn simulation over random_interval. Byte-identical to default_rng(seed).hypergeometric.

Exceptions

ValueError

In NumPy's order: ngood or nbad is at least 10^9; ngood + nbad < nsample; then a negative ngood, nbad or nsample (ngood < 0, ...).

integers(NDArray, NDArray, Shape?, DType, bool)

Array-bounds overload of integers(long, long?, Shape, DType, bool): NumPy's integers(low, high) with array-like bounds, which broadcast against each other (and against size when one is given) — one draw per output position, each from its own [low, high) (or [low, high] when endpoint).

public NDArray integers(NDArray low, NDArray high = null, Shape? size = null, DType dtype = null, bool endpoint = false)

Parameters

low NDArray

The low bound(s) — any integer, bool or float array (a float truncates toward zero, as Python's int() and NumPy's forced cast do). Null is Python's None (a TypeError).

high NDArray

The high bound(s); null is NumPy's high=None: the bounds are [0, low).

size Shape?

Output shape; null (NumPy's None, the default) is the bounds' broadcast shape (or one value when both are 0-d).

dtype DType

Desired native integer or bool dtype. Default is int64.

endpoint bool

If true, sample from the closed interval [low, high].

Returns

NDArray

The draws, of dtype.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.integers.html
NumPy's rand<dtype>: two 0-d bounds take the scalar path above (Python's int() of each); otherwise rand<dtype>_broadcast — the bounds checked over the whole array in NumPy's order, then one Lemire draw per position in C order, the 8/16-bit and bool dtypes splitting 32-bit words across positions. NumPy's two broadcast quirks are reproduced (a size smaller than the bounds' broadcast, and 64-bit float bounds in a non-C layout) — see DrawArray(BitGenerator, NDArray, NDArray, Shape, DType, bool, bool, string, bool). Byte-identical to default_rng(seed).integers(low_arr, high_arr, ...).

Exceptions

TypeError

dtype is a native non-integer dtype; a bound is None or a 0-d complex.

ValueError

Non-native byte order; a bound outside the dtype; an empty interval anywhere; a NaN bound; bounds that do not broadcast, or a size they do not broadcast with; a negative size.

OverflowError

An infinite bound (NumPy's OverflowError).

integers(long, long?, Shape?, DType, bool)

Return random integers from low (inclusive) to high (exclusive, or inclusive when endpoint is true).

public NDArray integers(long low, long? high = null, Shape? size = null, DType dtype = null, bool endpoint = false)

Parameters

low long

Lowest integer drawn (or, when high is null, one above the highest with low = 0).

high long?

If provided, one above the largest integer drawn (or the largest when endpoint).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value; () returns a 0-d array.

dtype DType

Desired native integer or bool dtype. Default is int64.

endpoint bool

If true, sample from the closed interval [low, high].

Returns

NDArray

The draws, of dtype.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.integers.html
Uses Lemire's method (NumPy's Generator default, use_masked=False) — NOT the legacy masked rejection of RandomState.randint — so the stream is byte-identical to default_rng(seed).integers(...). A zero-size request returns an empty array before the bounds are checked and draws nothing, exactly as NumPy's rand* does. Validation and the per-width fills are shared with the legacy randint (NumSharp.BoundedIntegers).

Exceptions

TypeError

dtype is a native non-integer dtype (Unsupported dtype dtype('float64') for integers).

ValueError

dtype has a non-native byte order; or the bounds fall outside the dtype (low/high is out of bounds for <dtype>); or the interval is empty (low >= high, high <= 0 and their closed-interval forms).

integers(BigInteger, BigInteger?, Shape?, DType, bool)

Arbitrary-precision overload of integers(long, long?, Shape, DType, bool) — the C# spelling of a Python int past the long/ulong range, such as NumPy's full-range idiom integers(0, 264, dtype=np.uint64) (an EXCLUSIVE 264) or a bound NumPy rejects as out of range.

public NDArray integers(BigInteger low, BigInteger? high = null, Shape? size = null, DType dtype = null, bool endpoint = false)

Parameters

low BigInteger

Lowest integer drawn (or, when high is null, one above the highest with low = 0).

high BigInteger?

If provided, one above the largest integer drawn (or the largest when endpoint).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value; () returns a 0-d array.

dtype DType

Desired native integer or bool dtype. Default is int64.

endpoint bool

If true, sample from the closed interval [low, high].

Returns

NDArray

The draws, of dtype.

Remarks

Validated exactly as NumPy validates the Python int: a value past ±2**100 — beyond every dtype's range — reaches the checks clamped, which report the same error the exact value would.

Exceptions

TypeError

dtype is a native non-integer dtype.

ValueError

Non-native byte order, bounds outside the dtype (low/high is out of bounds for <dtype>), or an empty interval.

integers(ulong, ulong?, Shape?, DType, bool)

Unsigned overload of integers(long, long?, Shape, DType, bool) — the C# spelling of a bound above MaxValue, which NumPy expresses with arbitrary-precision Python ints: the upper half of the uint64 range (full range: integers(0UL, ulong.MaxValue, dtype: np.uint64, endpoint: true)) and the exclusive int64 high 2**63 (integers(0UL, 9223372036854775808UL, dtype: np.int64)).

public NDArray integers(ulong low, ulong? high = null, Shape? size = null, DType dtype = null, bool endpoint = false)

Parameters

low ulong

Lowest integer drawn (or, when high is null, one above the highest with low = 0).

high ulong?

If provided, one above the largest integer drawn (or the largest when endpoint).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value; () returns a 0-d array.

dtype DType

Desired native integer or bool dtype. Default is int64.

endpoint bool

If true, sample from the closed interval [low, high].

Returns

NDArray

The draws, of dtype.

Remarks

Both overloads share one arbitrary-precision (Int128) range check, so every value expressible in either spelling is validated exactly as NumPy validates the Python int.

Exceptions

TypeError

dtype is a native non-integer dtype.

ValueError

Non-native byte order, bounds outside the dtype, or an empty interval — as for the signed overload.

laplace(NDArray, NDArray, Shape?)

Draw samples from the Laplace distribution with array-valued, broadcast location and scale.

public NDArray laplace(NDArray loc, NDArray scale = null, Shape? size = null)

Parameters

loc NDArray

The peak's position. Null is NumPy's default, 0.

scale NDArray

The exponential decay, non-negative (-0.0 rejected; NaN accepted). Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.laplace.html
random_laplace per position (one uniform, redrawn only on an exact 0). Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to float64 under 'safe'.

ValueError

An element of scale is negative, or the shapes do not broadcast / the size is incompatible.

laplace(double, double, Shape?)

Draw samples from the Laplace or double exponential distribution with specified location and scale.

public NDArray laplace(double loc = 0, double scale = 1, Shape? size = null)

Parameters

loc double

The position of the distribution peak. Default 0.

scale double

The exponential decay, non-negative (-0.0 rejected; NaN accepted). Default 1.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.laplace.html
NumPy's random_laplace (shared with RandomState), one uniform per value.

Exceptions

ValueError

scale is negative (scale < 0).

logistic(NDArray, NDArray, Shape?)

Draw samples from a logistic distribution with array-valued, broadcast location and scale.

public NDArray logistic(NDArray loc, NDArray scale = null, Shape? size = null)

Parameters

loc NDArray

The mean. Null is NumPy's default, 0.

scale NDArray

The scale, non-negative (-0.0 rejected; NaN accepted). Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

Exceptions

TypeError

A parameter does not cast to float64 under 'safe'.

ValueError

An element of scale is negative, or the shapes do not broadcast / the size is incompatible.

logistic(double, double, Shape?)

Draw samples from a logistic distribution.

public NDArray logistic(double loc = 0, double scale = 1, Shape? size = null)

Parameters

loc double

The mean. Default 0.

scale double

The scale, non-negative (-0.0 rejected; NaN accepted). Default 1.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.logistic.html
NumPy's random_logistic (shared with RandomState), one uniform per value.

Exceptions

ValueError

scale is negative (scale < 0).

lognormal(NDArray, NDArray, Shape?)

Draw samples from a log-normal distribution with array-valued, broadcast parameters.

public NDArray lognormal(NDArray mean, NDArray sigma = null, Shape? size = null)

Parameters

mean NDArray

Mean of the underlying normal. Null is NumPy's default, 0.

sigma NDArray

Standard deviation of the underlying normal, non-negative (-0.0 rejected; NaN accepted). Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.lognormal.html
exp(mean + sigma * N) per position over bulk-filled ziggurat normals. Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to float64 under 'safe'.

ValueError

An element of sigma is negative, or the shapes do not broadcast / the size is incompatible.

lognormal(double, double, Shape?)

Draw samples from a log-normal distribution.

public NDArray lognormal(double mean = 0, double sigma = 1, Shape? size = null)

Parameters

mean double

Mean of the underlying normal distribution. Default 0.

sigma double

Standard deviation of the underlying normal, non-negative (-0.0 rejected; NaN accepted). Default 1.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.lognormal.html
NumPy's random_lognormal: exp(mean + sigma * N) over a ziggurat normal — a fill is the normal fill, then the transform in place. Byte-identical to default_rng(seed).lognormal.

Exceptions

ValueError

sigma is negative (sigma < 0).

logseries(NDArray, Shape?)

Draw samples from a logarithmic series distribution with an array-valued, broadcast shape.

public NDArray logseries(NDArray p, Shape? size = null)

Parameters

p NDArray

Shape, in [0, 1) (NaN rejected). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is p's shape.

Returns

NDArray

The int64 draws (>= 1); a 0-d array for a 0-d p and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.logseries.html
The modern random_logseries per position; like the scalar sampler, a count can differ only where Windows NumPy's expm1 and Expm1(double) part by an ulp at a boundary.

Exceptions

TypeError

p does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element is outside [0, 1) or NaN (p < 0, p >= 1 or p contains NaNs), or the size is incompatible.

logseries(double, Shape?)

Draw samples from a logarithmic series distribution.

public NDArray logseries(double p, Shape? size = null)

Parameters

p double

Shape parameter, in [0, 1) (NaN rejected).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The int64 draws (>= 1).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.logseries.html
NumPy's modern random_logseries (log1p/expm1 spellings). The draws are NumPy's; a count can differ only where Windows NumPy's expm1 and Expm1(double) part by an ulp AND a uniform lands inside that ulp of a boundary (see Logseries(ref DrawBufferDouble, double, double)).

Exceptions

ValueError

p is outside [0, 1) or NaN (p < 0, p >= 1 or p is NaN).

multinomial(NDArray, NDArray, Shape?)

Draw samples from a multinomial distribution with broadcasting trial counts and probability rows.

public NDArray multinomial(NDArray n, NDArray pvals, Shape? size = null)

Parameters

n NDArray

Number of experiments: a scalar or an array broadcast against pvals' leading shape. Its dtype must reach int64 under the 'safe' rule (bool, the signed integers, uint8-uint32).

pvals NDArray

Probabilities; the last axis holds the d outcomes, the leading axes broadcast. Any real dtype and layout (cast to float64); null reads as NumPy's None (a 0-d NaN, rejected as dimensionless).

size Shape?

Leading output shape. null (NumPy's None, the default) uses the broadcast shape of n and pvals' leading axes.

Returns

NDArray

The int64 counts, shape (*broadcast, d).

Remarks

With a 0-d n and 1-D pvals this is the plain path (one row per size position); otherwise NumPy's vector path, which pairs every broadcast position with its own count and probability row, in C order.

Exceptions

TypeError

In NumPy's order: n is null, or its dtype is not safely castable to int64 (a float or uint64 count: Cannot cast array data from dtype('float64') to dtype('int64') according to the rule 'safe', scalar for a 0-d array); pvals is complex.

ValueError

In NumPy's order: pvals is 0-d or has an empty last axis; an element is outside [0, 1] or NaN; a row's sum(pvals[...,:-1]) > 1.0 (NumPy's alternate text for a float16/float32 array whose own sum is below 1.0001); an element of n is negative; the inputs and size do not broadcast (NumPy's shape mismatch text) or broadcast to a shape other than size (Output size ... is not compatible ...).

multinomial(long, NDArray, Shape?)

Draw samples from a multinomial distribution, with array-valued probabilities (the last axis is the outcomes).

public NDArray multinomial(long n, NDArray pvals, Shape? size = null)

Parameters

n long

Number of experiments, non-negative.

pvals NDArray

Probabilities, any numeric dtype and layout (cast to float64); rows along the last axis.

size Shape?

Leading output shape; must equal the broadcast of pvals' leading shape.

Returns

NDArray

The int64 counts, shape (*broadcast, d).

Exceptions

ValueError

See multinomial(NDArray, NDArray, Shape).

TypeError

pvals is complex (not safely castable to float64).

multinomial(long, double[], Shape?)

Draw samples from a multinomial distribution.

public NDArray multinomial(long n, double[] pvals, Shape? size = null)

Parameters

n long

Number of experiments, non-negative.

pvals double[]

Probabilities of each of the d outcomes, each in [0, 1]; sum(pvals[:-1]) must not exceed 1 (the last entry takes whatever probability is left).

size Shape?

Leading output shape. null (NumPy's None, the default) draws one vector of shape (d,).

Returns

NDArray

The int64 counts, shape (*size, d).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.multinomial.html
NumPy's random_multinomial — one conditional binomial per category over this Generator's binomial cache. Byte-identical to default_rng(seed).multinomial.

Exceptions

ValueError

In NumPy's order: pvals is empty; an element is outside [0, 1] or NaN; sum(pvals[:-1]) > 1.0; then (after the output exists) n is negative (n < 0).

multivariate_hypergeometric(NDArray, long, Shape?, string)

Generate variates from a multivariate hypergeometric distribution, the colors given as an array.

public NDArray multivariate_hypergeometric(NDArray colors, long nsample, Shape? size = null, string method = "marginals")

Parameters

colors NDArray

1-D array of non-negative integers (any integer dtype; an empty array of any dtype is allowed).

nsample long

The number of items selected.

size Shape?

Leading output shape. null (NumPy's None, the default) draws one variate.

method string

"marginals" (default) or "count".

Returns

NDArray

The int64 variates, shape (*size, len(colors)).

Exceptions

ValueError

See multivariate_hypergeometric(long[], long, Shape, string); also a non-1-D or non-integer colors.

OutOfMemoryException

"count" cannot allocate its work array.

multivariate_hypergeometric(long[], long, Shape?, string)

Generate variates from a multivariate hypergeometric distribution.

public NDArray multivariate_hypergeometric(long[] colors, long nsample, Shape? size = null, string method = "marginals")

Parameters

colors long[]

The number of each type of item in the collection (non-negative integers).

nsample long

The number of items selected, 0 <= nsample <= sum(colors).

size Shape?

Leading output shape. null (NumPy's None, the default) draws one variate of shape (len(colors),).

method string

"marginals" (default; successive univariate hypergeometric draws, sum(colors) < 10^9) or "count" (a partial Fisher-Yates shuffle over an array of sum(colors) entries).

Returns

NDArray

The int64 variates, shape (*size, len(colors)).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.multivariate_hypergeometric.html
NumPy's random_multivariate_hypergeometric_count / _marginals. Byte-identical to default_rng(seed).multivariate_hypergeometric.

Exceptions

ValueError

In NumPy's order: an unknown method; a negative nsample; a negative color; a sum of colors past int64; "marginals" with sum(colors) >= 10^9; "count" with a sum too large to index; nsample > sum(colors).

OutOfMemoryException

"count" cannot allocate its sum(colors)-entry work array.

multivariate_normal(NDArray, NDArray, Shape?, string, double, string)

Draw random samples from a multivariate normal distribution.

public NDArray multivariate_normal(NDArray mean, NDArray cov, Shape? size = null, string check_valid = "warn", double tol = 1E-08, string method = "svd")

Parameters

mean NDArray

Mean of the N-dimensional distribution (1-D).

cov NDArray

Covariance matrix (N x N, symmetric positive-semidefinite for proper sampling).

size Shape?

Leading output shape. null (NumPy's None, the default) draws one sample of shape (N,).

check_valid string

Behaviour when cov is not positive-semidefinite: "warn" (NumPy warns; NumSharp has no warnings channel, so this is silent), "raise" or "ignore".

tol double

Tolerance of the positive-semidefiniteness check.

method string

"svd" (default), "eigh" or "cholesky": the factorisation of cov.

Returns

NDArray

The float64 samples, shape (*size, N).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.multivariate_normal.html
NumPy's algorithm: the standard normals are drawn FIRST, then mean + x @ factor.T with factor = u * sqrt(s) (svd), u * sqrt(|s|) (eigh) or L (cholesky). Byte-identical to NumPy when NumSharp.Interop.OpenBLAS supplies LAPACK (the same gesdd/syevd/potrf); without it managed factorisations stand in (Jacobi eigen for svd/eigh, Cholesky-Banachiewicz), which give a valid sample but can differ in a singular vector's sign.

Exceptions

ValueError

In NumPy's order: an unknown method; a non-1-D (or null) mean, non-square (or null) cov or mismatched lengths; an invalid check_valid (not checked for cholesky); a covariance that is not positive-semidefinite under "raise".

TypeError

mean or cov is complex (checked before the shapes, as NumPy does).

LinAlgError

"cholesky" of a covariance that is not positive definite.

multivariate_normal(double[], double[,], Shape?, string, double, string)

Draw random samples from a multivariate normal distribution (array arguments).

public NDArray multivariate_normal(double[] mean, double[,] cov, Shape? size = null, string check_valid = "warn", double tol = 1E-08, string method = "svd")

Parameters

mean double[]

Mean of the N-dimensional distribution.

cov double[,]

Covariance matrix, N x N.

size Shape?

Leading output shape. null (NumPy's None, the default) draws one sample.

check_valid string

"warn", "raise" or "ignore".

tol double

Tolerance of the positive-semidefiniteness check.

method string

"svd", "eigh" or "cholesky".

Returns

NDArray

The float64 samples, shape (*size, N).

Exceptions

ValueError

See multivariate_normal(NDArray, NDArray, Shape, string, double, string).

LinAlgError

"cholesky" of a covariance that is not positive definite.

negative_binomial(NDArray, NDArray, Shape?)

Draw samples from a negative binomial distribution with array-valued, broadcast parameters.

public NDArray negative_binomial(NDArray n, NDArray p, Shape? size = null)

Parameters

n NDArray

Parameter, positive and not NaN (need not be an integer). Null is Python's None — NumPy reads it as NaN here (n must not be NaN), not as a TypeError.

p NDArray

Probability of success, in (0, 1]. Null is Python's None (NaN, rejected).

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The int64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.negative_binomial.html
The modern random_negative_binomial per position: a Poisson of a gamma draw. Byte-identical to NumPy.

Exceptions

TypeError

p (converted first) or n does not cast to float64 under 'safe'.

ValueError

In NumPy's order: n NaN or not positive, p outside (0, 1], the implied Poisson mean (1-p)/p * (n + 10*sqrt(n)) above the int64-safe bound (n too large or p too small, see Generator.negative_binomial Notes) — whose whole-array arithmetic raises NumPy's ufunc broadcast error for mismatched shapes — or an incompatible size.

negative_binomial(double, double, Shape?)

Draw samples from a negative binomial distribution.

public NDArray negative_binomial(double n, double p, Shape? size = null)

Parameters

n double

Parameter of the distribution, positive and not NaN (need not be an integer).

p double

Probability of success, in (0, 1].

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The int64 draws (the number of failures before n successes).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.negative_binomial.html
NumPy's modern random_negative_binomial: a Poisson whose mean is a gamma draw of shape n and scale (1 - p) / p. Byte-identical to default_rng(seed).negative_binomial.

Exceptions

ValueError

In NumPy's order: n is NaN (n must not be NaN) or not positive (n <= 0); p outside (0, 1]; or the implied Poisson mean (1-p)/p * (n + 10*sqrt(n)) exceeds the int64-safe bound (n too large or p too small, see Generator.negative_binomial Notes).

noncentral_chisquare(NDArray, NDArray, Shape?)

Draw samples from a noncentral chi-square distribution with array-valued, broadcast parameters.

public NDArray noncentral_chisquare(NDArray df, NDArray nonc, Shape? size = null)

Parameters

df NDArray

Degrees of freedom, positive (NaN accepted). Null is Python's None.

nonc NDArray

Non-centrality, non-negative (-0.0 rejected; NaN returns NaN without drawing). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.noncentral_chisquare.html
The modern random_noncentral_chisquare per position; a NaN non-centrality returns NaN without drawing (so an array holding one reads per draw). Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element of df (checked first) is not positive or of nonc negative, or the shapes do not broadcast / the size is incompatible.

noncentral_chisquare(double, double, Shape?)

Draw samples from a noncentral chi-square distribution.

public NDArray noncentral_chisquare(double df, double nonc, Shape? size = null)

Parameters

df double

Degrees of freedom, positive (NaN accepted).

nonc double

Non-centrality, non-negative (-0.0 rejected; NaN accepted and returns NaN without drawing).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.noncentral_chisquare.html
NumPy's modern random_noncentral_chisquare — unlike the legacy sampler it tests a NaN non-centrality BEFORE drawing (so it advances nothing). Byte-identical to default_rng(seed).noncentral_chisquare.

Exceptions

ValueError

df is not positive (checked first) or nonc is negative.

noncentral_f(NDArray, NDArray, NDArray, Shape?)

Draw samples from the noncentral F distribution with array-valued, broadcast parameters.

public NDArray noncentral_f(NDArray dfnum, NDArray dfden, NDArray nonc, Shape? size = null)

Parameters

dfnum NDArray

Numerator degrees of freedom, positive (NaN accepted). Null is Python's None.

dfden NDArray

Denominator degrees of freedom, positive (NaN accepted). Null is Python's None.

nonc NDArray

Non-centrality, non-negative (-0.0 rejected; NaN accepted). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when every parameter is 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.noncentral_f.html
NumPy's random_noncentral_f per position. Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

In NumPy's order: dfnum / dfden not positive, nonc negative; or the shapes do not broadcast / the size is incompatible.

noncentral_f(double, double, double, Shape?)

Draw samples from the noncentral F distribution.

public NDArray noncentral_f(double dfnum, double dfden, double nonc, Shape? size = null)

Parameters

dfnum double

Numerator degrees of freedom, positive (NaN accepted).

dfden double

Denominator degrees of freedom, positive (NaN accepted).

nonc double

Non-centrality, non-negative (-0.0 rejected; NaN accepted).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.noncentral_f.html
NumPy's random_noncentral_f: (ncchi2(dfnum, nonc) * dfden) / (chi2(dfden) * dfnum). Byte-identical to default_rng(seed).noncentral_f.

Exceptions

ValueError

In NumPy's order: dfnum or dfden is not positive, or nonc is negative.

normal(NDArray, NDArray, Shape?)

Draw samples from a normal (Gaussian) distribution with array-valued, broadcast parameters.

public NDArray normal(NDArray loc, NDArray scale = null, Shape? size = null)

Parameters

loc NDArray

Mean of the distribution. Null is NumPy's default, 0.

scale NDArray

Standard deviation; sign bit must be clear (-0.0 rejected), NaN propagates. Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.normal.html
loc + scale * standard_normal() per position: the ziggurat normals are bulk-filled (one per value) and transformed in place. Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to float64 under 'safe' (complex).

ValueError

An element of scale is negative, or the shapes do not broadcast / the size is incompatible.

normal(double, double, Shape?)

Draw samples from a normal (Gaussian) distribution.

public NDArray normal(double loc = 0, double scale = 1, Shape? size = null)

Parameters

loc double

Mean of the distribution.

scale double

Standard deviation (sign bit must be clear; NaN propagates).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

Exceptions

ValueError

scale is negative, including -0.0 (NumPy's scale < 0).

pareto(NDArray, Shape?)

Draw samples from a Pareto II (Lomax) distribution with an array-valued, broadcast shape.

public NDArray pareto(NDArray a, Shape? size = null)

Parameters

a NDArray

Shape, positive (NaN accepted). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is a's shape.

Returns

NDArray

The float64 draws; a 0-d array for a 0-d a and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.pareto.html
expm1(E / a) per position over bulk-filled exponentials; the values carry the scalar pareto(double, Shape)'s documented expm1 band difference (see Expm1(double)).

Exceptions

TypeError

a does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element is not positive (a <= 0), or the size is incompatible.

pareto(double, Shape?)

Draw samples from a Pareto II (AKA Lomax) distribution with specified shape.

public NDArray pareto(double a, Shape? size = null)

Parameters

a double

Shape of the distribution, positive (NaN accepted).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.pareto.html
NumPy's modern random_pareto: expm1(E / a) over a ziggurat exponential. The draws are NumPy's; the value is bit-identical wherever E / a lies outside [-ln 2, ln 1.5] and can sit up to 2 ulp from Windows NumPy's inside it, where the MSVC expm1 uses an approximation no public formula reproduces (see Expm1(double)). Measured over 20000 draws: 30% of pareto(3) values differ (1% by 2 ulp), 8% of pareto(0.5).

Exceptions

ValueError

a is not positive (a <= 0).

permutation(NDArray, int)

Randomly permute a copy of x along axis.

public NDArray permutation(NDArray x, int axis = 0)

Parameters

x NDArray

The array to permute (at least 1-D).

axis int

The axis whose slices are permuted.

Returns

NDArray

The permuted data, never sharing x's memory, laid out as NumPy lays it out: for 1-D input or axis=0, a fresh C-contiguous array that owns its data; for axis > 0 of an N-D input, a VIEW of a fresh array whose first axis is the permuted one (owndata False; F-contiguous for 2-D, permuted strides beyond) — NumPy's fancy-index result.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.permutation.html
1-D input: a copy shuffled in place; N-D input: a shuffled index vector gathered with take (NumPy's arr[tuple(slices)]), consuming the stream identically.
The layout is observable (flags.owndata, the contiguity flags, strides), so it follows NumPy's indexing machinery rather than np.take's C-ordered result; see the method body.

Exceptions

AxisError

axis is outside [-x.ndim, x.ndim) — which every axis is for a 0-d x, and for a null one (NumPy's np.asarray(None) is 0-d): axis 0 is out of bounds for array of dimension 0.

permutation(long, int)

Randomly permute arange(x).

public NDArray permutation(long x, int axis = 0)

Parameters

x long

The length of the range.

axis int

Accepted for NumPy's signature permutation(x, axis=0) and, as in NumPy, ignored for an integer x (its isinstance(x, int) branch shuffles np.arange(x) before the axis is ever normalized), so any value is accepted.

Returns

NDArray

A shuffled int64 range.

Remarks

permuted(NDArray, int?, NDArray)

Randomly permute x along axis. Unlike shuffle(NDArray, int), each slice along the axis is shuffled INDEPENDENTLY of the others.

public NDArray permuted(NDArray x, int? axis = null, NDArray @out = null)

Parameters

x NDArray

Array to shuffle (at least 1-D when an axis is given).

axis int?

Axis whose slices are each shuffled; null shuffles the flattened array.

out NDArray

Optional writeable destination of x's shape, filled with casting='safe'; returned when given.

Returns

NDArray

The permuted array: out when given, else a copy of x with its memory layout kept (order='K').

Remarks

A null x is NumPy's np.asarray(None): a 0-d OBJECT array, failing exactly where any 0-d input fails (the len() TypeError without an axis, the AxisError with one), and an out can only mismatch its shape or refuse the object-to-dtype cast.

Exceptions

ValueError

out is read-only, or its shape differs from x's.

TypeError

x's dtype cannot be cast to out's under 'safe'; or axis is null and x is 0-d.

AxisError

axis is outside [-x.ndim, x.ndim).

poisson(NDArray, Shape?)

Draw samples from a Poisson distribution with an array-valued, broadcast mean.

public NDArray poisson(NDArray lam, Shape? size = null)

Parameters

lam NDArray

Expected number of events, non-negative, not NaN, at most int64 max - 10*sqrt(int64 max). Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is lam's shape.

Returns

NDArray

The int64 draws; a 0-d array for a 0-d mean and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.poisson.html
random_poisson per position (product method below 10, PTRS above, 0 without a draw for lam == 0). Byte-identical to NumPy.

Exceptions

TypeError

lam does not cast to float64 under 'safe'.

ValueError

An element is too large or NaN (lam value too large — the array test runs the bound FIRST, so NaN reports it) or negative (lam < 0 or lam contains NaNs), or the size is incompatible.

poisson(double, Shape?)

Draw samples from a Poisson distribution.

public NDArray poisson(double lam = 1, Shape? size = null)

Parameters

lam double

Expected number of events, non-negative, not NaN, at most int64 max - 10*sqrt(int64 max). Default 1.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The int64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.poisson.html
NumPy's random_poisson: 0 without drawing for lam == 0, the product method below 10 and PTRS above, its setup evaluated once per call. Byte-identical to default_rng(seed).poisson.

Exceptions

ValueError

lam is negative or NaN (lam < 0 or lam is NaN, checked first) or too large (lam value too large).

power(NDArray, Shape?)

Draw samples in [0, 1] from a power distribution with an array-valued, broadcast exponent.

public NDArray power(NDArray a, Shape? size = null)

Parameters

a NDArray

Parameter, positive (NaN accepted). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is a's shape.

Returns

NDArray

The float64 draws; a 0-d array for a 0-d a and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.power.html
(-expm1(-E))^(1/a) per position over bulk-filled exponentials; the values carry the scalar power(double, Shape)'s documented expm1 band difference.

Exceptions

TypeError

a does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element is not positive (a <= 0), or the size is incompatible.

power(double, Shape?)

Draws samples in [0, 1] from a power distribution with positive exponent a - 1.

public NDArray power(double a, Shape? size = null)

Parameters

a double

Parameter of the distribution, positive (NaN accepted).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.power.html
NumPy's modern random_power: (-expm1(-E))^(1/a) over a ziggurat exponential; like pareto(NDArray, Shape?), bit-identical except where -E lies in [-ln 2, 0], where the MSVC expm1 can differ by up to 2 ulp (see Expm1(double)) — and the power 1/a scales that relative difference: measured over 20000 draws, power(2.5) stays within 1 ulp (8% of values differ) while power(0.3) reaches 9 ulp (20% of values).

Exceptions

ValueError

a is not positive (a <= 0).

random(Shape?, DType, NDArray)

Return random floats in the half-open interval [0.0, 1.0).

public NDArray random(Shape? size = null, DType dtype = null, NDArray @out = null)

Parameters

size Shape?

Output shape. null (NumPy's None, the default) returns a single value; () returns a 0-d array.

dtype DType

Desired dtype — only native float64 (default) and float32 are supported.

out NDArray

Optional C- or F-contiguous output array to fill in memory order; returned when given.

Returns

NDArray

The draws; a float64 0-d array for size=None (NumPy widens a float32 scalar draw to a Python float).

Remarks

Exceptions

TypeError

dtype is not a native float32/float64, or out has the wrong dtype.

ValueError

out is not contiguous/writeable, or its shape disagrees with size.

rayleigh(NDArray, Shape?)

Draw samples from a Rayleigh distribution with an array-valued, broadcast scale.

public NDArray rayleigh(NDArray scale, Shape? size = null)

Parameters

scale NDArray

Scale (also the mode), non-negative (-0.0 rejected; NaN accepted). Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is scale's shape.

Returns

NDArray

The float64 draws; a 0-d array for a 0-d scale and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.rayleigh.html
The modern mode * sqrt(2 * E) per position over bulk-filled exponentials. Byte-identical to NumPy.

Exceptions

TypeError

scale does not cast to float64 under 'safe'.

ValueError

An element is negative (scale < 0), or the size is incompatible.

rayleigh(double, Shape?)

Draw samples from a Rayleigh distribution.

public NDArray rayleigh(double scale = 1, Shape? size = null)

Parameters

scale double

Scale, also equals the mode; non-negative (-0.0 rejected; NaN accepted). Default 1.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.rayleigh.html
NumPy's modern random_rayleigh: mode * sqrt(2 * E) over a ziggurat exponential (the legacy sampler uses -log1p(-U) instead). Byte-identical to default_rng(seed).rayleigh.

Exceptions

ValueError

scale is negative (scale < 0).

shuffle(NDArray, int)

Modify an array in-place by shuffling its contents along the given axis.

public void shuffle(NDArray x, int axis = 0)

Parameters

x NDArray

The writeable array to shuffle (at least 1-D).

axis int

The axis whose slices are permuted (the other axes move with them).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.shuffle.html
Fisher–Yates using random_interval (mask-rejection), byte-identical to NumPy. The draws hold the bit generator's lock.

Exceptions

TypeError

x is null (object of type 'NoneType' has no len()) or 0-d (len() of unsized object) — NumPy evaluates len(x) first.

ValueError

x is read-only.

AxisError

axis is outside [-x.ndim, x.ndim) (NumPy's normalize_axis_index).

spawn(int)

Create new independent child generators (NumPy's Generator.spawn): each wraps a child of bit_generator's seed sequence, via spawn(int) — the recommended way to hand non-overlapping streams to parallel workers.

public Generator[] spawn(int n_children)

Parameters

n_children int

The number of children.

Returns

Generator[]

The children, each a Generator over a fresh bit generator of the same type.

Remarks

Spawning advances the seed sequence's n_children_spawned, so it never repeats a child; it does NOT consume this generator's stream (the children are seeded, not drawn).

Exceptions

ValueError

n_children is negative: NumPy 2.5's n_children must be non-negative, raised first.

TypeError

The bit generator's seed sequence cannot spawn (a legacy-seeded MT19937, a keyed Philox): The underlying SeedSequence does not implement spawning.

OverflowError

The seed sequence's child count would leave its uint32 range.

standard_cauchy(Shape?)

Draw samples from a standard Cauchy distribution with mode = 0.

public NDArray standard_cauchy(Shape? size = null)

Parameters

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.standard_cauchy.html
NumPy's random_standard_cauchy: the ratio of two ziggurat normals, numerator first — so a fill is the Generator's normal fill of consecutive pairs, divided (the same division, the same bits). Byte-identical to default_rng(seed).standard_cauchy.

standard_exponential(Shape?, DType, string, NDArray)

Draw samples from the standard exponential distribution.

public NDArray standard_exponential(Shape? size = null, DType dtype = null, string method = "zig", NDArray @out = null)

Parameters

size Shape?

Output shape. null (NumPy's None, the default) returns a single value; () returns a 0-d array.

dtype DType

Native float64 (default) or float32.

method string

"zig" (ziggurat, default); any other string selects the inverse-CDF sampler, as in NumPy.

out NDArray

Optional C- or F-contiguous output array, filled in memory order and returned.

Returns

NDArray

The draws; a float64 0-d array for size=None even when dtype is float32.

Remarks

Exceptions

TypeError

dtype is not a native float32/float64, or out has the wrong dtype.

ValueError

out is not contiguous/writeable, or its shape disagrees with size.

standard_gamma(NDArray, Shape?, DType, NDArray)

Draw samples from a standard Gamma distribution with an array-valued, broadcast shape.

public NDArray standard_gamma(NDArray shape, Shape? size = null, DType dtype = null, NDArray @out = null)

Parameters

shape NDArray

The shape parameter; sign bit must be clear, NaN propagates. Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is shape's shape (or out's when given).

dtype DType

Native float64 (default) or float32.

out NDArray

Optional C-contiguous output of the loop dtype; its shape must be one the parameter broadcasts into. Returned when given.

Returns

NDArray

The draws (float64, or float32 for dtype float32 unless the scalar path returns the float64 0-d scalar NumPy returns for size=None).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.standard_gamma.html
NumPy's order: the dtype, then check_output, then the conversion. float64 converts under 'safe' (cont); float32 under FORCECAST (cont_f): every dtype is cast (complex keeps its real part) and the constraint runs on the float32 values, so 1e-50 becomes a zero shape that draws nothing. A zero shape returns 0 without drawing on both paths. Byte-identical to NumPy.

Exceptions

TypeError

dtype is unsupported, out has the wrong dtype, the float64 path cannot cast shape under 'safe', or a None / 0-d complex reaches the scalar path.

ValueError

out is not C-contiguous/writeable or disagrees with the size or the parameter's shape, or an element is negative (shape < 0).

standard_gamma(double, Shape?, DType, NDArray)

Draw samples from a standard Gamma distribution (scale = 1).

public NDArray standard_gamma(double shape, Shape? size = null, DType dtype = null, NDArray @out = null)

Parameters

shape double

The shape parameter; sign bit must be clear (-0.0 rejected), NaN propagates.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value; () returns a 0-d array.

dtype DType

Native float64 (default) or float32.

out NDArray

Optional C-CONTIGUOUS output array (NumPy's cont/cont_f reject F order), returned when given.

Returns

NDArray

The draws; a float64 0-d array for size=None even when dtype is float32.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.standard_gamma.html
Validation order follows NumPy's cont: dtype → out (check_output runs first inside cont) → the shape constraint, so a call that is wrong in several ways reports NumPy's first error.

Exceptions

TypeError

dtype is not a native float32/float64, or out has the wrong dtype.

ValueError

out is not C-contiguous/writeable or mis-shaped, or shape is negative.

standard_normal(Shape?, DType, NDArray)

Draw samples from a standard Normal distribution (mean 0, stdev 1).

public NDArray standard_normal(Shape? size = null, DType dtype = null, NDArray @out = null)

Parameters

size Shape?

Output shape. null (NumPy's None, the default) returns a single value; () returns a 0-d array.

dtype DType

Desired dtype — native float64 (default) or float32.

out NDArray

Optional C- or F-contiguous output array, filled in memory order and returned.

Returns

NDArray

The draws; a float64 0-d array for size=None even when dtype is float32.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.standard_normal.html
Uses NumPy's ziggurat sampler, so the stream matches default_rng(seed).standard_normal(...).

Exceptions

TypeError

dtype is not a native float32/float64, or out has the wrong dtype.

ValueError

out is not contiguous/writeable, or its shape disagrees with size.

standard_t(NDArray, Shape?)

Draw samples from a standard Student's t distribution with array-valued, broadcast degrees of freedom.

public NDArray standard_t(NDArray df, Shape? size = null)

Parameters

df NDArray

Degrees of freedom, positive (NaN accepted). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is df's shape.

Returns

NDArray

The float64 draws; a 0-d array for a 0-d df and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.standard_t.html
sqrt(df/2) * N / sqrt(G(df/2)) per position, the normal drawn first. Byte-identical to NumPy.

Exceptions

TypeError

df does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element is not positive (df <= 0), or the size is incompatible.

standard_t(double, Shape?)

Draw samples from a standard Student's t distribution with df degrees of freedom.

public NDArray standard_t(double df, Shape? size = null)

Parameters

df double

Degrees of freedom, positive (NaN accepted).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.standard_t.html
NumPy's random_standard_t: sqrt(df/2) * N / sqrt(G(df/2)), the normal drawn first. Byte-identical to default_rng(seed).standard_t.

Exceptions

ValueError

df is not positive (df <= 0).

triangular(NDArray, NDArray, NDArray, Shape?)

Draw samples from the triangular distribution over [left, right] with array-valued, broadcast limits.

public NDArray triangular(NDArray left, NDArray mode, NDArray right, Shape? size = null)

Parameters

left NDArray

Lower limit. Null is Python's None.

mode NDArray

The peak, left <= mode <= right. Null is Python's None.

right NDArray

Upper limit, greater than left. Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is the limits' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when every limit is 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.triangular.html
NumPy's three whole-array comparisons (np.greater / np.equal), then cont_broadcast_3 over random_triangular. A NaN limit passes every comparison and samples NaN. Byte-identical to NumPy.

Exceptions

TypeError

A limit does not cast to float64 under 'safe', or a None reaches the scalar path (read in NumPy's order: left, right, mode).

ValueError

In NumPy's order: any left > mode, any mode > right, any left == right; the comparisons' own broadcast errors (operands could not be broadcast together with shapes …); or an incompatible size.

triangular(double, double, double, Shape?)

Draw samples from the triangular distribution over the interval [left, right].

public NDArray triangular(double left, double mode, double right, Shape? size = null)

Parameters

left double

Lower limit.

mode double

The peak; left <= mode <= right.

right double

Upper limit, greater than left.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.triangular.html
NumPy's random_triangular (shared with RandomState), one uniform per value. A NaN limit passes the checks (every comparison is false) and samples NaN, as in NumPy.

Exceptions

ValueError

In NumPy's order: left > mode, mode > right, left == right.

uniform(NDArray, NDArray, Shape?)

Draw samples from a uniform distribution over [low, high) with array-valued, broadcast bounds.

public NDArray uniform(NDArray low, NDArray high = null, Shape? size = null)

Parameters

low NDArray

Lower boundary (inclusive). Null is NumPy's default, 0.

high NDArray

Upper boundary (exclusive). Null is NumPy's default, 1.

size Shape?

Output shape. null (NumPy's None, the default) is the broadcast shape of low and high - low.

Returns

NDArray

The float64 draws; a 0-d array when both bounds are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.uniform.html
NumPy computes np.subtract(high, low) as a whole array first (its broadcast error is the ufunc's), then draws low + range * next_double() per position over the broadcast of low and the range. The uniforms are bulk-filled (one per value) and transformed in place. Byte-identical to NumPy.

Exceptions

TypeError

A bound does not cast to float64 under 'safe' (complex).

OverflowError

An element of high - low is infinite or NaN — NumPy's OverflowError('Range exceeds valid bounds') ('high - low range exceeds valid bounds' on the scalar path).

ValueError

The bounds do not broadcast (NumPy's np.subtract text: operands could not be broadcast together with shapes …), an element of high - low has its sign bit set (high - low < 0), or the size is incompatible.

uniform(double, double, Shape?)

Draw samples from a uniform distribution over [low, high).

public NDArray uniform(double low = 0, double high = 1, Shape? size = null)

Parameters

low double

Lower boundary (inclusive). Default 0.

high double

Upper boundary (exclusive). Default 1.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.uniform.html
low + (high - low) * next_double(), byte-identical to NumPy.

Exceptions

OverflowError

high - low is not finite (NumPy's OverflowError).

ValueError

high - low has its sign bit set (NumPy's CONS_NON_NEGATIVE: -0.0 included).

vonmises(NDArray, NDArray, Shape?)

Draw samples from a von Mises distribution with array-valued, broadcast parameters.

public NDArray vonmises(NDArray mu, NDArray kappa, Shape? size = null)

Parameters

mu NDArray

Mode ("center"). Null is Python's None.

kappa NDArray

Concentration, non-negative (-0.0 rejected; NaN returns NaN without drawing). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws in [-pi, pi]; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.vonmises.html
The modern random_vonmises per position. Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element of kappa is negative, or the shapes do not broadcast / the size is incompatible.

vonmises(double, double, Shape?)

Draw samples from a von Mises distribution.

public NDArray vonmises(double mu, double kappa, Shape? size = null)

Parameters

mu double

Mode ("center") of the distribution.

kappa double

Concentration, non-negative (-0.0 rejected; NaN accepted and returns NaN without drawing).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws, in [-pi, pi].

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.vonmises.html
NumPy's modern random_vonmises: a uniform below kappa = 1e-8, Best & Fisher's wrapped-Cauchy rejection up to 1e6, the wrapped normal above (so kappa = inf returns mu). Byte-identical to default_rng(seed).vonmises.

Exceptions

ValueError

kappa is negative (kappa < 0).

wald(NDArray, NDArray, Shape?)

Draw samples from a Wald (inverse Gaussian) distribution with array-valued, broadcast parameters.

public NDArray wald(NDArray mean, NDArray scale, Shape? size = null)

Parameters

mean NDArray

Distribution mean, positive (NaN accepted). Null is Python's None.

scale NDArray

Scale, positive (NaN accepted). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is the parameters' broadcast shape.

Returns

NDArray

The float64 draws; a 0-d array when both parameters are 0-d and no size is given.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.wald.html
The modern random_wald per position. Byte-identical to NumPy.

Exceptions

TypeError

A parameter does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element of mean (checked first) or scale is not positive, or the shapes do not broadcast / the size is incompatible.

wald(double, double, Shape?)

Draw samples from a Wald, or inverse Gaussian, distribution.

public NDArray wald(double mean, double scale, Shape? size = null)

Parameters

mean double

Distribution mean, positive (NaN accepted).

scale double

Scale parameter, positive (NaN accepted).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.wald.html
NumPy's modern random_wald (the cancellation-free form), one ziggurat normal and one uniform per value. Byte-identical to default_rng(seed).wald.

Exceptions

ValueError

mean (checked first) or scale is not positive.

weibull(NDArray, Shape?)

Draw samples from a Weibull distribution with an array-valued, broadcast shape.

public NDArray weibull(NDArray a, Shape? size = null)

Parameters

a NDArray

Shape, non-negative (-0.0 rejected; NaN accepted); 0 returns 0 without drawing. Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is a's shape.

Returns

NDArray

The float64 draws; a 0-d array for a 0-d a and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.weibull.html
E^(1/a) per position, 0 without a draw where a == 0. The exponentials the drawing positions take are bulk-filled into the TAIL of the output and consumed front to back — a position never reads a slot an earlier position overwrote, because at most as many positions precede it as draw-free positions exist. Byte-identical to NumPy.

Exceptions

TypeError

a does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element is negative (a < 0), or the size is incompatible.

weibull(double, Shape?)

Draw samples from a Weibull distribution.

public NDArray weibull(double a, Shape? size = null)

Parameters

a double

Shape parameter, non-negative (-0.0 rejected; NaN accepted). 0 returns 0 without drawing.

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The float64 draws.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.weibull.html
NumPy's random_weibull: 0 (no draw) for a == 0, else E^(1/a) over a ziggurat exponential. Byte-identical to default_rng(seed).weibull.

Exceptions

ValueError

a is negative (a < 0).

zipf(NDArray, Shape?)

Draw samples from a Zipf distribution with an array-valued, broadcast parameter.

public NDArray zipf(NDArray a, Shape? size = null)

Parameters

a NDArray

Distribution parameter, greater than 1 (NaN rejected). Null is Python's None.

size Shape?

Output shape. null (NumPy's None, the default) is a's shape.

Returns

NDArray

The int64 draws (>= 1); a 0-d array for a 0-d a and no size.

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.zipf.html
The modern random_zipf per position; a >= 1025 (infinity included) returns 1 without drawing. Byte-identical to NumPy.

Exceptions

TypeError

a does not cast to float64 under 'safe', or a None reaches the scalar path.

ValueError

An element is not above 1 or is NaN (a <= 1 or a contains NaNs), or the size is incompatible.

zipf(double, Shape?)

Draw samples from a Zipf distribution.

public NDArray zipf(double a, Shape? size = null)

Parameters

a double

Distribution parameter, greater than 1 (NaN rejected).

size Shape?

Output shape. null (NumPy's None, the default) returns a single value.

Returns

NDArray

The int64 draws (>= 1).

Remarks

https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.zipf.html
NumPy's modern random_zipf: candidates are drawn from a window that keeps them within int64, and a >= 1025 (infinity included) returns 1 without drawing. Byte-identical to default_rng(seed).zipf.

Exceptions

ValueError

a is not greater than 1 or is NaN (a <= 1 or a is NaN).