README.md (7852B)
1 # Star SamPling 2 3 Star-SamPling is a library whose purpose is to generate pseudo-random 4 numbers and sample distributions. A proxy generator can also be used to 5 generate independent random sequences from the same pseudo-random 6 generator. This is particularly useful for ensuring the statistical 7 independence of random sequences on parallel computations. Although 8 Star-SamPling relies on C++ libraries, its API is still raw C. 9 10 ## Requirements 11 12 - C++ compiler (C++11) 13 - POSIX make 14 - pkg-config 15 - [Random123](https://github.com/DEShawResearch/random123) 16 - [RSys](https://gitlab.com/vaplv/rsys) 17 18 ## Installation 19 20 Edit config.mk as needed, then run: 21 22 make clean install 23 24 ## Release notes 25 26 ### Version 0.15 27 28 - Keep RNG caches managed by proxy in memory to avoid write failures 29 when the temporary directory ran out of space. 30 - Reduce the size of the RNG cache managed by proxy to 4MB to limit the 31 memory footprint of the proxy. 32 - Write state cache in case of fatal error to help debug what went 33 wrong. 34 - Improve the building system. Simplify it by doing everything in one 35 place (Makefile). Provide additional macros to control installation 36 subdirectories. 37 38 ### Version 0.14 39 40 Replace CMake by Makefile as build system. The build procedure is 41 written in POSIX make, which the user can configure via the `config.mk` 42 file. The POSIX script `make.sh` contains commands that could be found 43 directly in the Makefile, but which are placed here to simplify its 44 writing. Finally, a pkg-config file is provided to link the library as 45 an external dependency. 46 47 In addition to the features already provided by its CMake alternative, 48 the Makefile supports the construction of static libraries, provides an 49 uninstall target and updates compiler and linker flags to increase the 50 security and robustness of generated binaries. In any case, the main 51 motivation for using POSIX make is to rely on a good old 52 well-established standard with simple functionality, available on all 53 UNIX systems, thus simplifying its portability and support while being 54 much lighter. 55 56 ### Version 0.13 57 58 #### Index of the RNG proxy sequence 59 60 Add the `sequence_id` variable to the RNG proxy. A sequence is a set of 61 random numbers consumed by the buckets managed by the RNG proxy. This 62 new variable saves the index of the current sequence relative to the 63 initial state of the RNG proxy. It thus identifies the set of random 64 numbers already consumed and currently reserved by an RNG proxy. This 65 data is provided to allow the caller to synchronize multiple RNG 66 proxies. 67 68 The new `ssp_rng_proxy_get_sequence_id` function allows the caller to 69 retrieve the index of the current sequence while the 70 `ssp_rng_proxy_flush_sequences` function allows to remove random numbers 71 from the current sequence and those from the next one. 72 73 #### Issues in RNG proxy 74 75 - Fixes the `ssp_rng_proxy_read` function: cached RNG states were not 76 being cleaned up when updating the proxy state, resulting in the use 77 of random numbers generated from the wrong state. 78 - Fixes critical issues in the caching mechanism of the RNG proxy: a 79 cache size smaller than the size of an RNG state led to critical bugs. 80 81 ### Version 0.12.1 82 83 Fix creating a random number proxy generator using the KISS type: this 84 type was considered invalid while it is not. 85 86 ### Version 0.12 87 88 Ensures C++11 compliance to correct gcc 11 compilation errors. On the 89 other hand, this introduces API breaks. 90 91 According to the C++11 standard, the min/max values of a 92 UniformRandomBitGenerator must be static constant expressions. But until 93 now, gcc has been flexible enough to allow the use of 94 UniformRandomBitGenerators with regular min/max values. At run time, the 95 caller could thus define its own RNG type as provided by the struct 96 `ssp_rng_type` data structure. Unfortunately, since its version 11, gcc 97 is more severe and refuses to compile this code. 98 99 This version updates the API to respect this C++11 constraint. The 100 `ssp_rng_type` is no longer a structure; it becomes an enumeration which 101 is then instantiated internally in a specific UniformRandomBitGenerator 102 with min/max values resolved at compilation time. 103 104 ### Version 0.11.1 105 106 Sets the CMake minimum version to 3.1 in the Random123Config.cmake file: 107 since CMake 3.20, version 2 has become obsolete. 108 109 ### Version 0.11 110 111 - Add the `ssp_ran_spherical_zone_uniform` distribution that uniformly 112 samples a position on a truncated spherical cap. 113 - Rename the library to `star-sp` to avoid conflicts with GCC's 114 `libssp`. 115 116 ### Version 0.10 117 118 - Add the `ssp_ran_exp_truncated` distribution. 119 120 ### Version 0.9 121 122 - Rewrite the caching mechanism used to register the RNG states provided 123 by the proxy to its managed generators. These states are no more saved 124 in files that continuously grow. The streams have now a limited size, 125 and the states are structured into them as in a FIFO circular queue. 126 When a queue is full, the RNG states are no more stored into it but 127 will be generated by the associated managed RNG. 128 - Update the `ssp_rng_proxy_create2` function: input arguments are now 129 provided through a structured variable. Furthermore, its initial state 130 can be setup from an optionnal RNG. 131 - Add the `ssp_ran_tetrahedron_uniform[_float]` random variates that 132 uniformly distributes a point into a tetrahedron. 133 - Fix the read function of the KISS RNG: de-serialised data could be 134 wrong. 135 136 ### Version 0.8.1 137 138 - Fix a possible invalid memory read on proxy allocator clear. 139 140 ### Version 0.8 141 142 - Add the `ssp_ran_sphere_cap_uniform[_local][_float]` random variates 143 that uniformly distributes a point onto a unit sphere cap centered in 144 zero. 145 - Fix the allocation of the `ssp_rng` data structure: the `ssp_rng` 146 structure contains a long double attribute that might be not correctly 147 aligned on 16 bytes. 148 149 ### Version 0.7 150 151 - Add the `ssp_ran_circle_uniform` random variate that uniformly 152 distributes a 2 dimensional position onto a unit circle. 153 154 ### Version 0.6 155 156 - Add the `ssp_rng_proxy_create2` function that allows to tune the sub 157 sets of pseudo random numbers that the proxy generator can use. Pseudo 158 random numbers that do not lie in these partitions are skipped by the 159 proxy. Thanks to this functionality, on can create several proxies, 160 each generating its own set of pseudo random numbers that does not 161 overlap the sequences of the other proxies. 162 - Update the version of the RSys dependency to 0.6: replace the 163 deprecated `[N]CHECK` macros by the new macro `CHK`. 164 165 ### Version 0.5 166 167 - Rename the `ssp_ran_uniform_disk` API call into 168 `ssp_ran_uniform_disk_local`. 169 - Add a more general version of the uniform disk random variate allowing 170 users to provide the disk's normal. 171 - Add a float equivalent for all the already defined double random 172 variates. 173 - Add some missing pdf API calls. 174 - Change the API of some random variates that returned the pdf as an 175 additional vector component along with the sampled vector (i.e. 176 filling up a vector[4] instead of a vector[3]). The pdf is now 177 returned through an optional dedicated argument. 178 179 ### Version 0.4 180 181 - Update the API of the random variates to return double precision reals 182 rather than single precision values. 183 - Use the specific prefix `ssp_ranst` to name the state-based random 184 variates. 185 - Add the piecewise linear and uniform disk random variates. 186 - Ensure that the single precision version of the canonical uniform 187 distribution does not return 1. 188 - Speed up the canonical uniform distribution. 189 - Add the `ssp_rng_proxy_write` and `ssp_rng_proxy_read` functions that 190 serializes and deserializes the data of the proxy RNG, respectively. 191 192 ## License 193 194 Copyright (C) 2015-2025 |Méso|Star> (contact@meso-star.com) 195 196 Star-SP is free software released under GPL v3+ license: GNU GPL version 197 3 or later. You are welcome to redistribute it under certain conditions; 198 refer to the COPYING file for details.