Random numbers

Pseudo-random and low-discrepancy generators, mirroring QuantLib's ql/math/randomnumbers/. The class names follow QuantLib's Python API, so UniformRandomGenerator is the Mersenne Twister and UniformRandomSequenceGenerator the sequence generator over it. GaussianRandomSequenceGenerator is the pseudo-random policy the Monte Carlo engines draw from; SobolRsg, HaltonRsg and GaussianLowDiscrepancySequenceGenerator are the low-discrepancy counterparts. Draws come back as floats or NumPy arrays rather than weighted samples, and the next_sequences(count) methods draw a whole (count, dimension) matrix in one call.

randomnumbers

Runtime source shim for the native itofin.randomnumbers submodule.

The real itofin.randomnumbers is a compiled submodule registered into sys.modules by the extension; it wins at import time, so nothing here runs. This file exists only so static type checkers resolve from itofin.randomnumbers import ... from randomnumbers/__init__.pyi without a reportMissingModuleSource warning.

Auto-generated by scripts/gen_submodule_shims.py from randomnumbers/__init__.pyi; do not edit or delete by hand.

GaussianLowDiscrepancySequenceGenerator

GaussianLowDiscrepancySequenceGenerator(rsg: SobolRsg)

The Gaussian low-discrepancy sequence generator: Sobol points mapped through the inverse cumulative normal, QuantLib's InverseCumulativeRsg<SobolRsg, InverseCumulativeNormal>.

The first draw is 0.0 in every dimension, the inverse normal of the first Sobol point 0.5. The generator copies the Sobol generator it is built from, as QuantLib does.

Build a Gaussian sequence generator over a copy of a Sobol generator.

Parameters:

Name	Type	Description	Default
rsg	SobolRsg	The Sobol generator to copy the state from; its dimension is the dimension here.	required

dimension

dimension() -> int

The number of draws per sequence.

Returns:

Name	Type	Description
int	int	The dimension the generator was built with.

next_sequence

next_sequence() -> NDArray[float64]

Draw the next sequence.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,) of standard
NDArray[float64]	normal deviates.

last_sequence

last_sequence() -> NDArray[float64]

The most recently drawn sequence, without advancing.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,); all zeros
NDArray[float64]	before the first draw.

next_sequences

next_sequences(count: int) -> NDArray[float64]

Draw many sequences in one call.

Parameters:

Name	Type	Description	Default
count	int	The number of sequences to draw.	required

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (count, dimension), row i
NDArray[float64]	being what the (i + 1)-th next_sequence() call would have returned.

Raises:

Type	Description
ItofinError	If a buffer of count sequences cannot be allocated.

GaussianRandomGenerator

GaussianRandomGenerator(rng: UniformRandomGenerator)

The Gaussian pseudo-random number generator: the polar Box-Muller transform over a Mersenne Twister, QuantLib's BoxMullerGaussianRng<MersenneTwisterUniformRng>.

Each pair of uniform draws yields two standard normal deviates; the second is cached and returned by the next call, as in QuantLib.

Build a generator over a copy of a uniform generator.

Parameters:

Name	Type	Description	Default
rng	UniformRandomGenerator	The uniform generator to copy the state from.	required

with_seed staticmethod

with_seed(seed: int = 0) -> GaussianRandomGenerator

Build a generator over a fresh Mersenne Twister.

Parameters:

Name	Type	Description	Default
seed	int	The 32-bit seed; 0 draws a random seed.	0

Returns:

Name	Type	Description
GaussianRandomGenerator	GaussianRandomGenerator	The seeded generator.

next_gaussian

next_gaussian() -> float

Draw the next standard normal deviate.

Returns:

Name	Type	Description
float	float	A deviate with mean 0 and standard deviation 1.

next_gaussians

next_gaussians(count: int) -> NDArray[float64]

Draw many standard normal deviates in one call.

Parameters:

Name	Type	Description	Default
count	int	The number of deviates to draw.	required

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (count,), holding exactly
NDArray[float64]	what count successive next_gaussian() calls would have returned.

Raises:

Type	Description
ItofinError	If a buffer of count draws cannot be allocated.

GaussianRandomSequenceGenerator

GaussianRandomSequenceGenerator(usg: UniformRandomSequenceGenerator)

The Gaussian random sequence generator: uniform Mersenne-Twister sequences mapped through the inverse cumulative normal, QuantLib's InverseCumulativeRsg<RandomSequenceGenerator<MersenneTwisterUniformRng>, InverseCumulativeNormal>.

This is the PseudoRandom policy the Monte Carlo engines draw their paths from: with_seed(dimension, seed) reproduces the engines' generator for the same dimension and seed. The generator copies the uniform sequence generator it is built from, as QuantLib does.

Build a Gaussian sequence generator over a copy of a uniform one.

Parameters:

Name	Type	Description	Default
usg	UniformRandomSequenceGenerator	The uniform sequence generator to copy the state from; its dimension is the dimension here.	required

with_seed staticmethod

with_seed(dimension: int, seed: int = 0) -> GaussianRandomSequenceGenerator

Build a Gaussian sequence generator over a fresh Mersenne Twister.

Parameters:

Name	Type	Description	Default
dimension	int	The number of draws per sequence, at least 1.	required
seed	int	The 32-bit seed; 0 draws a random seed.	0

Returns:

Name	Type	Description
GaussianRandomSequenceGenerator	GaussianRandomSequenceGenerator	The seeded sequence generator.

Raises:

Type	Description
ItofinError	If dimension is 0.

dimension

dimension() -> int

The number of draws per sequence.

Returns:

Name	Type	Description
int	int	The dimension the generator was built with.

next_sequence

next_sequence() -> NDArray[float64]

Draw the next sequence.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,) of standard
NDArray[float64]	normal deviates.

last_sequence

last_sequence() -> NDArray[float64]

The most recently drawn sequence, without advancing.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,); all zeros
NDArray[float64]	before the first draw.

next_sequences

next_sequences(count: int) -> NDArray[float64]

Draw many sequences in one call.

Parameters:

Name	Type	Description	Default
count	int	The number of sequences to draw.	required

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (count, dimension), row i
NDArray[float64]	being what the (i + 1)-th next_sequence() call would have returned.

Raises:

Type	Description
ItofinError	If a buffer of count sequences cannot be allocated.

HaltonRsg

HaltonRsg(dimension: int)

The Halton low-discrepancy sequence generator, QuantLib's HaltonRsg with randomStart and randomShift both off.

Draw k (1-based) is the radical inverse of k in a distinct prime base per dimension: base 2 for the first dimension, 3 for the second, 5 for the third, and so on. The sequence is deterministic; the randomized start and shift of QuantLib's default constructor are not exposed, being deferred in the core.

Build a Halton generator.

Parameters:

Name	Type	Description	Default
dimension	int	The number of draws per point, at least 1.	required

Raises:

Type	Description
ItofinError	If dimension is 0.

dimension

dimension() -> int

The number of draws per point.

Returns:

Name	Type	Description
int	int	The dimension the generator was built with.

next_sequence

next_sequence() -> NDArray[float64]

Draw the next Halton point.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,), every entry
NDArray[float64]	inside [0, 1).

last_sequence

last_sequence() -> NDArray[float64]

The most recently drawn point, without advancing.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,); all zeros
NDArray[float64]	before the first draw.

next_sequences

next_sequences(count: int) -> NDArray[float64]

Draw many points in one call.

Parameters:

Name	Type	Description	Default
count	int	The number of points to draw.	required

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (count, dimension), row i
NDArray[float64]	being what the (i + 1)-th next_sequence() call would have returned.

Raises:

Type	Description
ItofinError	If a buffer of count points cannot be allocated.

PoissonRandomGenerator

PoissonRandomGenerator(seed: int = 0, lambda_: float = 1.0)

Scalar Poisson variates from MT19937. Seed zero selects a random seed.

Construct with a finite positive rate; the default rate is one.

next_real

next_real() -> float

Draw the next count. Unresolvable quantiles raise ItofinError.

copy

copy() -> PoissonRandomGenerator

Copy the current state without advancing either generator.

PoissonRandomSequenceGenerator

PoissonRandomSequenceGenerator(dimension: int, seed: int = 0, lambda_: float = 1.0)

Weighted Poisson sequences from MT19937, with an explicit per-generator rate.

Construct a positive-dimensional sequence; the default rate is one.

dimension

dimension() -> int

Number of components per draw.

next_sequence

next_sequence() -> list[float]

Draw one sequence; an error preserves the last successful sequence.

last_sequence

last_sequence() -> list[float]

Last successful sequence, initially zeros.

copy

copy() -> PoissonRandomSequenceGenerator

Copy the current state without advancing either generator.

SobolRsg

SobolRsg(dimension: int, seed: int = 0, direction_integers: DirectionIntegers = Jaeckel, use_gray_code: bool = True)

The Sobol low-discrepancy sequence generator, QuantLib's SobolRsg.

Successive draws fill the unit hypercube evenly rather than randomly, so a Monte Carlo estimate over them converges faster than over pseudo-random draws. The first draw is 0.5 in every dimension, and every draw lies strictly inside (0, 1). The generator is deterministic for a given seed: the seed only matters for dimensions beyond the tabulated initializers.

Build a Sobol generator.

Parameters:

Name	Type	Description	Default
dimension	int	The number of draws per sequence, from 1 to the number of primitive polynomials shipped (21200).	required
seed	int	The seed for the free direction integers past the tabulated dimensions; used literally, so 0 is a fixed seed.	0
direction_integers	DirectionIntegers	The direction-integer table, Jaeckel by default as in QuantLib.	Jaeckel
use_gray_code	bool	Generate through the Gray-code counter (the QuantLib default) rather than the plain counter.	True

Raises:

Type	Description
ItofinError	If dimension is 0 or exceeds 21200.

dimension

dimension() -> int

The number of draws per sequence.

Returns:

Name	Type	Description
int	int	The dimension the generator was built with.

next_sequence

next_sequence() -> NDArray[float64]

Draw the next Sobol point.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,), every entry
NDArray[float64]	strictly inside (0, 1).

last_sequence

last_sequence() -> NDArray[float64]

The most recently drawn point, without advancing.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,); all zeros
NDArray[float64]	before the first draw.

next_int32_sequence

next_int32_sequence() -> NDArray[uint32]

Draw the next point as raw 32-bit Sobol integers.

Returns:

Type	Description
NDArray[uint32]	numpy.ndarray: A uint32 array of shape (dimension,); the float
NDArray[uint32]	point is this array scaled by 2^-32.

next_sequences

next_sequences(count: int) -> NDArray[float64]

Draw many points in one call.

Parameters:

Name	Type	Description	Default
count	int	The number of points to draw.	required

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (count, dimension), row i
NDArray[float64]	being what the (i + 1)-th next_sequence() call would have returned.

Raises:

Type	Description
ItofinError	If a buffer of count points cannot be allocated.

skip_to

skip_to(n: int) -> NDArray[uint32]

Skip to the n-th point of the sequence and return it as raw integers.

QuantLib's skipTo, whose counter semantics are kept: with the Gray-code counter the following draw returns point n + 1, unless it is the very first draw made on the generator, which returns point n itself; with the plain counter the following draw returns point n. The float point is the returned array scaled by 2^-32.

Parameters:

Name	Type	Description	Default
n	int	The 0-based index of the point to skip to.	required

Returns:

Type	Description
NDArray[uint32]	numpy.ndarray: A uint32 array of shape (dimension,), point n as
NDArray[uint32]	raw Sobol integers.

Raises:

Type	Description
ItofinError	If n is 2^32 - 1, past the sequence period.

UniformRandomGenerator

UniformRandomGenerator(seed: int = 0)

The uniform pseudo-random number generator: a Mersenne Twister (MT19937) with period 2^19937 - 1, QuantLib's MersenneTwisterUniformRng.

Draws are deterministic for a non-zero seed: the same seed reproduces the same stream bitwise, on every platform. A seed of 0 draws a random seed from the core seed generator, so two zero-seeded generators diverge.

Build a generator from a seed.

Parameters:

Name	Type	Description	Default
seed	int	The 32-bit seed. 0 (the default) draws a random seed from the core seed generator, matching QuantLib.	0

from_seeds staticmethod

from_seeds(seeds: Sequence[int]) -> UniformRandomGenerator

Build a generator from an array of seeds, the reference init_by_array initialization.

Parameters:

Name	Type	Description	Default
seeds	list[int]	The 32-bit seed words; at least one.	required

Returns:

Name	Type	Description
UniformRandomGenerator	UniformRandomGenerator	The generator initialized from the array.

Raises:

Type	Description
ItofinError	If seeds is empty.

next_real

next_real() -> float

Draw the next uniform deviate.

Returns:

Name	Type	Description
float	float	A deviate strictly inside (0, 1): the raw 32-bit output
	float	shifted by one half and scaled by 2^-32, so neither endpoint is
	float	ever returned.

next_u32

next_u32() -> int

Draw the next raw 32-bit output.

Returns:

Name	Type	Description
int	int	An integer uniform over [0, 2^32 - 1].

next_reals

next_reals(count: int) -> NDArray[float64]

Draw many uniform deviates in one call.

Parameters:

Name	Type	Description	Default
count	int	The number of deviates to draw.	required

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (count,), holding exactly
NDArray[float64]	what count successive next_real() calls would have returned.

Raises:

Type	Description
ItofinError	If a buffer of count draws cannot be allocated.

UniformRandomSequenceGenerator

UniformRandomSequenceGenerator(dimension: int, rng: UniformRandomGenerator)

The uniform random sequence generator: dimension Mersenne-Twister draws per sequence, QuantLib's RandomSequenceGenerator<MersenneTwisterUniformRng>.

The generator copies the scalar generator it is built from, as QuantLib does, so later draws on the original do not affect the sequence.

Build a sequence generator over a copy of a scalar generator.

Parameters:

Name	Type	Description	Default
dimension	int	The number of draws per sequence, at least 1.	required
rng	UniformRandomGenerator	The scalar generator to copy the state from.	required

Raises:

Type	Description
ItofinError	If dimension is 0.

with_seed staticmethod

with_seed(dimension: int, seed: int = 0) -> UniformRandomSequenceGenerator

Build a sequence generator over a fresh Mersenne Twister.

Parameters:

Name	Type	Description	Default
dimension	int	The number of draws per sequence, at least 1.	required
seed	int	The 32-bit seed; 0 draws a random seed.	0

Returns:

Name	Type	Description
UniformRandomSequenceGenerator	UniformRandomSequenceGenerator	The seeded sequence generator.

Raises:

Type	Description
ItofinError	If dimension is 0.

dimension

dimension() -> int

The number of draws per sequence.

Returns:

Name	Type	Description
int	int	The dimension the generator was built with.

next_sequence

next_sequence() -> NDArray[float64]

Draw the next sequence.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,), every entry
NDArray[float64]	strictly inside (0, 1).

last_sequence

last_sequence() -> NDArray[float64]

The most recently drawn sequence, without advancing.

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (dimension,); all zeros
NDArray[float64]	before the first draw.

next_sequences

next_sequences(count: int) -> NDArray[float64]

Draw many sequences in one call.

Parameters:

Name	Type	Description	Default
count	int	The number of sequences to draw.	required

Returns:

Type	Description
NDArray[float64]	numpy.ndarray: A float64 array of shape (count, dimension), row i
NDArray[float64]	being what the (i + 1)-th next_sequence() call would have returned.

Raises:

Type	Description
ItofinError	If a buffer of count sequences cannot be allocated.

DirectionIntegers

The choice of free direction integers for the Sobol dimensions beyond the first, QuantLib's SobolRsg::DirectionIntegers.

Jaeckel is QuantLib's default. Unit uses the unit initialization for every dimension; the others are the tabulated initializers shipped with QuantLib, with a seeded Mersenne Twister drawing the free integers past each table.