Random Number Generator: API to the C++ Random library as a c-extension for Python3
Project description
RNG: Random Number Generator
Default Random Engine: Mersenne Twister 64, with hardware entropy. Additional engines and seeding strategies are planned to be available in the unbounded future. More info about MT64: https://en.wikipedia.org/wiki/Mersenne_Twister
The RNG module is not suitable for cryptography, and perfect for other non-deterministic needs like A.I. or games of chance.
Recommended Installation: $ pip install RNG
RNG is not intended to be a drop-in replacement for the Python random module, RNG is a whole different beast.
Random Binary Functions
random_bool(truth_factor: float) -> bool
- Bernoulli distribution.
- @param truth_factor :: the probability of True. Expected input range: [0.0, 1.0]
- @return :: True or False
Random Integer Functions
random_int(lo: int, hi: int) -> int
- Flat uniform distribution.
- @param lo :: the lower bound. Param lo must not be greater than param hi.
- @param hi :: the upper bound.
- @return :: random integer in the inclusive range [lo..hi]
random_binomial(number_of_trials: int, probability: float) -> int
- Based on the idea of flipping a coin and counting how many heads come up after some number of flips.
- @param number_of_trials :: how many times to flip a coin.
- @param probability :: how likely heads will be flipped. 0.50 is a fair coin.
- @return :: count of how many heads came up.
random_negative_binomial(trial_successes: int, probability: float) -> int
- Based on the idea of flipping a coin as long as it takes to succeed.
- @param trial_successes :: the required number of heads flipped to succeed.
- @param probability :: how likely heads will be flipped. 0.50 is a fair coin.
- @return :: the count of how many tails came up before the required number of heads.
random_geometric(probability: float) -> int
- Same as random_negative_binomial(1, probability).
random_poisson(mean: float) -> int
- @param mean :: sets the average output of the function.
- @return :: random integer, poisson distribution centered on the mean.
random_discrete(count: int, xmin: int, xmax: int, step: int) -> int
- @param count :: number of weighted values
- @param xmin :: smallest weight of the set
- @param xmin :: largest weight of the set
- @param step :: value stepping
Random Floating Point Functions
random_float(lo: float, hi: float) -> float
- @param lo :: lower bound Float
- @param hi :: upper bound Float
- @return :: random Float in range {lo, hi} biclusive.
- biclusive: feature/bug rendering the exclusivity of this function a bit more mysterious than desired. This is a known compiler bug.
- The spec defines the output range to be [lo, hi).
random_normal(mean: float, std_dev: float) -> float
- @param mean :: sets the average output of the function.
- @param std_dev :: standard deviation. Specifies spread of data from the mean.
random_log_normal(log_mean: float, log_deviation: float) -> float
- @param log_mean :: sets the log of the mean of the function.
- @param log_deviation :: log of the standard deviation. Specifies spread of data from the mean.
random_exponential(lambda_rate: float) -> float
- Produces random non-negative floating-point values, distributed according to probability density function.
- @param lambda_rate :: λ constant rate of a random event per unit of time/distance.
- @return :: The time/distance until the next random event. For example, this distribution describes the time between the clicks of a Geiger counter or the distance between point mutations in a DNA strand.
random_gamma(shape: float, scale: float) -> float
- Generalization of the exponential distribution.
- Produces random positive floating-point values, distributed according to probability density function.
- @param shape :: α the number of independent exponentially distributed random variables.
- @param scale :: β the scale factor or the mean of each of the distributed random variables.
- @return :: the sum of α independent exponentially distributed random variables, each of which has a mean of β.
random_weibull(shape: float, scale: float) -> float
- Generalization of the exponential distribution.
- Similar to the gamma distribution but uses a closed form distribution function.
- Popular in reliability and survival analysis.
random_extreme_value(location: float, scale: float) -> float
- Based on Extreme Value Theory.
- Used for statistical models of the magnitude of earthquakes and volcanoes.
random_chi_squared(degrees_of_freedom: float) -> float
- Used with the Chi Squared Test and Null Hypotheses to test if sample data fits an expected distribution.
random_cauchy(location: float, scale: float) -> float
- Continuous Distribution.
random_fisher_f(degrees_of_freedom_1: float, degrees_of_freedom_2: float) -> float
- F distributions often arise when comparing ratios of variances.
random_student_t(degrees_of_freedom: float) -> float
- T distribution. Same as a normal distribution except it uses the sample standard deviation rather than the population standard deviation.
- As degrees_of_freedom goes to infinity it tends to match the normal distribution.
piecewise_constant_distribution
coming soon- Produces real values distributed on constant subintervals.
piecewise_linear_distribution
coming soon- Produces real values distributed on defined subintervals.
Utilities
generate_canonical() -> float
- Evenly distributes real values of given precision across [0, 1). Suffers from the same biclusive feature/bug noted for random_float.
- Currently set to max precision for long double. Precision could be parameterized in the future.
seed_seq
coming soon- General-purpose bias-eliminating scrambled seed sequence generator.
- Currently RNG uses hardware seeding exclusively. Software seeding may be a feature in a future release.
Engines
mersenne_twister_engine
- Implements Mersenne twister algorithm. Default engine on most modern systems.
linear_congruential_engine
coming soon- Implements linear congruential algorithm.
subtract_with_carry_engine
coming soon- Implements a subtract-with-carry (lagged Fibonacci) algorithm.
Engine Adaptors
Engine adaptors generate pseudo-random numbers using another random number engine as entropy source. They are generally used to alter the spectral characteristics of the underlying engine.
discard_block_engine
coming soon- Discards some output of a random number engine.
independent_bits_engine
coming soon- Packs the output of a random number engine into blocks of a specified number of bits.
shuffle_order_engine
coming soon- Delivers the output of a random number engine in a different order.
Seeding or Entropy Source
- Non-deterministic hardware entropy source:
std::random_device()
. RNG is non-deterministic by default. - Repeatable deterministic software seeding: coming soon.
Development Log
RNG 0.1.10 beta
- Fixed some typos.
RNG 0.1.9 beta
- Fixed some typos.
RNG 0.1.8 beta
- Fixed some typos.
- More documentation added.
RNG 0.1.7 beta
- The
random_floating_point
function renamed torandom_float
. - The function
c_rand()
has been removed as well as all the cruft it required. - Major Documentation Upgrade.
- Fixed an issue where keyword arguments would fail to propagate. Both, positional args and kwargs now work as intended.
- Added this Dev Log.
RNG 0.0.6 alpha
- Minor ABI changes.
RNG 0.0.5 alpha
- Tests redesigned slightly for Float functions.
RNG 0.0.4 alpha
- Random Float Functions Implemented.
RNG 0.0.3 alpha
- Random Integer Functions Implemented.
RNG 0.0.2 alpha
- Random Bool Function Implemented.
RNG 0.0.1 pre-alpha
- Planning & Design.
Distribution and Performance Test Suite
RNG 0.1.10 BETA
Binary RNG Tests
random_bool(truth_factor=1/3)
Time: min: 62ns, mode: 62ns, mean: 68ns, max: 156ns
Distribution:
False: 66.548%
True: 33.452%
Integer RNG Tests
Base Case: randint(1, 6)
Time: min: 1375ns, mode: 1406ns, mean: 1436ns, max: 1968ns
Distribution:
1: 16.723%
2: 16.828%
3: 16.62%
4: 16.559%
5: 16.583%
6: 16.687%
random_int(lo=1, hi=6)
Time: min: 62ns, mode: 62ns, mean: 81ns, max: 250ns
Distribution:
1: 16.669%
2: 16.744%
3: 16.816%
4: 16.644%
5: 16.382%
6: 16.745%
random_binomial(number_of_trials=4, probability=0.5)
Time: min: 156ns, mode: 187ns, mean: 185ns, max: 375ns
Distribution:
0: 6.228%
1: 24.842%
2: 37.779%
3: 24.823%
4: 6.328%
random_negative_binomial(number_of_trials=5, probability=0.75)
Time: min: 93ns, mode: 125ns, mean: 124ns, max: 156ns
Distribution:
0: 23.63%
1: 29.907%
2: 22.116%
3: 12.949%
4: 6.563%
5: 2.899%
6: 1.193%
7: 0.486%
8: 0.156%
9: 0.067%
10: 0.027%
11: 0.005%
12: 0.002%
random_geometric(probability=0.75)
Time: min: 62ns, mode: 62ns, mean: 73ns, max: 125ns
Distribution:
0: 74.809%
1: 18.798%
2: 4.801%
3: 1.165%
4: 0.326%
5: 0.079%
6: 0.014%
7: 0.007%
8: 0.001%
random_poisson(mean=4.5)
Time: min: 125ns, mode: 125ns, mean: 143ns, max: 531ns
Distribution:
0: 1.096%
1: 5.075%
2: 11.298%
3: 16.693%
4: 19.059%
5: 17.182%
6: 12.69%
7: 8.25%
8: 4.618%
9: 2.349%
10: 0.997%
11: 0.434%
12: 0.169%
13: 0.061%
14: 0.018%
15: 0.005%
16: 0.005%
17: 0.001%
random_discrete(count=6, xmin=0.7, xmax=21.0, step=1)
Time: min: 531ns, mode: 531ns, mean: 556ns, max: 1062ns
Distribution:
0: 4.855%
1: 9.637%
2: 14.321%
3: 19.116%
4: 23.649%
5: 28.422%
Floating Point RNG Tests
random_float(lo=0.0, hi=10.0)
Time: min: 62ns, mode: 62ns, mean: 65ns, max: 156ns
Floored Distribution:
0: 10.147%
1: 9.899%
2: 10.04%
3: 9.858%
4: 10.07%
5: 10.055%
6: 10.065%
7: 9.923%
8: 10.109%
9: 9.834%
random_exponential(lambda_rate=1.0)
Time: min: 62ns, mode: 93ns, mean: 83ns, max: 125ns
Floored Distribution:
0: 63.13%
1: 23.316%
2: 8.543%
3: 3.168%
4: 1.189%
5: 0.395%
6: 0.154%
7: 0.065%
8: 0.028%
9: 0.008%
10: 0.002%
11: 0.002%
random_gamma(shape=1.0, scale=1.0)
Time: min: 93ns, mode: 93ns, mean: 98ns, max: 187ns
Floored Distribution:
0: 63.61%
1: 22.975%
2: 8.402%
3: 3.24%
4: 1.129%
5: 0.415%
6: 0.142%
7: 0.063%
8: 0.018%
9: 0.002%
11: 0.002%
12: 0.002%
random_weibull(shape=1.0, scale=1.0)
Time: min: 156ns, mode: 187ns, mean: 193ns, max: 406ns
Floored Distribution:
0: 63.07%
1: 23.326%
2: 8.478%
3: 3.244%
4: 1.224%
5: 0.434%
6: 0.13%
7: 0.059%
8: 0.022%
9: 0.007%
10: 0.003%
11: 0.002%
12: 0.001%
random_extreme_value(location=0.0, scale=1.0)
Time: min: 125ns, mode: 156ns, mean: 157ns, max: 406ns
Rounded Distribution:
-2: 1.191%
-1: 18.262%
0: 34.983%
1: 25.393%
2: 12.204%
3: 4.961%
4: 1.923%
5: 0.68%
6: 0.256%
7: 0.084%
8: 0.033%
9: 0.016%
10: 0.005%
11: 0.007%
13: 0.001%
15: 0.001%
random_normal(mean=5.0, std_dev=2.0)
Time: min: 93ns, mode: 125ns, mean: 124ns, max: 156ns
Rounded Distribution:
-3: 0.016%
-2: 0.068%
-1: 0.236%
0: 0.899%
1: 2.838%
2: 6.361%
3: 12.07%
4: 17.666%
5: 19.821%
6: 17.342%
7: 12.255%
8: 6.441%
9: 2.761%
10: 0.887%
11: 0.27%
12: 0.061%
13: 0.007%
14: 0.001%
random_log_normal(log_mean=1.6, log_deviation=0.25)
Time: min: 187ns, mode: 218ns, mean: 218ns, max: 312ns
Rounded Distribution:
2: 0.291%
3: 8.013%
4: 26.868%
5: 31.378%
6: 19.681%
7: 8.931%
8: 3.307%
9: 1.061%
10: 0.339%
11: 0.101%
12: 0.018%
13: 0.01%
14: 0.001%
15: 0.001%
random_chi_squared(degrees_of_freedom=1.0)
Time: min: 187ns, mode: 218ns, mean: 236ns, max: 468ns
Rounded Distribution:
0: 52.263%
1: 25.565%
2: 10.726%
3: 5.287%
4: 2.83%
5: 1.491%
6: 0.773%
7: 0.463%
8: 0.25%
9: 0.151%
10: 0.089%
11: 0.039%
12: 0.029%
13: 0.019%
14: 0.012%
15: 0.006%
16: 0.002%
17: 0.003%
18: 0.001%
21: 0.001%
random_cauchy(location=0.0, scale=0.0005)
Time: min: 93ns, mode: 125ns, mean: 114ns, max: 156ns
Rounded Distribution:
-10: 0.001%
-8: 0.001%
-6: 0.001%
-5: 0.002%
-2: 0.004%
-1: 0.026%
0: 99.928%
1: 0.024%
2: 0.005%
3: 0.003%
4: 0.004%
7: 0.001%
random_fisher_f(degrees_of_freedom_1=3.0, degrees_of_freedom_2=8.0)
Time: min: 250ns, mode: 312ns, mean: 311ns, max: 343ns
Rounded Distribution:
0: 30.747%
1: 40.251%
2: 15.494%
3: 6.437%
4: 3.026%
5: 1.545%
6: 0.898%
7: 0.525%
8: 0.334%
9: 0.218%
10: 0.144%
11: 0.106%
12: 0.078%
13: 0.047%
14: 0.029%
15: 0.026%
16: 0.016%
17: 0.016%
18: 0.007%
19: 0.007%
20: 0.011%
21: 0.005%
22: 0.004%
23: 0.006%
24: 0.002%
25: 0.003%
26: 0.001%
27: 0.001%
28: 0.001%
29: 0.002%
30: 0.001%
31: 0.001%
32: 0.001%
33: 0.002%
34: 0.003%
41: 0.001%
43: 0.001%
48: 0.001%
57: 0.001%
58: 0.001%
random_student_t(degrees_of_freedom=8.0)
Time: min: 281ns, mode: 312ns, mean: 300ns, max: 343ns
Rounded Distribution:
-8: 0.001%
-7: 0.006%
-6: 0.029%
-5: 0.08%
-4: 0.294%
-3: 1.496%
-2: 6.756%
-1: 22.855%
0: 36.909%
1: 22.961%
2: 6.759%
3: 1.446%
4: 0.291%
5: 0.082%
6: 0.019%
7: 0.008%
8: 0.004%
9: 0.003%
12: 0.001%
generate_canonical()
Time: min: 31ns, mode: 31ns, mean: 42ns, max: 62ns
Rounded Distribution:
0: 49.989%
1: 50.011%
All tests passed!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for RNG-0.1.10-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5e3066b0f388a60374fb8a067e631ce556e0934cd7d2bdb251d3563155040536 |
|
MD5 | 046f3907f79910c5b921e9f6fee52abb |
|
BLAKE2b-256 | 290e03e451263586766e387e59e731822e94a3094ae5b88e9be54d48f77ec63a |