Package com.github.tommyettinger.random

Class DistributedRandom

java.lang.Object
java.util.Random
com.github.tommyettinger.random.EnhancedRandom
com.github.tommyettinger.random.DistributedRandom
All Implemented Interfaces:
Externalizable, Serializable, RandomGenerator
public class DistributedRandom extends EnhancedRandom
An EnhancedRandom that delegates to a Distribution to distribute any floats, ints, or doubles as by that distribution.
See Also:

  • Field Details

  • Constructor Details

    • DistributedRandom

      public DistributedRandom()

    • DistributedRandom

      public DistributedRandom(long seed)

    • DistributedRandom

      public DistributedRandom(EnhancedRandom random)
      Creates a DistributedRandom that follows a ContinuousUniformDistribution, limiting its results using DistributedRandom.ReductionMode.FRACTION, and uses a direct reference to the given EnhancedRandom. You can copy the EnhancedRandom if you want it to change independently of the original EnhancedRandom, using EnhancedRandom.copy(). This is probably not very useful on its own, since you will probably want to change the distribution (using setDistribution(Distribution)), and that also changes the EnhancedRandom that was assigned here.
      Parameters:
      random - referenced directly; if you don't want this, use a EnhancedRandom.copy()

    • DistributedRandom

      public DistributedRandom(long stateA, long stateB, long stateC, long stateD)

    • DistributedRandom

      public DistributedRandom(Distribution distribution, DistributedRandom.ReductionMode reductionMode)

    • DistributedRandom

      public DistributedRandom(Distribution distribution, DistributedRandom.ReductionMode reductionMode, long seed)

    • DistributedRandom

      public DistributedRandom(Distribution distribution, DistributedRandom.ReductionMode reductionMode, EnhancedRandom random)
      Creates a DistributedRandom that follows the given Distribution (copied), limiting its results using the given ReductionMode, and uses a direct reference to the given EnhancedRandom. You can copy the EnhancedRandom if you want it to change independently of the original EnhancedRandom, using EnhancedRandom.copy().
      Parameters:
      distribution - a Distribution that will be copied; the copy's generator will be reassigned.
      reductionMode - how to reduce values outside the 0 to 1 range, as an enum constant
      random - referenced directly; if you don't want this, use a EnhancedRandom.copy()

    • DistributedRandom

      public DistributedRandom(Distribution distribution, DistributedRandom.ReductionMode reductionMode, long stateA, long stateB, long stateC, long stateD)

  • Method Details

    • getTag

      public String getTag()
      Description copied from class: EnhancedRandom
      Gets the tag used to identify this type of EnhancedRandom, as a String. This tag should be unique, and for uniformity purposes, all tags used in this library are 4 characters long. User-defined tags should have a different length.
      Specified by:
      getTag in class EnhancedRandom
      Returns:
      a unique String identifier for this type of EnhancedRandom; usually 4 chars long.

    • getReduction

      public DistributedRandom.ReductionMode getReduction()

    • setReduction

      public void setReduction(DistributedRandom.ReductionMode reduction)

    • nextLong

      public long nextLong()
      Description copied from class: EnhancedRandom
      Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence. The general contract of nextLong is that one long value is pseudorandomly generated and returned.
      The only methods that need to be implemented by this interface are this and EnhancedRandom.copy(), though other methods can be implemented as appropriate for generators that, for instance, natively produce ints rather than longs.
      Specified by:
      nextLong in interface RandomGenerator
      Specified by:
      nextLong in class EnhancedRandom
      Returns:
      the next pseudorandom, uniformly distributed long value from this random number generator's sequence

    • next

      public int next(int bits)
      Description copied from class: EnhancedRandom
      Generates the next pseudorandom number with a specific maximum size in bits (not a max number). If you want to get a random number in a range, you should usually use EnhancedRandom.nextInt(int) instead. For some specific cases, this method is more efficient and less biased than EnhancedRandom.nextInt(int). For bits values between 1 and 30, this should be similar in effect to nextInt(1 << bits); though it won't typically produce the same values, they will have the correct range. If bits is 31, this can return any non-negative int; note that nextInt(1 << 31) won't behave this way because 1 << 31 is negative. If bits is 32 (or 0), this can return any int.

      The general contract of next is that it returns an int value and if the argument bits is between 1 and 32 (inclusive), then that many low-order bits of the returned value will be (approximately) independently chosen bit values, each of which is (approximately) equally likely to be 0 or 1.

      Note that you can give this values for bits that are outside its expected range of 1 to 32, but the value used, as long as bits is positive, will effectively be bits % 32. As stated before, a value of 0 for bits is the same as a value of 32.

      Overrides:
      next in class EnhancedRandom
      Parameters:
      bits - the amount of random bits to request, from 1 to 32
      Returns:
      the next pseudorandom value from this random number generator's sequence

    • nextDouble

      public double nextDouble()
      Description copied from class: EnhancedRandom
      Returns the next pseudorandom, uniformly distributed double value between 0.0 (inclusive) and 1.0 (exclusive) from this random number generator's sequence.

      The general contract of nextDouble is that one double value, chosen (approximately) uniformly from the range 0.0d (inclusive) to 1.0d (exclusive), is pseudorandomly generated and returned.

      The public implementation uses the upper 53 bits of EnhancedRandom.nextLong(), with an unsigned right shift and a multiply by a very small double (1.1102230246251565E-16, or 0x1p-53). It should perform well if nextLong() performs well, and is expected to perform less well if the generator naturally produces 32 or fewer bits at a time.

      Specified by:
      nextDouble in interface RandomGenerator
      Overrides:
      nextDouble in class EnhancedRandom
      Returns:
      the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence

    • nextFloat

      public float nextFloat()
      Description copied from class: EnhancedRandom
      Returns the next pseudorandom, uniformly distributed float value between 0.0 (inclusive) and 1.0 (exclusive) from this random number generator's sequence.

      The general contract of nextFloat is that one float value, chosen (approximately) uniformly from the range 0.0f (inclusive) to 1.0f (exclusive), is pseudorandomly generated and returned. All 224 possible float values of the form m x 2-24, where m is a positive integer less than 224, are produced with (approximately) equal probability.

      The public implementation uses the upper 24 bits of EnhancedRandom.nextLong(), with an unsigned right shift and a multiply by a very small float (5.9604645E-8f or 0x1p-24f). It tends to be fast if nextLong() is fast, but alternative implementations could use 24 bits of EnhancedRandom.nextInt() (or just EnhancedRandom.next(int), giving it 24) if that generator doesn't efficiently generate 64-bit longs.

      Specified by:
      nextFloat in interface RandomGenerator
      Overrides:
      nextFloat in class EnhancedRandom
      Returns:
      the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence

    • nextBytes

      public void nextBytes(byte[] bytes)
      Description copied from class: EnhancedRandom
      Generates random bytes and places them into a user-supplied byte array. The number of random bytes produced is equal to the length of the byte array.
      Specified by:
      nextBytes in interface RandomGenerator
      Overrides:
      nextBytes in class EnhancedRandom
      Parameters:
      bytes - the byte array to fill with random bytes

    • nextInt

      public int nextInt()
      Description copied from class: EnhancedRandom
      Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence. The general contract of nextInt is that one int value is pseudorandomly generated and returned. All 232 possible int values are produced with (approximately) equal probability.
      Specified by:
      nextInt in interface RandomGenerator
      Overrides:
      nextInt in class EnhancedRandom
      Returns:
      the next pseudorandom, uniformly distributed int value from this random number generator's sequence

    • nextInt

      public int nextInt(int bound)
      Description copied from class: EnhancedRandom
      Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract of nextInt is that one int value in the specified range is pseudorandomly generated and returned. All bound possible int values are produced with (approximately) equal probability.
      This method clamps bound to be at least 0; it never returns a negative int.
      It should be mentioned that the technique this uses has some bias, depending on bound, but it typically isn't measurable without specifically looking for it. Using the method this does allows this method to always advance the state by one step, instead of a varying and unpredictable amount with the more typical ways of rejection-sampling random numbers and only using numbers that can produce an int within the bound without bias. See M.E. O'Neill's blog about random numbers for discussion of alternative, unbiased methods.
      Specified by:
      nextInt in interface RandomGenerator
      Overrides:
      nextInt in class EnhancedRandom
      Parameters:
      bound - the upper bound (exclusive). If negative or 0, this always returns 0.
      Returns:
      the next pseudorandom, uniformly distributed int value between zero (inclusive) and bound (exclusive) from this random number generator's sequence

    • nextSignedInt

      public int nextSignedInt(int outerBound)
      Description copied from class: EnhancedRandom
      Returns a pseudorandom, uniformly distributed int value between an inner bound of 0 (inclusive) and the specified outerBound (exclusive). This is meant for cases where the outer bound may be negative, especially if the bound is unknown or may be user-specified. A negative outer bound is used as the lower bound; a positive outer bound is used as the upper bound. An outer bound of -1, 0, or 1 will always return 0, keeping the bound exclusive (except for outer bound 0). This method is slightly slower than EnhancedRandom.nextInt(int).
      Overrides:
      nextSignedInt in class EnhancedRandom
      Parameters:
      outerBound - the outer exclusive bound; may be any int value, allowing negative
      Returns:
      a pseudorandom int between 0 (inclusive) and outerBound (exclusive)
      See Also:

    • nextBoolean

      public boolean nextBoolean()
      Description copied from class: EnhancedRandom
      Returns the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence. The general contract of nextBoolean is that one boolean value is pseudorandomly generated and returned. The values true and false are produced with (approximately) equal probability.
      The public implementation simply returns a sign check on EnhancedRandom.nextLong(), returning true if the generated long is negative. This is typically the safest way to implement this method; many types of generators have less statistical quality on their lowest bit, so just returning based on the lowest bit isn't always a good idea.
      Specified by:
      nextBoolean in interface RandomGenerator
      Overrides:
      nextBoolean in class EnhancedRandom
      Returns:
      the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence

    • nextGaussian

      public double nextGaussian()
      This runs Distributor.probit(double) on a distributed double this produces.
      Specified by:
      nextGaussian in interface RandomGenerator
      Overrides:
      nextGaussian in class EnhancedRandom
      Returns:
      a "Gaussian-ized" result of nextDouble()

    • nextExclusiveDouble

      public double nextExclusiveDouble()
      This does not use the optimizations from EnhancedRandom.nextExclusiveDouble(), because those aren't reasonable when distributed.
      Overrides:
      nextExclusiveDouble in class EnhancedRandom
      Returns:
      a pseudo-random double between 0.0, exclusive, and 1.0, exclusive

    • nextExclusiveSignedDouble

      public double nextExclusiveSignedDouble()
      This differs from the implementation used by other EnhancedRandom types in that the distribution applies to the (0,1) range as normal, but half the time this will negate that distribution, so it is on (-1,0) and the high and low ends are reversed. For example, if you use DistributedRandom.ReductionMode.REJECT on an ExponentialDistribution, which normally has most of its results near 0 and few near 1, then the results will still have most near 0, few near 1, and equally few near -1.
      Overrides:
      nextExclusiveSignedDouble in class EnhancedRandom
      Returns:
      a random uniform double between -1 and 1 with a tiny hole around 0 (all exclusive)

    • nextExclusiveFloat

      public float nextExclusiveFloat()
      This acts the same as EnhancedRandom.nextExclusiveFloatEquidistant(); it does not use the optimizations from EnhancedRandom.nextExclusiveFloat(), because those aren't reasonable when distributed.
      Overrides:
      nextExclusiveFloat in class EnhancedRandom
      Returns:
      a pseudo-random float between 0.0, exclusive, and 1.0, exclusive

    • nextExclusiveSignedFloat

      public float nextExclusiveSignedFloat()
      This differs from the implementation used by other EnhancedRandom types in that the distribution applies to the (0,1) range as normal, but half the time this will negate that distribution, so it is on (-1,0) and the high and low ends are reversed. For example, if you use DistributedRandom.ReductionMode.REJECT on an ExponentialDistribution, which normally has most of its results near 0 and few near 1, then the results will still have most near 0, few near 1, and equally few near -1.
      Overrides:
      nextExclusiveSignedFloat in class EnhancedRandom
      Returns:
      a random uniform float between -1 and 1 with a tiny hole around 0 (all exclusive)

    • copy

      public DistributedRandom copy()
      Description copied from class: EnhancedRandom
      Creates a new EnhancedRandom with identical states to this one, so if the same EnhancedRandom methods are called on this object and its copy (in the same order), the same outputs will be produced. This is not guaranteed to copy the inherited state of any parent class, so if you call methods that are only implemented by a superclass (like Random) and not this one, the results may differ.
      Specified by:
      copy in class EnhancedRandom
      Returns:
      a deep copy of this EnhancedRandom.

    • setState

      public void setState(long stateA)
      Description copied from class: EnhancedRandom
      Sets each state variable to the given state. If EnhancedRandom.getStateCount() is 1, then this should set the whole state to the given value using EnhancedRandom.setSelectedState(int, long). If getStateCount() is more than 1, then all states will be set in the same way (using setSelectedState(), all to state).
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for each state variable

    • setState

      public void setState(long stateA, long stateB)
      Description copied from class: EnhancedRandom
      Sets each state variable to either stateA or stateB, alternating. This uses EnhancedRandom.setSelectedState(int, long) to set the values. If there is one state variable (EnhancedRandom.getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. If there are more, it reuses stateA, then stateB, then stateA, and so on until all variables are set.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 2, 4, 6...
      stateB - the long value to use for states at index 1, 3, 5, 7...

    • setState

      public void setState(long stateA, long stateB, long stateC)
      Description copied from class: EnhancedRandom
      Sets each state variable to stateA, stateB, or stateC, alternating. This uses EnhancedRandom.setSelectedState(int, long) to set the values. If there is one state variable (EnhancedRandom.getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. If there are more, it reuses stateA, then stateB, then stateC, then stateA, and so on until all variables are set.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 3, 6, 9...
      stateB - the long value to use for states at index 1, 4, 7, 10...
      stateC - the long value to use for states at index 2, 5, 8, 11...

    • setState

      public void setState(long stateA, long stateB, long stateC, long stateD)
      Description copied from class: EnhancedRandom
      Sets each state variable to stateA, stateB, stateC, or stateD, alternating. This uses EnhancedRandom.setSelectedState(int, long) to set the values. If there is one state variable (EnhancedRandom.getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. With four state variables, the first is set to stateA, the second to stateB, the third to stateC, and the fourth to stateD. If there are more, it reuses stateA, then stateB, then stateC, then stateD, then stateA, and so on until all variables are set.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 4, 8, 12...
      stateB - the long value to use for states at index 1, 5, 9, 13...
      stateC - the long value to use for states at index 2, 6, 10, 14...
      stateD - the long value to use for states at index 3, 7, 11, 15...

    • getStateCount

      public int getStateCount()
      Description copied from class: EnhancedRandom
      Gets the number of possible state variables that can be selected with EnhancedRandom.getSelectedState(int) or EnhancedRandom.setSelectedState(int, long). This defaults to returning 0, making no state variable available for reading or writing. An implementation that has only one long state, like DistinctRandom generator, should return 1. A generator that permits setting two different long values, like LaserRandom, should return 2. Much larger values are possible for types like the Mersenne Twister or some CMWC generators.
      Overrides:
      getStateCount in class EnhancedRandom
      Returns:
      the non-negative number of selections possible for state variables

    • getSelectedState

      public long getSelectedState(int selection)
      Description copied from class: EnhancedRandom
      Gets a selected state value from this EnhancedRandom. The number of possible selections is up to the implementing class, and is accessible via EnhancedRandom.getStateCount(), but negative values for selection are typically not tolerated. This should return the exact value of the selected state, assuming it is implemented. The default implementation throws an UnsupportedOperationException, and implementors only have to allow reading the state if they choose to implement this differently. If this method is intended to be used, EnhancedRandom.getStateCount() must also be implemented.
      Overrides:
      getSelectedState in class EnhancedRandom
      Parameters:
      selection - used to select which state variable to get; generally non-negative
      Returns:
      the exact value of the selected state

    • setSelectedState

      public void setSelectedState(int selection, long value)
      Description copied from class: EnhancedRandom
      Sets a selected state value to the given long value. The number of possible selections is up to the implementing class, but negative values for selection are typically not tolerated. Implementors are permitted to change value if it is not valid, but they should not alter it if it is valid. The public implementation calls EnhancedRandom.setSeed(long) with value, which doesn't need changing if the generator has one state that is set verbatim by setSeed(). Otherwise, this method should be implemented when EnhancedRandom.getSelectedState(int) is and the state is allowed to be set by users. Having accurate ways to get and set the full state of a random number generator makes it much easier to serialize and deserialize that class.
      Overrides:
      setSelectedState in class EnhancedRandom
      Parameters:
      selection - used to select which state variable to set; generally non-negative
      value - the exact value to use for the selected state, if valid

    • setSeed

      public void setSeed(long seed)
      Description copied from class: EnhancedRandom
      Sets the seed of this random number generator using a single long seed. This should behave exactly the same as if a new object of this type was created with the constructor that takes a single long value. This does not necessarily assign the state variable(s) of the implementation with the exact contents of seed, so EnhancedRandom.getSelectedState(int) should not be expected to return seed after this, though it may. If this implementation has more than one long of state, then the expectation is that none of those state variables will be exactly equal to seed (almost all the time).
      Specified by:
      setSeed in class EnhancedRandom
      Parameters:
      seed - the initial seed

    • getDistribution

      public Distribution getDistribution()

    • setDistribution

      public void setDistribution(Distribution distribution)

    • getRandom

      public EnhancedRandom getRandom()

    • setRandom

      public void setRandom(EnhancedRandom random)

    • stringSerialize

      public String stringSerialize(com.github.tommyettinger.digital.Base base)
      Description copied from class: EnhancedRandom
      Serializes the current state of this EnhancedRandom to a String that can be used by EnhancedRandom.stringDeserialize(String) to load this state at another time.
      Overrides:
      stringSerialize in class EnhancedRandom
      Parameters:
      base - which Base to use, from the "digital" library, such as Base.BASE10
      Returns:
      this, for chaining

    • stringDeserialize

      public DistributedRandom stringDeserialize(String data, com.github.tommyettinger.digital.Base base)
      Description copied from class: EnhancedRandom
      Given a String in the format produced by EnhancedRandom.stringSerialize(Base), and the same Base used by the serialization, this will attempt to set this EnhancedRandom object to match the state in the serialized data. This only works if this EnhancedRandom is the same implementation that was serialized, and also needs the Bases to be identical. Returns this EnhancedRandom, after possibly changing its state.
      Overrides:
      stringDeserialize in class EnhancedRandom
      Parameters:
      data - a String probably produced by stringSerialize(Base)
      base - which Base to use, from the "digital" library, such as Base.BASE10
      Returns:
      this, for chaining

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Needs the type of distribution registered.
      Specified by:
      writeExternal in interface Externalizable
      Overrides:
      writeExternal in class EnhancedRandom
      Parameters:
      out - the stream to write the object to
      Throws:
      IOException - Includes any I/O exceptions that may occur

    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal.
      Specified by:
      readExternal in interface Externalizable
      Overrides:
      readExternal in class EnhancedRandom
      Parameters:
      in - the stream to read data from in order to restore the object
      Throws:
      IOException - if I/O errors occur
      ClassNotFoundException

    • toString

      public String toString()
      Overrides:
      toString in class Object