randn — Generate standard normal random numbers in MATLAB and RunMat.
randn draws pseudorandom samples from the standard normal distribution (μ = 0, σ = 1). Size forms and 'like' behavior follow MATLAB semantics.
Syntax
A = randn()
A = randn(n)
A = randn(size_vector)
A = randn(m, n, ...)
A = randn(..., typename)
A = randn(..., "like", prototype)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
n | SizeArg | Yes | — | Square size. |
size_vector | SizeArg | Yes | — | Size vector defining output dimensions. |
dims | SizeArg | Variadic | — | Dimension sizes. |
typename | StringScalar | No | "double" | Class override ('double'|'single'|'gpuArray'). |
like_kw | StringScalar | Yes | "like" | Like keyword. |
prototype | LikePrototype | Yes | — | Prototype array used for class/device. |
Returns
| Name | Type | Description |
|---|---|---|
A | NumericArray | Normal random array (mean 0, variance 1). |
Errors
| Identifier | When | Message |
|---|---|---|
| — | The 'like' keyword is provided without a prototype argument. | randn: expected prototype after 'like' |
| — | A trailing option string is not supported. | randn: unrecognised option |
| — | A prototype type cannot be used for randn(..., 'like', prototype). | randn: unsupported prototype |
| — | Dimension arguments fail numeric/shape parsing. | randn: dimension arguments must be numeric and nonnegative |
How randn works
randn()returns a scalar double drawn from𝒩(0, 1).randn(n)returns ann × ndense double matrix.randn(m, n, ...)accepts an arbitrary number of dimension arguments.randn(sz)accepts a documented row size vector; a column size vector is an independently gated RunMat-mode extension.- All eight integer classes are documented for scalar, separate-dimension, and row-size-vector controls and are decoded structurally from authoritative storage; resident size controls are separately gated RunMat extensions.
randn(___, 'like', A)matches the type, complexity, and residency ofA, while ordinary size arguments determine shape and omission of size arguments returns a scalar. The old implicitrandn(A)prototype form is not supported.- Complex prototypes yield complex Gaussian samples with independent
𝒩(0, 1)real and imaginary parts. - Class specifiers support native
'single'and'double'; integer and logical output prototypes are rejected before generation.
Does RunMat run randn on the GPU?
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.
GPU memory and residency
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.
Examples
Drawing a single standard normal variate
rng(0);
z = randn()Expected output:
z = 1.8179Creating 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.1386Specifying dimensions with a size vector
rng(0);
shape = [2 2 2];
T = randn(shape)Expected output:
T(:, :, 1) =
1.8179 0.3895
-1.1645 0.4175
T(:, :, 2) =
0.9838 -1.1226
0.1386 2.7430Matching 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.9986Generating 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.1386iProducing 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]Using randn with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how randn changes the result.
Run a small randn example, explain the result, then change one input and compare the output.
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 returns a native single-precision tensor. GPU generation uses a matching provider path when available and otherwise preserves single precision through the fallback.
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.
Related Array functions
Creation
colon · createArray · empty · eye · false · full · inf · linspace · logspace · magic · meshgrid · nan · nchoosek · ndgrid · nonzeros · ones · peaks · perms · rand · randi · randperm · range · sparse · spdiags · speye · spones · sprand · true · zeros
Grouping
accumarray · combinations · discretize · findgroups · groupcounts · grp2idx · splitapply
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how randn is executed, line by line, in Rust.
- View the source for randn 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.