RunMat
GitHub

View all functions

CategoryMath: Reduction
GPUYes

What does the mean function do in MATLAB / RunMat?

mean(x) computes the arithmetic mean of scalars, vectors, matrices, and higher-dimensional tensors. When no dimension is supplied, the reduction runs along the first non-singleton dimension.

How does the mean function behave in MATLAB / RunMat?

  • mean(X) on an m × n matrix returns a row vector (1 × n) with column averages.
  • mean(X, 2) returns a column vector (m × 1) containing row averages.
  • mean(X, 'all') collapses every dimension and returns a scalar average of all elements.
  • mean(X, vecdim) accepts a vector of dimensions (e.g., [1 3]) and reduces each listed axis in one call while preserving the others.
  • Complex inputs are supported and follow MATLAB's rule mean(a + bi) = mean(real(a + bi)) + i·mean(imag(a + bi)), propagating NaN through either component.
  • Logical inputs are promoted to double precision (true → 1.0, false → 0.0).
  • mean(..., 'omitnan') ignores NaN values; if every element in the slice is NaN, the result is NaN.
  • mean(..., 'includenan') (default) propagates NaN when any element in the slice is NaN.
  • mean(___, outtype) accepts 'double', 'default', or 'native' to control the output numeric class. Integer outputs round to the nearest integer, matching MATLAB.
  • mean(___, 'like', prototype) matches the numeric class and residency of prototype, including GPU tensors and complex arrays.
  • Empty slices produce NaN outputs that follow MATLAB's shape semantics.
  • Dimensions larger than ndims(X) leave the input unchanged.

mean Function GPU Execution Behaviour

When the input tensor lives on the GPU, RunMat first asks the active acceleration provider for a device-side result via reduce_mean_dim or (when the entire tensor collapses) reduce_mean. If the provider lacks those hooks or the call specifies 'omitnan', RunMat gathers the data back to the host and evaluates the mean with the CPU reference implementation. Output templates are then applied: 'native' restores integer classes, and 'like' mirrors both the numeric class and residency—re-uploading to the GPU when the prototype is device-resident.

Examples of using the mean function in MATLAB / RunMat

Computing the mean of a matrix

A = [1 2 3; 4 5 6];
colMeans = mean(A);      % column averages
rowMeans = mean(A, 2);   % row averages

Expected output:

colMeans = [2.5 3.5 4.5];
rowMeans = [2; 5];

Computing the mean of a vector with NaN values

values = [1 NaN 3];
avg = mean(values, 'omitnan');

Expected output:

avg = 2;

Computing the overall mean across all elements

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

Expected output:

overall = 6.5;

Reducing across multiple dimensions at once

C = cat(3, [1 2; 3 4], [5 6; 7 8]);
slice_means = mean(C, [1 3]);   % reduce rows and pages, keep columns

Expected output:

slice_means = [4 5];

Matching a prototype with 'like'

G = gpuArray(single([1 3; 5 7]));
mu = mean(G, 'all', 'like', G);
result = gather(mu);

Expected output:

result = single(4);

mu remains on the GPU as a single-precision scalar because it inherits the prototype's class and residency.

Computing the mean of a matrix on a GPU

G = gpuArray([1 2 NaN; 3 4 5]);
means = mean(G, 2, 'omitnan');
result = gather(means);

Expected output:

result = [1.5; 4];

Using 'omitnan' triggers the host fallback, but the runtime still honours 'like' and 'native' requests when present.

GPU residency in RunMat (Do I need gpuArray?)

You usually do NOT need to call gpuArray yourself in RunMat (unlike MATLAB).

In RunMat, the fusion planner keeps residency on GPU in branches of fused expressions. As such, in the above example, the result of the mean call will already be on the GPU when the fusion planner has detected a net benefit to operating the fused expression it is part of on the GPU.

To preserve backwards compatibility with MathWorks MATLAB, and for when you want to explicitly bootstrap GPU residency, you can call gpuArray explicitly to move data to the GPU if you want to be explicit about the residency.

Since MathWorks MATLAB does not have a fusion planner, and they kept their parallel execution toolbox separate from the core language, as their toolbox is a separate commercial product, MathWorks MATLAB users need to call gpuArray to move data to the GPU manually whereas RunMat users can rely on the fusion planner to keep data on the GPU automatically.

FAQ

When should I use the mean function?

Use mean whenever you need to compute the arithmetic mean of a tensor. This is useful for calculating averages, central tendencies, or performing statistical analysis.

What does mean(A) return?

If you call mean(A), where A is an array, the result is a new array of the same shape as A with the mean of each slice along the first non-singleton dimension. For example, if A is a 2x3 matrix, mean(A) will return a 1x3 matrix with the mean of each column.

How do I compute the mean of a specific dimension?

You can use the dim argument to specify the dimension along which to compute the mean. For example, mean(A, 2) will return a 2x1 matrix with the mean of each row.

How do I average across multiple dimensions at once?

Pass a vector of dimensions such as mean(A, [1 3]). RunMat reduces each listed axis in a single pass, leaving the remaining dimensions unchanged.

What happens if the slice contains only NaN values?

When you specify 'omitnan', slices that contain only NaN still return NaN, mirroring MATLAB. With 'includenan' (the default), any NaN in the slice forces the result to NaN.

Does mean support GPU arrays automatically?

Yes. If a GPU provider is registered, device-resident tensors remain on the GPU and run through reduce_mean_dim/reduce_mean. Calls that the provider cannot satisfy—most notably 'omitnan' and unsupported dimension combinations—are gathered to the CPU transparently.

How are complex numbers handled?

RunMat averages the real and imaginary components separately. If either component in a slice is NaN, the result for that slice becomes complex NaN, matching MATLAB's behaviour.

How can I control the output type?

By default, RunMat promotes inputs to double precision. Use the optional outtype argument to override this behaviour: pass 'native' to round back to the input's integer class, or 'double'/'default' to force double precision explicitly. 'like', prototype matches the numeric flavour and residency of prototype, including complex outputs.

Can I keep the result on the GPU or match an existing prototype?

Yes. When you pass 'like', prototype, RunMat mirrors both the class and residency of prototype. Providing a GPU tensor keeps the result on the device even when the reduction itself had to fall back to the host (for example with 'omitnan').

See Also

sum, median, cumsum, gpuArray, gather

Source & Feedback