blob: 901f51ac792d93b030e7d59dd5e5d1601c77ba91 [file] [log] [blame]
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!--
This file is used by the maven-changes-plugin to generate the release notes.
Useful ways of finding items to add to this file are:
1. Add items when you fix a bug or add a feature (this makes the
release process easy :-).
2. Do a JIRA search for tickets closed since the previous release.
3. Use the report generated by the maven-changelog-plugin to see all
SVN commits.
To generate the file RELEASE-NOTES.txt from this file:
mvn changes:announcement-generate -Prelease-notes [-Dchanges.version]
The <action> type attribute can be add,update,fix,remove.
-->
<!-- NOTE:
The description attribute entries below are specially formatted
so as to improve the layout of the generated text release notes.
The parsing process removes all line feeds, replacing them with a single space.
The Velocity template in src/changes/release-notes.vm has been enhanced to replace pairs of adjacent spaces
with a new-line in the release notes. (These spaces are ignored when displaying HTML).
If the output is not quite correct, check for invisible trailing spaces!
-->
<document xmlns="http://maven.apache.org/changes/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/changes/1.0.0 http://maven.apache.org/xsd/changes-1.0.0.xsd">
<properties>
<title>Apache Commons RNG Release Notes</title>
</properties>
<body>
<release version="1.4" date="2021-09-13" description="
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).
">
<action dev="aherbert" type="update" issue="163">
Update test suite to JUnit 5.
</action>
<action dev="aherbert" due-to="Arturo Bernal" type="update">
Simplify assertions with simpler equivalent.
</action>
<action dev="aherbert" type="update" issue="162">
Update the minimum Java version to 1.8.
</action>
<action dev="aherbert" type="update" issue="160">
"ZigguratSampler.NormalizedGaussian": Performance improvement by extracting ziggurat
edge sampling to a separate method.
</action>
<action dev="aherbert" type="fix" issue="159">
"ZigguratSampler.NormalizedGaussian": Corrected biased sampling within convex regions
at the edge of the ziggurat.
</action>
<action dev="aherbert" type="add" issue="156">
New "DirichletSampler" class to sample from a Dirichlet distribution.
</action>
<action dev="aherbert" type="update" issue="157">
"UnitSphereSampler": Deprecate public constructor. Use the factory constructor to create
an optimal sampler.
</action>
<action dev="aherbert" type="add" issue="137">
New "StableSampler" class to sample from a stable distribution.
</action>
<action dev="aherbert" type="add" issue="138">
New "CompositeSamplers" class to sample from a weighted combination of samplers.
</action>
<action dev="aherbert" type="add" issue="140">
New "LongSampler" interface for sampling a long. New "UniformLongSampler" to sample
from a range.
</action>
<action dev="aherbert" type="update" issue="155">
"ZigguratNormalizedGaussianSampler": Update to a table size of 256.
</action>
<action dev="aherbert" type="update" issue="152">
Update samplers to use ZigguratSampler.NormalizedGaussian for Gaussian deviates.
</action>
<action dev="aherbert" type="fix" issue="146">
"GaussianSampler": Prevent infinite mean and standard deviation.
</action>
<action dev="aherbert" type="update" issue="154">
Update Gaussian samplers to avoid infinity in the tails of the distribution. Applies
to: ZigguratNormalisedGaussianSampler; BoxMullerNormalizedGaussianSampler; and
BoxMullerGaussianSampler.
</action>
<action dev="aherbert" type="update" issue="153">
"UnitBallSampler": Update to use the ZigguratSampler for an exponential deviate for
ball point picking.
</action>
<action dev="aherbert" type="update" issue="150">
Update "LargeMeanPoissonSampler" and "GeometricSampler" to use the ZigguratSampler for
exponential deviates.
</action>
<action dev="aherbert" type="add" issue="151">
New "ZigguratSampler" implementation of the modified "Ziggurat" algorithm for
Gaussian and exponential sampling.
</action>
<action dev="aherbert" type="add" issue="147">
New "LevySampler" to sample from a Levy distribution.
</action>
<action dev="aherbert" type="add" issue="145">
"ContinuousUniformSampler": Add optional support for an open interval: (lower, upper).
</action>
<action dev="aherbert" type="fix" issue="144">
"AhrensDieterExponentialSampler": Avoid possible infinite loop during sampling if the
underlying UniformRandomProvider creates a zero for the uniform deviate.
</action>
<action dev="aherbert" type="add" issue="143">
"RandomSource": Add an instance create method. Deprecate the static create method.
</action>
<action dev="aherbert" type="add" issue="136">
New "ObjectSampler&lt;T&gt;" and "SharedStateObjectSampler&lt;T&gt;" interfaces.
These interfaces are implemented by samplers returning an object.
This changes the functional compatibility of existing samplers that implement
SharedStatedSampler&lt;R&gt;: CollectionSampler&lt;T&gt;; CombinationSampler;
DiscreteProbabilityCollectionSampler&lt;T&gt;; PermutationSampler; and UnitSphereSampler.
The method signature of the SharedStateSampler&lt;R&gt; 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&lt;R&gt;. It can now be assigned to SharedStateObjectSampler&lt;T&gt;
which can be used to generate samples of type &lt;T&gt;.
Code that assigned to SharedStatedSampler&lt;R&gt; should be updated.
</action>
<action dev="aherbert" type="add" issue="135">
New "TetrahedronSampler" to sample uniformly from a tetrahedron.
</action>
<action dev="aherbert" type="add" issue="134">
New "BoxSampler" to sample uniformly from a box (or hyperrectangle).
</action>
<action dev="aherbert" type="add" issue="133">
New "LineSampler" to sample uniformly on a line segment.
</action>
<action dev="aherbert" type="add" issue="131">
New "TriangleSampler" to sample uniformly from a triangle.
</action>
<action dev="aherbert" type="add" issue="132">
New "o.a.c.rng.sampling.shape" package for sampling coordinates from shapes.
</action>
<action dev="aherbert" type="fix" issue="130">
"UnitSphereSampler": Fix 1 dimension sampling to only return vectors containing 1 or -1.
</action>
<action dev="aherbert" type="update" issue="129">
"UnitSphereSampler": Improve performance with specialisations for low order dimensions.
Added a factory constructor to create the sampler.
</action>
<action dev="aherbert" type="add" issue="128">
New "UnitBallSampler" to generate coordinates uniformly within an n-unit ball.
</action>
<action dev="aherbert" type="add" issue="126">
"PoissonSamplerCache": Method to return a SharedStateDiscreteSampler.
</action>
<action dev="aherbert" type="add" issue="124">
Add fixed increment versions of the PCG generators.
</action>
</release>
<release version="1.3" date="2019-11-08" description="
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).
">
<action dev="aherbert" type="update" issue="RNG-122">
"SeedFactory": Use XoRoShiRo1024PlusPlus as the default source of randomness.
</action>
<action dev="aherbert" type="update" issue="RNG-121">
"ChengBetaSampler": Algorithms for different distribution parameters have
been delegated to specialised classes.
</action>
<action dev="aherbert" type="update" issue="RNG-120">
Update security of serialization code for java.util.Random instances. Implement
look-ahead deserialization or remove the use of ObjectInputStream.readObject().
</action>
<action dev="aherbert" type="update" issue="RNG-76">
"SplitMix64": Added primitive long constructor.
</action>
<action dev="aherbert" type="add" issue="RNG-117">
Additional "XorShiRo" family generators. This adds 4 PlusPlus general purpose variants
of existing generators and 3 variants of a large state (1024-bit) generator.
</action>
<action dev="aherbert" type="update" issue="RNG-119">
Add LongJumpable support to XoShiRo generators previously only supporting Jumpable.
</action>
<action dev="aherbert" type="add" issue="RNG-117">
"RandomSource": Support creating a byte[] seed suitable for the implementing
generator class.
</action>
<action dev="aherbert" type="add" issue="RNG-116">
"RandomSource": Expose interfaces supported by the implementing generator class
with methods isJumpable() and isLongJumpable().
</action>
<action dev="aherbert" type="add" issue="RNG-111">
New "JenkinsSmallFast32" and "JenkinsSmallFast64" generators.
</action>
<action dev="aherbert" type="update" issue="RNG-114">
"ListSampler": Select the shuffle algorithm based on the list type. This improves
performance for non-RandomAccess lists such as LinkedList.
</action>
<action dev="aherbert" type="add" issue="RNG-19">
"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.
</action>
<action dev="aherbert" type="fix" issue="RNG-115">
"JDKRandom": Fixed the restore state method to function when the instance has not
previously been used to save state.
</action>
<action dev="aherbert" type="add" issue="RNG-112">
New "DotyHumphreySmallFastCounting32" and "DotyHumphreySmallFastCounting64" generators.
</action>
<action dev="aherbert" type="update" issue="RNG-109">
"DiscreteProbabilityCollectionSampler": Use a faster enumerated probability
distribution sampler to replace the binary search algorithm.
</action>
<action dev="aherbert" type="add" issue="RNG-85">
New "MiddleSquareWeylSequence" generator.
</action>
<action dev="aherbert" type="update" issue="RNG-90">
"BaseProvider": Updated to use faster algorithm for nextInt(int).
</action>
<action dev="aherbert" type="update" issue="RNG-95">
"DiscreteUniformSampler": Updated to use faster algorithms for generation of ranges.
</action>
<action dev="aherbert" type="add" issue="RNG-110">
Factory methods for Discrete and Continuous distribution samplers. The factory method
can choose the optimal implementation for the distribution parameters.
</action>
<action dev="aherbert" type="add" issue="RNG-84" due-to="Abhishek Singh Dhadwal">
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.
</action>
<action dev="aherbert" type="add" issue="RNG-102">
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.
</action>
<action dev="aherbert" type="add" issue="RNG-108">
Update "SeedFactory" to improve performance.
</action>
<action dev="aherbert" type="add" issue="RNG-99">
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.
</action>
<action dev="aherbert" type="add" issue="RNG-100">
New "GuideTableDiscreteSampler" that can sample from any discrete distribution defined
by an array of probabilities.
</action>
<action dev="aherbert" type="update" issue="RNG-106">
Ensure SeedFactory produces non-zero seed arrays. This avoids invalid seeding of
generators that cannot recover from a seed of zeros.
</action>
<action dev="aherbert" type="add" issue="RNG-98">
New "LongJumpableUniformRandomProvider" interface extends JumpableUniformRandomProvider
with a long jump method.
</action>
<action dev="aherbert" type="add" issue="RNG-97">
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.
</action>
<action dev="aherbert" type="update" issue="RNG-103">
"LargeMeanPoissonSampler: Switch from SmallMeanPoissonSampler to use
KempSmallMeanPoissonSampler for the fractional mean sample.
</action>
<action dev="aherbert" type="update" issue="RNG-75">
"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.
</action>
<action dev="aherbert" type="update" issue="RNG-77">
"NumberFactory": Improve performance of int and long array to/from byte array
conversions.
</action>
<action dev="aherbert" type="add" issue="RNG-101">
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.
</action>
<action dev="aherbert" type="fix" issue="RNG-96">
"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.
</action>
<action dev="aherbert" type="add" issue="RNG-91">
New "KempSmallMeanPoissonSampler" that provides Poisson samples using only 1 random
deviate per sample. This algorithm outperforms the SmallMeanPoissonSampler
when the generator is slow.
</action>
<action dev="aherbert" type="fix" issue="RNG-93">
"SmallMeanPoissonSampler": Requires the Poisson probability for p(x=0) to be positive
setting an upper bound on the mean of approximately 744.44.
</action>
<action dev="aherbert" type="fix" issue="RNG-92">
"LargeMeanPoissonSampler": Requires mean >= 1.
</action>
<action dev="aherbert" type="add" issue="RNG-70">
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.
</action>
<action dev="aherbert" type="update" issue="RNG-88">
Update the generation performance JMH benchmarks to have a reference baseline.
</action>
<action dev="aherbert" type="update" issue="RNG-87">
"MultiplyWithCarry256": Performance improvement by advancing state one step per sample.
</action>
<action dev="aherbert" type="add" issue="RNG-82">
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.
</action>
<action dev="aherbert" type="add" issue="RNG-78">
New "ThreadLocalRandomSource" class provides thread safe access to random generators.
</action>
<action dev="aherbert" type="update" issue="RNG-81">
"NumberFactory": Evenly sample all dyadic rationals between 0 and 1.
</action>
<action dev="aherbert" type="add" issue="RNG-79">
Benchmark methods for producing nextDouble and nextFloat.
</action>
<action dev="aherbert" type="update" issue="RNG-73">
Add the methods used from UniformRandomProvider to each sampler in the sampling module.
</action>
<action dev="aherbert" type="update" issue="RNG-74">
"DiscreteUniformSampler": Algorithms for small and large integer ranges have
been delegated to specialised classes.
</action>
<action dev="aherbert" type="add" issue="RNG-72">
Add new JMH benchmark ConstructionPerformance.
</action>
<action dev="aherbert" type="add" issue="RNG-71">
Validate parameters for the distribution samplers.
</action>
<action dev="aherbert" type="update" issue="RNG-68">
"AhrensDieterMarsagliaTsangGammaSampler": Algorithms for small and large theta have
been delegated to specialised classes.
</action>
<action dev="aherbert" type="add" issue="RNG-67">
Instructions for how to build and run the examples-stress code.
</action>
<action dev="aherbert" type="add" issue="RNG-69">
New "GeometricSampler" class.
</action>
</release>
<release version="1.2" date="2018-12-12" description="
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).
">
<action dev="erans" type="update" issue="RNG-63">
"NumberFactory": Some methods have become obsolete following RNG-57.
</action>
<action dev="erans" type="update" issue="RNG-64" due-to="Alex D. Herbert">
"PermutationSampler" and "CombinationSampler" shared code moved to a utility class.
</action>
<action dev="erans" type="add" issue="RNG-62" due-to="Alex D. Herbert">
New "CombinationSampler" class.
</action>
<action dev="erans" type="update" issue="RNG-61" due-to="Alex D. Herbert">
"PermutationSampler": Performance improvement.
</action>
<action dev="erans" type="update" issue="RNG-57" due-to="Alex D. Herbert">
Cache for using up all the bits provided by the underlying source of randomness.
</action>
<action dev="erans" type="update" issue="RNG-60">
Use random seeds for unit testing.
</action>
<action dev="erans" type="update" issue="RNG-52">
Set conservative upper bound in "LargePoissonSampler" to avoid truncation.
</action>
<action dev="erans" type="fix" issue="RNG-59">
Use JDK's "SecureRandom" to seed the "SeedFactory".
</action>
<action dev="erans" type="update" issue="RNG-58">
Allow part of RNG state to be contained in base classes, e.g. to enable
caching in common code (see RNG-57).
</action>
<action dev="erans" type="update" issue="RNG-51" due-to="Alex D. Herbert">
"PoissonSampler": Performance improvement.
</action>
<action dev="erans" type="fix" issue="RNG-56">
"ZigguratNormalizedGaussianSampler": Missing statements in least used branch.
</action>
<action dev="erans" type="fix" issue="RNG-55" due-to="Alex D. Herbert">
"UnitSphereSampler": Prevent returning NaN components and forbid
negative dimension.
</action>
</release>
<release version="1.1" date="2018-08-14" description="
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).
">
<action dev="erans" type="fix" issue="RNG-53">
Class "SamplerBase" has been deprecated. It was meant for internal use
only but, through inheritance, it allows incorrect usage of the sampler
classes.
</action>
<action dev="erans" type="update" issue="RNG-50" due-to="Alex D. Herbert">
"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.
</action>
<action dev="erans" type="add" issue="RNG-37">
Implementation of the "Ziggurat" algorithm for Gaussian sampling.
</action>
<action dev="erans" type="update" issue="RNG-42">
Use "ZigguratNormalizedGaussianSampler" within the library.
</action>
<action dev="erans" type="add" issue="RNG-47">
"DiscreteProbabilityCollectionSampler": Sampling from a collection of items
with user-defined probabilities (feature ported from "Commons Math").
</action>
<action dev="erans" type="add" issue="RNG-43">
"LogNormalSampler" with user-defined underlying "NormalizedGaussianSampler".
</action>
<action dev="erans" type="update" issue="RNG-46">
Following RNG-43, "BoxMullerLogNormalSampler" has been deprecated.
</action>
<action dev="erans" type="add" issue="RNG-39">
"UnitSphereSampler": generate random vectors isotropically located
on the surface of a sphere (feature ported from "Commons Math").
</action>
<action dev="erans" type="add" issue="RNG-36">
"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).
</action>
<action dev="erans" type="add" issue="RNG-35">
New generic "GaussianSampler" based on "NormalizedGaussianSampler"
marker interface.
Implementation of "BoxMullerNormalizedGaussianSampler" deprecates
"BoxMullerGaussianSampler".
</action>
</release>
<release version="1.0" date="2016-12-13" description="
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>
</body>
</document>