This is a simple C++ library for Pseudo Random Number Generation. It provides a functionality similar to that of the python standard library random.
- Ease of Use: Straightforward API for quick integration into your C++ projects.
- Versatility: Supports different PRNG algorithms, allowing you to choose based on your requirements.
- Convenience: Provides various standard distributions used in scientific computation and also has rudimentary support for custom probability distributions.
- Detailed documentation on distrbutions
Pseudorandom Number Generators
- Mersenne Twister (MT)
- Linear Feedback Shift Register (LFSR)
- XOR-Shift (XOR)
- Blum Blum Shub (BBS)
- Naor-Reingold (NR)
Distrbutions
- Cauchy
- Exponential
- Gaussian
- Maxwell
- Weibull
- Bernoulli
- Binomial
- Gibbs
- Hypergeometric
- Negative-Hypergeometric
- Poisson
Add results here
Using DiceForge's pseudo random number generators to create a uniformly distributed random variable in [0,1), the statistical analysis for 100000000 random samples is:
Generator | Mean | Variance |
---|---|---|
BBS32 | 0.500189 | 0.0834384 |
BBS64 | 0.499066 | 0.0834061 |
XOR32 | 0.499978 | 0.08334 |
XOR64 | 0.499931 | 0.0833327 |
MT32 | 0.499956 | 0.0833425 |
MT64 | 0.500034 | 0.0833241 |
LFSR32 | 0.500033 | 0.0833329 |
LFSR64 | 0.49994 | 0.0833352 |
NR | 0.341687 | 0.0498607 |
The theoretical mean and variance for a uniformly distributed random variable in [0,1) are
mean = 1/2 (0.5)
variance = 1/12 (0.08333...)
Time taken for generating 100000000 random numbers:
Generator | Time Taken |
---|---|
XorShift32 | 435.497ms |
XorShift64 | 410.498ms |
BBS32 | 14780ms |
BBS64 | 24568.6ms |
MT32 | 1738.91ms |
MT64 | 1811.27ms |
LFSR | 18540.7ms |
Naor Reingold | 7143ms |
For comparison, benchmarking other existing standard libraries for the same test.
Generator | Time Taken |
---|---|
C++'s Mersenne Twister | 4032.7ms |
C rand() function | 1388.03ms |
python's random | 51171.51 ms |
numpy's randint | 194015.44 ms |
Check out the Documentation for detailed information on library usage, supported algorithms, and more!
- C++ compiler (minimum C++17 or later, note that C++20 is required for using 2D probability functions)
- CMake (>=3.28) [If building library]
- Download the compiled binaries from out folder along with the include files include
- If you want compact compilation commands later on, add the path to include/ and out/ to the system environment variable PATH
- Start generating pseudo-random numbers!
- Clone the repository:
git clone https://github.com/yourusername/diceforge-library-clone.git
- Create the build folder by using the CMakeLists.txt
- Build library using the given CMake configurations (
cmake --build <build-folder>
) - After the build is sucessful, follow the steps mentioned in Using a prebuilt library
Here's a quick example to get you started:
example.cpp
#include "diceforge.h"
int main() {
// Create a PRNG object
DiceForge::XORShift32 prng = DiceForge::XORShift32(123);
// Generate and print a random number
std::cout << "Random Number: " << prng.next() << std::endl;
return 0;
}
Now to compile it with a compiler of your choice (we use g++ in the following example), enter the following command in your terminal
- If you added diceforge to PATH
g++ example.cpp libdiceforge_s.a -o example.out
- If you do not with to include diceforge to PATH
g++ example.cpp "out/libdiceforge_s.a" -I "include" -o example.out
Feel free to explore the library and experiment with different algorithms!
Currently, this is an IIT-M Math Club exclusive project and we aren't accepting outside contributions.
-
View the Tasks folder to view the tasks to be done.
-
Reference materials are provided in the Contributors_Only folder.
Current TODO
Final pending tasks
- BBS robustness
- Maxwell curve fitting code
- Packing 2D RV code into the diceforge header files
- Update header files after all of the code is available
- Proofreading and finalizing documentation
- Update README with latest results
Documentation
- Curve fitting
- Custom Distribution
- Diehard Tests
- 2D RV
Good to haves
- Get bigger primes for PRNGs
- More examples on using DiceForge in Documentation
- Non-linear transformation in LFSR
- A defualt random singleton for convenience
Completed
- Bernoulli docuumentation
- Custom pdf distribution
- Geometric distribution
- Fix bug in Naor Reingold RNG, also decide what to do when seed is zero and mention it in code documentation
- Exception handling
- 2d rv
- Testing the RNGs