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 org.apache.commons.rng.UniformRandomProvider; 020import org.apache.commons.rng.RestorableUniformRandomProvider; 021import org.apache.commons.rng.simple.internal.ProviderBuilder; 022import org.apache.commons.rng.simple.internal.SeedFactory; 023 024/** 025 * This class provides the API for creating generators of random numbers. 026 * 027 * <p>Usage examples:</p> 028 * <pre><code> 029 * UniformRandomProvider rng = RandomSource.MT.create(); 030 * </code></pre> 031 * or 032 * <pre><code> 033 * final int[] seed = new int[] { 196, 9, 0, 226 }; 034 * UniformRandomProvider rng = RandomSource.MT.create(seed); 035 * </code></pre> 036 * or 037 * <pre><code> 038 * final int[] seed = RandomSource.createIntArray(256); 039 * UniformRandomProvider rng = RandomSource.MT.create(seed); 040 * </code></pre> 041 * where the enum value is the identifier of the generator's concrete 042 * implementation, and the argument to method {@code create} is the 043 * (optional) seed. 044 * 045 * <p> 046 * In the first form, a random seed will be {@link SeedFactory generated 047 * automatically}; in the second form, a fixed seed is used; a random seed 048 * is explicitly generated in the third form. 049 * </p> 050 * 051 * <h2>Seeding</h2> 052 * <p> 053 * Seeding is the procedure by which a value (or set of values) is 054 * used to <i>initialize</i> a generator instance. 055 * The requirement that a given seed will always result in the same 056 * internal state allows to create different instances of a generator 057 * that will produce the same sequence of pseudo-random numbers. 058 * </p> 059 * 060 * <p> 061 * The type of data used as a seed depends on the concrete implementation 062 * as some types may not provide enough information to fully initialize 063 * the generator's internal state. 064 * <br> 065 * The reference algorithm's seeding procedure (if provided) operates 066 * on a value of a (single) <i>native</i> type: 067 * Each concrete implementation's constructor creates an instance using 068 * the native type whose information contents is used to set the 069 * internal state. 070 * <br> 071 * When the seed value passed by the caller is of the native type, it is 072 * expected that the sequences produced will be identical to those 073 * produced by other implementations of the same reference algorithm. 074 * <br> 075 * However, when the seed value passed by the caller is not of the native 076 * type, a transformation is performed by this library and the resulting 077 * native type value will <i>not</i> contain more information than the 078 * original seed value. 079 * If the algorithm's native type is "simpler" than the type passed by 080 * the caller, then some (unused) information will even be lost. 081 * <br> 082 * The transformation from non-native to native seed type is arbitrary, 083 * as long as it does not reduce the amount of information required by 084 * the algorithm to initialize its state. 085 * The consequence of the transformation is that sequences produced 086 * by this library may <i>not</i> be the same as the sequences produced 087 * by other implementations of the same algorithm! 088 * </p> 089 * 090 * <p> 091 * For each algorithm, the Javadoc mentions the "ideal" size of the seed, 092 * meaning the number of {@code int} or {@code long} values that is neither 093 * too large (i.e. some of the seed is useless) or too small (i.e. an 094 * internal procedure will fill the state with redundant information 095 * computed from the given seed). 096 * </p> 097 * 098 * <p> 099 * Note that some algorithms are inherently sensitive to having too low 100 * diversity in their initial state. 101 * For example, it is often a bad idea to use a seed that is mostly 102 * composed of zeroes, or of repeated values. 103 * </p> 104 * 105 * <p> 106 * This class provides methods to generate random seeds (single values 107 * or arrays of values, of {@code int} or {@code long} types) that can 108 * be passed to the {@link RandomSource#create(Object,Object[]) 109 * generator's factory method}. 110 * </p> 111 * <p> 112 * Although the seed-generating methods defined in this class will likely 113 * return different values each time they are called, there is no guarantee: 114 * </p> 115 * <ul> 116 * <li> 117 * In any sub-sequence, it is <a href="https://en.wikipedia.org/wiki/Birthday_problem"> 118 * expected</a> that the same numbers can occur, with a probability getting 119 * higher as the range of allowed values is smaller and the sequence becomes 120 * longer. 121 * </li> 122 * <li> 123 * It possible that the resulting "seed" will not be <i>good</i> (i.e. 124 * it will not generate a sufficiently uniformly random sequence for the 125 * intended purpose), even if the generator is good! 126 * The only way to ensure that the selected seed will make the generator 127 * produce a good sequence is to submit that sequence to a series of 128 * stringent tests, as provided by tools such as 129 * <a href="http://www.phy.duke.edu/~rgb/General/dieharder.php">dieharder</a> 130 * or <a href="http://simul.iro.umontreal.ca/testu01/tu01.html">TestU01</a>. 131 * </li> 132 * </ul> 133 * 134 * <p> 135 * <b>Note:</b> 136 * Seeding is not equivalent to restoring the internal state of an 137 * <i>already initialized</i> generator. 138 * Indeed, generators can have a state that is more complex than the 139 * seed, and seeding is thus a transformation (from seed to state). 140 * Implementations do not provide the inverse transformation (from 141 * state to seed), hence it is not generally possible to know the seed 142 * that would initialize a new generator instance to the current state 143 * of another instance. 144 * Reseeding is also inefficient if the purpose is to continue the 145 * same sequence where another instance left off, as it would require 146 * to "replay" all the calls performed by that other instance (and it 147 * would require to know the number of calls to the primary source of 148 * randomness, which is also not usually accessible). 149 * </p> 150 * 151 * <h2>Parallel applications</h2> 152 * <p> 153 * For parallel applications, some implementations have provision for producing 154 * non-overlapping sequences by copying the generator and then advancing a large number 155 * of steps in the generator sequence. Repeated jumps can create a series of 156 * child generators that will output non-overlapping sequences over a specified number 157 * of outputs. These implementations are identified using the {@link #isJumpable()} 158 * and {@link #isLongJumpable()} methods. 159 * </p> 160 * <pre><code> 161 * RandomSource source = RandomSource.XO_RO_SHI_RO_128_SS; // Known to be jumpable. 162 * 163 * JumpableUniformRandomProvider jumpable = (JumpableUniformRandomProvider) source.create(); 164 * 165 * // For use in parallel 166 * UniformRandomProvider[] rngs = new UniformRandomProvider[10]; 167 * for (int i = 0; i < rngs.length; i++) { 168 * rngs[i] = jumpable.jump(); 169 * } 170 * </code></pre> 171 * <p> 172 * For implementations that have no provision for producing non-overlapping 173 * sequences, a possible workaround is that each thread uses 174 * a generator of a different type (see {@link #TWO_CMRES_SELECT}). 175 * </p> 176 * 177 * @since 1.0 178 */ 179public enum RandomSource { 180 /** 181 * Source of randomness is {@link org.apache.commons.rng.core.source32.JDKRandom}. 182 * <ul> 183 * <li>Native seed type: {@code Long}.</li> 184 * </ul> 185 */ 186 JDK(ProviderBuilder.RandomSourceInternal.JDK), 187 /** 188 * Source of randomness is {@link org.apache.commons.rng.core.source32.Well512a}. 189 * <ul> 190 * <li>Native seed type: {@code int[]}.</li> 191 * <li>Native seed size: 16.</li> 192 * </ul> 193 */ 194 WELL_512_A(ProviderBuilder.RandomSourceInternal.WELL_512_A), 195 /** 196 * Source of randomness is {@link org.apache.commons.rng.core.source32.Well1024a}. 197 * <ul> 198 * <li>Native seed type: {@code int[]}.</li> 199 * <li>Native seed size: 32.</li> 200 * </ul> 201 */ 202 WELL_1024_A(ProviderBuilder.RandomSourceInternal.WELL_1024_A), 203 /** 204 * Source of randomness is {@link org.apache.commons.rng.core.source32.Well19937a}. 205 * <ul> 206 * <li>Native seed type: {@code int[]}.</li> 207 * <li>Native seed size: 624.</li> 208 * </ul> 209 */ 210 WELL_19937_A(ProviderBuilder.RandomSourceInternal.WELL_19937_A), 211 /** 212 * Source of randomness is {@link org.apache.commons.rng.core.source32.Well19937c}. 213 * <ul> 214 * <li>Native seed type: {@code int[]}.</li> 215 * <li>Native seed size: 624.</li> 216 * </ul> 217 */ 218 WELL_19937_C(ProviderBuilder.RandomSourceInternal.WELL_19937_C), 219 /** 220 * Source of randomness is {@link org.apache.commons.rng.core.source32.Well44497a}. 221 * <ul> 222 * <li>Native seed type: {@code int[]}.</li> 223 * <li>Native seed size: 1391.</li> 224 * </ul> 225 */ 226 WELL_44497_A(ProviderBuilder.RandomSourceInternal.WELL_44497_A), 227 /** 228 * Source of randomness is {@link org.apache.commons.rng.core.source32.Well44497b}. 229 * <ul> 230 * <li>Native seed type: {@code int[]}.</li> 231 * <li>Native seed size: 1391.</li> 232 * </ul> 233 */ 234 WELL_44497_B(ProviderBuilder.RandomSourceInternal.WELL_44497_B), 235 /** 236 * Source of randomness is {@link org.apache.commons.rng.core.source32.MersenneTwister}. 237 * <ul> 238 * <li>Native seed type: {@code int[]}.</li> 239 * <li>Native seed size: 624.</li> 240 * </ul> 241 */ 242 MT(ProviderBuilder.RandomSourceInternal.MT), 243 /** 244 * Source of randomness is {@link org.apache.commons.rng.core.source32.ISAACRandom}. 245 * <ul> 246 * <li>Native seed type: {@code int[]}.</li> 247 * <li>Native seed size: 256.</li> 248 * </ul> 249 */ 250 ISAAC(ProviderBuilder.RandomSourceInternal.ISAAC), 251 /** 252 * Source of randomness is {@link org.apache.commons.rng.core.source64.SplitMix64}. 253 * <ul> 254 * <li>Native seed type: {@code Long}.</li> 255 * </ul> 256 */ 257 SPLIT_MIX_64(ProviderBuilder.RandomSourceInternal.SPLIT_MIX_64), 258 /** 259 * Source of randomness is {@link org.apache.commons.rng.core.source64.XorShift1024Star}. 260 * <ul> 261 * <li>Native seed type: {@code long[]}.</li> 262 * <li>Native seed size: 16.</li> 263 * </ul> 264 * 265 * @deprecated Since 1.3, where it is recommended to use {@code XOR_SHIFT_1024_S_PHI} 266 * instead due to its slightly better (more uniform) output. {@code XOR_SHIFT_1024_S} 267 * is still quite usable but both are variants of the same algorithm and maintain their 268 * internal state identically. Their outputs are correlated and the two should not be 269 * used together when independent sequences are assumed. 270 */ 271 @Deprecated 272 XOR_SHIFT_1024_S(ProviderBuilder.RandomSourceInternal.XOR_SHIFT_1024_S), 273 /** 274 * Source of randomness is {@link org.apache.commons.rng.core.source64.TwoCmres}. 275 * This generator is equivalent to {@link #TWO_CMRES_SELECT} with the choice of the 276 * pair {@code (0, 1)} for the two subcycle generators. 277 * <ul> 278 * <li>Native seed type: {@code Integer}.</li> 279 * </ul> 280 */ 281 TWO_CMRES(ProviderBuilder.RandomSourceInternal.TWO_CMRES), 282 /** 283 * Source of randomness is {@link org.apache.commons.rng.core.source64.TwoCmres}, 284 * with explicit selection of the two subcycle generators. 285 * The selection of the subcycle generator is by passing its index in the internal 286 * table, a value between 0 (included) and 13 (included). 287 * The two indices must be different. 288 * Different choices of an ordered pair of indices create independent generators. 289 * <ul> 290 * <li>Native seed type: {@code Integer}.</li> 291 * </ul> 292 */ 293 TWO_CMRES_SELECT(ProviderBuilder.RandomSourceInternal.TWO_CMRES_SELECT), 294 /** 295 * Source of randomness is {@link org.apache.commons.rng.core.source64.MersenneTwister64}. 296 * <ul> 297 * <li>Native seed type: {@code long[]}.</li> 298 * <li>Native seed size: 312.</li> 299 * </ul> 300 */ 301 MT_64(ProviderBuilder.RandomSourceInternal.MT_64), 302 /** 303 * Source of randomness is {@link org.apache.commons.rng.core.source32.MultiplyWithCarry256}. 304 * <ul> 305 * <li>Native seed type: {@code int[]}.</li> 306 * <li>Native seed size: 257.</li> 307 * </ul> 308 */ 309 MWC_256(ProviderBuilder.RandomSourceInternal.MWC_256), 310 /** 311 * Source of randomness is {@link org.apache.commons.rng.core.source32.KISSRandom}. 312 * <ul> 313 * <li>Native seed type: {@code int[]}.</li> 314 * <li>Native seed size: 4.</li> 315 * </ul> 316 */ 317 KISS(ProviderBuilder.RandomSourceInternal.KISS), 318 /** 319 * Source of randomness is {@link org.apache.commons.rng.core.source64.XorShift1024StarPhi}. 320 * <ul> 321 * <li>Native seed type: {@code long[]}.</li> 322 * <li>Native seed size: 16.</li> 323 * </ul> 324 * @since 1.3 325 */ 326 XOR_SHIFT_1024_S_PHI(ProviderBuilder.RandomSourceInternal.XOR_SHIFT_1024_S_PHI), 327 /** 328 * Source of randomness is {@link org.apache.commons.rng.core.source32.XoRoShiRo64Star}. 329 * <ul> 330 * <li>Native seed type: {@code int[]}.</li> 331 * <li>Native seed size: 2.</li> 332 * </ul> 333 * @since 1.3 334 */ 335 XO_RO_SHI_RO_64_S(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_64_S), 336 /** 337 * Source of randomness is {@link org.apache.commons.rng.core.source32.XoRoShiRo64StarStar}. 338 * <ul> 339 * <li>Native seed type: {@code int[]}.</li> 340 * <li>Native seed size: 2.</li> 341 * </ul> 342 * @since 1.3 343 */ 344 XO_RO_SHI_RO_64_SS(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_64_SS), 345 /** 346 * Source of randomness is {@link org.apache.commons.rng.core.source32.XoShiRo128Plus}. 347 * <ul> 348 * <li>Native seed type: {@code int[]}.</li> 349 * <li>Native seed size: 4.</li> 350 * </ul> 351 * @since 1.3 352 */ 353 XO_SHI_RO_128_PLUS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_128_PLUS), 354 /** 355 * Source of randomness is {@link org.apache.commons.rng.core.source32.XoShiRo128StarStar}. 356 * <ul> 357 * <li>Native seed type: {@code int[]}.</li> 358 * <li>Native seed size: 4.</li> 359 * </ul> 360 * @since 1.3 361 */ 362 XO_SHI_RO_128_SS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_128_SS), 363 /** 364 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo128Plus}. 365 * <ul> 366 * <li>Native seed type: {@code long[]}.</li> 367 * <li>Native seed size: 2.</li> 368 * </ul> 369 * @since 1.3 370 */ 371 XO_RO_SHI_RO_128_PLUS(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_128_PLUS), 372 /** 373 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo128StarStar}. 374 * <ul> 375 * <li>Native seed type: {@code long[]}.</li> 376 * <li>Native seed size: 2.</li> 377 * </ul> 378 * @since 1.3 379 */ 380 XO_RO_SHI_RO_128_SS(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_128_SS), 381 /** 382 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo256Plus}. 383 * <ul> 384 * <li>Native seed type: {@code long[]}.</li> 385 * <li>Native seed size: 4.</li> 386 * </ul> 387 * @since 1.3 388 */ 389 XO_SHI_RO_256_PLUS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_256_PLUS), 390 /** 391 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo256StarStar}. 392 * <ul> 393 * <li>Native seed type: {@code long[]}.</li> 394 * <li>Native seed size: 4.</li> 395 * </ul> 396 * @since 1.3 397 */ 398 XO_SHI_RO_256_SS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_256_SS), 399 /** 400 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo512Plus}. 401 * <ul> 402 * <li>Native seed type: {@code long[]}.</li> 403 * <li>Native seed size: 8.</li> 404 * </ul> 405 * @since 1.3 406 */ 407 XO_SHI_RO_512_PLUS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_512_PLUS), 408 /** 409 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo512StarStar}. 410 * <ul> 411 * <li>Native seed type: {@code long[]}.</li> 412 * <li>Native seed size: 8.</li> 413 * </ul> 414 * @since 1.3 415 */ 416 XO_SHI_RO_512_SS(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_512_SS), 417 /** 418 * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgXshRr32}. 419 * <ul> 420 * <li>Native seed type: {@code long[]}.</li> 421 * <li>Native seed size: 2.</li> 422 * </ul> 423 * @since 1.3 424 */ 425 PCG_XSH_RR_32(ProviderBuilder.RandomSourceInternal.PCG_XSH_RR_32), 426 /** 427 * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgXshRs32}. 428 * <ul> 429 * <li>Native seed type: {@code long[]}.</li> 430 * <li>Native seed size: 2.</li> 431 * </ul> 432 * @since 1.3 433 */ 434 PCG_XSH_RS_32(ProviderBuilder.RandomSourceInternal.PCG_XSH_RS_32), 435 /** 436 * Source of randomness is {@link org.apache.commons.rng.core.source64.PcgRxsMXs64}. 437 * <ul> 438 * <li>Native seed type: {@code long[]}.</li> 439 * <li>Native seed size: 2.</li> 440 * </ul> 441 * @since 1.3 442 */ 443 PCG_RXS_M_XS_64(ProviderBuilder.RandomSourceInternal.PCG_RXS_M_XS_64), 444 /** 445 * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgMcgXshRr32}. 446 * <ul> 447 * <li>Native seed type: {@code Long}.</li> 448 * </ul> 449 * @since 1.3 450 */ 451 PCG_MCG_XSH_RR_32(ProviderBuilder.RandomSourceInternal.PCG_MCG_XSH_RR_32), 452 /** 453 * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgMcgXshRs32}. 454 * <ul> 455 * <li>Native seed type: {@code Long}.</li> 456 * </ul> 457 * @since 1.3 458 */ 459 PCG_MCG_XSH_RS_32(ProviderBuilder.RandomSourceInternal.PCG_MCG_XSH_RS_32), 460 /** 461 * Source of randomness is {@link org.apache.commons.rng.core.source32.MiddleSquareWeylSequence}. 462 * <ul> 463 * <li>Native seed type: {@code long[]}.</li> 464 * <li>Native seed size: 3.</li> 465 * </ul> 466 * @since 1.3 467 */ 468 MSWS(ProviderBuilder.RandomSourceInternal.MSWS), 469 /** 470 * Source of randomness is {@link org.apache.commons.rng.core.source32.DotyHumphreySmallFastCounting32}. 471 * <ul> 472 * <li>Native seed type: {@code int[]}.</li> 473 * <li>Native seed size: 3.</li> 474 * </ul> 475 * @since 1.3 476 */ 477 SFC_32(ProviderBuilder.RandomSourceInternal.SFC_32), 478 /** 479 * Source of randomness is {@link org.apache.commons.rng.core.source64.DotyHumphreySmallFastCounting64}. 480 * <ul> 481 * <li>Native seed type: {@code long[]}.</li> 482 * <li>Native seed size: 3.</li> 483 * </ul> 484 * @since 1.3 485 */ 486 SFC_64(ProviderBuilder.RandomSourceInternal.SFC_64), 487 /** 488 * Source of randomness is {@link org.apache.commons.rng.core.source32.JenkinsSmallFast32}. 489 * <ul> 490 * <li>Native seed type: {@code Integer}.</li> 491 * </ul> 492 * @since 1.3 493 */ 494 JSF_32(ProviderBuilder.RandomSourceInternal.JSF_32), 495 /** 496 * Source of randomness is {@link org.apache.commons.rng.core.source64.JenkinsSmallFast64}. 497 * <ul> 498 * <li>Native seed type: {@code Long}.</li> 499 * </ul> 500 * @since 1.3 501 */ 502 JSF_64(ProviderBuilder.RandomSourceInternal.JSF_64), 503 /** 504 * Source of randomness is {@link org.apache.commons.rng.core.source32.XoShiRo128PlusPlus}. 505 * <ul> 506 * <li>Native seed type: {@code int[]}.</li> 507 * <li>Native seed size: 4.</li> 508 * </ul> 509 * @since 1.3 510 */ 511 XO_SHI_RO_128_PP(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_128_PP), 512 /** 513 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo128PlusPlus}. 514 * <ul> 515 * <li>Native seed type: {@code long[]}.</li> 516 * <li>Native seed size: 2.</li> 517 * </ul> 518 * @since 1.3 519 */ 520 XO_RO_SHI_RO_128_PP(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_128_PP), 521 /** 522 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo256PlusPlus}. 523 * <ul> 524 * <li>Native seed type: {@code long[]}.</li> 525 * <li>Native seed size: 4.</li> 526 * </ul> 527 * @since 1.3 528 */ 529 XO_SHI_RO_256_PP(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_256_PP), 530 /** 531 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoShiRo512PlusPlus}. 532 * <ul> 533 * <li>Native seed type: {@code long[]}.</li> 534 * <li>Native seed size: 8.</li> 535 * </ul> 536 * @since 1.3 537 */ 538 XO_SHI_RO_512_PP(ProviderBuilder.RandomSourceInternal.XO_SHI_RO_512_PP), 539 /** 540 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo1024PlusPlus}. 541 * <ul> 542 * <li>Native seed type: {@code long[]}.</li> 543 * <li>Native seed size: 16.</li> 544 * </ul> 545 * @since 1.3 546 */ 547 XO_RO_SHI_RO_1024_PP(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_1024_PP), 548 /** 549 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo1024Star}. 550 * <ul> 551 * <li>Native seed type: {@code long[]}.</li> 552 * <li>Native seed size: 16.</li> 553 * </ul> 554 * @since 1.3 555 */ 556 XO_RO_SHI_RO_1024_S(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_1024_S), 557 /** 558 * Source of randomness is {@link org.apache.commons.rng.core.source64.XoRoShiRo1024StarStar}. 559 * <ul> 560 * <li>Native seed type: {@code long[]}.</li> 561 * <li>Native seed size: 16.</li> 562 * </ul> 563 * @since 1.3 564 */ 565 XO_RO_SHI_RO_1024_SS(ProviderBuilder.RandomSourceInternal.XO_RO_SHI_RO_1024_SS), 566 /** 567 * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgXshRr32}. 568 * <ul> 569 * <li>Native seed type: {@code Long}.</li> 570 * </ul> 571 * @since 1.4 572 */ 573 PCG_XSH_RR_32_OS(ProviderBuilder.RandomSourceInternal.PCG_XSH_RR_32_OS), 574 /** 575 * Source of randomness is {@link org.apache.commons.rng.core.source32.PcgXshRs32}. 576 * <ul> 577 * <li>Native seed type: {@code Long}.</li> 578 * </ul> 579 * @since 1.4 580 */ 581 PCG_XSH_RS_32_OS(ProviderBuilder.RandomSourceInternal.PCG_XSH_RS_32_OS), 582 /** 583 * Source of randomness is {@link org.apache.commons.rng.core.source64.PcgRxsMXs64}. 584 * <ul> 585 * <li>Native seed type: {@code Long}.</li> 586 * </ul> 587 * @since 1.4 588 */ 589 PCG_RXS_M_XS_64_OS(ProviderBuilder.RandomSourceInternal.PCG_RXS_M_XS_64_OS); 590 591 /** Internal identifier. */ 592 private final ProviderBuilder.RandomSourceInternal internalIdentifier; 593 594 /** 595 * @param id Internal identifier. 596 */ 597 RandomSource(ProviderBuilder.RandomSourceInternal id) { 598 internalIdentifier = id; 599 } 600 601 /** 602 * @return the internal identifier. 603 */ 604 ProviderBuilder.RandomSourceInternal getInternalIdentifier() { 605 return internalIdentifier; 606 } 607 608 /** 609 * Checks whether the type of given {@code seed} is the native type 610 * of the implementation. 611 * 612 * @param seed Seed value. 613 * @return {@code true} if the type of {@code seed} is the native 614 * type for this RNG source. 615 */ 616 public boolean isNativeSeed(Object seed) { 617 return internalIdentifier.isNativeSeed(seed); 618 } 619 620 /** 621 * Creates a seed suitable for the implementing class represented by this random source. 622 * 623 * <p>The seed will be created as if passing a {@code null} seed to the method 624 * {@link #create(Object, Object...)}. It will satisfy the seed size and any 625 * other seed requirements for the implementing class. The seed is converted from the native 626 * type to a byte representation.</p> 627 * 628 * <p>Usage example:</p> 629 * <pre><code> 630 * RandomSource source = ...; 631 * byte[] seed = source.createSeed(); 632 * UniformRandomProvider rng = source.create(seed); 633 * </code></pre> 634 * 635 * @return the seed 636 * @since 1.3 637 */ 638 public byte[] createSeed() { 639 return internalIdentifier.createSeedBytes(); 640 } 641 642 /** 643 * Creates a seed suitable for the implementing class represented by this random source 644 * using the supplied source of randomness. 645 * 646 * <p>The seed will satisfy the seed size and any other seed requirements for the 647 * implementing class.</p> 648 * 649 * <p>Usage example:</p> 650 * <pre><code> 651 * RandomSource source = ...; 652 * UniformRandomProvider seedRng = new JDKRandomWrapper(new SecureRandom()); 653 * byte[] seed = source.createSeed(seedRng); 654 * UniformRandomProvider rng = source.create(seed); 655 * </code></pre> 656 * 657 * @param rng Source of randomness. 658 * @return the seed 659 * @since 1.3 660 */ 661 public byte[] createSeed(UniformRandomProvider rng) { 662 return internalIdentifier.createSeedBytes(rng); 663 } 664 665 /** 666 * Checks whether the implementing class represented by this random source 667 * supports the {@link org.apache.commons.rng.JumpableUniformRandomProvider 668 * JumpableUniformRandomProvider} interface. If {@code true} the instance returned 669 * by {@link #create(RandomSource)} may be cast to the interface; otherwise a class 670 * cast exception will occur. 671 * 672 * <p>Usage example:</p> 673 * <pre><code> 674 * RandomSource source = ...; 675 * if (source.isJumpable()) { 676 * JumpableUniformRandomProvider rng = 677 * (JumpableUniformRandomProvider) source.create(); 678 * } 679 * </code></pre> 680 * 681 * @return {@code true} if jumpable 682 * @since 1.3 683 */ 684 public boolean isJumpable() { 685 return isAssignableTo(org.apache.commons.rng.JumpableUniformRandomProvider.class); 686 } 687 688 /** 689 * Checks whether the implementing class represented by this random source 690 * supports the {@link org.apache.commons.rng.LongJumpableUniformRandomProvider 691 * LongJumpableUniformRandomProvider} interface. If {@code true} the instance returned 692 * by {@link #create(RandomSource)} may be cast to the interface; otherwise a class 693 * cast exception will occur. 694 * 695 * <p>Usage example:</p> 696 * <pre><code> 697 * RandomSource source = ...; 698 * if (source.isJumpable()) { 699 * LongJumpableUniformRandomProvider rng = 700 * (LongJumpableUniformRandomProvider) source.create(); 701 * } 702 * </code></pre> 703 * 704 * @return {@code true} if long jumpable 705 * @since 1.3 706 */ 707 public boolean isLongJumpable() { 708 return isAssignableTo(org.apache.commons.rng.LongJumpableUniformRandomProvider.class); 709 } 710 711 /** 712 * Determines if the implementing class represented by this random source is either the same 713 * as, or is a subclass or subinterface of, the class or interface represented 714 * by the specified {@code Class} parameter. It returns true if so; otherwise it returns 715 * false. 716 * 717 * @param type the {@code Class} object to be checked 718 * @return the boolean value indicating whether the class of this random source 719 * can be assigned to objects of the specified type 720 */ 721 private boolean isAssignableTo(Class<?> type) { 722 return type.isAssignableFrom(internalIdentifier.getRng()); 723 } 724 725 /** 726 * Creates a random number generator with a random seed. 727 * 728 * <p>Usage example:</p> 729 * <pre><code> 730 * UniformRandomProvider rng = RandomSource.MT.create(); 731 * </code></pre> 732 * <p>or, if a {@link RestorableUniformRandomProvider "save/restore"} functionality is needed,</p> 733 * <pre><code> 734 * RestorableUniformRandomProvider rng = RandomSource.MT.create(); 735 * </code></pre> 736 * 737 * <p>This method will raise an exception if the generator requires arguments in addition 738 * to a seed (e.g. {@link #TWO_CMRES_SELECT}).</p> 739 * 740 * @return the RNG. 741 * @throws IllegalArgumentException if the generator requires arguments in addition 742 * to a seed. 743 * 744 * @see #create(Object,Object[]) 745 * @since 1.4 746 */ 747 public RestorableUniformRandomProvider create() { 748 return ProviderBuilder.create(getInternalIdentifier()); 749 } 750 751 /** 752 * Creates a random number generator with the given {@code seed}. 753 * 754 * <p>Usage example:</p> 755 * <pre><code> 756 * UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create(0x123abcL); 757 * UniformRandomProvider rng = RandomSource.TWO_CMRES_SELECT.create(26219, 6, 9); 758 * // null seed with arguments 759 * UniformRandomProvider rng = RandomSource.TWO_CMRES_SELECT.create((Object) null, 6, 9); 760 * </code></pre> 761 * 762 * <p>Valid types for the {@code seed} are:</p> 763 * <ul> 764 * <li>{@code Integer} (or {@code int})</li> 765 * <li>{@code Long} (or {@code long})</li> 766 * <li>{@code int[]}</li> 767 * <li>{@code long[]}</li> 768 * <li>{@code byte[]}</li> 769 * </ul> 770 * 771 * <p>Notes:</p> 772 * <ul> 773 * <li> 774 * When the seed type passed as argument is more complex (i.e. more 775 * bits can be independently chosen) than the generator's 776 * {@link #isNativeSeed(Object) native type}, the conversion of a 777 * set of different seeds will necessarily result in the same value 778 * of the native seed type. 779 * </li> 780 * <li> 781 * When the native seed type is an array, the same remark applies 782 * when the array contains more bits than the state of the generator. 783 * </li> 784 * <li> 785 * When the {@code seed} is {@code null}, a seed of the native type 786 * will be generated. If the native type is an array, the generated 787 * size is limited a maximum of 128. 788 * </li> 789 * </ul> 790 * 791 * <p>This method will raise an exception if the additional arguments for 792 * the implementation's constructor are incorrect (e.g. {@link #TWO_CMRES_SELECT}). 793 * This includes the case where arguments are supplied and the implementation 794 * does not require additional arguments.</p> 795 * 796 * @param seed Seed value. It can be {@code null} (in which case a 797 * random value will be used). 798 * @param data Additional arguments to the implementation's constructor. 799 * Please refer to the documentation of each specific implementation. 800 * @return the RNG. 801 * @throws IllegalArgumentException if the argument data required to initialize the 802 * generator is incorrect. 803 * @throws UnsupportedOperationException if the type of the {@code seed} 804 * is invalid. 805 * 806 * @see #create() 807 * @since 1.4 808 */ 809 public RestorableUniformRandomProvider create(Object seed, 810 Object... data) { 811 return ProviderBuilder.create(getInternalIdentifier(), seed, data); 812 } 813 814 /** 815 * Creates a random number generator with a random seed. 816 * 817 * <p>Usage example:</p> 818 * <pre><code> 819 * UniformRandomProvider rng = RandomSource.create(RandomSource.MT); 820 * </code></pre> 821 * <p>or, if a {@link RestorableUniformRandomProvider "save/restore"} functionality is needed,</p> 822 * <pre><code> 823 * RestorableUniformRandomProvider rng = RandomSource.create(RandomSource.MT); 824 * </code></pre> 825 * 826 * <p>This method will raise an exception if the generator requires arguments in addition 827 * to a seed (e.g. {@link #TWO_CMRES_SELECT}).</p> 828 * 829 * @param source RNG type. 830 * @return the RNG. 831 * @throws IllegalArgumentException if the generator requires arguments in addition 832 * to a seed. 833 * 834 * @see #create(RandomSource,Object,Object[]) 835 * @deprecated It is preferred to use the {@link RandomSource#create()} instance method. 836 */ 837 @Deprecated 838 public static RestorableUniformRandomProvider create(RandomSource source) { 839 return ProviderBuilder.create(source.getInternalIdentifier()); 840 } 841 842 /** 843 * Creates a random number generator with the given {@code seed}. 844 * 845 * <p>Usage example:</p> 846 * <pre><code> 847 * UniformRandomProvider rng = RandomSource.create(RandomSource.XO_RO_SHI_RO_128_PP, 0x123abcL); 848 * UniformRandomProvider rng = RandomSource.create(RandomSource.TWO_CMRES_SELECT, 26219, 6, 9); 849 * </code></pre> 850 * 851 * <p>Valid types for the {@code seed} are:</p> 852 * <ul> 853 * <li>{@code Integer} (or {@code int})</li> 854 * <li>{@code Long} (or {@code long})</li> 855 * <li>{@code int[]}</li> 856 * <li>{@code long[]}</li> 857 * <li>{@code byte[]}</li> 858 * </ul> 859 * 860 * <p>Notes:</p> 861 * <ul> 862 * <li> 863 * When the seed type passed as argument is more complex (i.e. more 864 * bits can be independently chosen) than the generator's 865 * {@link #isNativeSeed(Object) native type}, the conversion of a 866 * set of different seeds will necessarily result in the same value 867 * of the native seed type. 868 * </li> 869 * <li> 870 * When the native seed type is an array, the same remark applies 871 * when the array contains more bits than the state of the generator. 872 * </li> 873 * <li> 874 * When the {@code seed} is {@code null}, a seed of the native type 875 * will be generated. If the native type is an array, the generated 876 * size is limited a maximum of 128. 877 * </li> 878 * </ul> 879 * 880 * <p>This method will raise an exception if the additional arguments for 881 * the implementation's constructor are incorrect (e.g. {@link #TWO_CMRES_SELECT}). 882 * This includes the case where arguments are supplied and the implementation 883 * does not require additional arguments.</p> 884 * 885 * @param source RNG type. 886 * @param seed Seed value. It can be {@code null} (in which case a 887 * random value will be used). 888 * @param data Additional arguments to the implementation's constructor. 889 * Please refer to the documentation of each specific implementation. 890 * @return the RNG. 891 * @throws IllegalArgumentException if the argument data required to initialize the 892 * generator is incorrect. 893 * @throws UnsupportedOperationException if the type of the {@code seed} 894 * is invalid. 895 * 896 * @see #create(RandomSource) 897 * @deprecated It is preferred to use the {@link RandomSource#create(Object, Object...)} instance method. 898 */ 899 @Deprecated 900 public static RestorableUniformRandomProvider create(RandomSource source, 901 Object seed, 902 Object... data) { 903 return ProviderBuilder.create(source.getInternalIdentifier(), seed, data); 904 } 905 906 /** 907 * Creates a number for use as a seed. 908 * 909 * @return a random number. 910 */ 911 public static int createInt() { 912 return SeedFactory.createInt(); 913 } 914 915 /** 916 * Creates a number for use as a seed. 917 * 918 * @return a random number. 919 */ 920 public static long createLong() { 921 return SeedFactory.createLong(); 922 } 923 924 /** 925 * Creates an array of numbers for use as a seed. 926 * 927 * @param n Size of the array to create. 928 * @return an array of {@code n} random numbers. 929 */ 930 public static int[] createIntArray(int n) { 931 return SeedFactory.createIntArray(n); 932 } 933 934 /** 935 * Creates an array of numbers for use as a seed. 936 * 937 * @param n Size of the array to create. 938 * @return an array of {@code n} random numbers. 939 */ 940 public static long[] createLongArray(int n) { 941 return SeedFactory.createLongArray(n); 942 } 943 944 /** 945 * Wraps the given {@code delegate} generator in a new instance that 946 * does not allow access to the "save/restore" functionality. 947 * 948 * @param delegate Generator to which calls will be delegated. 949 * @return a new instance whose state cannot be saved or restored. 950 */ 951 public static UniformRandomProvider unrestorable(final UniformRandomProvider delegate) { 952 return new UniformRandomProvider() { 953 /** {@inheritDoc} */ 954 @Override 955 public void nextBytes(byte[] bytes) { 956 delegate.nextBytes(bytes); 957 } 958 959 /** {@inheritDoc} */ 960 @Override 961 public void nextBytes(byte[] bytes, 962 int start, 963 int len) { 964 delegate.nextBytes(bytes, start, len); 965 } 966 967 /** {@inheritDoc} */ 968 @Override 969 public int nextInt() { 970 return delegate.nextInt(); 971 } 972 973 /** {@inheritDoc} */ 974 @Override 975 public int nextInt(int n) { 976 return delegate.nextInt(n); 977 } 978 979 /** {@inheritDoc} */ 980 @Override 981 public long nextLong() { 982 return delegate.nextLong(); 983 } 984 985 /** {@inheritDoc} */ 986 @Override 987 public long nextLong(long n) { 988 return delegate.nextLong(n); 989 } 990 991 /** {@inheritDoc} */ 992 @Override 993 public boolean nextBoolean() { 994 return delegate.nextBoolean(); 995 } 996 997 /** {@inheritDoc} */ 998 @Override 999 public float nextFloat() { 1000 return delegate.nextFloat(); 1001 } 1002 1003 /** {@inheritDoc} */ 1004 @Override 1005 public double nextDouble() { 1006 return delegate.nextDouble(); 1007 } 1008 1009 /** {@inheritDoc} */ 1010 @Override 1011 public String toString() { 1012 return delegate.toString(); 1013 } 1014 }; 1015 } 1016}