Apache Commons logo Apache Commons RNG

Apache Commons RNG Release Notes

Release History

Version Date Description
1.4 2021-09-13 This is a minor release of Apache Commons RNG, containing a few new features and performance improvements. Apache Commons RNG 1.4 contains the following library modules: commons-rng-client-api (requires Java 8) commons-rng-core (requires Java 8) commons-rng-simple (requires Java 8) commons-rng-sampling (requires Java 8) The code in module 'commons-rng-core' should not be accessed directly by applications as a future release might make use of the JPMS modularization feature available in Java 11+. Additional code is provided in the following modules: commons-rng-examples-quadrature (requires Java 8) commons-rng-examples-jmh (requires Java 8) commons-rng-examples-sampling (requires Java 8) commons-rng-examples-stress (requires Java 8) commons-rng-examples-jpms (requires Java 11) It is however not part of the official API and no compatibility should be expected in subsequent releases. It must be noted that, due to the nature of random number generation, some unit tests are bound to fail with some probability. The 'maven-surefire-plugin' is configured to re-run tests that fail, and pass the build if they succeed within the allotted number of reruns (the test will be marked as 'flaky' in the report).
1.3 2019-11-08 This is a minor release of Apache Commons RNG, containing a few new features and performance improvements. Apache Commons RNG 1.3 contains the following library modules: commons-rng-client-api (requires Java 6) commons-rng-core (requires Java 6) commons-rng-simple (requires Java 6) commons-rng-sampling (requires Java 6) The code in module 'commons-rng-core' should not be accessed directly by applications as a future release might make use of the JPMS modularization feature available in Java 9+. Additional code is provided in the following module: commons-rng-examples (requires Java 9) It is however not part of the official API and no compatibility should be expected in subsequent releases. It must be noted that, due to the nature of random number generation, some of unit tests are bound to fail with some probability. The 'maven-surefire-plugin' is configured to re-run tests that fail, and pass the build if they succeed within the allotted number of reruns (the test will be marked as 'flaky' in the report).
1.2 2018-12-12 This is a minor release of Apache Commons RNG, containing a few new features and performance improvements. Apache Commons RNG 1.2 contains the following library modules: commons-rng-client-api (requires Java 6) commons-rng-core (requires Java 6) commons-rng-simple (requires Java 6) commons-rng-sampling (requires Java 6) The code in module 'commons-rng-core' should not be accessed directly by applications as a future release might make use of the JPMS modularization feature available in Java 9+. Additional code is provided in the following module: commons-rng-examples (requires Java 9) It is however not part of the official API and no compatibility should be expected in subsequent releases. It must be noted that, due to the nature of random number generation, some of unit tests are bound to fail with some probability. The 'maven-surefire-plugin' is configured to re-run tests that fail, and pass the build if they succeed within the allotted number of reruns (the test will be marked as 'flaky' in the report).
1.1 2018-08-14 This is a minor release of Apache Commons RNG, containing a few new features and performance improvements. Apache Commons RNG 1.1 contains the following library modules: commons-rng-client-api (requires Java 6) commons-rng-core (requires Java 6) commons-rng-simple (requires Java 6) commons-rng-sampling (requires Java 6) The code in module 'commons-rng-core' should not be accessed directly by applications as a future release might make use of the JPMS modularization feature available in Java 9+. Additional code is provided in the following module: commons-rng-examples (requires Java 9) It is however not part of the official API and no compatibility should be expected in subsequent releases. We would like to also note that unit tests in module 'commons-rng-sampling' are bound to fail with some probability; this is expected due to the nature of random number generation. The 'maven-surefire-plugin' can be configured to re-run tests that fail and pass the build if they succeed (the test will be marked as 'flaky' in the report).
1.0 2016-12-13 This is the first release of Apache Commons RNG. Apache Commons RNG 1.0 contains the following modules: commons-rng-client-api (requires Java 6) commons-rng-core (requires Java 6) commons-rng-simple (requires Java 6) commons-rng-sampling (requires Java 6) commons-rng-jmh (requires Java 6) commons-rng-examples (requires Java 7)

Release 1.4 – 2021-09-13

Type Changes By
Update Update test suite to JUnit 5. Fixes 163. aherbert
Update Simplify assertions with simpler equivalent. Thanks to Arturo Bernal. aherbert
Update Update the minimum Java version to 1.8. Fixes 162. aherbert
Update "ZigguratSampler.NormalizedGaussian": Performance improvement by extracting ziggurat edge sampling to a separate method. Fixes 160. aherbert
Fix "ZigguratSampler.NormalizedGaussian": Corrected biased sampling within convex regions at the edge of the ziggurat. Fixes 159. aherbert
Add New "DirichletSampler" class to sample from a Dirichlet distribution. Fixes 156. aherbert
Update "UnitSphereSampler": Deprecate public constructor. Use the factory constructor to create an optimal sampler. Fixes 157. aherbert
Add New "StableSampler" class to sample from a stable distribution. Fixes 137. aherbert
Add New "CompositeSamplers" class to sample from a weighted combination of samplers. Fixes 138. aherbert
Add New "LongSampler" interface for sampling a long. New "UniformLongSampler" to sample from a range. Fixes 140. aherbert
Update "ZigguratNormalizedGaussianSampler": Update to a table size of 256. Fixes 155. aherbert
Update Update samplers to use ZigguratSampler.NormalizedGaussian for Gaussian deviates. Fixes 152. aherbert
Fix "GaussianSampler": Prevent infinite mean and standard deviation. Fixes 146. aherbert
Update Update Gaussian samplers to avoid infinity in the tails of the distribution. Applies to: ZigguratNormalisedGaussianSampler; BoxMullerNormalizedGaussianSampler; and BoxMullerGaussianSampler. Fixes 154. aherbert
Update "UnitBallSampler": Update to use the ZigguratSampler for an exponential deviate for ball point picking. Fixes 153. aherbert
Update Update "LargeMeanPoissonSampler" and "GeometricSampler" to use the ZigguratSampler for exponential deviates. Fixes 150. aherbert
Add New "ZigguratSampler" implementation of the modified "Ziggurat" algorithm for Gaussian and exponential sampling. Fixes 151. aherbert
Add New "LevySampler" to sample from a Levy distribution. Fixes 147. aherbert
Add "ContinuousUniformSampler": Add optional support for an open interval: (lower, upper). Fixes 145. aherbert
Fix "AhrensDieterExponentialSampler": Avoid possible infinite loop during sampling if the underlying UniformRandomProvider creates a zero for the uniform deviate. Fixes 144. aherbert
Add "RandomSource": Add an instance create method. Deprecate the static create method. Fixes 143. aherbert
Add New "ObjectSampler<T>" and "SharedStateObjectSampler<T>" interfaces. These interfaces are implemented by samplers returning an object. This changes the functional compatibility of existing samplers that implement SharedStatedSampler<R>: CollectionSampler<T>; CombinationSampler; DiscreteProbabilityCollectionSampler<T>; PermutationSampler; and UnitSphereSampler. The method signature of the SharedStateSampler<R> interface remains 'public R withUniformRandomProvider(UniformRandomProvider)'. The result can still be assigned to an instance of the same class R; it can no longer be assigned to an instance of SharedStatedSampler<R>. It can now be assigned to SharedStateObjectSampler<T> which can be used to generate samples of type <T>. Code that assigned to SharedStatedSampler<R> should be updated. Fixes 136. aherbert
Add New "TetrahedronSampler" to sample uniformly from a tetrahedron. Fixes 135. aherbert
Add New "BoxSampler" to sample uniformly from a box (or hyperrectangle). Fixes 134. aherbert
Add New "LineSampler" to sample uniformly on a line segment. Fixes 133. aherbert
Add New "TriangleSampler" to sample uniformly from a triangle. Fixes 131. aherbert
Add New "o.a.c.rng.sampling.shape" package for sampling coordinates from shapes. Fixes 132. aherbert
Fix "UnitSphereSampler": Fix 1 dimension sampling to only return vectors containing 1 or -1. Fixes 130. aherbert
Update "UnitSphereSampler": Improve performance with specialisations for low order dimensions. Added a factory constructor to create the sampler. Fixes 129. aherbert
Add New "UnitBallSampler" to generate coordinates uniformly within an n-unit ball. Fixes 128. aherbert
Add "PoissonSamplerCache": Method to return a SharedStateDiscreteSampler. Fixes 126. aherbert
Add Add fixed increment versions of the PCG generators. Fixes 124. aherbert

Release 1.3 – 2019-11-08

Type Changes By
Update "SeedFactory": Use XoRoShiRo1024PlusPlus as the default source of randomness. Fixes RNG-122. aherbert
Update "ChengBetaSampler": Algorithms for different distribution parameters have been delegated to specialised classes. Fixes RNG-121. aherbert
Update Update security of serialization code for java.util.Random instances. Implement look-ahead deserialization or remove the use of ObjectInputStream.readObject(). Fixes RNG-120. aherbert
Update "SplitMix64": Added primitive long constructor. Fixes RNG-76. aherbert
Add Additional "XorShiRo" family generators. This adds 4 PlusPlus general purpose variants of existing generators and 3 variants of a large state (1024-bit) generator. Fixes RNG-117. aherbert
Update Add LongJumpable support to XoShiRo generators previously only supporting Jumpable. Fixes RNG-119. aherbert
Add "RandomSource": Support creating a byte[] seed suitable for the implementing generator class. Fixes RNG-117. aherbert
Add "RandomSource": Expose interfaces supported by the implementing generator class with methods isJumpable() and isLongJumpable(). Fixes RNG-116. aherbert
Add New "JenkinsSmallFast32" and "JenkinsSmallFast64" generators. Fixes RNG-111. aherbert
Update "ListSampler": Select the shuffle algorithm based on the list type. This improves performance for non-RandomAccess lists such as LinkedList. Fixes RNG-114. aherbert
Add "JDKRandomWrapper": Wraps an instance of java.util.Random for use as a UniformRandomProvider. Can wrap a SecureRandom to use functionality provided by the JDK for cryptographic random numbers and platform dependent features such as reading /dev/urandom on Linux. Fixes RNG-19. aherbert
Fix "JDKRandom": Fixed the restore state method to function when the instance has not previously been used to save state. Fixes RNG-115. aherbert
Add New "DotyHumphreySmallFastCounting32" and "DotyHumphreySmallFastCounting64" generators. Fixes RNG-112. aherbert
Update "DiscreteProbabilityCollectionSampler": Use a faster enumerated probability distribution sampler to replace the binary search algorithm. Fixes RNG-109. aherbert
Add New "MiddleSquareWeylSequence" generator. Fixes RNG-85. aherbert
Update "BaseProvider": Updated to use faster algorithm for nextInt(int). Fixes RNG-90. aherbert
Update "DiscreteUniformSampler": Updated to use faster algorithms for generation of ranges. Fixes RNG-95. aherbert
Add Factory methods for Discrete and Continuous distribution samplers. The factory method can choose the optimal implementation for the distribution parameters. Fixes RNG-110. aherbert
Add New Permuted Congruential Generators (PCG) from the PCG family. Added the LCG and MCG 32 bit output versions of the XSH-RS and XSH-RR operations, along with the 64 bit RXS-M-XS edition. Fixes RNG-84. Thanks to Abhishek Singh Dhadwal. aherbert
Add New "SharedStateSampler" interface to allow a sampler to create a new instance with a new source of randomness. Any pre-computed state can be shared between the samplers. Fixes RNG-102. aherbert
Add Update "SeedFactory" to improve performance. Fixes RNG-108. aherbert
Add New "AliasMethodDiscreteSampler" that can sample from any discrete distribution defined by an array of probabilities. Set-up is O(n) time and sampling is O(1) time. Fixes RNG-99. aherbert
Add New "GuideTableDiscreteSampler" that can sample from any discrete distribution defined by an array of probabilities. Fixes RNG-100. aherbert
Update Ensure SeedFactory produces non-zero seed arrays. This avoids invalid seeding of generators that cannot recover from a seed of zeros. Fixes RNG-106. aherbert
Add New "LongJumpableUniformRandomProvider" interface extends JumpableUniformRandomProvider with a long jump method. Fixes RNG-98. aherbert
Add New "JumpableUniformRandomProvider" interface provides a jump method that advances the generator a large number of steps of the output sequence in a single operation. A copy is returned allowing repeat invocations to create a series of generators for use in parallel computations. Fixes RNG-97. aherbert
Update "LargeMeanPoissonSampler: Switch from SmallMeanPoissonSampler to use KempSmallMeanPoissonSampler for the fractional mean sample. Fixes RNG-103. aherbert
Update "RandomSource.create(...)": Refactor internal components to allow custom seeding routines per random source. Improvements were made to the speed of creating generators with small seeds. Fixes RNG-75. aherbert
Update "NumberFactory": Improve performance of int and long array to/from byte array conversions. Fixes RNG-77. aherbert
Add New "MarsagliaTsangWangDiscreteSampler" that provides samples from a discrete distribution stored as a look-up table using a single random integer deviate. Computes tables for the Poisson or Binomial distributions, and generically any provided discrete probability distribution. Fixes RNG-101. aherbert
Fix "AhrensDieterMarsagliaTsangGammaSampler": Fix parameter interpretation so that alpha is a 'shape' parameter and theta is a 'scale' parameter. This reverses the functionality of the constructor parameters from previous versions. Dependent code should be checked and parameters reversed to ensure existing functionality is maintained. Fixes RNG-96. aherbert
Add New "KempSmallMeanPoissonSampler" that provides Poisson samples using only 1 random deviate per sample. This algorithm outperforms the SmallMeanPoissonSampler when the generator is slow. Fixes RNG-91. aherbert
Fix "SmallMeanPoissonSampler": Requires the Poisson probability for p(x=0) to be positive setting an upper bound on the mean of approximately 744.44. Fixes RNG-93. aherbert
Fix "LargeMeanPoissonSampler": Requires mean >= 1. Fixes RNG-92. aherbert
Add New "XorShiRo" family of generators. This adds 6 new general purpose generators with different periods and 4 related generators with improved performance for floating-point generation. Fixes RNG-70. aherbert
Update Update the generation performance JMH benchmarks to have a reference baseline. Fixes RNG-88. aherbert
Update "MultiplyWithCarry256": Performance improvement by advancing state one step per sample. Fixes RNG-87. aherbert
Add New "XorShift1024StarPhi" generator. This is a modified implementation of XorShift1024Star that improves randomness of the output sequence. The XOR_SHIFT_1024_S enum has been marked deprecated as a note to users to switch to the new XOR_SHIFT_1024_S_PHI version. Fixes RNG-82. aherbert
Add New "ThreadLocalRandomSource" class provides thread safe access to random generators. Fixes RNG-78. aherbert
Update "NumberFactory": Evenly sample all dyadic rationals between 0 and 1. Fixes RNG-81. aherbert
Add Benchmark methods for producing nextDouble and nextFloat. Fixes RNG-79. aherbert
Update Add the methods used from UniformRandomProvider to each sampler in the sampling module. Fixes RNG-73. aherbert
Update "DiscreteUniformSampler": Algorithms for small and large integer ranges have been delegated to specialised classes. Fixes RNG-74. aherbert
Add Add new JMH benchmark ConstructionPerformance. Fixes RNG-72. aherbert
Add Validate parameters for the distribution samplers. Fixes RNG-71. aherbert
Update "AhrensDieterMarsagliaTsangGammaSampler": Algorithms for small and large theta have been delegated to specialised classes. Fixes RNG-68. aherbert
Add Instructions for how to build and run the examples-stress code. Fixes RNG-67. aherbert
Add New "GeometricSampler" class. Fixes RNG-69. aherbert

Release 1.2 – 2018-12-12

Type Changes By
Update "NumberFactory": Some methods have become obsolete following RNG-57. Fixes RNG-63. erans
Update "PermutationSampler" and "CombinationSampler" shared code moved to a utility class. Fixes RNG-64. Thanks to Alex D. Herbert. erans
Add New "CombinationSampler" class. Fixes RNG-62. Thanks to Alex D. Herbert. erans
Update "PermutationSampler": Performance improvement. Fixes RNG-61. Thanks to Alex D. Herbert. erans
Update Cache for using up all the bits provided by the underlying source of randomness. Fixes RNG-57. Thanks to Alex D. Herbert. erans
Update Use random seeds for unit testing. Fixes RNG-60. erans
Update Set conservative upper bound in "LargePoissonSampler" to avoid truncation. Fixes RNG-52. erans
Fix Use JDK's "SecureRandom" to seed the "SeedFactory". Fixes RNG-59. erans
Update Allow part of RNG state to be contained in base classes, e.g. to enable caching in common code (see RNG-57). Fixes RNG-58. erans
Update "PoissonSampler": Performance improvement. Fixes RNG-51. Thanks to Alex D. Herbert. erans
Fix "ZigguratNormalizedGaussianSampler": Missing statements in least used branch. Fixes RNG-56. erans
Fix "UnitSphereSampler": Prevent returning NaN components and forbid negative dimension. Fixes RNG-55. Thanks to Alex D. Herbert. erans

Release 1.1 – 2018-08-14

Type Changes By
Fix Class "SamplerBase" has been deprecated. It was meant for internal use only but, through inheritance, it allows incorrect usage of the sampler classes. Fixes RNG-53. erans
Update "PoissonSampler": Algorithms for small mean and large mean have been separated into dedicated classes. Cache precomputation has been disabled as it is only marginally used and is a performance hit for small sampling sets. Fixes RNG-50. Thanks to Alex D. Herbert. erans
Add Implementation of the "Ziggurat" algorithm for Gaussian sampling. Fixes RNG-37. erans
Update Use "ZigguratNormalizedGaussianSampler" within the library. Fixes RNG-42. erans
Add "DiscreteProbabilityCollectionSampler": Sampling from a collection of items with user-defined probabilities (feature ported from "Commons Math"). Fixes RNG-47. erans
Add "LogNormalSampler" with user-defined underlying "NormalizedGaussianSampler". Fixes RNG-43. erans
Update Following RNG-43, "BoxMullerLogNormalSampler" has been deprecated. Fixes RNG-46. erans
Add "UnitSphereSampler": generate random vectors isotropically located on the surface of a sphere (feature ported from "Commons Math"). Fixes RNG-39. erans
Add "MarsagliaNormalizedGaussianSampler": Faster variation of the Box-Muller algorithm. This version is used within "AhrensDieterMarsagliaTsangGammaSampler" "MarsagliaLogNormalSampler" and "PoissonSampler" (generated sequences will thus differ from those generated by version 1.0 of the library). Fixes RNG-36. erans
Add New generic "GaussianSampler" based on "NormalizedGaussianSampler" marker interface. Implementation of "BoxMullerNormalizedGaussianSampler" deprecates "BoxMullerGaussianSampler". Fixes RNG-35. erans

Release 1.0 – 2016-12-13

No changes in this release.