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 < 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 }