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 d93b5934799158e92fa70619eec8201e079dc4a2
Author: aherbert <aherb...@apache.org>
AuthorDate: Tue Jul 30 15:57:55 2019 +0100
Revise javadoc for new PCG family of generators.
This updates the javadoc to be consistent with other code in the same
package.
Contains no code changes.
---
.../commons/rng/core/source32/AbstractPcg6432.java | 34 +++++++++++++---------
.../rng/core/source32/AbstractPcgMcg6432.java | 28 +++++++++++-------
.../commons/rng/core/source32/PcgMcgXshRr32.java | 7 +++--
.../commons/rng/core/source32/PcgMcgXshRs32.java | 7 +++--
.../commons/rng/core/source32/PcgXshRr32.java | 7 +++--
.../commons/rng/core/source32/PcgXshRs32.java | 7 +++--
.../commons/rng/core/source64/PcgRxsMXs64.java | 33 ++++++++++++---------
.../commons/rng/core/source32/PcgXshRr32Test.java | 4 ++-
.../commons/rng/core/source32/PcgXshRs32Test.java | 4 ++-
.../commons/rng/core/source64/PcgRxsMXs64Test.java | 4 ++-
10 files changed, 83 insertions(+), 52 deletions(-)
diff --git
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/AbstractPcg6432.java
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/AbstractPcg6432.java
index 4b7e193..3a592ee 100644
---
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/AbstractPcg6432.java
+++
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/AbstractPcg6432.java
@@ -17,9 +17,11 @@
package org.apache.commons.rng.core.source32;
import org.apache.commons.rng.core.util.NumberFactory;
+
/**
- * This class aids in implementation of the PCG suite of generators, a family
of
- * simple fast space-efficient statistically good algorithms for random number
generation.
+ * This abstract class is a base for algorithms from the Permuted Congruential
Generator (PCG)
+ * family that use an internal 64-bit Linear Congruential Generator (LCG) and
output 32-bits
+ * per cycle.
*
* @see <a href="http://www.pcg-random.org/";>
* PCG, A Family of Better Random Number Generators</a>
@@ -29,10 +31,10 @@ abstract class AbstractPcg6432 extends IntProvider {
/** Size of the seed array. */
private static final int SEED_SIZE = 2;
- /** Displays the current state. */
+ /** The state of the LCG. */
private long state;
- /** Used as a part of the LCG. */
+ /** The increment of the LCG. */
private long increment;
/**
@@ -53,19 +55,21 @@ abstract class AbstractPcg6432 extends IntProvider {
}
/**
- * Modifies input parameters into current state.
- * @param seed the new seed.
+ * Seeds the RNG.
+ *
+ * @param seed Seed.
*/
private void setSeedInternal(long[] seed) {
- // Ensuring that the increment is odd to provide a maximal period LCG.
+ // Ensure the increment is odd to provide a maximal period LCG.
this.increment = (seed[1] << 1) | 1;
this.state = bump(seed[0] + this.increment);
}
/**
* Provides the next state of the LCG.
- * @param input - The previous state of the generator.
- * @return Next state of the LCG.
+ *
+ * @param input Current state.
+ * @return next state
*/
private long bump(long input) {
return input * 6364136223846793005L + increment;
@@ -80,17 +84,20 @@ abstract class AbstractPcg6432 extends IntProvider {
}
/**
+ * Transform the 64-bit state of the generator to a 32-bit output.
* The transformation function shall vary with respect to different
generators.
- * @param x The input.
- * @return The output of the generator.
+ *
+ * @param x State.
+ * @return the output
*/
protected abstract int transform(long x);
/** {@inheritDoc} */
@Override
protected byte[] getStateInternal() {
- /*This transform is used in the reference PCG code; it prevents
restoring from
- a byte state a non-odd increment that results in a sub-maximal period
generator.*/
+ // The increment is divided by 2 before saving.
+ // This transform is used in the reference PCG code; it prevents
restoring from
+ // a byte state a non-odd increment that results in a sub-maximal
period generator.
return composeStateInternal(NumberFactory.makeByteArray(
new long[] {state, increment >>> 1}),
super.getStateInternal());
@@ -102,6 +109,7 @@ abstract class AbstractPcg6432 extends IntProvider {
final byte[][] c = splitStateInternal(s, SEED_SIZE * 8);
final long[] tempseed = NumberFactory.makeLongArray(c[0]);
state = tempseed[0];
+ // Reverse the transform performed during getState to make the
increment odd again.
increment = tempseed[1] << 1 | 1;
super.setStateInternal(c[1]);
}
diff --git
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/AbstractPcgMcg6432.java
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/AbstractPcgMcg6432.java
index 7675307..60c4dae 100644
---
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/AbstractPcgMcg6432.java
+++
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/AbstractPcgMcg6432.java
@@ -17,18 +17,18 @@
package org.apache.commons.rng.core.source32;
import org.apache.commons.rng.core.util.NumberFactory;
+
/**
- * This class aids in implementation of the Multiplicative congruential
generator (MCG)
- * versions of the PCG suite of generators, a family of simple fast
space-efficient statistically
- * good algorithms for random number generation.
+ * This abstract class is a base for algorithms from the Permuted Congruential
Generator (PCG)
+ * family that use an internal 64-bit Multiplicative Congruential Generator
(MCG) and output
+ * 32-bits per cycle.
*
* @see <a href="http://www.pcg-random.org/";>
* PCG, A Family of Better Random Number Generators</a>
* @since 1.3
*/
abstract class AbstractPcgMcg6432 extends IntProvider {
-
- /** Displays the current state. */
+ /** The state of the MCG. */
private long state;
/**
@@ -37,15 +37,20 @@ abstract class AbstractPcgMcg6432 extends IntProvider {
* @param seed Initial seed.
*/
AbstractPcgMcg6432(Long seed) {
+ // A seed of zero will result in a non-functional MCG; it must be odd
for a maximal
+ // period MCG. The multiplication factor always sets the 2
least-significant bits to 1
+ // if they are already 1 so these are explicitly set. Bit k
(zero-based) will have
+ // period 2^(k-1) starting from bit 2 with a period of 1. Bit 63 has
period 2^62.
state = seed | 3;
}
/**
* Provides the next state of the MCG.
- * @param input - The previous state of the generator.
- * @return Next state of the MCG.
+ *
+ * @param input Current state.
+ * @return next state
*/
- private long bump(long input) {
+ private static long bump(long input) {
return input * 6364136223846793005L;
}
@@ -58,9 +63,11 @@ abstract class AbstractPcgMcg6432 extends IntProvider {
}
/**
+ * Transform the 64-bit state of the generator to a 32-bit output.
* The transformation function shall vary with respect to different
generators.
- * @param x The input.
- * @return The output of the generator.
+ *
+ * @param x State.
+ * @return the output
*/
protected abstract int transform(long x);
@@ -75,6 +82,7 @@ abstract class AbstractPcgMcg6432 extends IntProvider {
@Override
protected void setStateInternal(byte[] s) {
final byte[][] d = splitStateInternal(s, 8);
+ // As per the constructor, ensure the lower 2 bits of state are set.
state = NumberFactory.makeLong(d[0]) | 3;
super.setStateInternal(d[1]);
}
diff --git
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgMcgXshRr32.java
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgMcgXshRr32.java
index b2e6a17..95afd64 100644
---
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgMcgXshRr32.java
+++
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgMcgXshRr32.java
@@ -17,10 +17,11 @@
package org.apache.commons.rng.core.source32;
/**
- * A Permutated Congruential Generator (PCG) that is composed of a 64-bit
Multiplicative Congruential
- * Generator (MCG) combined with the XSH-RR (high xorshift, followed by a
random rotate) output
+ * A Permuted Congruential Generator (PCG) that is composed of a 64-bit
Multiplicative Congruential
+ * Generator (MCG) combined with the XSH-RR (xorshift; random rotate) output
* transformation to create 32-bit output.
- * State size is 64 bits and the period is 2<sup>62</sup>.
+ *
+ * <p>State size is 64 bits and the period is 2<sup>62</sup>.</p>
*
* @see <a href="http://www.pcg-random.org/";>
* PCG, A Family of Better Random Number Generators</a>
diff --git
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgMcgXshRs32.java
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgMcgXshRs32.java
index 95cbad8..7ba974a 100644
---
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgMcgXshRs32.java
+++
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgMcgXshRs32.java
@@ -17,10 +17,11 @@
package org.apache.commons.rng.core.source32;
/**
- * A Permutated Congruential Generator (PCG) that uses a 64-bit Multiplicative
Congruential
- * Generator (MCG) combined with the XSH-RS (high xorshift, followed by a
random shift) output
+ * A Permuted Congruential Generator (PCG) that is composed of a 64-bit
Multiplicative Congruential
+ * Generator (MCG) combined with the XSH-RS (xorshift; random shift) output
* transformation to create 32-bit output.
- * State size is 64 bits and the period is 2<sup>62</sup>.
+ *
+ * <p>State size is 64 bits and the period is 2<sup>62</sup>.</p>
*
* @see <a href="http://www.pcg-random.org/";>
* PCG, A Family of Better Random Number Generators</a>
diff --git
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgXshRr32.java
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgXshRr32.java
index 2a4f16a..27c22b3 100644
---
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgXshRr32.java
+++
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgXshRr32.java
@@ -17,10 +17,11 @@
package org.apache.commons.rng.core.source32;
/**
- * A Permutated Congruential Generator (PCG) that is composed of a 64-bit
Linear Congruential
- * Generator (LCG) combined with the XSH-RR (high xorshift, followed by a
random rotate) output
+ * A Permuted Congruential Generator (PCG) that is composed of a 64-bit Linear
Congruential
+ * Generator (LCG) combined with the XSH-RR (xorshift; random rotate) output
* transformation to create 32-bit output.
- * State size is 128 bits and the period is 2<sup>64</sup>.
+ *
+ * <p>State size is 128 bits and the period is 2<sup>64</sup>.</p>
*
* @see <a href="http://www.pcg-random.org/";>
* PCG, A Family of Better Random Number Generators</a>
diff --git
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgXshRs32.java
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgXshRs32.java
index 61c971f..c7ee68a 100644
---
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgXshRs32.java
+++
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source32/PcgXshRs32.java
@@ -17,10 +17,11 @@
package org.apache.commons.rng.core.source32;
/**
- * A Permutated Congruential Generator (PCG) that uses a 64-bit Linear
Congruential
- * Generator (LCG) combined with the XSH-RS (high xorshift, followed by a
random shift) output
+ * A Permuted Congruential Generator (PCG) that is composed of a 64-bit Linear
Congruential
+ * Generator (LCG) combined with the XSH-RS (xorshift; random shift) output
* transformation to create 32-bit output.
- * State size is 128 bits and the period is 2<sup>64</sup>.
+ *
+ * <p>State size is 128 bits and the period is 2<sup>64</sup>.</p>
*
* @see <a href="http://www.pcg-random.org/";>
* PCG, A Family of Better Random Number Generators</a>
diff --git
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/PcgRxsMXs64.java
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/PcgRxsMXs64.java
index 4ae7ed5..3ac9ddd 100644
---
a/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/PcgRxsMXs64.java
+++
b/commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/PcgRxsMXs64.java
@@ -17,25 +17,26 @@
package org.apache.commons.rng.core.source64;
import org.apache.commons.rng.core.util.NumberFactory;
+
/**
- * A Permutated Congruential Generator (PCG) that uses a 64-bit Linear
Congruential Generator
- * (LCG) combined with the RXS-M-XS (random xorshift, multiply, fixed
xorshift) output transformation
- * to create 64-bit output.
- * State size is 128 bits and the period is 2<sup>64</sup>.
+ * A Permuted Congruential Generator (PCG) that is composed of a 64-bit Linear
Congruential
+ * Generator (LCG) combined with the RXS-M-XS (random xorshift; multiply;
xorshift) output
+ * transformation to create 64-bit output.
+ *
+ * <p>State size is 128 bits and the period is 2<sup>64</sup>.</p>
*
* @see <a href="http://www.pcg-random.org/";>
* PCG, A Family of Better Random Number Generators</a>
* @since 1.3
*/
public class PcgRxsMXs64 extends LongProvider {
-
/** Size of the seed array. */
private static final int SEED_SIZE = 2;
- /** Displays the current state. */
+ /** The state of the LCG. */
private long state;
- /** Used as a part of the LCG. */
+ /** The increment of the LCG. */
private long increment;
/**
@@ -56,19 +57,21 @@ public class PcgRxsMXs64 extends LongProvider {
}
/**
- * Modifies input parameters into current state.
- * @param seed the new seed.
+ * Seeds the RNG.
+ *
+ * @param seed Seed.
*/
private void setSeedInternal(long[] seed) {
- // Ensuring that the increment is odd to provide a maximal period LCG.
+ // Ensure the increment is odd to provide a maximal period LCG.
this.increment = (seed[1] << 1) | 1;
this.state = bump(seed[0] + this.increment);
}
/**
* Provides the next state of the LCG.
- * @param input - The previous state of the generator.
- * @return Next state of the LCG.
+ *
+ * @param input Current state.
+ * @return next state
*/
private long bump(long input) {
return input * 6364136223846793005L + increment;
@@ -86,8 +89,9 @@ public class PcgRxsMXs64 extends LongProvider {
/** {@inheritDoc} */
@Override
protected byte[] getStateInternal() {
- /*This transform is used in the reference PCG code; it prevents
restoring from
- a byte state a non-odd increment that results in a sub-maximal period
generator.*/
+ // The increment is divided by 2 before saving.
+ // This transform is used in the reference PCG code; it prevents
restoring from
+ // a byte state a non-odd increment that results in a sub-maximal
period generator.
return composeStateInternal(NumberFactory.makeByteArray(
new long[] {state, increment >>> 1}),
super.getStateInternal());
@@ -99,6 +103,7 @@ public class PcgRxsMXs64 extends LongProvider {
final byte[][] c = splitStateInternal(s, SEED_SIZE * 8);
final long[] tempseed = NumberFactory.makeLongArray(c[0]);
state = tempseed[0];
+ // Reverse the transform performed during getState to make the
increment odd again.
increment = tempseed[1] << 1 | 1;
super.setStateInternal(c[1]);
}
diff --git
a/commons-rng-core/src/test/java/org/apache/commons/rng/core/source32/PcgXshRr32Test.java
b/commons-rng-core/src/test/java/org/apache/commons/rng/core/source32/PcgXshRr32Test.java
index ed2b52f..b744ac1 100644
---
a/commons-rng-core/src/test/java/org/apache/commons/rng/core/source32/PcgXshRr32Test.java
+++
b/commons-rng-core/src/test/java/org/apache/commons/rng/core/source32/PcgXshRr32Test.java
@@ -39,6 +39,8 @@ public class PcgXshRr32Test {
0xe116141a, 0xf465fe45, 0xa95f35bb, 0xf0398d4d,
0xe880af3e, 0xc2951dfd, 0x984ec575, 0x8679addb,
};
- RandomAssert.assertEquals(expectedSequence, new PcgXshRr32(new long[]
{0x012de1babb3c4104L, 0xc8161b4202294965L}));
+ RandomAssert.assertEquals(expectedSequence, new PcgXshRr32(new long[] {
+ 0x012de1babb3c4104L, 0xc8161b4202294965L
+ }));
}
}
diff --git
a/commons-rng-core/src/test/java/org/apache/commons/rng/core/source32/PcgXshRs32Test.java
b/commons-rng-core/src/test/java/org/apache/commons/rng/core/source32/PcgXshRs32Test.java
index e72ca67..1d8ef51 100644
---
a/commons-rng-core/src/test/java/org/apache/commons/rng/core/source32/PcgXshRs32Test.java
+++
b/commons-rng-core/src/test/java/org/apache/commons/rng/core/source32/PcgXshRs32Test.java
@@ -39,6 +39,8 @@ public class PcgXshRs32Test {
0x0a006e21, 0x8cb811b7, 0x5f26c916, 0x3990837f,
0x15f2983d, 0x546ccb4a, 0x4eda8716, 0xb8666a25,
};
- RandomAssert.assertEquals(expectedSequence, new PcgXshRs32(new long[]
{0x012de1babb3c4104L, 0xc8161b4202294965L}));
+ RandomAssert.assertEquals(expectedSequence, new PcgXshRs32(new long[] {
+ 0x012de1babb3c4104L, 0xc8161b4202294965L
+ }));
}
}
diff --git
a/commons-rng-core/src/test/java/org/apache/commons/rng/core/source64/PcgRxsMXs64Test.java
b/commons-rng-core/src/test/java/org/apache/commons/rng/core/source64/PcgRxsMXs64Test.java
index 14149b6..dac1191 100644
---
a/commons-rng-core/src/test/java/org/apache/commons/rng/core/source64/PcgRxsMXs64Test.java
+++
b/commons-rng-core/src/test/java/org/apache/commons/rng/core/source64/PcgRxsMXs64Test.java
@@ -39,6 +39,8 @@ public class PcgRxsMXs64Test {
0x32877df7625ae7b5L, 0xa3dc41742161f87dL, 0x9556e15438c1aca1L,
0xb2c890ac0e32cd37L,
0xf1d53427ff980d09L, 0x0e227593be626d22L, 0x0fcbdacbf19d6ae1L,
0xe425b9f0345bd813L,
};
- RandomAssert.assertEquals(expectedSequence, new PcgRxsMXs64(new long[]
{0x012de1babb3c4104L, 0xc8161b4202294965L}));
+ RandomAssert.assertEquals(expectedSequence, new PcgRxsMXs64(new long[]
{
+ 0x012de1babb3c4104L, 0xc8161b4202294965L
+ }));
}
}
