sum

Sum of array elements

collapse all in page

Syntax

S = sum(A)

S = sum(A,"all")

S = sum(A,dim)

S = sum(A,vecdim)

S = sum(___,outtype)

S = sum(___,nanflag)

Description

S = sum(A) returns the sum of the elements of A along the first array dimension whose size does not equal 1.

If A is a vector, then sum(A) returns the sum of the elements.
If A is a matrix, then sum(A) returns a row vector containing the sum of each column.
If A is a multidimensional array, then sum(A) operates along the first array dimension whose size does not equal 1, treating the elements as vectors. The size of S in this dimension becomes 1 while the sizes of all other dimensions remain the same as in A.
If A is a table or timetable, then sum(A) returns a one-row table containing the sum of each variable. (since R2023a)

example

S = sum(A,"all") returns the sum of all elements of A.

example

S = sum(A,dim) returns the sum along dimension dim. For example, if A is a matrix, then sum(A,2) returns a column vector containing the sum of each row.

example

S = sum(A,vecdim) sums the elements of A based on the dimensions specified in the vector vecdim. For example, if A is a matrix, then sum(A,[1 2]) returns the sum of all elements in A because every element of a matrix is contained in the array slice defined by dimensions 1 and 2.

example

S = sum(___,outtype) returns the sum with the specified data type, using any of the input arguments in the previous syntaxes. outtype can be "default", "double", or "native".

example

S = sum(___,nanflag) specifies whether to include or omit NaN values in A. For example, sum(A,"omitnan") ignores NaN values when computing the sum. By default, sum includes NaN values.

example

Examples

collapse all

Sum of Vector Elements

Open Live Script

Create a vector and compute the sum of its elements.

A = 1:10;
S = sum(A)

S = 
55

Sum of Matrix Columns

Open Live Script

Create a matrix and compute the sum of the elements in each column.

A = [1 3 2; 4 2 5; 6 1 4]

A = 3×3

     1     3     2
     4     2     5
     6     1     4

S = sum(A)

S = 1×3

    11     6    11

Sum of Matrix Rows

Open Live Script

Create a matrix and compute the sum of the elements in each row.

A = [1 3 2; 4 2 5; 6 1 4]

A = 3×3

     1     3     2
     4     2     5
     6     1     4

S = sum(A,2)

Sum of Array Slices

Open Live Script

Use a vector dimension argument to operate on specific slices of an array.

Create a 3-D array whose elements are 1.

A = ones(4,3,2);

To sum all elements in each page of A, specify the dimensions in which to sum (row and column) using a vector dimension argument. Since both pages are a 4-by-3 matrix of ones, the sum of each page is 12.

S1 = sum(A,[1 2])

S1 = 
S1(:,:,1) =

    12


S1(:,:,2) =

    12

If you slice A along the first dimension, you can sum the elements of the resulting 4 pages, which are each 3-by-2 matrices.

S2 = sum(A,[2 3])

Slicing along the second dimension, each page sum is over a 4-by-2 matrix.

S3 = sum(A,[1 3])

S3 = 1×3

     8     8     8

To compute the sum over all dimensions of an array, you can either specify each dimension in the vector dimension argument, or use the "all" option.

S4 = sum(A,[1 2 3])

S4 = 
24

Sall = sum(A,"all")

Sall = 
24

Sum of 3-D Array

Open Live Script

Create a 4-by-2-by-3 array of ones and compute the sum along the third dimension.

A = ones(4,2,3);
S = sum(A,3)

Sum of 32-Bit Integers

Open Live Script

Create a vector of 32-bit integers and compute the int32 sum of its elements by specifying the output type as native.

A = int32(1:10);
S = sum(A,"native")

S = int32

55

Sum Excluding Missing Values

Open Live Script

Create a matrix containing NaN values.

A = [1.77 -0.005 NaN -2.95; NaN 0.34 NaN 0.19]

A = 2×4

    1.7700   -0.0050       NaN   -2.9500
       NaN    0.3400       NaN    0.1900

Compute the sum of the matrix, excluding NaN values. For matrix columns that contain any NaN value, sum computes with the non-NaN elements. For matrix columns that contain all NaN values, the sum is 0.

S = sum(A,"omitnan")

S = 1×4

    1.7700    0.3350         0   -2.7600

Input Arguments

collapse all

`A` — Input array
vector | matrix | multidimensional array | table | timetable

Input array, specified as a vector, matrix, multidimensional array, table, or timetable.

If A is a scalar, then sum(A) returns A.
If A is an empty 0-by-0 matrix, then sum(A) returns 0.

`dim` — Dimension to operate along
positive integer scalar

Dimension to operate along, specified as a positive integer scalar. If you do not specify the dimension, then the default is the first array dimension whose size does not equal 1.

Dimension dim indicates the dimension whose length reduces to 1. The size(S,dim) is 1, while the sizes of all other dimensions remain the same.

Consider a two-dimensional input array, A:

sum(A,1) operates on successive elements in the columns of A and returns a row vector of the sums of each column.
sum(A,2) operates on successive elements in the rows of A and returns a column vector of the sums of each row.

sum returns A when dim is greater than ndims(A) or when size(A,dim) is 1.

`vecdim` — Vector of dimensions
vector of positive integers

Vector of dimensions, specified as a vector of positive integers. Each element represents a dimension of the input array. The lengths of the output in the specified operating dimensions are 1, while the others remain the same.

Consider a 2-by-3-by-3 input array, A. Then sum(A,[1 2]) returns a 1-by-1-by-3 array whose elements are the sums of each page of A.

sum(A,[1 2]) collapses the pages of a 2-by-3-by-3 array into a 1-by-1-by-3 array.

`outtype` — Output data type
`"default"` (default) | `"double"` | `"native"`

Output data type, specified as "default", "double", or "native". These options also specify the data type in which the operation is performed.

`outtype`	Output data type
`"default"`	`double`, unless the input data type is `single`, `duration`, `table`, or `timetable`, in which case, the output is `"native"`
`"double"`	`double`, unless the data type is `duration`, `table`, or `timetable`, in which case, `"double"` is not supported
`"native"`	Same data type as the input, unless the input data type is `char`, in which case, `"native"` is not supported; or unless the input data type is `timetable`, in which case the output data type is `table`

`nanflag` — Missing value condition
`"includemissing"` (default) | `"includenan"` | `"omitmissing"` | `"omitnan"`

Missing value condition, specified as one of these values:

"includemissing" or "includenan" — Include NaN values in A when computing the sum. If any element in the operating dimension is NaN, then the corresponding element in S is NaN. "includemissing" and "includenan" have the same behavior.
"omitmissing" or "omitnan" — Ignore NaN values in A, and compute the sum over fewer points. If all elements in the operating dimension are NaN, then the corresponding element in S is 0. "omitmissing" and "omitnan" have the same behavior.

Extended Capabilities

Tall Arrays
Calculate with arrays that have more rows than fit in memory.

The sum function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

If you specify dim, then it must be a constant.
The outtype and nanflag options must be constant character vectors.
See Variable-Sizing Restrictions for Code Generation of Toolbox Functions (MATLAB Coder).

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

If you specify dim, then it must be a constant.
The outtype and nanflag options must be constant character vectors.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The sum function supports GPU array input with these usage notes and limitations:

64-bit integers are not supported with the "native" option.
The order of the additions in the sum operation is not defined. Therefore, the sum operation on a GPU array might not return exactly the same answer as the sum operation on the corresponding numeric array. The difference might be significant when A is a signed integer type and its product is accumulated natively.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

The order of the additions in sum operation is not defined. Therefore, the sum operation on a distributed array might not return exactly the same answer as the sum operation on the corresponding numeric array. The difference might be significant when A is a signed integer type and its product is accumulated natively.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

expand all

R2023a: Specify missing value condition

Include or omit missing values in the input array when computing the sum by using the "includemissing" or "omitmissing" options. These options have the same behavior as the "includenan" and "omitnan" options, respectively.

R2023a: Perform calculations directly on tables and timetables

The sum function can calculate on all variables within a table or timetable without indexing to access those variables. All variables must have data types that support the calculation. For more information, see Direct Calculations on Tables and Timetables.

R2018b: Operate on multiple dimensions

Operate on multiple dimensions of the input array at a time. Specify a vector of operating dimensions, or specify the "all" option to operate on all array dimensions.

sum

Syntax

Description

Examples

Sum of Vector Elements

Sum of Matrix Columns

Sum of Matrix Rows

Sum of Array Slices

Sum of 3-D Array

Sum of 32-Bit Integers

Sum Excluding Missing Values

Input Arguments

A — Input array vector | matrix | multidimensional array | table | timetable

dim — Dimension to operate along positive integer scalar

vecdim — Vector of dimensions vector of positive integers

outtype — Output data type "default" (default) | "double" | "native"

nanflag — Missing value condition "includemissing" (default) | "includenan" | "omitmissing" | "omitnan"

Extended Capabilities

Tall Arrays Calculate with arrays that have more rows than fit in memory.

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Version History

R2023a: Specify missing value condition

R2023a: Perform calculations directly on tables and timetables

R2018b: Operate on multiple dimensions

See Also

`A` — Input array
vector | matrix | multidimensional array | table | timetable

`dim` — Dimension to operate along
positive integer scalar

`vecdim` — Vector of dimensions
vector of positive integers

`outtype` — Output data type
`"default"` (default) | `"double"` | `"native"`

`nanflag` — Missing value condition
`"includemissing"` (default) | `"includenan"` | `"omitmissing"` | `"omitnan"`

Tall Arrays
Calculate with arrays that have more rows than fit in memory.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.