# Randomness#

Simulating physical systems with computers often involve generating random numbers or randomly sampling from a set. This poses a challenge to programmers, in that computers, as mostly deterministic creatures, are quite bad at this sort of task.

Another aspect of this problem is reproducibility. Researchers need their results to be reproducible, meaning that if someone else runs the same code on another computer, they should be able to get the same results as everyone else. True random number generators are not really the tool for this purpose.

Pseudorandom number generators, on the other hand, can produce results “random
enough” for the purpose of scientific simulation. On C++ side, you can simply
use any pseudorandom number generator as long as it conforms to the concept
`std::uniform_random_bit_generator`

, for example, Mersenne Twister
implementation from the standard library `std::mt19937_64`

or PCG random
number generator.

On Python side, everything is slightly more involved. You cannot simply use the
random number generators implemented by Python or NumPy, as Reticula cannot
manipulate Python objects in any way that matters. Similar situation is also in
place for distributions. We have provided bindings to some pseudorandom number
generators and distributions for use with this library, some bindings over C++
standard library implementation (e.g., `geomtric_distribution`

and
`exponential_distirbution`

) and some based on our own implementation.

Warning

Reticula currently relies on C++ standard library distributions and pseudorandom number generators, execept for a few distributions that are implemented by Reticula. This has negative implecations for reproducability across platforms. At some point in the future, these will have to change into ones with reproducability guarantees tied to Reticula version and not the platform or the standard library implementation. Until this change happens, we will try our best keep the Python build environment consistant, but there are no guarantees.

For now, the only real thing you can do with these classes are to create them and pass them on to Reticula functions, as Reticula is not a general purpose numerical computation library.

## Pseudorandom number generators#

- mersenne_twister([seed: int])
Creates an instance of 64-bit Mersenne twister [1]. Bindings over C++ standard library implementation.

We recommand using one pseudorandom number generator per thread in multi-threaded environment.

If no

`seed`

is provided, the generator is seeded using a non-deterministic source, e.g., a hardware device, if one is available.

## Distributions#

- geometric_distribution[integral_type](p: float)
A discrete distribution of the number of required Bernoulli trials with probability

`p`

to get one success. This distribution has a mean of \(\frac{1}{p}\). It’s the discrete analogue to`exponential_distribution[floating_point_type]`

- exponential_distribution[floating_point_type](lambda: float)
A continuous distribution indicating the time between two consecutive events if that event happens at a constant rate, i.e., a Poisson point process. The parameter

`lambda`

indicates the rate and the distribution has a mean of \(\frac{1}{\lambda}\).

- power_law_with_specified_mean[floating_point_type](exponent: float, mean: float)
A power-law distribution with minimum-value cutoff, selected in a way to produce values with mean

`mean`

. The parameter`exponent`

, indicating the power-law exponent has to be larger than 2.

- residual_power_law_with_specified_mean[floating_point_type](exponent: float, mean: float)
Residual distribution of the distribution

`power_law_with_specified_mean[floating_point_type]`

.

- hawkes_univariate_exponential[floating_point_type](mu: float, alpha: float, theta: float, phi: float = 0.0)
A univariate exponential formulation of Hawkes self-exciting process. The parameter

`mu`

indicates background (or exogenous) intensity of events, indicating the random probability of events happening without being caused through self-excitement, parameter`alpha`

indicates the infectivity factor, often interpreted as the expected number of induced self-exciting events per each event,`theta`

indicates the rate parameter of the delay and`phi`

specifies the history of the distribution until this point in time.

- uniform_real_distribution[floating_point_type](a: float, b: float)
Returns floating point value selected uniformly at random from the range \([a, b)\).

- uniform_int_distribution[integral_type](a: int, b: int)
Returns an integer value selected uniformly at random from the range \([a, b]\).

- delta_distribution[numeric_type](mean: int | float)
Always returns the value of

`mean`

.