27   * Package info goes here.

    27   * Classes and interfaces that support the definition and use of "random generators", a term that

    28   * is meant to cover what have traditionally been called "random number generators" as well as

    29   * generators of other sorts of randomly chosen values, and also to cover not only deterministic

    30   * (pseudorandom) algorithms but also generators of values that use some "truly random" physical

    31   * source (perhaps making use of thermal noise, for example, or quantum-mechanical effects).

    32   *

    33   * The principal interface is {@link java.util.random.RandomGenerator}, which provides methods

    34   * for requesting individual values of type {@code int}, {@code long}, {@code float}, {@code double}, or {@code boolean}

    35   * chosen (pseudo)randomly from a uniform distribution; methods for requesting values of type {@code double}

    36   * chosen (pseudo)randomly from a normal distribution or from an exponential distribution;

    37   * and methods for creating streams of (pseudo)randomly chosen values of type {@code int}, {@code long}, or {@code double}.

    38   * These streams are spliterator-based, allowing for parallel processing of their elements.

    39   *

    40   * An important subsidiary interface is {@link java.util.random.RandomGenerator.StreamableGenerator},

    41   * which provides methods for creating spliterator-based streams of {@code RandomGenerator} objects,

    42   * allowing for allowing for parallel processing of these objects using multiple threads.

    43   * Unlike {@link java.util.Random}, most implementations of {@code java.util.random.RandomGenerator}

    44   * are <i>not</i> thread-safe.  The intent is that instances should not be shared among threads;

    45   * rather, each thread should have its own random generator(s) to use.  The various pseudorandom algorithms

    46   * provided by this package are designed so that multiple instances will (with very high probability) behave as

    47   * if statistically independent.

    48   *

    49   * Historically, most pseudorandom generator algorithms have been based on some sort of

    50   * finite-state machine with a single, large cycle of states; when it is necessary to have

    51   * multiple threads use the same algorithm simultaneously, the usual technique is to arrange for

    52   * each thread to traverse a different region of the state cycle.  These regions may be doled out

    53   * to threads by starting with a single initial state and then using a "jump function" that

    54   * travels a long distance around the cycle (perhaps 2<sup>64</sup> steps or more); the jump function is applied repeatedly

    55   * and sequentially, to identify widely spaced initial states for each thread's generator.  This strategy is

    56   * supported by the interface {@link java.util.random.RandomGenerator.JumpableGenerator}.

    57   * Sometimes it is desirable to support two levels of jumping (by long distances and

    58   * by <i>really</i> long distances); this strategy is supported by the interface

    59   * {@link java.util.random.RandomGenerator.LeapableGenerator}.  There is also an interface

    60   * {@link java.util.random.RandomGenerator.ArbitrarilyJumpableGenerator} for algorithms that

    61   * allow jumping along the state cycle by any user-specified distance.

    62   * In this package, implementations of these interfaces include

    63   * {@link java.util.random.Xoroshiro128PlusPlus},

    64   * {@link java.util.random.Xoroshiro128StarStar},

    65   * {@link java.util.random.Xoshiro256StarStar},

    66   * and {@link java.util.random.MRG32K3A}.

    67   *

    68   * A more recent category of "splittable" pseudorandom generator algorithms uses a large family

    69   * of state cycles and makes some attempt to ensure that distinct instances use different state

    70   * cycles; but even if two instances "accidentally" use the same state cycle, they are highly

    71   * likely to traverse different regions parts of that shared state cycle.  This strategy is

    72   * supported by the interface {@link java.util.random.RandomGenerator.SplittableGenerator}.

    73   * In this package, implementations of this interface include

    74   * {@link java.util.random.L32X64MixRandom},

    75   * {@link java.util.random.L64X128MixRandom},

    76   * {@link java.util.random.L64X128PlusPlusRandom},

    77   * {@link java.util.random.L64X128StarStarMixRandom},

    78   * {@link java.util.random.L64X256MixRandom},

    79   * {@link java.util.random.L64X1024MixRandom},

    80   * {@link java.util.random.L128X128MixRandom},

    81   * {@link java.util.random.L128X128PlusPlusRandom},

    82   * {@link java.util.random.L128X128StarStarMixRandom},

    83   * {@link java.util.random.L128X256MixRandom},

    84   * {@link java.util.random.L128X1024MixRandom},

    85   * and {@link java.util.SplittableRandom}.

    86   * Generally speaking, among the "{@code LmmmXnnn}" generators, the state size of the generator is

    87   * {@code (mmm - 1 + nnn)} bits and the memory required for an instance is {@code (2 * mmm + nnn)} bits;

    88   * larger values of "{@code mmm}" imply a lower probability that two instances will traverse the

    89   * same state cycle; and larger values of "{@code nnn}" imply that the generator is equidistributed

    90   * in a larger number of dimensions.  A class with "{@code Mix}" in its name uses a strong mixing

    91   * function with excellent avalanche characteristics; a class with "{@code StarStar}" or "{@code PlusPlus}"

    92   * in its name uses a weaker but faster mixing function.  See the documentation for individual classes

    93   * for details about their specific characteristics.

    94   *

    95   * The class {@link java.util.random.RandomSupport} provides utility methods, constants, and

    96   * abstract classes frequently useful in the implementation of pseudorandom number generators

    97   * that satisfy the interface {@link RandomGenerator}.