Star-SamPling Random number generators & random variates

The Star-SamPling library provides a set of random number generators as well as a large collection of random variates. Its API is pure C and the exposed functions make no reference to the actual generator used. One can thus easely switch the generator without any impact on the application source code.

Star-SamPling proposes generators well suited for use in simulation: they have extremely long periods and low correlation. In addition of regular generators such as Mersen Twister or RANLUX, it relies on the Random123 library to provide "counter based" generators that satisfy rigourous statistical testing.

Gaussian distribution and its cumulative used to generate a sample according to this probability distribution function.

Beyond uniform distribution, Star-SamPling can be used to generate random variates from exponental, gaussian or lognormal distributions. It also implements uniform sampling of a triangle, a disk, a sphere, an hemisphere or a circle as well as the cosine weighted sampling of an hemisphere or the sampling of a sphere with respect to the Henyey & Greenstein function.

Star-SamPling provides the notion of proxy of a random number generator. A proxy is used to split the random numbers of a generator in a set of N partitions, where N is a user defined parameter. Each partition is assigned to a generator that is actually a regular generator regarding the Star-SamPling API. The main benefit is that such generators can be used by different processes that concurrently participate to the same simulation since in such situation each process must ensure that it relies on its own set of random numbers. Star-SamPling is thus well suited to parallel computations that use message passing and/or shared memory communication models.

Release notes

Version 0.12.1

Fix creating a random number proxy generator using the KISS type: this type was considered invalid while it is not.

Version 0.12

Ensures C++11 compliance to correct gcc 11 compilation errors. On the other hand, this introduces API breaks.

According to the C++11 standard, the min/max values of a UniformRandomBitGenerator must be static constant expressions. But until now, gcc has been flexible enough to allow the use of UniformRandomBitGenerators with regular min/max values. At run time, the caller could thus define its own RNG type as provided by the struct ssp_rng_type data structure. Unfortunately, since its version 11, gcc is more severe and refuses to compile this code.

This version updates the API to respect this C++11 constraint. The ssp_rng_type is no longer a structure; it becomes an enumeration which is then instantiated internally in a specific UniformRandomBitGenerator with min/max values resolved at compilation time.

Version 0.11.1

Sets the CMake minimum version to 3.1 in the Random123Config.cmake file: since CMake 3.20, version 2 has become obsolete.

Version 0.11

• Add the ssp_ran_spherical_zone_uniform distribution that uniformly samples a position on a truncated spherical cap.
• Rename the library to star-sp to avoid conflicts with GCC's libssp.

Version 0.10

• Add the ssp_ran_exp_truncated distribution.

Version 0.9

• Rewrite the caching mechanism used to register the RNG states provided by the proxy to its managed generators. These states are no more saved in files that continuously grow. The streams have now a limited size, and the states are structured into them as in a FIFO circular queue. When a queue is full, the RNG states are no more stored into it but will be generated by the associated managed RNG.
• Update the ssp_rng_proxy_create2 function: input arguments are now provided through a structured variable. Furthermore, its initial state can be setup from an optionnal RNG.
• Add the ssp_ran_tetrahedron_uniform[_float] random variates that uniformly distributes a point into a tetrahedron.
• Fix the read function of the KISS RNG: de-serialised data could be wrong.

Version 0.8.1

• Fix a possible invalid memory read on proxy allocator clear.

Version 0.8

• Add the ssp_ran_sphere_cap_uniform[_local][_float] random variates that uniformly distributes a point onto a unit sphere cap centered in zero.
• Fix the allocation of the ssp_rng data structure: the ssp_rng structure contains a long double attribute that might be not correctly aligned on 16 bytes.

Version 0.7

• Add the ssp_ran_circle_uniform random variate that uniformly distributes a 2 dimensional position onto a unit circle.

Version 0.6

• Add the ssp_rng_proxy_create2 function that allows to tune the sub sets of pseudo random numbers that the proxy generator can use. Pseudo random numbers that do not lie in these partitions are skipped by the proxy. Thanks to this functionality, on can create several proxies, each generating its own set of pseudo random numbers that does not overlap the sequences of the other proxies.
• Update the version of the RSys dependency to 0.6: replace the deprecated [N]CHECK macros by the new macro CHK.

Version 0.5

• Rename the ssp_ran_uniform_disk API call into ssp_ran_uniform_disk_local.
• Add a more general version of the uniform disk random variate allowing users to provide the disk's normal.
• Add a float equivalent for all the already defined double random variates.
• Add some missing pdf API calls.
• Change the API of some random variates that returned the pdf as an additional vector component along with the sampled vector (i.e. filling up a vector[4] instead of a vector[3]). The pdf is now returned through an optional dedicated argument.

Version 0.4

• Update the API of the random variates to return double precision reals rather than single precision values.
• Use the specific prefix ssp_ranst to name the state-based random variates.
• Add the piecewise linear and uniform disk random variates.
• Ensure that the single precision version of the canonical uniform distribution does not return 1.
• Speed up the canonical uniform distribution.
• Add the ssp_rng_proxy_write and ssp_rng_proxy_read functions that serializes and deserializes the data of the proxy RNG, respectively.

License

Copyright © 2015-2021 |Meso|Star> (contact@meso-star.com). Star-Sampling is free software released under the CeCILLv2.1 license. You are welcome to redistribute it under certain conditions; refer to the COPYING files for details.