Random Module

The random module provides pseudorandom number generation for Mux programs. It uses a time-based seed by default, but can be manually seeded for reproducible results.

Import

Mux

Functions

Fallible generation and collection operations return RandomError, with read-only kind and detail fields plus message() and to_string().

Independent generators

Use Random.seeded for a reproducible generator that is independent of the module-level state, or Random.system for a generator seeded from system entropy and the process clock. Seeded generators use a specified SplitMix64 sequence, so the same seed has the same results on every supported platform.

random_object.mux

Random values are explicit shared generators: copying one shares its stream. The object API covers integer, range, float, boolean, byte, normal, and exponential generation. Collection operations are available as module functions below and use the module's thread-local generator.

The module also provides collection operations:

random.choose(list<T>) -> optional<T> returns none for an empty list.
random.shuffle(list<T>) -> void applies Fisher-Yates in place.
random.sample(list<T>, int count) -> result<list<T>, RandomError> samples without replacement.
random.weighted_choice(list<T>, list<float>) -> result<T, RandomError> validates finite, non-negative weights.

weighted_choice also rejects a total weight that overflows to infinity; the total must remain finite and positive.

random.seed

random.seed(int seed) returns void

Initialize the random number generator with a specific seed. Use this when you need reproducible random sequences, such as in testing or simulations.

seed_example.mux

random.next_int

random.next_int() returns int

Generate a random integer between 0 and 2,147,483,647 (inclusive).

The generator auto-initializes with the current time on first use if not explicitly seeded.

dice_roll.mux

random.next_range

random.next_range(int min, int max) returns int

Generate a random integer in the range [min, max). The lower bound is inclusive, the upper bound is exclusive.

Returns min if min >= max.

lottery_numbers.mux

random.next_float

random.next_float() returns float

Generate a random floating-point number in the range [0.0, 1.0).

Useful for probabilities, animations, and scientific calculations.

probability_example.mux

random.next_bool

random.next_bool() returns bool

Generate a random boolean value (true or false) with equal probability (50/50).

coin_flip.mux

random.bytes

random.bytes(int length) returns result<bytes, RandomError>

Generate length pseudorandom bytes from the module generator. A negative length is returned as an error rather than being converted to a huge allocation. Seed the module first when deterministic bytes are required.

random_bytes.mux

random.normal and random.exponential

random.normal(float mean, float standard_deviation) returns result<float, RandomError>
random.exponential(float rate) returns result<float, RandomError>

normal uses a Box-Muller draw and requires a finite, non-negative standard deviation. exponential requires a finite, positive rate. Invalid parameters are returned as errors; a zero normal deviation returns the mean.

Complete Example

random_demo.mux

Implementation Details

The random module uses a custom Linear Congruential Generator (LCG) with the following characteristics:

Thread safety: Module shortcuts use one independent state per thread
Auto-initialization: Seeds automatically with current time if not explicitly seeded
Range distribution: next_range scales the generator's output by the span with a fixed-point multiply. It is intended for simulation and application randomness, not cryptographic use
Float precision: Independent Random objects produce 53 bits of precision

Independent seeded Random objects use SplitMix64 instead of the module LCG so their sequences are portable and reproducible.

For cryptographic applications or high-precision simulations, consider using a specialized library.

Import​

Functions​

Independent generators​

random.seed​

random.next_int​

random.next_range​

random.next_float​

random.next_bool​

random.bytes​

random.normal and random.exponential​

Complete Example​

Implementation Details​