Skip to content

Random Module

The py.random standard library module provides relational predicates for random number generation, random selection, and seeding. Uses a module-local PRNG instance to avoid polluting global state.

Purity warning: Random predicates are inherently impure — they produce different results on each call and do not behave consistently under backtracking. A goal like Random(X) will bind X to a new random value each time it is re-entered, which breaks the referential transparency that pure logic programs rely on. Use these predicates at the boundaries of your program (e.g. to generate test data or make stochastic choices) rather than deep inside relational code. For reproducible results, seed the PRNG with RandomSeed/1 before use.

The implementation lives in clausal/modules/py/random.py.

Import

-import_from(py.random, [Random, RandomInteger, RandomMember,
                         RandomPermutation, RandomSample,
                         RandomSeed, Maybe])

Or via module import:

-import_module(py.random)
# then use py.random.Random(X_), py.random.RandomInteger(1, 6, X_), etc.

Predicates

Random/1

Random(X) — bind X to a random float in [0.0, 1.0).

random_unit(X) <- Random(X)

RandomFloat/3

RandomFloat(Low, High, X) — bind X to a random float in [Low, High). Fails if Low >= High or args are unbound.

random_temperature(T) <- RandomFloat(36.0, 42.0, T)

RandomInteger/3

RandomInteger(Low, High, X) — bind X to a random integer in [Low, High] (inclusive both ends).

roll_die(N) <- RandomInteger(1, 6, N)

RandomMember/2

RandomMember(List, X) — bind X to a randomly chosen element of List. Deterministic (one solution). Fails if List is empty or unbound.

pick_color(COLOR) <- RandomMember(["red", "green", "blue"], COLOR)

RandomPermutation/2

RandomPermutation(List, Shuffled) — bind Shuffled to a random permutation of List.

shuffle_deck(DECK, SHUFFLED) <- RandomPermutation(DECK, SHUFFLED)

RandomSample/3

RandomSample(List, K, Sample) — bind Sample to K randomly chosen elements without replacement. Fails if K > length of List.

draw_hand(DECK, HAND) <- RandomSample(DECK, 5, HAND)

RandomSeed/1

RandomSeed(Seed) — set the PRNG seed for reproducibility. Always succeeds (given a ground arg).

deterministic_test(X) <- (RandomSeed(42), Random(X))

Maybe/0, Maybe/1

Maybe — succeeds with probability 0.5, fails otherwise.

Maybe(P) — succeeds with probability P (float in [0.0, 1.0]).

maybe_print(X) <- (Maybe(), writeln(X))

risky_action(X) <- (Maybe(0.1), writeln(X))

Example

-import_from(py.random, [RandomInteger, RandomSeed, RandomMember, Maybe])

roll_die(N) <- RandomInteger(1, 6, N)

pick_color(COLOR) <- RandomMember(["red", "green", "blue"], COLOR)

maybe_greet(NAME) <- (Maybe(), writeln(f"Hello, {NAME}!"))