Welcome to RandomIterator’s documentation!¶
What is it?¶
RandomIterator is a small header-only library providing iterators pointing to streams of pseudorandom numbers. The library operates using lazy-evaluation and is intented for usage on multi-thread calculations.
RandomIterator deploys state-of-the-art counter-based pseudorandom numbers generators from Random123: library and a pair of native generators based Squares: algorithm, together with TBB: iterators, exposing a concise, lightweght and thread-safe API capable of handling up to \(2^{32}\) streams of pseudorandom numbers, with lenght of \(2^{64}\).
Main features¶
Five primary generators: Philox, ARS and Threefry from Random123 and Squares3 and Squares4, which are natively implemented.
Completely thread-safe.
Compatibility with all C++ distributions defined in the standard library.
For each seed, the
random_iterator::Stream<Distribution, Engine>
manages up to \(2^{32}\) streams, with length \({2}^{64}\).When instantiated to produce 64bit output, like double, each stream can provide up to 128EB of data.
Installation and requirements¶
RandomIterator iterator is a header-only library with no dependences.
The Latest Version¶
Code of RandomIterator is maintened at KIT Gitlab repository
Licensing¶
RandomIterator is released under the GNU General Public License version 3. Please, see the file called LICENSE.
Contacting the developers¶
Here’s what you should do if you need help or would like to contribute:
If you found a bug or what to ask any question, use GitLab issues.
If you have an idea, suggestion or whatever, use GitHub issues.
If you want to contribute, submit a pull request.
Acknowledgement¶
The authors acknowledge support by the High Performance and Cloud Computing Group at the Zentrum für Datenverarbeitung of the University of Tübingen, the state of Baden- Württemberg through bwHPC and the German Research Foundation (DFG) through grant no. INST 37/935-1 FUGG.
Manual¶
RandomIterator is a header-only library with no dependencies. So, it is only
necessary to drop the random_iterator
directory, which contains the library
source code somewhere reachable to the compiler and include the random_iterator/Stream.cpp
in the project code. All classes, functions and typedefs of the API are declared in the
namespace random_iterator.
The primary object of RandomIterator’s API is random_iterator::Stream<Distribution, Engine>. These
objects represent streams of pseudorandom numbers distributed according with the template parameter
Distribution
, and generated by the algorithm speficied in Engine
.
Suported Distribution¶
All statistical distrucions implemented in the C++ standard library are supported, as well as distrucions implemented elsewhere, following the same interface guide lines. Addicionally, the distrucions are required to be thread-safe.
Example of suported distrucions:
std::uniform_int_distribution
std::uniform_real_distribution
std::bernoulli_distribution
std::binomial_distribution
std::negative_binomial_distribution
std::geometric_distribution
std::poisson_distribution
std::exponential_distribution
std::gamma_distribution
std::weibull_distribution
std::extreme_value_distribution
std::normal_distribution
std::lognormal_distribution
std::chi_squared_distribution
std::cauchy_distribution
std::fisher_f_distribution
std::student_t_distribution
std::discrete_distribution
std::piecewise_constant_distribution
std::piecewise_linear_distribution
Detailed information on how on these distributions is available on the page Pseudo-random number generation
Supported counter-based pseudorandom number generators (CBPRNGs)¶
random_iterator::Stream<Distribution, Engine> class template can be instatiaded with the CBPRNGs :
ars
, philox
and threefry
are implemented in Random123:.
squares3_128
, squares4_128
, random_iterator::squares3_64
and random_iterator::squares4_64
are natively implemented.
Exemplos¶
Sequential access¶
1#include <random_iterator/Stream.hpp>
2#include <random>
3
4...
5
6random_iterator::squares4_128 rng(0x548c9decbce65295);
7std::uniform_int_distribution<double> distribution(0.0, 1.0);
8
9auto stream = random_iterator::make_stream( distribution, rng, 0 );
10
11for(size_t i=0; i<10; ++i)
12 std::cout << stream() << std::endl;
Access using iterators¶
1#include <random_iterator/Stream.hpp>
2#include <random>
3
4...
5
6random_iterator::squares4_128 rng(0x548c9decbce65295);
7std::uniform_int_distribution<double> distribution(0.0, 1.0);
8
9auto its = random_iterator::make_stream( distribution, rng, 0 ).begin();
10
11for(size_t i=0; i<10; ++i)
12 std::cout << *(its++) << std::endl;
Access using range semantics¶
1#include <random_iterator/Stream.hpp>
2#include <random>
3
4...
5
6random_iterator::squares4_128 rng(0x548c9decbce65295);
7std::uniform_int_distribution<double> distribution(0.0, 1.0);
8
9auto stream = random_iterator::make_stream( distribution, rng, 0 );
10size_t i=0;
11for(auto x: stream )
12{
13 std::cout << x << std::endl;
14 if( ++i > 10) break;
15}