rng — Configure, query, and restore the global pseudorandom number generator state with MATLAB-compatible forms.

rng queries or reconfigures the global pseudorandom number generator used by rand, randn, randi, and randperm. It supports MATLAB-compatible default, seeded, shuffled, and state-restore workflows.

Syntax

s = rng()
s = rng(seed)
s = rng(option)
s = rng(state)
s = rng(seed, generator)
s = rng(option, generator)

Inputs

Returns

Errors

How rng works

• 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 memory and 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

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

Using rng with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how rng changes the result.

FAQ

Related Stats functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how rng is executed, line by line, in Rust.

• View the source for rng in Rust on GitHub
• Learn how the RunMat runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

• RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
• Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing