D.12.1 mtwist calling conventions

All of the functions in this library simulate a random draw from a distribution. There is a choice of distribution statistics depending on the function used.

bern

takes a floating point number p between 0 and 1, encoded as in math, and returns a boolean value, either (nil,nil) for true or nil for false. A true value is returned only if a random draw from a uniform distribution ranging from 0 to 1 is less than p. This function therefore simulates a draw from a Bernoulli distribution. A nil value of p is treated as 1/2.

u_cont

takes a floating point number x as an argument, and returns a random draw from a continuous uniform distribution ranging from 0 to x. A nil value of x is treated as unity.

u_disc

simulates a draw from a uniform discrete distribution whose domain is the set of natural numbers from 0 to n - 1. The number n is given as a parameter to this function, and the retuned value is the draw.

• The returned value will have at most 64 bits regardless of n.
• Natural numbers are encoded as described in Representation of Numeric and Textual Data.
• If a value of 0 is passed for n, the full 64 bit range is used.

u_path

takes a pair of natural numbers (n,m) and returns a randomly chosen tree (Raw Material) with 1 leaf and n non-leaves each having either a left or a right descendent but not both. The number m constrains the result to fall within the first m - 1 trees of this form enumerated by exhausting all possibilities at lower levels before admitting a right descendent at a higher level. Within these criteria, all possible results are equally probable. Both numbers are masked to 64 bits, but if m is zero, it is treated as 2^n.

u_enum

simulates a random draw from a uniform discrete distribution whose domain is enumerated. The argument to the function is a non-empty list, and the result is an item selected from the list, with all choices being equally probable.

w_disc

simulates a random draw from a non-uniform, or “weighted” discrete distribution whose domain is a set of consecutive natural numbers starting from zero. The argument to the function is a list giving the probability of each outcome starting from zero as a floating point number. Probabilities must be non-negative but needn't be normalized.

w_enum

simulates a random draw from a non-uniform, or “weighted” discrete distribution with an arbitrary domain enumerated in the argument. The argument is a list of pairs <(x,p)..>, where x is a possible outcome and p is its probability. The result returned is one of the values of x from the input list chosen at random according to the associated probability. Probabilities must be non-negative but needn't be normalized.