<?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>
  <properties>
    <title>Apache Commons RNG Release Notes</title>
  </properties>
  <body>

    <release version="1.4" date="TBD" 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 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="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>