Random Numbers

Overview

NCL provides two forms of random number generation: a hardware random number generator and a deterministic pseudorandom number generator.

RNG generates random values independently of program state.

PRNG uses an internal 32-bit xorshift state to produce a deterministic sequence of values. The sequence can be controlled using SEED, allowing it to be reproduced when required.

Both generators use max as an exclusive bound extending away from zero.

 max > 0   →   0 through max - 1
 max < 0   →   max + 1 through 0
 max = 0   →   0

Hardware RNG

RNG — Random Number Generation

RNG <dst> <max>

Generates a random integer between zero and the specified exclusive bound and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst Integer register — Destination register.
2 max Integer value — Exclusive random bound.

Modified registers

Register Description
dst Random value.

Examples

-- Generate a value from 0 through 9.
RNG r0 10
-- > r0 is between 0 and 9

-- Generate a value from -9 through 0.
RNG r0 -10
-- > r0 is between -9 and 0

-- A zero bound always produces zero.
RNG r0 0
-- > r0 = 0

Notes

  • max is exclusive.
  • A positive max generates values from 0 upward toward max.
  • A negative max generates values from 0 downward toward max.
  • A max of 0 always produces 0.
  • RNG is independent of the pseudorandom generator and its seed.
  • RNG is intended for general-purpose randomness and is not suitable for cryptographic use.

Pseudorandom RNG

The pseudorandom number generator maintains an internal 32-bit xorshift state.

Unlike general program state, the PRNG state persists between program loads. Starting another program does not reset the generator.

Programs that simply require pseudorandom values may use the existing state. Programs requiring a specific or reproducible sequence should explicitly initialize the generator using SEED.

PRNG — Pseudorandom Number Generation

PRNG <dst> <max>

Generates a pseudorandom integer between zero and the specified exclusive bound and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst Integer register — Destination register.
2 max Integer value — Exclusive random bound.

Modified registers

Register Description
dst Pseudorandom value.

Examples

-- Generate a value from 0 through 99.
PRNG r0 100
-- > r0 is between 0 and 99

-- Generate a value from -99 through 0.
PRNG r0 -100
-- > r0 is between -99 and 0

-- Generate a reproducible sequence.
SEED 12345
PRNG r0 100
PRNG r1 100

-- Restart the same sequence.
SEED 12345
PRNG r2 100
PRNG r3 100

-- > r0 = r2
-- > r1 = r3

Notes

  • max is exclusive.
  • A positive max generates values from 0 upward toward max.
  • A negative max generates values from 0 downward toward max.
  • A max of 0 always produces 0.
  • The generated sequence is deterministic for a given non-zero seed.
  • The PRNG state persists between program loads.
  • Programs should not rely on the PRNG having a particular initial state.
  • Programs requiring reproducible results should explicitly set a non-zero seed before using PRNG.
  • Calling PRNG advances the pseudorandom generator even when max is 0.

SEED — Pseudorandom Seed

SEED <seed>

Sets the internal state used by PRNG.

Operands

Position Name Type Range Description
1 seed Integer value — Pseudorandom seed value.

Modified registers

This instruction does not modify any registers.

Examples

-- Start a repeatable pseudorandom sequence.
SEED 12345
PRNG r0 100
PRNG r1 100
-- > The same seed produces the same sequence each time

-- Select a random seed.
SEED 0
-- > PRNG begins from a randomly selected non-zero state

Notes

  • A non-zero seed directly initializes the pseudorandom generator.
  • Using the same non-zero seed reproduces the same sequence.
  • A seed of 0 selects a random non-zero seed using the hardware RNG.
  • SEED affects only PRNG; it has no effect on RNG.
  • The PRNG state is not automatically reset when another program is loaded.