001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.rng.simple;
018
019import java.util.stream.DoubleStream;
020import java.util.stream.IntStream;
021import java.util.stream.LongStream;
022import org.apache.commons.rng.UniformRandomProvider;
023import org.apache.commons.rng.RestorableUniformRandomProvider;
024import org.apache.commons.rng.simple.internal.ProviderBuilder;
025import org.apache.commons.rng.simple.internal.SeedFactory;
026
027/**
028 * This class provides the API for creating generators of random numbers.
029 *
030 * <p>Usage examples:</p>
031 * <pre><code>
032 *  UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
033 * </code></pre>
034 * or
035 * <pre><code>
036 *  final int[] seed = new int[] { 196, 9, 0, 226 };
037 *  UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create(seed);
038 * </code></pre>
039 * or
040 * <pre><code>
041 *  final int[] seed = RandomSource.createIntArray(256);
042 *  UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create(seed);
043 * </code></pre>
044 * where the enum value is the identifier of the generator's concrete
045 * implementation, and the argument to method {@code create} is the
046 * (optional) seed.
047 *
048 * <p>
049 * In the first form, a random seed will be {@link SeedFactory generated
050 * automatically}; in the second form, a fixed seed is used; a random seed
051 * is explicitly generated in the third form.
052 * </p>
053 *
054 * <h2>Seeding</h2>
055 * <p>
056 * Seeding is the procedure by which a value (or set of values) is
057 * used to <i>initialize</i> a generator instance.
058 * The requirement that a given seed will always result in the same
059 * internal state allows to create different instances of a generator
060 * that will produce the same sequence of pseudo-random numbers.
061 * </p>
062 *
063 * <p>
064 * The type of data used as a seed depends on the concrete implementation
065 * as some types may not provide enough information to fully initialize
066 * the generator's internal state.
067 * <br>
068 * The reference algorithm's seeding procedure (if provided) operates
069 * on a value of a (single) <i>native</i> type:
070 * Each concrete implementation's constructor creates an instance using
071 * the native type whose information contents is used to set the
072 * internal state.
073 * <br>
074 * When the seed value passed by the caller is of the native type, it is
075 * expected that the sequences produced will be identical to those
076 * produced by other implementations of the same reference algorithm.
077 * <br>
078 * However, when the seed value passed by the caller is not of the native
079 * type, a transformation is performed by this library and the resulting
080 * native type value will <i>not</i> contain more information than the
081 * original seed value.
082 * If the algorithm's native type is "simpler" than the type passed by
083 * the caller, then some (unused) information will even be lost.
084 * <br>
085 * The transformation from non-native to native seed type is arbitrary,
086 * as long as it does not reduce the amount of information required by
087 * the algorithm to initialize its state.
088 * The consequence of the transformation is that sequences produced
089 * by this library may <i>not</i> be the same as the sequences produced
090 * by other implementations of the same algorithm!
091 * </p>
092 *
093 * <p>
094 * For each algorithm, the Javadoc mentions the "ideal" size of the seed,
095 * meaning the number of {@code int} or {@code long} values that is neither
096 * too large (i.e. some of the seed is useless) or too small (i.e. an
097 * internal procedure will fill the state with redundant information
098 * computed from the given seed).
099 * </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 */
182public 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}