RunMat
GitHub

View all functions

CategoryArray: Creation
GPUYes

What does the randn function do in MATLAB / RunMat?

randn draws pseudorandom samples from the standard normal distribution (μ = 0, σ = 1). RunMat matches MATLAB call patterns for scalars, explicit dimension lists, size vectors, and 'like' prototypes while honouring GPU residency whenever an acceleration provider is active.

How does the randn function behave in MATLAB / RunMat?

  • randn() returns a scalar double drawn from 𝒩(0, 1).
  • randn(n) returns an n × n dense double matrix.
  • randn(m, n, ...) accepts an arbitrary number of dimension arguments.
  • randn(sz) accepts a size vector (row or column) and returns an array with shape sz.
  • randn(A) or randn(___, 'like', A) matches both the shape and residency of A, including GPU tensors and complex prototypes.
  • Complex prototypes yield complex Gaussian samples with independent 𝒩(0, 1) real and imaginary parts.
  • Class specifiers currently support 'double'; other classes (e.g., 'single') emit descriptive errors until native representations land.

randn Function GPU Execution Behaviour

When the output or 'like' prototype lives on the GPU, RunMat calls into the active acceleration provider via random_normal / random_normal_like. Providers without these hooks fall back to host generation followed by a single upload, ensuring the resulting tensor still resides on device even if samples were produced on the CPU.

Examples of using the randn function in MATLAB / RunMat

Drawing a single standard normal variate

rng(0);
z = randn();

Expected output:

z = 1.8179

Creating a matrix of Gaussian noise

rng(0);
E = randn(2, 3);

Expected output:

E =
    1.8179    0.3895    0.9838
   -1.1645    0.4175    0.1386

Specifying dimensions with a size vector

rng(0);
shape = [2 2 2];
T = randn(shape);

Expected output (pages shown along the third dimension):

T(:, :, 1) =
    1.8179    0.3895
   -1.1645    0.4175

T(:, :, 2) =
    0.9838   -1.1226
    0.1386    2.7430

Matching an existing gpuArray prototype

rng(0);
G = gpuArray.zeros(512, 512);
noise = randn('like', G);
stats = [mean(gather(noise(:))) std(gather(noise(:)))];

Expected output:

size(noise)
ans =
       512   512

stats =
   -0.0009    0.9986

Generating complex Gaussian samples

rng(0);
z = randn(3, 1, 'like', 1 + 1i);

Expected output:

z =
   1.8179 - 1.1645i
   0.3895 + 0.4175i
   0.9838 + 0.1386i

Producing reproducible noise for Monte Carlo tests

rng(0);
samples = randn(1, 5);

Expected output:

samples = [1.8179  -1.1645   0.3895   0.4175   0.9838]

GPU residency in RunMat (Do I need gpuArray?)

You usually do not need to call gpuArray explicitly in RunMat. The fusion planner keeps results on the GPU when downstream work benefits from device residency. However, for MATLAB compatibility—and when you want deterministic control—you can still use gpuArray to seed GPU execution manually.

MathWorks MATLAB lacks an integrated fusion planner and ships GPU acceleration as a separate toolbox, so MATLAB users move data manually. RunMat automates this to streamline accelerated workflows.

FAQ

What distribution does randn use?

randn returns samples from the standard normal distribution with mean 0 and standard deviation 1.

How is randn different from rand?

randn draws from a Gaussian distribution, whereas rand draws from the uniform distribution over (0, 1).

How do I control reproducibility?

Use the MATLAB-compatible rng builtin before calling randn to seed the global generator.

Does randn(___, 'like', A) work with complex prototypes?

Yes. When A is complex, RunMat emits complex Gaussian samples whose real and imaginary parts are independent 𝒩(0, 1) variates.

What happens if I request 'single' precision?

RunMat currently supports double precision. Supplying 'single' raises a descriptive error until native single-precision tensors land.

How does randn behave on the GPU?

If the active acceleration provider implements normal RNG hooks, samples are generated directly on device. Otherwise RunMat produces them on the host, uploads once, and continues execution on the GPU.

Can I request zero-sized dimensions?

Yes. Any dimension argument equal to zero yields an empty array, matching MATLAB semantics.

Does randn fuse with other operations?

No. Random generation is treated as a sink operation and excluded from fusion planning to preserve statistical properties.

See Also

rand, randi, gpuArray, gather

Source & Feedback