Star-SamPling Random number generators & random variates
Star-SP 0.12.1 is available
- Get source code: git
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.
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'slibssp
.
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: thessp_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 macroCHK
.
Version 0.5
- Rename the
ssp_ran_uniform_disk
API call intossp_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
andssp_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.