[commons-rng] branch master updated: Update javadoc.

[ah...@apache.org]

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 <ah...@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 &lt; 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 {