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

https://gitlab.ikp.kit.edu/AAAlvesJr/random_iterator

Documentation

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}

Reference Documentation

Find the latest full reference manual at Doxygen, or the components on: