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