Random Number Generators#

Counter-based#

heptools.math.random.SeedLike[source]#

A seed or a sequence of seeds.

Type:

int, str, Iterable[int or str]

class heptools.math.random.CBRNG(*seed)[source]#

Counter-based random number generator (CBRNG).

Notes

Rejection-based algorithms (e.g., the Ziggurat algorithm or Rejection Sampling) are computationally more expensive when implemented with CBRNGs—which typically rely on simplified cryptographic block ciphers—compared to traditional PRNGs.

In a CBRNG, each independent random sequence is defined by a unique key. .. math:

value_n = f(key, counter_n)

A seed is used to generate a valid key. For better traceability, it is recommended to use semantically meaningful seeds. Unlike traditional PRNGs where a single global instance is often reused, CBRNGs favor a stateless paradigm. When handling multiple independent streams, you should explicitly create a new generator instance for each, initialized with a distinct seed to avoid sequence overlap. The uniqueness of the sequence can be checked by using is_sequence_unique().

Parameters:

seed (SeedLike) – The seed used to generate the key.

uniform(counters, low=0.0, high=1.0)[source]#

Generates from uniform distribution.

Parameters:

  • counters (ArrayLike) – The counter array.

  • low (float, optional) – The lower (closed) bound of the distribution.

  • high (float, optional) – The upper (open) bound of the distribution.

Returns:

ndarray – The random sample.

normal(counters, loc=0.0, scale=1.0)[source]#

Generates from normal distribution using Box-Muller transform [1].

Warning

In an extremely rare case (\(1/2^{53}\)), it may raise a “divide by zero” warning.

Parameters:

  • counters (ArrayLike) – The counter array.

  • loc (float, optional) – The mean of the normal distribution.

  • scale (float, optional) – The standard deviation of the normal distribution.

Returns:

ndarray – The random sample.

References

choice(counters, a, p=None)[source]#

Generates a random sample from a given array.

Parameters:

  • counters (ArrayLike) – The counter array.

  • a (ArrayLike or int) – If an array-like object, a random sample is generated by choosing from the first dimension. If an int, it is used the same way as numpy.arange().

  • p (ArrayLike, optional) – The probabilities associated with each entry in a. If not given, the sample assumes a uniform distribution over all entries.

Returns:

ndarray – The random sample.

Notes

If the counters has shape \([x_{1}, x_{2}, ..., x_{n}]\) and a has shape \([y_{1}, y_{2}, ..., y_{m}]\), the output shape is given as follows:

\[\begin{split}&[x_{1}, x_{2}, ..., x_{n-1}, y_{2}, ..., y_{m}] & n > 1 \land m > 1\\ &[x_{1}, x_{2}, ..., x_{n-1}] & n > 1 \land m = 1\\ &[x_{1}, y_{2}, ..., y_{m}] & n = 1 \land m > 1\\ &[x_{1}] & n = 1 \land m = 1\end{split}\]
static is_sequence_unique(*generators)[source]#

Checks if all CBRNGs produce unique sequences.

Parameters:

*generators (CBRNG) – The CBRNG instances to check.

Returns:

bool