README.md

xoshiro256starstar

This is the xoshiro256starstar project, a header-only C++ library providing an implementation of xoshiro256** 1.0 conforming to the C++20 standard-library concept std::uniform_random_bit_generator. The header file is <xoshiro256starstar/xoshiro256starstar.hpp>. It defines a class named xoshiro256starstar::xoshiro256starstar.

The code is based on xoshiro256starstar.c written by David Blackman and Sebastian Vigna in 2018 and splitmix64.c written by Sebastian Vigna in 2015, which are in the public domain.

See Sebastian Vigna's PRNG pages and M. E. O'Neill's blog for description and discussion of xoshiro256** and pseudorandom number generators in general.

Usage

A Uniform Random Bit Generator can be used with a Random Number Distribution or passed to the std::shuffle algorithm.

To create a generator,

#include <xoshiro256starstar.hpp>
#include <random>

using urbg = xoshiro256starstar::xoshiro256starstar;
using xoshiro256starstar::seed_from_urbg;

// Seed with 256 bits generated by another urbg
auto generator1 = urbg{seed_from_urbg, std::random_device{}};

// Default constructor, same as urbg{seed_from_urbg, std::random_device{}}
auto generator2 = urbg{};

// Seed a splitmix64 generator with a given 64-bit seed and use it to fill
// the 256-bit xoshiro256** seed
auto generator2 = urbg{0xdeadbeeffeedbadbull};

// Provide a full 256-bit seed, which must not be everywhere zero
auto generator3 = urbg{
    0xdeadbeeffeedbadbull,
    0xbadfacedbeedeadfull,
    0xdadaddedbaddeedcull,
    0xdecadefadedfacedull,
};

// Copyable (both generators will produce the same sequence)
auto generator4 = generator3;

// The jump functions make a copy of the URBG, then advance the URBG's sequence
// as if by calling operator()(), then return the (unmodified) copy

// jump() is equivalent to 2^128 calls; it can be used to generate 2^128
// non-overlapping sequences for parallel computations
auto generator5 = generator4.jump();

// long_jump() is equivalent to 2^192 calls; it can be used to generate 2^64
// starting points, from each of which jump() will generate 2^64
// non-overlapping subsequences for parallel distributed computations
auto generator6 = generator4.long_jump();

Building and installing

See the BUILDING document.

Contributing

See the CONTRIBUTING document.

Licensing

Distributed under the Boost Software License, Version 1.0.