sum — Sum array elements along dimensions with MATLAB-compatible normalization and option handling.
sum(X) adds elements across arrays, defaulting to the first non-singleton dimension when no dimension is specified. It supports MATLAB-compatible dimension, 'all', and type-control options.
Syntax
S = sum(A)
S = sum(A, dim)
S = sum(A, "all")
S = sum(A, missingflag)
S = sum(A, outtype)
S = sum(A, dim, missingflag)
S = sum(A, missingflag, dim)
S = sum(A, vecdim)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input array. |
dim | Any | No | [] | Dimension selector or vector of dimensions. |
all | StringScalar | No | "all" | Reduce across all dimensions. |
missingflag | StringScalar | No | "includemissing" | Missing-data handling mode: "includemissing" or "omitmissing". |
outtype | StringScalar | No | "double" | Output class specifier: "double", "default", or "native". |
Returns
| Name | Type | Description |
|---|---|---|
S | NumericArray | Sum reduction result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:sum:InvalidArgument | Dimension, missing-data flag, or output class argument grammar is invalid. | sum: invalid argument |
RunMat:sum:InvalidInput | Input values cannot be converted to supported sum reduction domains. | sum: invalid input |
RunMat:sum:Internal | Reduction execution fails due to conversion, provider, allocation, or coercion operations. | sum: internal reduction failure |
How sum works
sum(X)on anm × nmatrix 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')ignoresNaNvalues; if every element in the slice isNaN, the result becomes0.sum(___, 'includenan')(default) propagatesNaNwhen any element in the slice isNaN.sum(___, outtype)accepts'double','default', or'native'to control the output class.sum(___, 'like', prototype)matches the numeric class and residency ofprototypewhen supported by the active provider.- Empty inputs or reductions along dimensions with size
0return zeros that follow MATLAB shape semantics.
Does RunMat run sum on the GPU?
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.
GPU memory and residency
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.
Examples
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 = 4Summing 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
6Summing all elements of an array into a scalar
C = [1 2 3; 4 5 6];
grandTotal = sum(C, 'all')Expected output:
grandTotal = 21Summing with native output type
ints = int32([100 200 300]);
total = sum(ints, 'native')Expected output:
total = int32(600)Using sum with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how sum changes the result.
Run a small sum example, explain the result, then change one input and compare the output.
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.
Related Math functions
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · trapz · var
Elementwise
abs · angle · bsxfun · complex · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Optim
coneprog · fminbnd · fminunc · fsolve · fzero · integral · linprog · lsqcurvefit · lsqnonlin · optimoptions · optimset · quad · secondordercone
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how sum is executed, line by line, in Rust.
- View the source for sum 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.