net.sf.ivmaidns.util
Class PseudoRandom

java.lang.Object
  extended by net.sf.ivmaidns.util.PseudoRandom
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, ReallyCloneable

public class PseudoRandom
extends java.lang.Object
implements ReallyCloneable, java.io.Serializable

Class for pseudo-random generator. An instance of this class is used to generate a stream of pseudo-random numbers. The class uses a 64-bit mutable seed, which contains 61-bit and 3-bit shift registers (which stand for ((x pow 61) + (x pow 3) + 1) and ((y pow 3) + y + 1) factory polynomes). Each single generated pseudo-random bit is ((x ^ y) & 1), where new x is set to (x * 2 | ((x >> 60) ^ (x >> 2)) & 1) and new y is set to (y * 2 | ((y >> 2) ^ y) & 1), which are the current non-zero values of the 61-bit and 3-bit shift registers, respectively. Such construction of these two shift registers guarantees good (but not cryptographically strong) uniformly distributed pseudo-random bits sequence with the aperiodity length of (((2 pow 61) - 1) * ((2 pow 3) - 1)). Of course, the actual algorithm is supplied with the fixes for zero values of these shift registers (if x is zero then a non-zero constant is added to this seed, if y is zero then it is filled with the first non-zero bits of x). The algorithm of this generator is entirely implemented in nextInt(int) core method, the others use it indirectly. The class also contains a method for generation of normally distributed ('Gaussian') pseudo-random numbers.

Version:
2.0
Author:
Ivan Maidanski
See Also:
UnsignedInt, UnsignedLong, JavaConsts, Serialized Form

Field Summary
protected static int GEN_A_SIZE
          Size of the first 'shift' register in seed (61).
protected static int GEN_B_SIZE
          Size of the second 'shift' register in the lowest part of seed (3).
protected  long seed
          The internal state associated with this pseudo-random number generator.
 
Constructor Summary
PseudoRandom(long initializer)
          Creates a new pseudo-random generator with the predefined initial state.
 
Method Summary
 java.lang.Object clone()
          Creates and returns a copy of this object.
 boolean equals(java.lang.Object obj)
          Indicates whether this object is equal to the specified one.
 int hashCode()
          Returns a hash code value for the object.
 int nextBits(int count)
          Generates and returns the next pseudo-random bits sequence packed into int value.
 void nextBytes(byte[] bytes, int offset, int len)
          Generates pseudo-random bytes and places them into the supplied byte array at the specified offset.
 double nextDouble()
          Generates and returns the next uniformly distributed double pseudo-random number in the range from 0 (inclusive) to 1 (exclusive).
 float nextFloat()
          Generates and returns the next uniformly distributed float pseudo-random number in the range from 0 (inclusive) to 1 (exclusive).
 double nextGaussian()
          Generates and returns the next normally distributed double pseudo-random number.
 int nextInt(int unsignedMax)
          Generates and returns the next uniformly distributed unsigned int pseudo-random number according to the specified maximum.
 long nextLong(long unsignedMax)
          Generates and returns the next uniformly distributed unsigned long pseudo-random number according to the specified maximum.
 long nextLongBits(int count)
          Generates and returns the next pseudo-random bits sequence packed into long value.
 java.lang.String nextName(int len)
          Generates and returns the next pseudo-random (file) name.
 java.lang.String toString()
          Returns the string representation of the object.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

GEN_A_SIZE

protected static final int GEN_A_SIZE
Size of the first 'shift' register in seed (61).

Since:
1.1
See Also:
GEN_B_SIZE, seed, nextInt(int), Constant Field Values

GEN_B_SIZE

protected static final int GEN_B_SIZE
Size of the second 'shift' register in the lowest part of seed (3).

Since:
1.1
See Also:
GEN_A_SIZE, seed, nextInt(int), Constant Field Values

seed

protected long seed
The internal state associated with this pseudo-random number generator. seed (which consists of two shift registers) is initially set by the constructor and modified each time this generator produces a new value. seed may be of any value, which may be modified asynchronously (since the algorithm includes the checks for zero values of any or both shift registers).

See Also:
PseudoRandom(long), clone(), nextInt(int), toString()
Constructor Detail

PseudoRandom

public PseudoRandom(long initializer)
Creates a new pseudo-random generator with the predefined initial state. Initial state (seed) of generator is fully (but not trivially) determined by initializer. Later, this state is altered only by every (direct or indirect) call of nextInt(int). Important notes: if two instances of this class are created with the same value of initializer, and the same sequence of method calls is made for each, they will generate and return identical sequences of numbers (and these instances will be equal); on the other hand, if output reproducibility of a pseudo-random generator is not required then it may be initialized on the current time.

Parameters:
initializer - the long value which fully determines the output pseudo-random bits sequence of the created generator.
See Also:
nextInt(int), clone(), equals(java.lang.Object), toString()
Method Detail

nextInt

public int nextInt(int unsignedMax)
Generates and returns the next uniformly distributed unsigned int pseudo-random number according to the specified maximum. Returned value is drawn from the bits sequence of this random number generator. The unsigned result is uniformly distributed in the range from 0 to unsignedMax, inclusive. All unsignedMax plus one possible int values are produced with (approximately) equal probability. The hedge 'approximately' is used in the foregoing description only because the method is only approximately an unbiased source of independently chosen bits. This is a core method of the generator. This method alters state of this generator. Important notes: synchronization is not needed even outside (unless two or more threads use the same pseudo-random generator constructed with some specified initializer), since seed may be modified in an asynchronous (even non-atomary) way by multiple threads; this method may be overridden in the subclasses.

Parameters:
unsignedMax - the unsigned maximum on the random number to be returned.
Returns:
a pseudo-random, uniformly distributed unsigned int value between 0 and unsignedMax (inclusive).
See Also:
nextBits(int), nextLong(long), nextBytes(byte[], int, int), nextName(int), nextFloat()

nextLong

public long nextLong(long unsignedMax)
Generates and returns the next uniformly distributed unsigned long pseudo-random number according to the specified maximum. This method uses only nextInt(int) core method. The unsigned result is uniformly distributed in the range from 0 to unsignedMax, inclusive. All unsignedMax plus one possible long values are produced with (approximately) equal probability. In fact, this is a secondary 'core' method.

Parameters:
unsignedMax - the unsigned maximum on the random number to be returned.
Returns:
a pseudo-random, uniformly distributed unsigned long value between 0 and unsignedMax (inclusive).
See Also:
nextInt(int), nextDouble(), nextGaussian()

nextBits

public final int nextBits(int count)
Generates and returns the next pseudo-random bits sequence packed into int value. The resulting sequence is in lowest count bits of the returned value (top bits are set to zero). Each bit of the sequence may be 0 or 1 with the equal probability. Negative count is treated as zero. If the sequence is too long (to fit int value) then it is truncated. This method uses only nextInt(int) method.

Parameters:
count - the count of bits to be generated.
Returns:
a packed sequence of pseudo-random bits.
Since:
1.1
See Also:
nextInt(int), nextLongBits(int), nextBytes(byte[], int, int)

nextLongBits

public final long nextLongBits(int count)
Generates and returns the next pseudo-random bits sequence packed into long value. The resulting sequence is in lowest count bits of the returned value (top bits are set to zero). Each bit of the sequence may be 0 or 1 with the equal probability. Negative count is treated as zero. If the sequence is too long (to fit long value) then it is truncated. This method uses only nextLong(long) method.

Parameters:
count - the count of bits to be generated.
Returns:
a packed sequence of pseudo-random bits.
Since:
1.1
See Also:
nextLong(long), nextBits(int), nextBytes(byte[], int, int)

nextBytes

public void nextBytes(byte[] bytes,
                      int offset,
                      int len)
               throws java.lang.NullPointerException,
                      java.lang.ArrayIndexOutOfBoundsException
Generates pseudo-random bytes and places them into the supplied byte array at the specified offset. Each byte is uniformly distributed in all its range. Negative len is treated as zero. If an exception is thrown then generator state and bytes content remain unchanged. This method uses only nextInt(int) core method.

Parameters:
bytes - the byte array (must be non-null and of enough length) in which to put the generated pseudo-random bytes.
offset - the offset (in the supplied byte array) at which to put the generated pseudo-random bytes.
len - the amount of pseudo-random bytes to generate.
Throws:
java.lang.NullPointerException - if bytes is null.
java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of bytes minus len).
See Also:
nextInt(int), nextBits(int), nextLongBits(int), nextName(int)

nextName

public java.lang.String nextName(int len)
Generates and returns the next pseudo-random (file) name. This method is useful for generation of random names for temporary files. The resulting string contains only uniformly distributed characters from the set of '0' through '9' and 'a' through 'z'. Negative len is treated as zero. If an exception is thrown then generator state remains unchanged. This method uses only nextInt(int) core method.

Parameters:
len - the amount of characters to generate.
Returns:
a string (not null, with length() of max(len, 0)), which is just created and contains only the pseudo-random characters from the set denoted above.
Throws:
java.lang.OutOfMemoryError - if there is not enough memory.
Since:
2.0
See Also:
nextInt(int), nextBytes(byte[], int, int)

nextFloat

public final float nextFloat()
Generates and returns the next uniformly distributed float pseudo-random number in the range from 0 (inclusive) to 1 (exclusive). All possible floating-point values from the denoted range are produced with (approximately) equal probability. This method uses only nextInt(int) core method (to fill up the mantissa of the floating-point value).

Returns:
a pseudo-random, uniformly distributed float value between 0 (inclusive) and 1 (exclusive).
See Also:
nextInt(int), nextDouble(), nextGaussian()

nextDouble

public final double nextDouble()
Generates and returns the next uniformly distributed double pseudo-random number in the range from 0 (inclusive) to 1 (exclusive). All possible floating-point values from the denoted range are produced with (approximately) equal probability. This method uses only nextLong(long) method (to fill up the mantissa of the floating-point value).

Returns:
a pseudo-random, uniformly distributed double value between 0 (inclusive) and 1 (exclusive).
See Also:
nextLong(long), nextFloat(), nextGaussian()

nextGaussian

public double nextGaussian()
Generates and returns the next normally distributed double pseudo-random number. Here, so called 'Polar Algorithm' is used to produce normally distributed ('Gaussian') pseudo-random numbers with the standard mean and deviation (mean 0 and deviation 1). The method uses only nextLong(long) method (to fill up the mantissa of the floating-point values), and log(double), sqrt(double) functions of Math class (to compute 'Gaussian' numbers). Important notes: most of all the produced Gaussian numbers are in the range from -6 to 6.

Returns:
a pseudo-random, normally distributed double value with mean 0 and deviation 1.
See Also:
nextDouble(), nextLong(long)

clone

public java.lang.Object clone()
Creates and returns a copy of this object. This method creates a new instance of the class of this object and initializes its seed value with the same as seed value of this object.

Specified by:
clone in interface ReallyCloneable
Overrides:
clone in class java.lang.Object
Returns:
a copy (not null and != this) of this instance.
Throws:
java.lang.OutOfMemoryError - if there is not enough memory.
See Also:
PseudoRandom(long), equals(java.lang.Object)

hashCode

public int hashCode()
Returns a hash code value for the object. This method returns seed value 'squeezed' (hashed) to value of int type.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code value for this object.
See Also:
equals(java.lang.Object)

equals

public boolean equals(java.lang.Object obj)
Indicates whether this object is equal to the specified one. This method returns true if and only if obj is instance of this class and its seed value is the same as seed value of this object.

Overrides:
equals in class java.lang.Object
Parameters:
obj - the object (may be null) with which to compare.
Returns:
true if and only if this value is the same as obj value.
See Also:
PseudoRandom(long), clone(), hashCode()

toString

public java.lang.String toString()
Returns the string representation of the object. This method returns the hexadecimal (with '0x' prefix) zero-padded representation of seed.

Overrides:
toString in class java.lang.Object
Returns:
the string representation (not null, with non-zero length()) of this object.
Throws:
java.lang.OutOfMemoryError - if there is not enough memory.