You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ah...@apache.org on 2022/10/10 12:53:23 UTC
[commons-rng] 01/10: Updated project documentation following release of version 1.5
This is an automated email from the ASF dual-hosted git repository.
aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-rng.git
commit 4b0cd5138c627ceeb422a49a08efae09e5092ef5
Author: aherbert <ah...@apache.org>
AuthorDate: Mon Oct 10 11:23:13 2022 +0100
Updated project documentation following release of version 1.5
---
RELEASE-NOTES.txt | 111 +++++++++++++++++++++
commons-rng-client-api/src/site/site.xml | 2 +
commons-rng-core/src/site/site.xml | 2 +
commons-rng-sampling/src/site/site.xml | 2 +
commons-rng-simple/src/site/site.xml | 2 +
src/changes/changes.xml | 21 ++--
.../resources/release-notes/RELEASE-NOTES-1.5.txt | 111 +++++++++++++++++++++
src/site/xdoc/download_rng.xml | 26 ++---
8 files changed, 257 insertions(+), 20 deletions(-)
diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt
index 3e5b3a74..ea2338d9 100644
--- a/RELEASE-NOTES.txt
+++ b/RELEASE-NOTES.txt
@@ -1,4 +1,115 @@
+ Apache Commons RNG 1.5 RELEASE NOTES
+
+The Apache Commons RNG team is pleased to announce the release of Apache Commons RNG 1.5
+
+The Apache Commons RNG project provides pure-Java implementation of pseudo-random generators.
+
+This is a minor release of Apache Commons RNG, containing a
+few new features and performance improvements.
+
+Apache Commons RNG 1.5 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).
+
+The source output type (int/long) of a RNG must maintain behavioural compatibility
+between releases; derived types may break behavioural compatibility. Any functional
+changes will be recorded in the release notes.
+
+Changes in this version include:
+
+New features:
+o RNG-182: 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.
+o RNG-181: LXM family to support SplittableUniformRandomProvider. This allows creating a parallel
+ stream of generators which will avoid sequence correlations between instances.
+o RNG-180: 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.
+o RNG-179: "FastLoadedDiceRollerDiscreteSampler": Distribution sampler that uses the
+ Fast Loaded Dice Roller (FLDR) algorithm for exact sampling from a discrete
+ probability distribution.
+o RNG-178: "JumpableUniformRandomProvider": Add support to generate Java 8 streams of new
+ random generator instances using the jump method.
+o RNG-176: "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.
+o RNG-177: "sampling": Add samples() method to the API to generate Java 8 streams of sample values.
+o RNG-168: New LXM family of random generators. Added implementations of the LXM generators
+ included in JDK 17.
+o RNG-174: "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.
+o RNG-173: "BaseProvider": Add a static method to extend input int[] and long[] seeds to a
+ minimum length.
+o RNG-167: New "TSampler" class to sample from Student's t-distribution.
+
+Fixed Bugs:
+o RNG-175: "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.
+o RNG-170: Update implementations of "UniformRandomProvider.nextBytes" with a range
+ [start, start + length) to be consistent with the exception conditions of the
+ JDK array range checks.
+o RNG-166: Update "LogNormalSampler" and "BoxMullerLogNormalSampler" to allow a negative mean for
+ the natural logarithm of the distribution values.
+o RNG-165: "RejectionInversionZipfSampler": Allow a zero exponent in the Zipf sampler.
+
+Changes:
+o RNG-171: 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).
+o RNG-172: "UniformLongSampler": Precompute rejection threshold for a non-power of 2 range.
+o RNG-169: "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.
+o RNG-160: "ZigguratSampler": Performance improvement using ternary operator to sort values.
+
+
+For complete information on Apache Commons RNG, including instructions on how to submit bug reports,
+patches, or suggestions for improvement, see the Apache Commons RNG website:
+
+https://commons.apache.org/proper/commons-rng/
+
+
+=============================================================================
+
Apache Commons RNG 1.4 RELEASE NOTES
The Apache Commons RNG team is pleased to announce the release of Apache Commons RNG 1.4
diff --git a/commons-rng-client-api/src/site/site.xml b/commons-rng-client-api/src/site/site.xml
index ac31a360..c972543a 100644
--- a/commons-rng-client-api/src/site/site.xml
+++ b/commons-rng-client-api/src/site/site.xml
@@ -28,6 +28,8 @@
<item name="Overview" href="index.html"/>
<item name="Latest API docs (development)"
href="apidocs/index.html"/>
+ <item name="Javadoc (1.5 release)"
+ href="https://commons.apache.org/rng/commons-rng-client-api/javadocs/api-1.5/index.html"/>
<item name="Javadoc (1.4 release)"
href="https://commons.apache.org/rng/commons-rng-client-api/javadocs/api-1.4/index.html"/>
<item name="Javadoc (1.3 release)"
diff --git a/commons-rng-core/src/site/site.xml b/commons-rng-core/src/site/site.xml
index ea92b395..7e4b032f 100644
--- a/commons-rng-core/src/site/site.xml
+++ b/commons-rng-core/src/site/site.xml
@@ -28,6 +28,8 @@
<item name="Overview" href="index.html"/>
<item name="Latest API docs (development)"
href="apidocs/index.html"/>
+ <item name="Javadoc (1.5 release)"
+ href="https://commons.apache.org/rng/commons-rng-core/javadocs/api-1.5/index.html"/>
<item name="Javadoc (1.4 release)"
href="https://commons.apache.org/rng/commons-rng-core/javadocs/api-1.4/index.html"/>
<item name="Javadoc (1.3 release)"
diff --git a/commons-rng-sampling/src/site/site.xml b/commons-rng-sampling/src/site/site.xml
index 6ab2ed68..d5f96050 100644
--- a/commons-rng-sampling/src/site/site.xml
+++ b/commons-rng-sampling/src/site/site.xml
@@ -28,6 +28,8 @@
<item name="Overview" href="index.html"/>
<item name="Latest API docs (development)"
href="apidocs/index.html"/>
+ <item name="Javadoc (1.5 release)"
+ href="https://commons.apache.org/rng/commons-rng-sampling/javadocs/api-1.5/index.html"/>
<item name="Javadoc (1.4 release)"
href="https://commons.apache.org/rng/commons-rng-sampling/javadocs/api-1.4/index.html"/>
<item name="Javadoc (1.3 release)"
diff --git a/commons-rng-simple/src/site/site.xml b/commons-rng-simple/src/site/site.xml
index 43d021ad..0aac3169 100644
--- a/commons-rng-simple/src/site/site.xml
+++ b/commons-rng-simple/src/site/site.xml
@@ -28,6 +28,8 @@
<item name="Overview" href="index.html"/>
<item name="Latest API docs (development)"
href="apidocs/index.html"/>
+ <item name="Javadoc (1.5 release)"
+ href="https://commons.apache.org/rng/commons-rng-simple/javadocs/api-1.5/index.html"/>
<item name="Javadoc (1.4 release)"
href="https://commons.apache.org/rng/commons-rng-simple/javadocs/api-1.4/index.html"/>
<item name="Javadoc (1.3 release)"
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index f51271fb..cdc44f97 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -53,7 +53,13 @@ If the output is not quite correct, check for invisible trailing spaces!
</properties>
<body>
- <release version="1.5" date="TBD" description="
+ <release version="1.6" date="TBD" description="
+This is a minor release of Apache Commons RNG, containing a
+few new features and performance improvements (requires Java 8).
+">
+</release>
+
+ <release version="1.5" date="2022-09-10" description="
This is a minor release of Apache Commons RNG, containing a
few new features and performance improvements.
Apache Commons RNG 1.5 contains the following library modules:
@@ -113,10 +119,10 @@ will be recorded in the release notes.
<action dev="aherbert" type="add" issue="RNG-176">
"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.
+ 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.
</action>
<action dev="aherbert" type="add" issue="RNG-177">
"sampling": Add samples() method to the API to generate Java 8 streams of sample values.
@@ -128,8 +134,9 @@ will be recorded in the release notes.
<action dev="aherbert" type="add" issue="RNG-174">
"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.
+ 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.
</action>
<action dev="aherbert" type="fix" issue="RNG-175">
"RandomSource.MSWS": createSeed(UniformRandomProvider) to handle a bad RNG.
diff --git a/RELEASE-NOTES.txt b/src/site/resources/release-notes/RELEASE-NOTES-1.5.txt
similarity index 76%
copy from RELEASE-NOTES.txt
copy to src/site/resources/release-notes/RELEASE-NOTES-1.5.txt
index 3e5b3a74..ea2338d9 100644
--- a/RELEASE-NOTES.txt
+++ b/src/site/resources/release-notes/RELEASE-NOTES-1.5.txt
@@ -1,4 +1,115 @@
+ Apache Commons RNG 1.5 RELEASE NOTES
+
+The Apache Commons RNG team is pleased to announce the release of Apache Commons RNG 1.5
+
+The Apache Commons RNG project provides pure-Java implementation of pseudo-random generators.
+
+This is a minor release of Apache Commons RNG, containing a
+few new features and performance improvements.
+
+Apache Commons RNG 1.5 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).
+
+The source output type (int/long) of a RNG must maintain behavioural compatibility
+between releases; derived types may break behavioural compatibility. Any functional
+changes will be recorded in the release notes.
+
+Changes in this version include:
+
+New features:
+o RNG-182: 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.
+o RNG-181: LXM family to support SplittableUniformRandomProvider. This allows creating a parallel
+ stream of generators which will avoid sequence correlations between instances.
+o RNG-180: 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.
+o RNG-179: "FastLoadedDiceRollerDiscreteSampler": Distribution sampler that uses the
+ Fast Loaded Dice Roller (FLDR) algorithm for exact sampling from a discrete
+ probability distribution.
+o RNG-178: "JumpableUniformRandomProvider": Add support to generate Java 8 streams of new
+ random generator instances using the jump method.
+o RNG-176: "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.
+o RNG-177: "sampling": Add samples() method to the API to generate Java 8 streams of sample values.
+o RNG-168: New LXM family of random generators. Added implementations of the LXM generators
+ included in JDK 17.
+o RNG-174: "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.
+o RNG-173: "BaseProvider": Add a static method to extend input int[] and long[] seeds to a
+ minimum length.
+o RNG-167: New "TSampler" class to sample from Student's t-distribution.
+
+Fixed Bugs:
+o RNG-175: "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.
+o RNG-170: Update implementations of "UniformRandomProvider.nextBytes" with a range
+ [start, start + length) to be consistent with the exception conditions of the
+ JDK array range checks.
+o RNG-166: Update "LogNormalSampler" and "BoxMullerLogNormalSampler" to allow a negative mean for
+ the natural logarithm of the distribution values.
+o RNG-165: "RejectionInversionZipfSampler": Allow a zero exponent in the Zipf sampler.
+
+Changes:
+o RNG-171: 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).
+o RNG-172: "UniformLongSampler": Precompute rejection threshold for a non-power of 2 range.
+o RNG-169: "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.
+o RNG-160: "ZigguratSampler": Performance improvement using ternary operator to sort values.
+
+
+For complete information on Apache Commons RNG, including instructions on how to submit bug reports,
+patches, or suggestions for improvement, see the Apache Commons RNG website:
+
+https://commons.apache.org/proper/commons-rng/
+
+
+=============================================================================
+
Apache Commons RNG 1.4 RELEASE NOTES
The Apache Commons RNG team is pleased to announce the release of Apache Commons RNG 1.4
diff --git a/src/site/xdoc/download_rng.xml b/src/site/xdoc/download_rng.xml
index cf764a20..842a66a6 100644
--- a/src/site/xdoc/download_rng.xml
+++ b/src/site/xdoc/download_rng.xml
@@ -113,32 +113,32 @@ limitations under the License.
</p>
</subsection>
</section>
- <section name="Apache Commons RNG 1.4 (requires Java 8+)">
+ <section name="Apache Commons RNG 1.5 (requires Java 8+)">
<subsection name="Binaries">
<table>
<tr>
- <td><a href="[preferred]/commons/rng/binaries/commons-rng-1.4-bin.tar.gz">commons-rng-1.4-bin.tar.gz</a></td>
- <td><a href="https://www.apache.org/dist/commons/rng/binaries/commons-rng-1.4-bin.tar.gz.sha512">sha512</a></td>
- <td><a href="https://www.apache.org/dist/commons/rng/binaries/commons-rng-1.4-bin.tar.gz.asc">pgp</a></td>
+ <td><a href="[preferred]/commons/rng/binaries/commons-rng-1.5-bin.tar.gz">commons-rng-1.5-bin.tar.gz</a></td>
+ <td><a href="https://www.apache.org/dist/commons/rng/binaries/commons-rng-1.5-bin.tar.gz.sha512">sha512</a></td>
+ <td><a href="https://www.apache.org/dist/commons/rng/binaries/commons-rng-1.5-bin.tar.gz.asc">pgp</a></td>
</tr>
<tr>
- <td><a href="[preferred]/commons/rng/binaries/commons-rng-1.4-bin.zip">commons-rng-1.4-bin.zip</a></td>
- <td><a href="https://www.apache.org/dist/commons/rng/binaries/commons-rng-1.4-bin.zip.sha512">sha512</a></td>
- <td><a href="https://www.apache.org/dist/commons/rng/binaries/commons-rng-1.4-bin.zip.asc">pgp</a></td>
+ <td><a href="[preferred]/commons/rng/binaries/commons-rng-1.5-bin.zip">commons-rng-1.5-bin.zip</a></td>
+ <td><a href="https://www.apache.org/dist/commons/rng/binaries/commons-rng-1.5-bin.zip.sha512">sha512</a></td>
+ <td><a href="https://www.apache.org/dist/commons/rng/binaries/commons-rng-1.5-bin.zip.asc">pgp</a></td>
</tr>
</table>
</subsection>
<subsection name="Source">
<table>
<tr>
- <td><a href="[preferred]/commons/rng/source/commons-rng-1.4-src.tar.gz">commons-rng-1.4-src.tar.gz</a></td>
- <td><a href="https://www.apache.org/dist/commons/rng/source/commons-rng-1.4-src.tar.gz.sha512">sha512</a></td>
- <td><a href="https://www.apache.org/dist/commons/rng/source/commons-rng-1.4-src.tar.gz.asc">pgp</a></td>
+ <td><a href="[preferred]/commons/rng/source/commons-rng-1.5-src.tar.gz">commons-rng-1.5-src.tar.gz</a></td>
+ <td><a href="https://www.apache.org/dist/commons/rng/source/commons-rng-1.5-src.tar.gz.sha512">sha512</a></td>
+ <td><a href="https://www.apache.org/dist/commons/rng/source/commons-rng-1.5-src.tar.gz.asc">pgp</a></td>
</tr>
<tr>
- <td><a href="[preferred]/commons/rng/source/commons-rng-1.4-src.zip">commons-rng-1.4-src.zip</a></td>
- <td><a href="https://www.apache.org/dist/commons/rng/source/commons-rng-1.4-src.zip.sha512">sha512</a></td>
- <td><a href="https://www.apache.org/dist/commons/rng/source/commons-rng-1.4-src.zip.asc">pgp</a></td>
+ <td><a href="[preferred]/commons/rng/source/commons-rng-1.5-src.zip">commons-rng-1.5-src.zip</a></td>
+ <td><a href="https://www.apache.org/dist/commons/rng/source/commons-rng-1.5-src.zip.sha512">sha512</a></td>
+ <td><a href="https://www.apache.org/dist/commons/rng/source/commons-rng-1.5-src.zip.asc">pgp</a></td>
</tr>
</table>
</subsection>