Skip to content
Permalink
Browse files
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.
  • Loading branch information
aherbert committed Sep 7, 2021
1 parent 9a1a05a commit bba61b9bb395580cea210d89ca12f8ad71527b2f
Showing 1 changed file with 31 additions and 11 deletions.
@@ -38,8 +38,8 @@
* 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 @@
* 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 @@
* <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 @@
* </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 @@
* 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 {

0 comments on commit bba61b9

Please sign in to comment.