View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.rng.simple;
18  
19  import java.util.stream.DoubleStream;
20  import java.util.stream.IntStream;
21  import java.util.stream.LongStream;
22  import org.apache.commons.rng.UniformRandomProvider;
23  import org.apache.commons.rng.RestorableUniformRandomProvider;
24  import org.apache.commons.rng.simple.internal.ProviderBuilder;
25  import org.apache.commons.rng.simple.internal.SeedFactory;
26  
27  /**
28   * This class provides the API for creating generators of random numbers.
29   *
30   * <p>Usage examples:</p>
31   * <pre><code>
32   *  UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
33   * </code></pre>
34   * or
35   * <pre><code>
36   *  final int[] seed = new int[] { 196, 9, 0, 226 };
37   *  UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create(seed);
38   * </code></pre>
39   * or
40   * <pre><code>
41   *  final int[] seed = RandomSource.createIntArray(256);
42   *  UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create(seed);
43   * </code></pre>
44   * where the enum value is the identifier of the generator's concrete
45   * implementation, and the argument to method {@code create} is the
46   * (optional) seed.
47   *
48   * <p>
49   * In the first form, a random seed will be {@link SeedFactory generated
50   * automatically}; in the second form, a fixed seed is used; a random seed
51   * is explicitly generated in the third form.
52   * </p>
53   *
54   * <h2>Seeding</h2>
55   * <p>
56   * Seeding is the procedure by which a value (or set of values) is
57   * used to <i>initialize</i> a generator instance.
58   * The requirement that a given seed will always result in the same
59   * internal state allows to create different instances of a generator
60   * that will produce the same sequence of pseudo-random numbers.
61   * </p>
62   *
63   * <p>
64   * The type of data used as a seed depends on the concrete implementation
65   * as some types may not provide enough information to fully initialize
66   * the generator's internal state.
67   * <br>
68   * The reference algorithm's seeding procedure (if provided) operates
69   * on a value of a (single) <i>native</i> type:
70   * Each concrete implementation's constructor creates an instance using
71   * the native type whose information contents is used to set the
72   * internal state.
73   * <br>
74   * When the seed value passed by the caller is of the native type, it is
75   * expected that the sequences produced will be identical to those
76   * produced by other implementations of the same reference algorithm.
77   * <br>
78   * However, when the seed value passed by the caller is not of the native
79   * type, a transformation is performed by this library and the resulting
80   * native type value will <i>not</i> contain more information than the
81   * original seed value.
82   * If the algorithm's native type is "simpler" than the type passed by
83   * the caller, then some (unused) information will even be lost.
84   * <br>
85   * The transformation from non-native to native seed type is arbitrary,
86   * as long as it does not reduce the amount of information required by
87   * the algorithm to initialize its state.
88   * The consequence of the transformation is that sequences produced
89   * by this library may <i>not</i> be the same as the sequences produced
90   * by other implementations of the same algorithm!
91   * </p>
92   *
93   * <p>
94   * For each algorithm, the Javadoc mentions the "ideal" size of the seed,
95   * meaning the number of {@code int} or {@code long} values that is neither
96   * too large (i.e. some of the seed is useless) or too small (i.e. an
97   * internal procedure will fill the state with redundant information
98   * computed from the given seed).
99   * </p>
100  *
101  * <p>
102  * Note that some algorithms are inherently sensitive to having too low
103  * diversity in their initial state.
104  * For example, it is often a bad idea to use a seed that is mostly
105  * composed of zeroes, or of repeated values.
106  * </p>
107  *
108  * <p>
109  * This class provides methods to generate random seeds (single values
110  * or arrays of values, of {@code int} or {@code long} types) that can
111  * be passed to the {@link RandomSource#create(Object,Object[])
112  * generator's factory method}.
113  * </p>
114  * <p>
115  * Although the seed-generating methods defined in this class will likely
116  * return different values each time they are called, there is no guarantee:
117  * </p>
118  * <ul>
119  *  <li>
120  *   In any sub-sequence, it is <a href="https://en.wikipedia.org/wiki/Birthday_problem">
121  *   expected</a> that the same numbers can occur, with a probability getting
122  *   higher as the range of allowed values is smaller and the sequence becomes
123  *   longer.
124  *  </li>
125  *  <li>
126  *   It possible that the resulting "seed" will not be <i>good</i> (i.e.
127  *   it will not generate a sufficiently uniformly random sequence for the
128  *   intended purpose), even if the generator is good!
129  *   The only way to ensure that the selected seed will make the generator
130  *   produce a good sequence is to submit that sequence to a series of
131  *   stringent tests, as provided by tools such as
132  *   <a href="http://www.phy.duke.edu/~rgb/General/dieharder.php">dieharder</a>
133  *   or <a href="http://simul.iro.umontreal.ca/testu01/tu01.html">TestU01</a>.
134  *  </li>
135  * </ul>
136  *
137  * <p>
138  * <b>Note:</b>
139  * Seeding is not equivalent to restoring the internal state of an
140  * <i>already initialized</i> generator.
141  * Indeed, generators can have a state that is more complex than the
142  * seed, and seeding is thus a transformation (from seed to state).
143  * Implementations do not provide the inverse transformation (from
144  * state to seed), hence it is not generally possible to know the seed
145  * that would initialize a new generator instance to the current state
146  * of another instance.
147  * Reseeding is also inefficient if the purpose is to continue the
148  * same sequence where another instance left off, as it would require
149  * to "replay" all the calls performed by that other instance (and it
150  * would require to know the number of calls to the primary source of
151  * randomness, which is also not usually accessible).
152  * </p>
153  *
154  * <h2>Parallel applications</h2>
155  * <p>
156  * For parallel applications, some implementations have provision for producing
157  * non-overlapping sequences by copying the generator and then advancing a large number
158  * of steps in the generator sequence. Repeated jumps can create a series of
159  * child generators that will output non-overlapping sequences over a specified number
160  * of outputs. These implementations are identified using the {@link #isJumpable()}
161  * and {@link #isLongJumpable()} methods.
162  * </p>
163  * <pre><code>
164  *  RandomSource source = RandomSource.XO_RO_SHI_RO_128_SS; // Known to be jumpable.
165  *
166  *  JumpableUniformRandomProvider jumpable = (JumpableUniformRandomProvider) source.create();
167  *
168  *  // For use in parallel
169  *  UniformRandomProvider[] rngs = new UniformRandomProvider[10];
170  *  for (int i = 0; i &lt; rngs.length; i++) {
171  *      rngs[i] = jumpable.jump();
172  *  }
173  * </code></pre>
174  * <p>
175  * For implementations that have no provision for producing non-overlapping
176  * sequences, a possible workaround is that each thread uses
177  * a generator of a different type (see {@link #TWO_CMRES_SELECT}).
178  * </p>
179  *
180  * @since 1.0
181  */
182 public enum RandomSource {
183     /**
184      * Source of randomness is {@link org.apache.commons.rng.core.source32.JDKRandom}.
185      * <ul>
186      *  <li>Native seed type: {@code Long}.</li>
187      * </ul>
188      */
189     JDK(ProviderBuilder.RandomSourceInternal.JDK),
190     /**
191      * Source of randomness is {@link org.apache.commons.rng.core.source32.Well512a}.
192      * <ul>
193      *  <li>Native seed type: {@code int[]}.</li>
194      *  <li>Native seed size: 16.</li>
195      * </ul>
196      */
197     WELL_512_A(ProviderBuilder.RandomSourceInternal.WELL_512_A),
198     /**
199      * Source of randomness is {@link org.apache.commons.rng.core.source32.Well1024a}.
200      * <ul>
201      *  <li>Native seed type: {@code int[]}.</li>
202      *  <li>Native seed size: 32.</li>
203      * </ul>
204      */
205     WELL_1024_A(ProviderBuilder.RandomSourceInternal.WELL_1024_A),
206     /**
207      * Source of randomness is {@link org.apache.commons.rng.core.source32.Well19937a}.
208      * <ul>
209      *  <li>Native seed type: {@code int[]}.</li>
210      *  <li>Native seed size: 624.</li>
211      * </ul>
212      */
213     WELL_19937_A(ProviderBuilder.RandomSourceInternal.WELL_19937_A),
214     /**
215      * Source of randomness is {@link org.apache.commons.rng.core.source32.Well19937c}.
216      * <ul>
217      *  <li>Native seed type: {@code int[]}.</li>
218      *  <li>Native seed size: 624.</li>
219      * </ul>
220      */
221     WELL_19937_C(ProviderBuilder.RandomSourceInternal.WELL_19937_C),
222     /**
223      * Source of randomness is {@link org.apache.commons.rng.core.source32.Well44497a}.
224      * <ul>
225      *  <li>Native seed type: {@code int[]}.</li>
226      *  <li>Native seed size: 1391.</li>
227      * </ul>
228      */
229     WELL_44497_A(ProviderBuilder.RandomSourceInternal.WELL_44497_A),
230     /**
231      * Source of randomness is {@link org.apache.commons.rng.core.source32.Well44497b}.
232      * <ul>
233      *  <li>Native seed type: {@code int[]}.</li>
234      *  <li>Native seed size: 1391.</li>
235      * </ul>
236      */
237     WELL_44497_B(ProviderBuilder.RandomSourceInternal.WELL_44497_B),
238     /**
239      * Source of randomness is {@link org.apache.commons.rng.core.source32.MersenneTwister}.
240      * <ul>
241      *  <li>Native seed type: {@code int[]}.</li>
242      *  <li>Native seed size: 624.</li>
243      * </ul>
244      */
245     MT(ProviderBuilder.RandomSourceInternal.MT),
246     /**
247      * Source of randomness is {@link org.apache.commons.rng.core.source32.ISAACRandom}.
248      * <ul>
249      *  <li>Native seed type: {@code int[]}.</li>
250      *  <li>Native seed size: 256.</li>
251      * </ul>
252      */
253     ISAAC(ProviderBuilder.RandomSourceInternal.ISAAC),
254     /**
255      * Source of randomness is {@link org.apache.commons.rng.core.source64.SplitMix64}.
256      * <ul>
257      *  <li>Native seed type: {@code Long}.</li>
258      * </ul>
259      */
260     SPLIT_MIX_64(ProviderBuilder.RandomSourceInternal.SPLIT_MIX_64),
261     /**
262      * Source of randomness is {@link org.apache.commons.rng.core.source64.XorShift1024Star}.
263      * <ul>
264      *  <li>Native seed type: {@code long[]}.</li>
265      *  <li>Native seed size: 16.</li>
266      * </ul>
267      *
268      * @deprecated Since 1.3, where it is recommended to use {@code XOR_SHIFT_1024_S_PHI}
269      * instead due to its slightly better (more uniform) output. {@code XOR_SHIFT_1024_S}
270      * is still quite usable but both are variants of the same algorithm and maintain their
271      * internal state identically. Their outputs are correlated and the two should not be
272      * used together when independent sequences are assumed.
273      */
274     @Deprecated
275     XOR_SHIFT_1024_S(ProviderBuilder.RandomSourceInternal.XOR_SHIFT_1024_S),
276     /**
277      * Source of randomness is {@link org.apache.commons.rng.core.source64.TwoCmres}.
278      * This generator is equivalent to {@link #TWO_CMRES_SELECT} with the choice of the
279      * pair {@code (0, 1)} for the two subcycle generators.
280      * <ul>
281      *  <li>Native seed type: {@code Integer}.</li>
282      * </ul>
283      */
284     TWO_CMRES(ProviderBuilder.RandomSourceInternal.TWO_CMRES),
285     /**
286      * Source of randomness is {@link org.apache.commons.rng.core.source64.TwoCmres},
287      * with explicit selection of the two subcycle generators.
288      * The selection of the subcycle generator is by passing its index in the internal
289      * table, a value between 0 (included) and 13 (included).
290      * The two indices must be different.
291      * Different choices of an ordered pair of indices create independent generators.
292      * <ul>
293      *  <li>Native seed type: {@code Integer}.</li>
294      * </ul>
295      */
296     TWO_CMRES_SELECT(ProviderBuilder.RandomSourceInternal.TWO_CMRES_SELECT),
297     /**
298      * Source of randomness is {@link org.apache.commons.rng.core.source64.MersenneTwister64}.
299      * <ul>
300      *  <li>Native seed type: {@code long[]}.</li>
301      *  <li>Native seed size: 312.</li>
302      * </ul>
303      */
304     MT_64(ProviderBuilder.RandomSourceInternal.MT_64),
305     /**
306      * Source of randomness is {@link org.apache.commons.rng.core.source32.MultiplyWithCarry256}.
307      * <ul>
308      *  <li>Native seed type: {@code int[]}.</li>
309      *  <li>Native seed size: 257.</li>
310      * </ul>
311      */
312     MWC_256(ProviderBuilder.RandomSourceInternal.MWC_256),
313     /**
314      * Source of randomness is {@link org.apache.commons.rng.core.source32.KISSRandom}.
315      * <ul>
316      *  <li>Native seed type: {@code int[]}.</li>
317      *  <li>Native seed size: 4.</li>
318      * </ul>
319      */
320     KISS(ProviderBuilder.RandomSourceInternal.KISS),
321     /**
322      * Source of randomness is {@link org.apache.commons.rng.core.source64.XorShift1024StarPhi}.
323      * <ul>
324      *  <li>Native seed type: {@code long[]}.</li>
325      *  <li>Native seed size: 16.</li>
326      * </ul>
327      * @since 1.3
328      */
329     XOR_SHIFT_1024_S_PHI(ProviderBuilder.RandomSourceInternal.XOR_SHIFT_1024_S_PHI),
330     /**
331      * Source of randomness is {@link org.apache.commons.rng.core.source32.XoRoShiRo64Star}.
332      * <ul>
333      *  <li>Native seed type: {@code int[]}.</li>
334      *  <li>Native seed size: 2.</li>
335      * </ul>
336      * @since 1.3
337      */
338     XO_RO_SHI_RO_64_S(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_64_S),
339     /**
340      * Source of randomness is {@link org.apache.commons.rng.core.source32.XoRoShiRo64StarStar}.
341      * <ul>
342      *  <li>Native seed type: {@code int[]}.</li>
343      *  <li>Native seed size: 2.</li>
344      * </ul>
345      * @since 1.3
346      */
347     XO_RO_SHI_RO_64_SS(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_64_SS),
348     /**
349      * Source of randomness is {@link org.apache.commons.rng.core.source32.XoShiRo128Plus}.
350      * <ul>
351      *  <li>Native seed type: {@code int[]}.</li>
352      *  <li>Native seed size: 4.</li>
353      * </ul>
354      * @since 1.3
355      */
356     XO_SHI_RO_128_PLUS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_128_PLUS),
357     /**
358      * Source of randomness is {@link org.apache.commons.rng.core.source32.XoShiRo128StarStar}.
359      * <ul>
360      *  <li>Native seed type: {@code int[]}.</li>
361      *  <li>Native seed size: 4.</li>
362      * </ul>
363      * @since 1.3
364      */
365     XO_SHI_RO_128_SS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_128_SS),
366     /**
367      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo128Plus}.
368      * <ul>
369      *  <li>Native seed type: {@code long[]}.</li>
370      *  <li>Native seed size: 2.</li>
371      * </ul>
372      * @since 1.3
373      */
374     XO_RO_SHI_RO_128_PLUS(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_128_PLUS),
375     /**
376      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo128StarStar}.
377      * <ul>
378      *  <li>Native seed type: {@code long[]}.</li>
379      *  <li>Native seed size: 2.</li>
380      * </ul>
381      * @since 1.3
382      */
383     XO_RO_SHI_RO_128_SS(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_128_SS),
384     /**
385      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo256Plus}.
386      * <ul>
387      *  <li>Native seed type: {@code long[]}.</li>
388      *  <li>Native seed size: 4.</li>
389      * </ul>
390      * @since 1.3
391      */
392     XO_SHI_RO_256_PLUS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_256_PLUS),
393     /**
394      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo256StarStar}.
395      * <ul>
396      *  <li>Native seed type: {@code long[]}.</li>
397      *  <li>Native seed size: 4.</li>
398      * </ul>
399      * @since 1.3
400      */
401     XO_SHI_RO_256_SS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_256_SS),
402     /**
403      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo512Plus}.
404      * <ul>
405      *  <li>Native seed type: {@code long[]}.</li>
406      *  <li>Native seed size: 8.</li>
407      * </ul>
408      * @since 1.3
409      */
410     XO_SHI_RO_512_PLUS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_512_PLUS),
411     /**
412      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo512StarStar}.
413      * <ul>
414      *  <li>Native seed type: {@code long[]}.</li>
415      *  <li>Native seed size: 8.</li>
416      * </ul>
417      * @since 1.3
418      */
419     XO_SHI_RO_512_SS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_512_SS),
420     /**
421      * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgXshRr32}.
422      * <ul>
423      *  <li>Native seed type: {@code long[]}.</li>
424      *  <li>Native seed size: 2.</li>
425      * </ul>
426      * @since 1.3
427      */
428     PCG_XSH_RR_32(ProviderBuilder.RandomSourceInternal.PCG_XSH_RR_32),
429     /**
430      * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgXshRs32}.
431      * <ul>
432      *  <li>Native seed type: {@code long[]}.</li>
433      *  <li>Native seed size: 2.</li>
434      * </ul>
435      * @since 1.3
436      */
437     PCG_XSH_RS_32(ProviderBuilder.RandomSourceInternal.PCG_XSH_RS_32),
438     /**
439      * Source of randomness is {@link org.apache.commons.rng.core.source64.PcgRxsMXs64}.
440      * <ul>
441      *  <li>Native seed type: {@code long[]}.</li>
442      *  <li>Native seed size: 2.</li>
443      * </ul>
444      * @since 1.3
445      */
446     PCG_RXS_M_XS_64(ProviderBuilder.RandomSourceInternal.PCG_RXS_M_XS_64),
447     /**
448      * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgMcgXshRr32}.
449      * <ul>
450      *  <li>Native seed type: {@code Long}.</li>
451      * </ul>
452      * @since 1.3
453      */
454     PCG_MCG_XSH_RR_32(ProviderBuilder.RandomSourceInternal.PCG_MCG_XSH_RR_32),
455     /**
456      * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgMcgXshRs32}.
457      * <ul>
458      *  <li>Native seed type: {@code Long}.</li>
459      * </ul>
460      * @since 1.3
461      */
462     PCG_MCG_XSH_RS_32(ProviderBuilder.RandomSourceInternal.PCG_MCG_XSH_RS_32),
463     /**
464      * Source of randomness is {@link org.apache.commons.rng.core.source32.MiddleSquareWeylSequence}.
465      * <ul>
466      *  <li>Native seed type: {@code long[]}.</li>
467      *  <li>Native seed size: 3.</li>
468      * </ul>
469      * @since 1.3
470      */
471     MSWS(ProviderBuilder.RandomSourceInternal.MSWS),
472     /**
473      * Source of randomness is {@link org.apache.commons.rng.core.source32.DotyHumphreySmallFastCounting32}.
474      * <ul>
475      *  <li>Native seed type: {@code int[]}.</li>
476      *  <li>Native seed size: 3.</li>
477      * </ul>
478      * @since 1.3
479      */
480     SFC_32(ProviderBuilder.RandomSourceInternal.SFC_32),
481     /**
482      * Source of randomness is {@link org.apache.commons.rng.core.source64.DotyHumphreySmallFastCounting64}.
483      * <ul>
484      *  <li>Native seed type: {@code long[]}.</li>
485      *  <li>Native seed size: 3.</li>
486      * </ul>
487      * @since 1.3
488      */
489     SFC_64(ProviderBuilder.RandomSourceInternal.SFC_64),
490     /**
491      * Source of randomness is {@link org.apache.commons.rng.core.source32.JenkinsSmallFast32}.
492      * <ul>
493      *  <li>Native seed type: {@code Integer}.</li>
494      * </ul>
495      * @since 1.3
496      */
497     JSF_32(ProviderBuilder.RandomSourceInternal.JSF_32),
498     /**
499      * Source of randomness is {@link org.apache.commons.rng.core.source64.JenkinsSmallFast64}.
500      * <ul>
501      *  <li>Native seed type: {@code Long}.</li>
502      * </ul>
503      * @since 1.3
504      */
505     JSF_64(ProviderBuilder.RandomSourceInternal.JSF_64),
506     /**
507      * Source of randomness is {@link org.apache.commons.rng.core.source32.XoShiRo128PlusPlus}.
508      * <ul>
509      *  <li>Native seed type: {@code int[]}.</li>
510      *  <li>Native seed size: 4.</li>
511      * </ul>
512      * @since 1.3
513      */
514     XO_SHI_RO_128_PP(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_128_PP),
515     /**
516      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo128PlusPlus}.
517      * <ul>
518      *  <li>Native seed type: {@code long[]}.</li>
519      *  <li>Native seed size: 2.</li>
520      * </ul>
521      * @since 1.3
522      */
523     XO_RO_SHI_RO_128_PP(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_128_PP),
524     /**
525      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo256PlusPlus}.
526      * <ul>
527      *  <li>Native seed type: {@code long[]}.</li>
528      *  <li>Native seed size: 4.</li>
529      * </ul>
530      * @since 1.3
531      */
532     XO_SHI_RO_256_PP(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_256_PP),
533     /**
534      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo512PlusPlus}.
535      * <ul>
536      *  <li>Native seed type: {@code long[]}.</li>
537      *  <li>Native seed size: 8.</li>
538      * </ul>
539      * @since 1.3
540      */
541     XO_SHI_RO_512_PP(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_512_PP),
542     /**
543      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo1024PlusPlus}.
544      * <ul>
545      *  <li>Native seed type: {@code long[]}.</li>
546      *  <li>Native seed size: 16.</li>
547      * </ul>
548      * @since 1.3
549      */
550     XO_RO_SHI_RO_1024_PP(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_1024_PP),
551     /**
552      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo1024Star}.
553      * <ul>
554      *  <li>Native seed type: {@code long[]}.</li>
555      *  <li>Native seed size: 16.</li>
556      * </ul>
557      * @since 1.3
558      */
559     XO_RO_SHI_RO_1024_S(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_1024_S),
560     /**
561      * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo1024StarStar}.
562      * <ul>
563      *  <li>Native seed type: {@code long[]}.</li>
564      *  <li>Native seed size: 16.</li>
565      * </ul>
566      * @since 1.3
567      */
568     XO_RO_SHI_RO_1024_SS(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_1024_SS),
569     /**
570      * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgXshRr32}.
571      * <ul>
572      *  <li>Native seed type: {@code Long}.</li>
573      * </ul>
574      * @since 1.4
575      */
576     PCG_XSH_RR_32_OS(ProviderBuilder.RandomSourceInternal.PCG_XSH_RR_32_OS),
577     /**
578      * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgXshRs32}.
579      * <ul>
580      *  <li>Native seed type: {@code Long}.</li>
581      * </ul>
582      * @since 1.4
583      */
584     PCG_XSH_RS_32_OS(ProviderBuilder.RandomSourceInternal.PCG_XSH_RS_32_OS),
585     /**
586      * Source of randomness is {@link org.apache.commons.rng.core.source64.PcgRxsMXs64}.
587      * <ul>
588      *  <li>Native seed type: {@code Long}.</li>
589      * </ul>
590      * @since 1.4
591      */
592     PCG_RXS_M_XS_64_OS(ProviderBuilder.RandomSourceInternal.PCG_RXS_M_XS_64_OS),
593     /**
594      * Source of randomness is {@link org.apache.commons.rng.core.source64.L64X128StarStar}.
595      * <ul>
596      *  <li>Native seed type: {@code long[]}.</li>
597      *  <li>Native seed size: 4.</li>
598      * </ul>
599      * @since 1.5
600      */
601     L64_X128_SS(ProviderBuilder.RandomSourceInternal.L64_X128_SS),
602     /**
603      * Source of randomness is {@link org.apache.commons.rng.core.source64.L64X128Mix}.
604      * <ul>
605      *  <li>Native seed type: {@code long[]}.</li>
606      *  <li>Native seed size: 4.</li>
607      * </ul>
608      * @since 1.5
609      */
610     L64_X128_MIX(ProviderBuilder.RandomSourceInternal.L64_X128_MIX),
611     /**
612      * Source of randomness is {@link org.apache.commons.rng.core.source64.L64X256Mix}.
613      * <ul>
614      *  <li>Native seed type: {@code long[]}.</li>
615      *  <li>Native seed size: 6.</li>
616      * </ul>
617      * @since 1.5
618      */
619     L64_X256_MIX(ProviderBuilder.RandomSourceInternal.L64_X256_MIX),
620     /**
621      * Source of randomness is {@link org.apache.commons.rng.core.source64.L64X1024Mix}.
622      * <ul>
623      *  <li>Native seed type: {@code long[]}.</li>
624      *  <li>Native seed size: 18.</li>
625      * </ul>
626      * @since 1.5
627      */
628     L64_X1024_MIX(ProviderBuilder.RandomSourceInternal.L64_X1024_MIX),
629     /**
630      * Source of randomness is {@link org.apache.commons.rng.core.source64.L128X128Mix}.
631      * <ul>
632      *  <li>Native seed type: {@code long[]}.</li>
633      *  <li>Native seed size: 6.</li>
634      * </ul>
635      * @since 1.5
636      */
637     L128_X128_MIX(ProviderBuilder.RandomSourceInternal.L128_X128_MIX),
638     /**
639      * Source of randomness is {@link org.apache.commons.rng.core.source64.L128X256Mix}.
640      * <ul>
641      *  <li>Native seed type: {@code long[]}.</li>
642      *  <li>Native seed size: 8.</li>
643      * </ul>
644      * @since 1.5
645      */
646     L128_X256_MIX(ProviderBuilder.RandomSourceInternal.L128_X256_MIX),
647     /**
648      * Source of randomness is {@link org.apache.commons.rng.core.source64.L128X1024Mix}.
649      * <ul>
650      *  <li>Native seed type: {@code long[]}.</li>
651      *  <li>Native seed size: 20.</li>
652      * </ul>
653      * @since 1.5
654      */
655     L128_X1024_MIX(ProviderBuilder.RandomSourceInternal.L128_X1024_MIX),
656     /**
657      * Source of randomness is {@link org.apache.commons.rng.core.source32.L32X64Mix}.
658      * <ul>
659      *  <li>Native seed type: {@code int[]}.</li>
660      *  <li>Native seed size: 4.</li>
661      * </ul>
662      * @since 1.5
663      */
664     L32_X64_MIX(ProviderBuilder.RandomSourceInternal.L32_X64_MIX);
665 
666     /** Internal identifier. */
667     private final ProviderBuilder.RandomSourceInternal internalIdentifier;
668 
669     /**
670      * @param id Internal identifier.
671      */
672     RandomSource(ProviderBuilder.RandomSourceInternal id) {
673         internalIdentifier = id;
674     }
675 
676     /**
677      * @return the internal identifier.
678      */
679     ProviderBuilder.RandomSourceInternal getInternalIdentifier() {
680         return internalIdentifier;
681     }
682 
683     /**
684      * Checks whether the type of given {@code seed} is the native type
685      * of the implementation.
686      *
687      * @param seed Seed value.
688      * @return {@code true} if the type of {@code seed} is the native
689      * type for this RNG source.
690      */
691     public boolean isNativeSeed(Object seed) {
692         return internalIdentifier.isNativeSeed(seed);
693     }
694 
695     /**
696      * Creates a seed suitable for the implementing class represented by this random source.
697      *
698      * <p>The seed will be created as if passing a {@code null} seed to the method
699      * {@link #create(Object, Object...)}. It will satisfy the seed size and any
700      * other seed requirements for the implementing class. The seed is converted from the native
701      * type to a byte representation.</p>
702      *
703      * <p>Usage example:</p>
704      * <pre><code>
705      *  RandomSource source = ...;
706      *  byte[] seed = source.createSeed();
707      *  UniformRandomProvider rng = source.create(seed);
708      * </code></pre>
709      *
710      * @return the seed
711      * @since 1.3
712      */
713     public byte[] createSeed() {
714         return internalIdentifier.createSeedBytes();
715     }
716 
717     /**
718      * Creates a seed suitable for the implementing class represented by this random source
719      * using the supplied source of randomness.
720      *
721      * <p>The seed will satisfy the seed size and any other seed requirements for the
722      * implementing class.</p>
723      *
724      * <p>Usage example:</p>
725      * <pre><code>
726      *  RandomSource source = ...;
727      *  UniformRandomProvider seedRng = new JDKRandomWrapper(new SecureRandom());
728      *  byte[] seed = source.createSeed(seedRng);
729      *  UniformRandomProvider rng = source.create(seed);
730      * </code></pre>
731      *
732      * @param rng Source of randomness.
733      * @return the seed
734      * @since 1.3
735      */
736     public byte[] createSeed(UniformRandomProvider rng) {
737         return internalIdentifier.createSeedBytes(rng);
738     }
739 
740     /**
741      * Checks whether the implementing class represented by this random source
742      * supports the {@link org.apache.commons.rng.JumpableUniformRandomProvider
743      * JumpableUniformRandomProvider} interface. If {@code true} the instance returned
744      * by {@link #create(RandomSource)} may be cast to the interface; otherwise a class
745      * cast exception will occur.
746      *
747      * <p>Usage example:</p>
748      * <pre><code>
749      *  RandomSource source = ...;
750      *  if (source.isJumpable()) {
751      *      JumpableUniformRandomProvider rng =
752      *          (JumpableUniformRandomProvider) source.create();
753      *  }
754      * </code></pre>
755      *
756      * @return {@code true} if jumpable
757      * @since 1.3
758      */
759     public boolean isJumpable() {
760         return isAssignableTo(org.apache.commons.rng.JumpableUniformRandomProvider.class);
761     }
762 
763     /**
764      * Checks whether the implementing class represented by this random source
765      * supports the {@link org.apache.commons.rng.LongJumpableUniformRandomProvider
766      * LongJumpableUniformRandomProvider} interface. If {@code true} the instance returned
767      * by {@link #create(RandomSource)} may be cast to the interface; otherwise a class
768      * cast exception will occur.
769      *
770      * <p>Usage example:</p>
771      * <pre><code>
772      *  RandomSource source = ...;
773      *  if (source.isJumpable()) {
774      *      LongJumpableUniformRandomProvider rng =
775      *          (LongJumpableUniformRandomProvider) source.create();
776      *  }
777      * </code></pre>
778      *
779      * @return {@code true} if long jumpable
780      * @since 1.3
781      */
782     public boolean isLongJumpable() {
783         return isAssignableTo(org.apache.commons.rng.LongJumpableUniformRandomProvider.class);
784     }
785 
786     /**
787      * Checks whether the implementing class represented by this random source
788      * supports the {@link org.apache.commons.rng.SplittableUniformRandomProvider
789      * SplittableUniformRandomProvider} interface. If {@code true} the instance returned
790      * by {@link #create(RandomSource)} may be cast to the interface; otherwise a class
791      * cast exception will occur.
792      *
793      * <p>Usage example:</p>
794      * <pre><code>
795      *  RandomSource source = ...;
796      *  if (source.isSplittable()) {
797      *      SplittableUniformRandomProvider rng =
798      *          (SplittableUniformRandomProvider) source.create();
799      *  }
800      * </code></pre>
801      *
802      * @return {@code true} if splittable
803      * @since 1.5
804      */
805     public boolean isSplittable() {
806         return isAssignableTo(org.apache.commons.rng.SplittableUniformRandomProvider.class);
807     }
808 
809     /**
810      * Determines if the implementing class represented by this random source is either the same
811      * as, or is a subclass or subinterface of, the class or interface represented
812      * by the specified {@code Class} parameter. It returns true if so; otherwise it returns
813      * false.
814      *
815      * @param type the {@code Class} object to be checked
816      * @return the boolean value indicating whether the class of this random source
817      * can be assigned to objects of the specified type
818      */
819     private boolean isAssignableTo(Class<?> type) {
820         return type.isAssignableFrom(internalIdentifier.getRng());
821     }
822 
823     /**
824      * Creates a random number generator with a random seed.
825      *
826      * <p>Usage example:</p>
827      * <pre><code>
828      *  UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
829      * </code></pre>
830      * <p>or, if a {@link RestorableUniformRandomProvider "save/restore"} functionality is needed,</p>
831      * <pre><code>
832      *  RestorableUniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
833      * </code></pre>
834      *
835      * <p>This method will raise an exception if the generator requires arguments in addition
836      * to a seed (e.g. {@link #TWO_CMRES_SELECT}).</p>
837      *
838      * @return the RNG.
839      * @throws IllegalArgumentException if the generator requires arguments in addition
840      * to a seed.
841      *
842      * @see #create(Object,Object[])
843      * @since 1.4
844      */
845     public RestorableUniformRandomProvider create() {
846         return ProviderBuilder.create(getInternalIdentifier());
847     }
848 
849     /**
850      * Creates a random number generator with the given {@code seed}.
851      *
852      * <p>Usage example:</p>
853      * <pre><code>
854      *  UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create(0x123abcL);
855      *  UniformRandomProvider rng = RandomSource.TWO_CMRES_SELECT.create(26219, 6, 9);
856      *  // null seed with arguments
857      *  UniformRandomProvider rng = RandomSource.TWO_CMRES_SELECT.create((Object) null, 6, 9);
858      * </code></pre>
859      *
860      * <p>Valid types for the {@code seed} are:</p>
861      *  <ul>
862      *   <li>{@code Integer} (or {@code int})</li>
863      *   <li>{@code Long} (or {@code long})</li>
864      *   <li>{@code int[]}</li>
865      *   <li>{@code long[]}</li>
866      *   <li>{@code byte[]}</li>
867      *  </ul>
868      *
869      * <p>Notes:</p>
870      * <ul>
871      *  <li>
872      *   When the seed type passed as argument is more complex (i.e. more
873      *   bits can be independently chosen) than the generator's
874      *   {@link #isNativeSeed(Object) native type}, the conversion of a
875      *   set of different seeds will necessarily result in the same value
876      *   of the native seed type.
877      *  </li>
878      *  <li>
879      *   When the native seed type is an array, the same remark applies
880      *   when the array contains more bits than the state of the generator.
881      *  </li>
882      *  <li>
883      *   When the {@code seed} is {@code null}, a seed of the native type
884      *   will be generated. If the native type is an array, the generated
885      *   size is limited a maximum of 128.
886      *  </li>
887      * </ul>
888      *
889      * <p>This method will raise an exception if the additional arguments for
890      * the implementation's constructor are incorrect (e.g. {@link #TWO_CMRES_SELECT}).
891      * This includes the case where arguments are supplied and the implementation
892      * does not require additional arguments.</p>
893      *
894      * @param seed Seed value.  It can be {@code null} (in which case a
895      * random value will be used).
896      * @param data Additional arguments to the implementation's constructor.
897      * Please refer to the documentation of each specific implementation.
898      * @return the RNG.
899      * @throws IllegalArgumentException if the argument data required to initialize the
900      * generator is incorrect.
901      * @throws UnsupportedOperationException if the type of the {@code seed}
902      * is invalid.
903      *
904      * @see #create()
905      * @since 1.4
906      */
907     public RestorableUniformRandomProvider create(Object seed,
908                                                   Object... data) {
909         return ProviderBuilder.create(getInternalIdentifier(), seed, data);
910     }
911 
912     /**
913      * Creates a random number generator with a random seed.
914      *
915      * <p>Usage example:</p>
916      * <pre><code>
917      *  UniformRandomProvider rng = RandomSource.create(RandomSource.MT);
918      * </code></pre>
919      * <p>or, if a {@link RestorableUniformRandomProvider "save/restore"} functionality is needed,</p>
920      * <pre><code>
921      *  RestorableUniformRandomProvider rng = RandomSource.create(RandomSource.MT);
922      * </code></pre>
923      *
924      * <p>This method will raise an exception if the generator requires arguments in addition
925      * to a seed (e.g. {@link #TWO_CMRES_SELECT}).</p>
926      *
927      * @param source RNG type.
928      * @return the RNG.
929      * @throws IllegalArgumentException if the generator requires arguments in addition
930      * to a seed.
931      *
932      * @see #create(RandomSource,Object,Object[])
933      * @deprecated It is preferred to use the {@link RandomSource#create()} instance method.
934      */
935     @Deprecated
936     public static RestorableUniformRandomProvider create(RandomSource source) {
937         return ProviderBuilder.create(source.getInternalIdentifier());
938     }
939 
940     /**
941      * Creates a random number generator with the given {@code seed}.
942      *
943      * <p>Usage example:</p>
944      * <pre><code>
945      *  UniformRandomProvider rng = RandomSource.create(RandomSource.XO_RO_SHI_RO_128_PP, 0x123abcL);
946      *  UniformRandomProvider rng = RandomSource.create(RandomSource.TWO_CMRES_SELECT, 26219, 6, 9);
947      * </code></pre>
948      *
949      * <p>Valid types for the {@code seed} are:</p>
950      *  <ul>
951      *   <li>{@code Integer} (or {@code int})</li>
952      *   <li>{@code Long} (or {@code long})</li>
953      *   <li>{@code int[]}</li>
954      *   <li>{@code long[]}</li>
955      *   <li>{@code byte[]}</li>
956      *  </ul>
957      *
958      * <p>Notes:</p>
959      * <ul>
960      *  <li>
961      *   When the seed type passed as argument is more complex (i.e. more
962      *   bits can be independently chosen) than the generator's
963      *   {@link #isNativeSeed(Object) native type}, the conversion of a
964      *   set of different seeds will necessarily result in the same value
965      *   of the native seed type.
966      *  </li>
967      *  <li>
968      *   When the native seed type is an array, the same remark applies
969      *   when the array contains more bits than the state of the generator.
970      *  </li>
971      *  <li>
972      *   When the {@code seed} is {@code null}, a seed of the native type
973      *   will be generated. If the native type is an array, the generated
974      *   size is limited a maximum of 128.
975      *  </li>
976      * </ul>
977      *
978      * <p>This method will raise an exception if the additional arguments for
979      * the implementation's constructor are incorrect (e.g. {@link #TWO_CMRES_SELECT}).
980      * This includes the case where arguments are supplied and the implementation
981      * does not require additional arguments.</p>
982      *
983      * @param source RNG type.
984      * @param seed Seed value.  It can be {@code null} (in which case a
985      * random value will be used).
986      * @param data Additional arguments to the implementation's constructor.
987      * Please refer to the documentation of each specific implementation.
988      * @return the RNG.
989      * @throws IllegalArgumentException if the argument data required to initialize the
990      * generator is incorrect.
991      * @throws UnsupportedOperationException if the type of the {@code seed}
992      * is invalid.
993      *
994      * @see #create(RandomSource)
995      * @deprecated It is preferred to use the {@link RandomSource#create(Object, Object...)} instance method.
996      */
997     @Deprecated
998     public static RestorableUniformRandomProvider create(RandomSource source,
999                                                          Object seed,
1000                                                          Object... data) {
1001         return ProviderBuilder.create(source.getInternalIdentifier(), seed, data);
1002     }
1003 
1004     /**
1005      * Creates a number for use as a seed.
1006      *
1007      * @return a random number.
1008      */
1009     public static int createInt() {
1010         return SeedFactory.createInt();
1011     }
1012 
1013     /**
1014      * Creates a number for use as a seed.
1015      *
1016      * @return a random number.
1017      */
1018     public static long createLong() {
1019         return SeedFactory.createLong();
1020     }
1021 
1022     /**
1023      * Creates an array of numbers for use as a seed.
1024      *
1025      * @param n Size of the array to create.
1026      * @return an array of {@code n} random numbers.
1027      */
1028     public static int[] createIntArray(int n) {
1029         return SeedFactory.createIntArray(n);
1030     }
1031 
1032     /**
1033      * Creates an array of numbers for use as a seed.
1034      *
1035      * @param n Size of the array to create.
1036      * @return an array of {@code n} random numbers.
1037      */
1038     public static long[] createLongArray(int n) {
1039         return SeedFactory.createLongArray(n);
1040     }
1041 
1042     /**
1043      * Wraps the given {@code delegate} generator in a new instance that
1044      * only provides access to the {@link UniformRandomProvider} methods.
1045      *
1046      * <p>This method can be used to prevent access to any methods of the {@code delegate}
1047      * that are not defined in the {@link UniformRandomProvider} interface.
1048      * For example this will prevent access to the "save/restore" functionality of
1049      * any {@link RestorableUniformRandomProvider} {@link #create() created}
1050      * by the {@link RandomSource} factory methods, or will prevent access to the jump
1051      * functionality of generators.
1052      *
1053      * <p>Since the method applies to more than the {@link RestorableUniformRandomProvider}
1054      * interface it is left to the caller to determine if any methods require hiding,
1055      * for example:
1056      *
1057      * <pre><code>
1058      * UniformRandomProvider rng = ...;
1059      * if (rng instanceof JumpableUniformRandomProvider) {
1060      *    rng = RandomSource.unrestorable(rng);
1061      * }
1062      * </code></pre>
1063      *
1064      * @param delegate Generator to which calls will be delegated.
1065      * @return a new instance
1066      */
1067     public static UniformRandomProvider unrestorable(final UniformRandomProvider delegate) {
1068         return new UniformRandomProvider() {
1069             @Override
1070             public void nextBytes(byte[] bytes) {
1071                 delegate.nextBytes(bytes);
1072             }
1073 
1074             @Override
1075             public void nextBytes(byte[] bytes,
1076                                   int start,
1077                                   int len) {
1078                 delegate.nextBytes(bytes, start, len);
1079             }
1080 
1081             @Override
1082             public int nextInt() {
1083                 return delegate.nextInt();
1084             }
1085 
1086             @Override
1087             public int nextInt(int n) {
1088                 return delegate.nextInt(n);
1089             }
1090 
1091             @Override
1092             public int nextInt(int origin, int bound) {
1093                 return delegate.nextInt(origin, bound);
1094             }
1095 
1096             @Override
1097             public long nextLong() {
1098                 return delegate.nextLong();
1099             }
1100 
1101             @Override
1102             public long nextLong(long n) {
1103                 return delegate.nextLong(n);
1104             }
1105 
1106             @Override
1107             public long nextLong(long origin, long bound) {
1108                 return delegate.nextLong(origin, bound);
1109             }
1110 
1111             @Override
1112             public boolean nextBoolean() {
1113                 return delegate.nextBoolean();
1114             }
1115 
1116             @Override
1117             public float nextFloat() {
1118                 return delegate.nextFloat();
1119             }
1120 
1121             @Override
1122             public float nextFloat(float bound) {
1123                 return delegate.nextFloat(bound);
1124             }
1125 
1126             @Override
1127             public float nextFloat(float origin, float bound) {
1128                 return delegate.nextFloat(origin, bound);
1129             }
1130 
1131             @Override
1132             public double nextDouble() {
1133                 return delegate.nextDouble();
1134             }
1135 
1136             @Override
1137             public double nextDouble(double bound) {
1138                 return delegate.nextDouble(bound);
1139             }
1140 
1141             @Override
1142             public double nextDouble(double origin, double bound) {
1143                 return delegate.nextDouble(origin, bound);
1144             }
1145 
1146             @Override
1147             public IntStream ints() {
1148                 return delegate.ints();
1149             }
1150 
1151             @Override
1152             public IntStream ints(int origin, int bound) {
1153                 return delegate.ints(origin, bound);
1154             }
1155 
1156             @Override
1157             public IntStream ints(long streamSize) {
1158                 return delegate.ints(streamSize);
1159             }
1160 
1161             @Override
1162             public IntStream ints(long streamSize, int origin, int bound) {
1163                 return delegate.ints(streamSize, origin, bound);
1164             }
1165 
1166             @Override
1167             public LongStream longs() {
1168                 return delegate.longs();
1169             }
1170 
1171             @Override
1172             public LongStream longs(long origin, long bound) {
1173                 return delegate.longs(origin, bound);
1174             }
1175 
1176             @Override
1177             public LongStream longs(long streamSize) {
1178                 return delegate.longs(streamSize);
1179             }
1180 
1181             @Override
1182             public LongStream longs(long streamSize, long origin, long bound) {
1183                 return delegate.longs(streamSize, origin, bound);
1184             }
1185 
1186             @Override
1187             public DoubleStream doubles() {
1188                 return delegate.doubles();
1189             }
1190 
1191             @Override
1192             public DoubleStream doubles(double origin, double bound) {
1193                 return delegate.doubles(origin, bound);
1194             }
1195 
1196             @Override
1197             public DoubleStream doubles(long streamSize) {
1198                 return delegate.doubles(streamSize);
1199             }
1200 
1201             @Override
1202             public DoubleStream doubles(long streamSize, double origin, double bound) {
1203                 return delegate.doubles(streamSize, origin, bound);
1204             }
1205 
1206             @Override
1207             public String toString() {
1208                 return delegate.toString();
1209             }
1210         };
1211     }
1212 }