RunMat
GitHub

View all functions

CategoryMath: Reduction
GPUYes

What does the var function do in MATLAB / RunMat?

var(x) measures the spread of the elements in x by returning their variance. By default, RunMat matches MATLAB’s sample definition (dividing by n-1) and works along the first non-singleton dimension.

How does the var function behave in MATLAB / RunMat?

  • var(X) on an m × n matrix returns a 1 × n row vector with the sample variance of each column.
  • var(X, 1) switches to population normalisation (n in the denominator). Use var(X, 0) or var(X, []) to keep the default sample behaviour.
  • var(X, flag, dim) lets you pick both the normalisation (flag = 0 sample, 1 population, or []) and the dimension to reduce. var(X, flag, 'all') collapses every dimension, while var(X, flag, vecdim) accepts a dimension vector such as [1 3] and reduces all listed axes in a single call.
  • Strings like 'omitnan' and 'includenan' decide whether NaN values are skipped or propagated.
  • Logical inputs are promoted to double precision before reduction so that results follow MATLAB’s numeric rules.
  • Empty slices return NaN with MATLAB-compatible shapes. Scalars return 0, regardless of the normalisation mode.
  • Dimensions greater than ndims(X) leave the input unchanged.
  • Weighted variances (flag as a vector) are not implemented yet; RunMat reports a descriptive error when they are requested.

Complex tensors are not currently supported; convert them to real magnitudes manually before calling var.

var Function GPU Execution Behaviour

When RunMat Accelerate is active, device-resident tensors remain on the GPU whenever the provider implements the relevant hooks. Providers that expose reduce_std_dim/reduce_std execute the reduction in-place on the device; the runtime squares the resulting standard deviation tensor with an elementwise multiply in device memory. Whenever 'omitnan', multi-axis reductions, or unsupported shapes are requested, RunMat transparently gathers the data to the host, computes the result there, and materialises the variance tensor before returning.

Examples of using the var function in MATLAB / RunMat

Sample variance of a vector

x = [1 2 3 4 5];
v = var(x);                 % uses flag = 0 (sample) by default

Expected output:

v = 2.5;

Population variance of each column

A = [1 3 5; 2 4 6];
vpop = var(A, 1);           % divide by n instead of n-1

Expected output:

vpop = [0.25 0.25 0.25];

Collapsing every dimension at once

B = reshape(1:12, [3 4]);
overall = var(B, 0, 'all');

Expected output:

overall = 13;

Reducing across multiple dimensions

C = cat(3, [1 2; 3 4], [5 6; 7 8]);
sliceVariance = var(C, [], [1 3]);   % keep columns, reduce rows & pages

Expected output:

sliceVariance = [6.6667 6.6667];

Ignoring NaN values

D = [1 NaN 3; 2 4 NaN];
rowVariance = var(D, 0, 2, 'omitnan');

Expected output:

rowVariance = [2; 2];

Variance on the GPU without manual gpuArray

G = rand(1024, 512);
spread = var(G, 1, 'all');   % stays on the GPU when the provider supports std reductions

spread remains device-resident. Use gather(spread) if you need the result on the host.

Preserving default behaviour with an empty normalisation flag

C = [1 2; 3 4];
rowVariance = var(C, [], 2);

Expected output:

rowVariance = [0.5; 0.5];

GPU residency in RunMat (Do I need gpuArray?)

Usually you do not need to call gpuArray manually. The fusion planner keeps tensors on the GPU across fused expressions and gathers them only when necessary. For explicit control or MATLAB compatibility, you can still call gpuArray/gather yourself.

FAQ

What values can I pass as the normalisation flag?

Use 0 (or []) for the sample definition, 1 for population. RunMat rejects non-scalar weight vectors and reports that weighted variances are not implemented yet.

How can I collapse multiple dimensions?

Pass a vector of dimensions such as var(A, [], [1 3]). You can also use 'all' to collapse every dimension into a single scalar.

How do 'omitnan' and 'includenan' work?

'omitnan' skips NaN values; if every element in a slice is NaN the result is NaN. 'includenan' (the default) propagates a single NaN to the output slice.

What happens if I request a dimension greater than ndims(X)?

RunMat returns the input unchanged so that MATLAB-compatible code relying on that behaviour continues to work. Scalars still return 0 to follow MATLAB’s edge-case semantics.

Are complex inputs supported?

Not yet. RunMat currently requires real inputs for var. Convert complex data to magnitude or separate real/imaginary parts before calling the builtin.

See Also

std, mean, sum, gpuArray, gather

Source & Feedback