The Machines · Runtime stack

seedrandom

A reckoner seed: random, plus the SEED builtin — machines/seeds/seedrandom.shoddy

Summary

seedrandom is a reckoner seed: the file that bridges random's words into the calculator. It carries RANDOM RANDOMRANGE RANDOMINT SHUFFLE SAMPLE, plus SEED. random.shoddy calls itself "seedless by construction", and that is true of the machine. (A seed in that sense is a starting number for the random generator, a different thing from this bridge file.) The machine never calls the runtime's Seed builtin, so nothing in it threads such a number through a program. But the builtin the runtime itself provides — Rnd's own generator, reseedable in one call — is exactly what a reproducible test session needs. It costs nothing to reach: Seed(n) is a builtin, callable with no Include at all, on the same footing Pi() and Rnd() stand on.

Why It's Useful

RANDOMRANGE and RANDOMINT refuse when hi is below lo. That check runs here, before the machine is ever reached. RANDOM, SHUFFLE and SEED are total — they have an answer for every input, so they need no guard. SAMPLE is already total in random.shoddy itself. An n at or below zero, or an empty list, answers empty. An n at or past the list's length answers every element, shuffled. So the only thing SAMPLE's word guards is that n arrived as a whole number. The underlying walk assumes that but never checks it.

Every word here touches the world. Calling RANDOM twice with the same arguments gives two different answers on purpose. That makes it an effect — an action on the outside world, exactly as reading a clock or a file is one. SEED is the strongest effect of all, since it changes what every later draw in the session answers.

User's Guide

Let st0 = RckSeedRandom(RckNew())
RckEval(st0, "42 SEED")                      ' ok: reproducible from here
RckEval(st0, "1 6 RANDOMINT")                ' x: the same value every run after a SEED
RckEval(st0, "{ 1 2 3 4 5 } SHUFFLE")        ' x: the list in a fresh random order
RckEval(st0, "{ 1 2 3 4 5 } 2 SAMPLE")       ' x: 2 distinct elements, random order

Word Reference

Word	Description
RANDOM ( -- x )	A fresh random number in [0, 1).
RANDOMRANGE ( lo hi -- x )	A fresh random number in [lo, hi); refuses hi below lo.
RANDOMINT ( lo hi -- n )	A fresh random whole number from lo to hi, both inclusive; refuses hi below lo.
SHUFFLE ( list -- list )	The list in a fresh random order.
SAMPLE ( list n -- list )	n distinct elements of the list without replacement, random order; every element, shuffled, when n is at or past its length.
SEED ( n -- )	Reseed RND so RANDOM, RANDOMRANGE, RANDOMINT, SHUFFLE and SAMPLE answer reproducibly from here.

Who Uses It

	User	How
	halifax	The calculator's randomness words: RANDOM, RANDOMRANGE, RANDOMINT, SHUFFLE, SAMPLE and SEED.
	sparky	Sparky folds it too, so a model calling eval reaches the same words halifax puts at a prompt.

A mill claims this seed by folding RckSeedRandom over its reckoner state, which is all halifax does.

The Machines It Uses

	Machine	Why
	cuttle	The Cell type every word here reads and answers.
	random	The domain this seed bridges: Random, RandomRange, RandomInt, Shuffle and Sample.
	reckoner	RckReg, RckSeeding and the argument readers every registered word is built from.