RunMat
GitHub

View all functions

CategoryStats: Random

rng — Seed, shuffle, and query the global random number generator.

rng queries or reconfigures the global pseudorandom number generator that powers rand, randn, randi, and randperm. RunMat mirrors MATLAB's semantics: you can reset to the default generator, seed with a specific integer, shuffle based on the system clock, or save/restore the full generator state.

How does the rng function behave in MATLAB / RunMat?

  • rng() returns a structure describing the current generator (fields Type, Seed, and State).
  • rng(seed) switches to the default generator with the supplied non-negative integer seed. Passing 0 reproduces MATLAB's rng('default').
  • rng('default') restores the default generator and seed (twister, seed 0).
  • rng('shuffle') seeds the generator with entropy derived from the current time.
  • rng(seed, 'twister') explicitly names the generator. RunMat currently supports twister, matching MATLAB's default stream.
  • rng(S) restores a state structure previously returned by rng. Whenever an acceleration provider is active, RunMat also pushes the new seed to the provider so GPU-resident random calls remain in sync with CPU sampling. Providers that lack set_rng_state simply fall back to their existing behaviour, which is documented below.

GPU residency

RunMat pushes the configured seed to the active acceleration provider whenever rng changes the host generator. Providers that expose set_rng_state (runmat-accelerate's in-process and WGPU backends) therefore produce the same sequences as CPU rand/randn when seeded via rng. If a provider omits this hook, RunMat logs a debug message and continues with the provider's internal seed stream; in that case GPU draws may differ from CPU draws even after calling rng. You do not need to call gpuArray explicitly for residency purposes—RunMat keeps GPU streams in sync automatically whenever the provider supports RNG state injection.

Examples of using rng in MATLAB / RunMat

Resetting the generator for reproducible simulation runs

rng(0);
rand(1, 4)

Expected output:

0.3969    0.8408    0.4221    0.6260

Saving and restoring RNG state around a computation

s = rng;
rng(1337);
A = randn(2, 2);
rng(s);            % restore original stream
B = randn(2, 2);   % continues from the saved state

Expected output:

A =
    0.6406   -0.8022
    0.2222   -0.7161

B =
    0.3969    0.8408
    0.4221    0.6260

Scrambling the generator with the system clock

rng('shuffle');
u = rand(1, 3)

Expected output:

u =
    0.1378    0.7086    0.8463

Keeping CPU and GPU random draws in sync

rng(2024);
G = gpuArray(rand(1, 3));
C = gather(G);
H = rand(1, 3);         % same values as C

Expected output:

C =
    0.6554    0.7501    0.6046

H =
    0.6554    0.7501    0.6046

Creating deterministic permutations with rng and randperm

rng(42);
p = randperm(6);
rng(42);
q = randperm(6)

Expected output:

p =
     6     2     1     4     3     5

q =
     6     2     1     4     3     5

FAQ

What generators does RunMat support?

RunMat currently exposes MATLAB's default 'twister' stream. Additional generators ('philox', 'combRecursive', etc.) will surface as the underlying engines land.

What numeric range is valid for seeds?

Any finite, non-negative integer representable exactly in double precision (0 <= seed <= 2^53) is accepted. Values outside this range produce an error.

How can I force a specific seed for rng('shuffle') in tests?

Set the environment variable RUNMAT_RNG_SHUFFLE_SEED to an unsigned integer before calling rng('shuffle'). RunMat uses that value instead of system time.

Does rng affect GPU random numbers?

Yes—if the active acceleration provider implements set_rng_state. The bundled in-process reference provider and the WGPU backend both honour this hook.

How do I restore a saved state structure?

Pass the structure back to rng: s = rng; ...; rng(s); resumes where the original state left off, matching MATLAB behaviour.

What is stored in the State field?

RunMat serialises the 64-bit internal state into a 1×2 double tensor containing the low and high 32-bit words. Feeding that tensor back to rng recreates the exact state.

Can I create independent streams?

Not yet. RunMat exposes MATLAB-compatible RandStream APIs in a separate roadmap item; for now rng operates on the single global stream.

Does rng change automatically when I call other random functions?

No. Only explicit calls to rng, RandStream, or provider-specific utilities reconfigure the seed. Sampling routines (rand, randn, randperm, etc.) consume the current stream but do not reseed it.

See also

rand, randn, randi, randperm, gpuArray

Source & Feedback