Apache Commons logo Apache Commons RNG
Apache Commons RNG ™
  • Last Published: 09 July 2024
  • |
  • Version: 1.6

Apache Commons RNG Release Notes

Release History

Version Date Description
1.6 2024-07-15 New features, updates and bug fixes (requires Java 8).
1.5 2022-09-10 New features, updates and bug fixes. Adds a commons-rng-bom module. Requires Java 8.
1.4 2021-09-13 New features, updates and bug fixes. Updates the minimum Java version to 8.
1.3 2019-11-08 New features, updates and bug fixes (requires Java 6).
1.2 2018-12-12 New features, updates and bug fixes (requires Java 6).
1.1 2018-08-14 New features, updates and bug fixes (requires Java 6).
1.0 2016-12-13 This is the first release of Apache Commons RNG. Contains the following modules: commons-rng-client-api; commons-rng-core; commons-rng-simple; commons-rng-sampling. Requires Java 6.

Release 1.6 – 2024-07-15

Type Changes By
Add Correct the module OSGi exports. Use of multiple modules is validated in an OSGi integration test. Fixes RNG-186. aherbert
Add New "ArraySampler" to support shuffling primitive and generic arrays with sub-range support. Fixes RNG-184. aherbert
Update "InverseTransformParetoSampler": Modified to concentrate samples at the distribution lower/upper bounds for extreme shape parameters. Eliminates generation of outlier infinite samples and NaN samples under certain conditions. Changes sampling to use the RNG nextLong() method in-place of nextDouble(). Fixes RNG-183. aherbert

Release 1.5 – 2022-09-10

Type Changes By
Add Add a Bill of Materials (BOM) to aid in dependency management when referencing multiple Apache Commons RNG artifacts. The BOM should be used to ensure all imported artifacts are compatible. Fixes RNG-182. aherbert
Add LXM family to support SplittableUniformRandomProvider. This allows creating a parallel stream of generators which will avoid sequence correlations between instances. Fixes RNG-181. aherbert
Add New "SplittableUniformRandomProvider" interface to allow splitting a RNG into two objects, each of which implements the same interface (and can be recursively split indefinitely). Add default methods to support parallel stream implementations of the UniformRandomProvider stream methods. Fixes RNG-180. aherbert
Add "FastLoadedDiceRollerDiscreteSampler": Distribution sampler that uses the Fast Loaded Dice Roller (FLDR) algorithm for exact sampling from a discrete probability distribution. Fixes RNG-179. aherbert
Add "JumpableUniformRandomProvider": Add support to generate Java 8 streams of new random generator instances using the jump method. Fixes RNG-178. aherbert
Add "UniformRandomProvider": Enhance the interface with default methods. Add range sample methods with a lower and upper bound. Add support to generate Java 8 streams of sample values. Note: This moves some method implementations from the core module to the client-api module. Binary compatibility is supported if the versions of these modules are matched. Users of the simple module should ensure the client-api and core modules are resolved as matched versions and not mismatched by transitive dependency resolution. Fixes RNG-176. aherbert
Add "sampling": Add samples() method to the API to generate Java 8 streams of sample values. Fixes RNG-177. aherbert
Add New LXM family of random generators. Added implementations of the LXM generators included in JDK 17. Fixes RNG-168. aherbert
Add "RandomSource": Improve support for non-zero seeds. Seeding has been changed to specify a sub-range of the seed that must not be all zero. Introduces a functional change where byte[] seeds generated by RandomSource with a fixed UniformRandomProvider may be different. Seeds are now reproducible across calls using an input random source in an identical state. Fixes RNG-174. aherbert
Fix "RandomSource.MSWS": createSeed(UniformRandomProvider) to handle a bad RNG. This fixes an infinite loop when the RNG output is not suitably random to create a seed. Fixes RNG-175. aherbert
Add "BaseProvider": Add a static method to extend input int[] and long[] seeds to a minimum length. Fixes RNG-173. aherbert
Update Reduce the memory footprint of the cached boolean and int source for the IntProvider and LongProvider. This change has a performance improvement on some JDKs. Note: This introduces a functional compatibility change to the output from the nextInt method of any LongProvider; the output is now little-endian as each long is returned as the low 32-bits then the high 32-bits. The bit output from nextBoolean is unchanged (little-endian order). Fixes RNG-171. aherbert
Update "UniformLongSampler": Precompute rejection threshold for a non-power of 2 range. Fixes RNG-172. aherbert
Update "RandomSource.create": Update array seed conversion to use optimum seed length. Avoid duplication of input bytes and conversion of bytes that will be discarded. This introduces a behavioural change for int[], long[], and int seed conversions. Any fixed seeds used in previous versions in byte[], long or the native seed type will create the same RNG state. All array-to-array seed conversions now use little endian format, matching the byte[] conversion behaviour since 1.0. All seed conversions that expand the seed size use the same generation method to provide additional bytes. Conversion of int[] to long avoids loss of bits changing the possible output seeds from 2^32 to 2^64. Fixes RNG-169. aherbert
Fix Update implementations of "UniformRandomProvider.nextBytes" with a range [start, start + length) to be consistent with the exception conditions of the JDK array range checks. Fixes RNG-170. aherbert
Add New "TSampler" class to sample from Student's t-distribution. Fixes RNG-167. aherbert
Fix Update "LogNormalSampler" and "BoxMullerLogNormalSampler" to allow a negative mean for the natural logarithm of the distribution values. Fixes RNG-166. aherbert
Fix "RejectionInversionZipfSampler": Allow a zero exponent in the Zipf sampler. Fixes RNG-165. aherbert
Update "ZigguratSampler": Performance improvement using ternary operator to sort values. Fixes RNG-160. aherbert

Release 1.4 – 2021-09-13

Type Changes By
Update Update test suite to JUnit 5. Fixes RNG-163. aherbert
Update Simplify assertions with simpler equivalent. Thanks to Arturo Bernal. aherbert
Update Update the minimum Java version to 1.8. Fixes RNG-162. aherbert
Update "ZigguratSampler.NormalizedGaussian": Performance improvement by extracting ziggurat edge sampling to a separate method. Fixes RNG-160. aherbert
Fix "ZigguratSampler.NormalizedGaussian": Corrected biased sampling within convex regions at the edge of the ziggurat. Fixes RNG-159. aherbert
Add New "DirichletSampler" class to sample from a Dirichlet distribution. Fixes RNG-156. aherbert
Update "UnitSphereSampler": Deprecate public constructor. Use the factory constructor to create an optimal sampler. Fixes RNG-157. aherbert
Add New "StableSampler" class to sample from a stable distribution. Fixes RNG-137. aherbert
Add New "CompositeSamplers" class to sample from a weighted combination of samplers. Fixes RNG-138. aherbert
Add New "LongSampler" interface for sampling a long. New "UniformLongSampler" to sample from a range. Fixes RNG-140. aherbert
Update "ZigguratNormalizedGaussianSampler": Update to a table size of 256. Fixes RNG-155. aherbert
Update Update samplers to use ZigguratSampler.NormalizedGaussian for Gaussian deviates. Fixes RNG-152. aherbert
Fix "GaussianSampler": Prevent infinite mean and standard deviation. Fixes RNG-146. aherbert
Update Update Gaussian samplers to avoid infinity in the tails of the distribution. Applies to: ZigguratNormalisedGaussianSampler; BoxMullerNormalizedGaussianSampler; and BoxMullerGaussianSampler. Fixes RNG-154. aherbert
Update "UnitBallSampler": Update to use the ZigguratSampler for an exponential deviate for ball point picking. Fixes RNG-153. aherbert
Update Update "LargeMeanPoissonSampler" and "GeometricSampler" to use the ZigguratSampler for exponential deviates. Fixes RNG-150. aherbert
Add New "ZigguratSampler" implementation of the modified "Ziggurat" algorithm for Gaussian and exponential sampling. Fixes RNG-151. aherbert
Add New "LevySampler" to sample from a Levy distribution. Fixes RNG-147. aherbert
Add "ContinuousUniformSampler": Add optional support for an open interval: (lower, upper). Fixes RNG-145. aherbert
Fix "AhrensDieterExponentialSampler": Avoid possible infinite loop during sampling if the underlying UniformRandomProvider creates a zero for the uniform deviate. Fixes RNG-144. aherbert
Add "RandomSource": Add an instance create method. Deprecate the static create method. Fixes RNG-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 RNG-136. aherbert
Add New "TetrahedronSampler" to sample uniformly from a tetrahedron. Fixes RNG-135. aherbert
Add New "BoxSampler" to sample uniformly from a box (or hyperrectangle). Fixes RNG-134. aherbert
Add New "LineSampler" to sample uniformly on a line segment. Fixes RNG-133. aherbert
Add New "TriangleSampler" to sample uniformly from a triangle. Fixes RNG-131. aherbert
Add New "o.a.c.rng.sampling.shape" package for sampling coordinates from shapes. Fixes RNG-132. aherbert
Fix "UnitSphereSampler": Fix 1 dimension sampling to only return vectors containing 1 or -1. Fixes RNG-130. aherbert
Update "UnitSphereSampler": Improve performance with specialisations for low order dimensions. Added a factory constructor to create the sampler. Fixes RNG-129. aherbert
Add New "UnitBallSampler" to generate coordinates uniformly within an n-unit ball. Fixes RNG-128. aherbert
Add "PoissonSamplerCache": Method to return a SharedStateDiscreteSampler. Fixes RNG-126. aherbert
Add Add fixed increment versions of the PCG generators. Fixes RNG-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.

Copyright © 2016-2024 The Apache Software Foundation. All Rights Reserved.

Apache Commons, Apache Commons RNG, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.