RunMat
GitHub

View all functions

CategoryMath: Reduction
GPUYes

What does the sum function do in MATLAB / RunMat?

sum(X) adds together elements 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 sum function behave in MATLAB / RunMat?

  • sum(X) on an m × n matrix returns a row vector (1 × n) with column sums.
  • sum(X, 2) returns a column vector (m × 1) containing row sums.
  • sum(X, dims) accepts a vector of dimensions (e.g., [1 3]) and collapses each listed axis while leaving the others untouched.
  • sum(X, 'all') flattens every dimension into a single scalar sum.
  • Logical inputs are promoted to double precision (true → 1.0, false → 0.0).
  • sum(___, 'omitnan') ignores NaN values; if every element in the slice is NaN, the result becomes 0.
  • sum(___, 'includenan') (default) propagates NaN when any element in the slice is NaN.
  • sum(___, outtype) accepts 'double', 'default', or 'native' to control the output class.
  • sum(___, 'like', prototype) matches the numeric class and residency of prototype when supported by the active provider.
  • Empty inputs or reductions along dimensions with size 0 return zeros that follow MATLAB shape semantics.

sum Function GPU Execution Behaviour

RunMat Accelerate keeps tensors on the GPU whenever a provider is active:

  1. If a tensor already resides on the device, the runtime calls the provider’s reduce_sum_dim (or reduce_sum for whole-array reductions). Successful hooks return a new GPU handle so downstream consumers stay on device.
  2. Cases that require extra bookkeeping—such as 'omitnan', multi-axis reductions, or 'like'/'native' class coercions—fall back to the host implementation. The runtime gathers the data, computes the correct MATLAB result, and re-uploads it only when a 'like' prototype demands GPU residency.
  3. The fusion planner keeps surrounding elementwise producers and consumers on the GPU, so manual gpuArray / gather calls are optional unless you want to force residency for interoperability with legacy MATLAB workflows.

Examples of using the sum function in MATLAB / RunMat

Summing the elements of a matrix

A = [1 2 3; 4 5 6];
colSums = sum(A);
rowSums = sum(A, 2);

Expected output:

colSums = [5 7 9];
rowSums = [6; 15];

Summing across multiple dimensions

B = reshape(1:24, [3 4 2]);
collapse = sum(B, [1 3]);

Expected output:

collapse = [48 66 84 102];

Summing with NaN values ignored

values = [1 NaN 3];
total = sum(values, 'omitnan');

Expected output:

total = 4;

Summing on the GPU and matching an existing prototype

proto = gpuArray.zeros(1, 1, 'single');
result = sum(gpuArray([1 2 3]), 'all', 'like', proto);

Expected output:

result =
  1x1 gpuArray  single
     6

Summing all elements of an array into a scalar

C = [1 2 3; 4 5 6];
grandTotal = sum(C, 'all');

Expected output:

grandTotal = 21;

Summing with native output type

ints = int32([100 200 300]);
total = sum(ints, 'native');

Expected output:

total = int32(600);

GPU residency in RunMat (Do I need gpuArray?)

You usually do not need to call gpuArray yourself. The fusion planner keeps tensors on the GPU whenever the provider exposes the required kernels. To mirror MATLAB, RunMat still accepts and respects explicit gpuArray / gather usage and the 'like' option to control residency explicitly.

FAQ

When should I use the sum function?

Use sum whenever you need to add together slices of a tensor, whether across a single dimension, multiple dimensions, or the entire dataset.

Does sum produce double arrays by default?

Yes. Unless you request 'native' or provide a 'like' prototype, the result is a dense double-precision array on the host.

What does sum(A) return?

For arrays, sum(A) reduces along the first non-singleton dimension, returning a new array whose reduced axis has size 1. Scalars are returned unchanged.

How do I compute the sum of a specific dimension?

Provide the dimension index: sum(A, 2) sums rows, sum(A, 3) sums along the third dimension, and so on. You can also pass a vector to collapse multiple dimensions.

What happens if all elements are NaN and I request 'omitnan'?

sum(..., 'omitnan') treats NaN values as missing data. If every element in the slice is NaN, the result becomes 0, matching MATLAB semantics.

Does sum preserve integer classes?

Only when you explicitly request 'native' or 'like'. Otherwise integers are promoted to double precision so you do not have to manage overflow manually.

See Also

prod, mean, cumsum, gpuArray, gather

Source & Feedback