# 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'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.