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 2019/03/25 12:08:39 UTC
[commons-rng] 02/04: RNG-82: Mark XOR_SHIFT_1024_S deprecated.
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 55c8c42b6818f1b813f29b785713b75a87302c2d
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Tue Mar 19 21:28:44 2019 +0000
RNG-82: Mark XOR_SHIFT_1024_S deprecated.
---
.../rng/core/source64/XorShift1024Star.java | 9 ++++----
.../rng/core/source64/XorShift1024StarPhi.java | 12 +++++-----
.../apache/commons/rng/simple/RandomSource.java | 26 ++++++++++++++--------
.../rng/simple/internal/ProviderBuilder.java | 9 ++++----
4 files changed, 34 insertions(+), 22 deletions(-)
diff --git a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/XorShift1024Star.java b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/XorShift1024Star.java
index c3557d0..2a871e6 100644
--- a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/XorShift1024Star.java
+++ b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/XorShift1024Star.java
@@ -23,6 +23,9 @@ import org.apache.commons.rng.core.util.NumberFactory;
/**
* A fast RNG implementing the {@code XorShift1024*} algorithm.
*
+ * <p>Note: This has been superseded by {@link XorShift1024StarPhi}. The sequences emitted
+ * by both generators are correlated.</p>
+ *
* @see <a href="http://xorshift.di.unimi.it/xorshift1024star.c">Original source code</a>
* @see <a href="https://en.wikipedia.org/wiki/Xorshift">Xorshift (Wikipedia)</a>
* @since 1.0
@@ -43,8 +46,7 @@ public class XorShift1024Star extends LongProvider {
* @param seed Initial seed.
* If the length is larger than 16, only the first 16 elements will
* be used; if smaller, the remaining elements will be automatically
- * set.
- * A seed containing all zeros will create a non-functional generator.
+ * set. A seed containing all zeros will create a non-functional generator.
*/
public XorShift1024Star(long[] seed) {
this(1181783497276652981L, seed);
@@ -57,8 +59,7 @@ public class XorShift1024Star extends LongProvider {
* @param seed Initial seed.
* If the length is larger than 16, only the first 16 elements will
* be used; if smaller, the remaining elements will be automatically
- * set.
- * A seed containing all zeros will create a non-functional generator.
+ * set. A seed containing all zeros will create a non-functional generator.
*/
protected XorShift1024Star(long multiplier, long[] seed) {
this.multiplier = multiplier;
diff --git a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/XorShift1024StarPhi.java b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/XorShift1024StarPhi.java
index 710dd6c..b8d60f8 100644
--- a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/XorShift1024StarPhi.java
+++ b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/XorShift1024StarPhi.java
@@ -20,9 +20,12 @@ package org.apache.commons.rng.core.source64;
/**
* A fast RNG implementing the {@code XorShift1024*} algorithm.
*
- * <p>This supersedes {@link XorShift1024Star}. The generator differs only in the multiplier (a
- * fixed-point representation of the golden ratio), which eliminates linear dependencies from one of
- * the lowest bits.
+ * <p>Note: This supersedes {@link XorShift1024Star}. The sequences emitted by both
+ * generators are correlated.</p>
+ *
+ * <p>This generator differs only in the final multiplier (a fixed-point representation
+ * of the golden ratio), which eliminates linear dependencies from one of the lowest
+ * bits.</p>
*
* @see <a href="http://xorshift.di.unimi.it/xorshift1024star.c">Original source code</a>
* @see <a href="https://en.wikipedia.org/wiki/Xorshift">Xorshift (Wikipedia)</a>
@@ -35,8 +38,7 @@ public class XorShift1024StarPhi extends XorShift1024Star {
* @param seed Initial seed.
* If the length is larger than 16, only the first 16 elements will
* be used; if smaller, the remaining elements will be automatically
- * set.
- * A seed containing all zeros will create a non-functional generator.
+ * set. A seed containing all zeros will create a non-functional generator.
*/
public XorShift1024StarPhi(long[] seed) {
super(0x9e3779b97f4a7c13L, seed);
diff --git a/commons-rng-simple/src/main/java/org/apache/commons/rng/simple/RandomSource.java b/commons-rng-simple/src/main/java/org/apache/commons/rng/simple/RandomSource.java
index f2a9bd5..35c847a 100644
--- a/commons-rng-simple/src/main/java/org/apache/commons/rng/simple/RandomSource.java
+++ b/commons-rng-simple/src/main/java/org/apache/commons/rng/simple/RandomSource.java
@@ -243,17 +243,16 @@ public enum RandomSource {
* <li>Native seed type: {@code long[]}.</li>
* <li>Native seed size: 16.</li>
* </ul>
+ *
+ * @deprecated Since 1.3, where it is recommended to use {@code XOR_SHIFT_1024_S_PHI}
+ * instead due to its slightly better (more uniform) output. {@code XOR_SHIFT_1024_S}
+ * is still quite usable but both are variants of the same algorithm and maintain their
+ * internal state identically. Their outputs are correlated and the two should not be
+ * used together when independent sequences are assumed.
*/
+ @Deprecated
XOR_SHIFT_1024_S(ProviderBuilder.RandomSourceInternal.XOR_SHIFT_1024_S),
/**
- * Source of randomness is {@link org.apache.commons.rng.core.source64.XorShift1024StarPhi}.
- * <ul>
- * <li>Native seed type: {@code long[]}.</li>
- * <li>Native seed size: 16.</li>
- * </ul>
- */
- XOR_SHIFT_1024_S_PHI(ProviderBuilder.RandomSourceInternal.XOR_SHIFT_1024_S_PHI),
- /**
* Source of randomness is {@link org.apache.commons.rng.core.source64.TwoCmres}.
* This generator is equivalent to {@link #TWO_CMRES_SELECT} with the choice of the
* pair {@code (0, 1)} for the two subcycle generators.
@@ -299,7 +298,16 @@ public enum RandomSource {
* <li>Native seed size: 4.</li>
* </ul>
*/
- KISS(ProviderBuilder.RandomSourceInternal.KISS);
+ KISS(ProviderBuilder.RandomSourceInternal.KISS),
+ /**
+ * Source of randomness is {@link org.apache.commons.rng.core.source64.XorShift1024StarPhi}.
+ * <ul>
+ * <li>Native seed type: {@code long[]}.</li>
+ * <li>Native seed size: 16.</li>
+ * </ul>
+ */
+ XOR_SHIFT_1024_S_PHI(ProviderBuilder.RandomSourceInternal.XOR_SHIFT_1024_S_PHI),
+ ;
/** Internal identifier. */
private final ProviderBuilder.RandomSourceInternal internalIdentifier;
diff --git a/commons-rng-simple/src/main/java/org/apache/commons/rng/simple/internal/ProviderBuilder.java b/commons-rng-simple/src/main/java/org/apache/commons/rng/simple/internal/ProviderBuilder.java
index e3a540e..059bb03 100644
--- a/commons-rng-simple/src/main/java/org/apache/commons/rng/simple/internal/ProviderBuilder.java
+++ b/commons-rng-simple/src/main/java/org/apache/commons/rng/simple/internal/ProviderBuilder.java
@@ -291,9 +291,6 @@ public final class ProviderBuilder {
/** Source of randomness is {@link XorShift1024Star}. */
XOR_SHIFT_1024_S(XorShift1024Star.class,
long[].class),
- /** Source of randomness is {@link XorShift1024StarPhi}. */
- XOR_SHIFT_1024_S_PHI(XorShift1024StarPhi.class,
- long[].class),
/** Source of randomness is {@link TwoCmres}. */
TWO_CMRES(TwoCmres.class,
Integer.class),
@@ -313,7 +310,11 @@ public final class ProviderBuilder {
int[].class),
/** Source of randomness is {@link KISSRandom}. */
KISS(KISSRandom.class,
- int[].class);
+ int[].class),
+ /** Source of randomness is {@link XorShift1024StarPhi}. */
+ XOR_SHIFT_1024_S_PHI(XorShift1024StarPhi.class,
+ long[].class),
+ ;
/** Source type. */
private final Class<? extends UniformRandomProvider> rng;