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
The following commit(s) were added to refs/heads/master by this push:
new bba61b9 Update javadoc.
bba61b9 is described below
commit bba61b9bb395580cea210d89ca12f8ad71527b2f
Author: aherbert <aherb...@apache.org>
AuthorDate: Tue Sep 7 12:39:11 2021 +0100
Update javadoc.
Correct description of new RandomSource.create(...) method where the
enum defines the concrete implementation, not the first argument to
create.
Move description of parallel applications to a sub-section. Add
description of parallel support from the jumpable generators with a code
example.
---
.../apache/commons/rng/simple/RandomSource.java | 42 ++++++++++++++++------
1 file changed, 31 insertions(+), 11 deletions(-)
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 ad41ddc..e656b54 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
@@ -38,8 +38,8 @@ import org.apache.commons.rng.simple.internal.SeedFactory;
* final int[] seed = RandomSource.createIntArray(256);
* UniformRandomProvider rng = RandomSource.MT.create(seed);
* </code></pre>
- * where the first argument to method {@code create} is the identifier
- * of the generator's concrete implementation, and the second the is the
+ * where the enum value is the identifier of the generator's concrete
+ * implementation, and the argument to method {@code create} is the
* (optional) seed.
*
* <p>
@@ -48,6 +48,7 @@ import org.apache.commons.rng.simple.internal.SeedFactory;
* is explicitly generated in the third form.
* </p>
*
+ * <h2>Seeding</h2>
* <p>
* Seeding is the procedure by which a value (or set of values) is
* used to <i>initialize</i> a generator instance.
@@ -104,8 +105,8 @@ import org.apache.commons.rng.simple.internal.SeedFactory;
* <p>
* This class provides methods to generate random seeds (single values
* or arrays of values, of {@code int} or {@code long} types) that can
- * be passed to the {@link RandomSource#create(RandomSource,Object,Object[])
- * generators factory method}.
+ * be passed to the {@link RandomSource#create(Object,Object[])
+ * generator's factory method}.
* </p>
* <p>
* Although the seed-generating methods defined in this class will likely
@@ -131,13 +132,6 @@ import org.apache.commons.rng.simple.internal.SeedFactory;
* </ul>
*
* <p>
- * The current implementations have no provision for producing non-overlapping
- * sequences.
- * For parallel applications, a possible workaround is that each thread uses
- * a generator of a different type (see {@link #TWO_CMRES_SELECT}).
- * </p>
- *
- * <p>
* <b>Note:</b>
* Seeding is not equivalent to restoring the internal state of an
* <i>already initialized</i> generator.
@@ -154,6 +148,32 @@ import org.apache.commons.rng.simple.internal.SeedFactory;
* randomness, which is also not usually accessible).
* </p>
*
+ * <h2>Parallel applications</h2>
+ * <p>
+ * For parallel applications, some implementations have provision for producing
+ * non-overlapping sequences by copying the generator and then advancing a
large number
+ * of steps in the generator sequence. Repeated jumps can create a series of
+ * child generators that will output non-overlapping sequences over a
specified number
+ * of outputs. These implementations are identified using the {@link
#isJumpable()}
+ * and {@link #isLongJumpable()} methods.
+ * </p>
+ * <pre><code>
+ * RandomSource source = RandomSource.XO_RO_SHI_RO_128_SS; // Known to be
jumpable.
+ *
+ * JumpableUniformRandomProvider jumpable = (JumpableUniformRandomProvider)
source.create();
+ *
+ * // For use in parallel
+ * UniformRandomProvider[] rngs = new UniformRandomProvider[10];
+ * for (int i = 0; i < rngs.length; i++) {
+ * rngs[i] = jumpable.jump();
+ * }
+ * </code></pre>
+ * <p>
+ * For implementations that have no provision for producing non-overlapping
+ * sequences, a possible workaround is that each thread uses
+ * a generator of a different type (see {@link #TWO_CMRES_SELECT}).
+ * </p>
+ *
* @since 1.0
*/
public enum RandomSource {
