CodeViking Random Documentation

Random number utility functions and generators. Provides cross-language random number generator compatibility (the same seed will yield the same sequence in all supported languages).

This package currently supports Python 3 only. There is no planned support for Python 2. Patches that provide Python 2 compatibility are welcome.

WARNING: Code and documentation are currently in beta testing. Everything documented here is expected to work, but not all features have been thoroughly tested yet. If you find any bugs, please file a bug report. at https://bitbucket.org/codeviking/python-codeviking.random/

Sphinx Bug The docs for this project can’t be built if any other codeviking.* packages are installed. This is bug in sphinx-apidoc: https://github.com/sphinx-doc/sphinx/issues/1500 As far as I know, the only workaround is uninstalling any codeviking.* packages before building the docs.

Overview

The main utility class In this package is random.RNG. This class provides a number of primitives for generating random int, float, and boolean values, as well as a list/array shuffle method. RNG does not actually generate randomnumbers, it requires an instance of PrimitiveRandomNumberGenerator.

Users that wish to use a custom random number generator simply need to subclass PrimitiveRandomNumberGenerator. Subclasses need to implement the next_int method, and pass the correct value of int_bound to the PrimitiveRandomNumberGenerator constructor.

codeviking.random Package

class RNG(generator_or_seed)[source]

A class that uses a PrimitiveRandomNumberGenerator to provide several higher-level random number generator methods.

__init__(generator_or_seed)[source]

Construct an RNG using the specified generator, if generatorOrSeed is an instance of PrimitiveRandomNumberGenerator. If generator_or_seed is an integer, create a LCG1 using that seed.

b()[source]

return a random boolean: True or False

choose(items)[source]

choose a random element of items.

Parameters:items (Seq) – the items to choose from.
dice(num_dice, die_size)[source]

Roll [num_dice] x [die_size]-sided dice and return the sum.

The dice are what you would expect in the real world: an integer in the range [1,die_size].

exp(beta)[source]

Exponential random deviate.

Parameters:beta (float) – survival parameter. This is the reciprocal of lambda, the rate parameter.
Returns:a random float with an exponential distribution.
Return type:float
f(mx=1.0)[source]

return a random float in the range [0,mx)

f2(half_width=1.0, center=0.0)[source]

Return sum of two uniform random deviates. Result will lie in [center-half_width, center+half_width) and have a triangular distribution with a standard deviation of approximately 0.41*half_width.

Parameters:
  • half_width (float) – half width of the resulting distribution
  • center (float) – the center (mean value) of the distribution
Returns:

random float in the specified region
Return type:

float
f2a(left, center, right)[source]

Return a random deviate in the range [left, right) with peak probability at center. Half of the values will lie to the right of center, and half will le to the left.

Parameters:
  • left (float) – left endpoint of range
  • right (float) – right endpoint of range
  • center (float) – left endpoint of range
Returns:

random float in [left, right)
Return type:

float
f2r(a, b)[source]

Return a random deviate in the range [a, b) with an approximately normal distribution.

Parameters:
  • a (float) – left endpoint of range
  • b (float) – right endpoint of range
Returns:

random float in [a, b)
Return type:

float
f3(half_width=1.0, center=0.0)[source]

Return sum of three uniform random deviates. The result has a distribution similar to a normal distribution, but has a finite range: [center-half_width, center+half_width) and approximate standard deviation 0.33*half_width

Parameters:
  • half_width (float) – half width of the resulting distribution
  • center (float) – the center (mean value) of the distribution
Returns:

random float in the specified region
Return type:

float
f3a(left, center, right)[source]

Return a random deviate in the range [left, right) with peak probability at center. Half of the values will lie to the right of center, and half will le to the left.

Parameters:
  • left (float) – left endpoint of range
  • right (float) – right endpoint of range
  • center (float) – left endpoint of range
Returns:

random float in [left, right)
Return type:

float
f3r(a, b)[source]

Return a random deviate in the range [a, b) with an approximately normal distribution.

Parameters:
  • a (float) – left endpoint of range
  • b (float) – right endpoint of range
Returns:

random float in [a, b)
Return type:

float
f4(half_width=1.0, center=0.0)[source]

Return sum of four uniform random deviates. The result has a distribution similar to a normal distribution, but has a finite range: [center-half_width, center+half_width) and approximate standard deviation 0.29*half_width

Parameters:
  • half_width (float) – half width of the resulting distribution
  • center (float) – the center (mean value) of the distribution
Returns:

random float in the specified region
Return type:

float
f4a(left, center, right)[source]

Return a random deviate in the range [left, right) with peak probability at center. Half of the values will lie to the right of center, and half will le to the left.

Parameters:
  • left (float) – left endpoint of range
  • right (float) – right endpoint of range
  • center (float) – left endpoint of range
Returns:

random float in [left, right)
Return type:

float
f4r(a, b)[source]

Return a random deviate in the range [a, b) with an approximately normal distribution.

Parameters:
  • a (float) – left endpoint of range
  • b (float) – right endpoint of range
Returns:

random float in [a, b)
Return type:

float
f5(half_width=1.0, center=0.0)[source]

Return sum of five uniform random deviates. The result has a distribution similar to a normal distribution, but has a finite range: [center-half_width, center+half_width) and approximate standard deviation 0.26*half_width

Parameters:
  • half_width (float) – half width of the resulting distribution
  • center (float) – the center (mean value) of the distribution
Returns:

random float in the specified region
Return type:

float
f5a(left, center, right)[source]

Return a random deviate in the range [left, right) with peak probability at center. Half of the values will lie to the right of center, and half will le to the left.

Parameters:
  • left (float) – left endpoint of range
  • right (float) – right endpoint of range
  • center (float) – left endpoint of range
Returns:

random float in [left, right)
Return type:

float
f5r(a, b)[source]

Return a random deviate in the range [a, b) with an approximately normal distribution.

Parameters:
  • a (float) – left endpoint of range
  • b (float) – right endpoint of range
Returns:

random float in [a, b)
Return type:

float
f6(half_width=1.0, center=0.0)[source]

Return sum of six uniform random deviates. The result has a distribution similar to a normal distribution, but has a finite range: [center-half_width, center+half_width) and approximate standard deviation 0.24*half_width

Parameters:
  • half_width (float) – half width of the resulting distribution
  • center (float) – the center (mean value) of the distribution
Returns:

random float in the specified region
Return type:

float
f6a(left, center, right)[source]

Return a random deviate in the range [left, right) with peak probability at center. Half of the values will lie to the right of center, and half will le to the left.

Parameters:
  • left (float) – left endpoint of range
  • right (float) – right endpoint of range
  • center (float) – left endpoint of range
Returns:

random float in [left, right)
Return type:

float
f6r(a, b)[source]

Return a random deviate in the range [a, b) with an approximately normal distribution.

Parameters:
  • a (float) – left endpoint of range
  • b (float) – right endpoint of range
Returns:

random float in [a, b)
Return type:

float
fr(mn, mx)[source]

return a random float in the range [mn, mx)

i(mx)[source]

return a random int in the range [0,mx-1]

i_sum(n, r)[source]

generate [n] random ints in the range [0,r) and return the sum.

in_triangle(a, b)[source]

Return a uniformly distributed random point within a right triangle with measurements [a]x[b]. One leg of the triangle lies on the x-axis: [0,a]. The other leg of the triangle lies on the y-axis: [0,b].

Parameters:
  • a (float) – the width of the triangle
  • b (float) – the height of the triangle
Returns:

A point inside the triangle.
Return type:

(float, float)
ir(mn, mx)[source]

return a random int in the range [mn,mx-1]

logistic(mean, scale)[source]

Logistic random deviate.

Parameters:
  • mean (float) – mean value
  • scale (float > 0) – the scale parameter. The variance of the distribution is related to the scale by variance = (scale*pi)**2/3r
Returns:

a random float with a logistic distribution.
Return type:

float
normal(std_dev=1.0)[source]

return a random float with a normal distribution having mean=0.0 and the specified standard deviation.

Parameters:std_dev (float) – the standard deviation of the distribution.
normal_asym(center, left_stddev, right_stddev)[source]

Asymmetric normal distribution. This distribution stretches the left and right sides of the distribution so that the resulting distribution is asymmetric.

Parameters:
  • left_stddev (float) – standard deviation of left half
  • center (float) – the center of the distribution. This is not the same as the mean unless left_stddev == right_stddev.
  • right_stddev (float) – standard deviation of right half
Returns:

random deviate with asymmetric normal distribution.
Return type:

float
shuffle(items)[source]

Shuffle the elements of an array/list. Items is shuffled in-place - no value is returned.

Parameters:items (Seq) – the items to shuffle.
sign()[source]

return a random sign: -1 or +1

Primitive Generators

class PrimitiveRandomNumberGenerator(int_bound)[source]

Abstract Base Class for primitive random number generators. Subclasses need to implement the next_int() method, and provide the correct value for int_bound in the constructor.

__init__(int_bound)[source]
Parameters:int_bound (int) – one greater than the maximum value that next_int can return.
int_bound
Returns:one greater than the maximum value returned by next_int()
Return type:int
next_bool()[source]
Returns:a random boolean
Return type:bool
next_float()[source]
Returns:a random float in the range [0, 1.0)
Return type:float
next_int()[source]

Implement this member in concrete subclasses.

Returns:this generator’s next random integer
Return type:int
scale
Returns:the number to multiply values returned by next_int() to get a float in the range [0.0, 1.0)
Return type:float

Linear Congruential Generators

class LCG(a, m, q, r, seed)[source]

Linear Congruential Random number Generator.

This is the MINSTD linear congruential random number generator. Under no circumstances should you pick a, m, q, r without doing some serious research into random number generation. You absolutely must understand these parameters and how to choose them. There are only a handful of known good combinations. If you choose these parameters carelessly, your RNG will not work properly.

There are a few subclasses provided that use known good parameters.

Note that the seed must be an integer >= 0. This is different from the standard MINSTD generator, which requires an integer > 0. Lots of users seem to like using a seed of zero, so we simply add 1 to the provided seed.

For more info, see:
Stephen K. Park and Keith W. Miller and Paul K. Stockmeyer (1988). “Technical Correspondence”. Communications of the ACM 36 (7): 105–110. doi:10.1145/159544.376068
which is available at:
[http://www.firstpr.com.au/dsp/rand31/p105-crawford.pdf]
class LCG0(seed)[source]

First variant of LCG.

  • a = 16807
  • m = 2147483647
  • q = 127773
  • r = 2836
__init__(seed)[source]
Parameters:seed (int >= 0) – random seed to use
class LCG1(seed)[source]

Second variant of LCG.

  • a = 48271
  • m = 2147483647
  • q = 44488
  • r = 3399
__init__(seed)[source]
Parameters:seed (int >= 0) – random seed to use
class LCG2(seed)[source]

Third variant of LCG.

  • a = 69621
  • m = 2147483647
  • q = 30845
  • r = 23902
__init__(seed)[source]
Parameters:seed (int >= 0) – random seed to use

Indices and tables