cumprod

Symbolic cumulative product

Syntax

B = cumprod(A)

B = cumprod(A,dim)

B = cumprod(___,direction)

B = cumprod(___,nanflag)

Description

B = cumprod(A) returns the cumulative product of A starting at the beginning of the first array dimension in A whose size does not equal 1. The output B has the same size as A.

• If A is a vector, then cumprod(A) returns a vector containing the cumulative product of the elements of A.

• If A is a matrix, then cumprod(A) returns a matrix containing the cumulative products of each column of A.

• If A is a multidimensional array, then cumprod(A) acts along the first nonsingleton dimension.

B = cumprod(A,dim) returns the cumulative product along dimension dim. For example, if A is a matrix, then cumprod(A,2) returns the cumulative product of each row.

B = cumprod(___,direction) specifies the direction using any of the previous syntaxes. For instance, cumprod(A,2,'reverse') returns the cumulative product within the rows of A by working from end to beginning of the second dimension.

B = cumprod(___,nanflag) specifies whether to include or omit NaN values from the calculation for any of the previous syntaxes. cumprod(A,'includenan') includes all NaN values in the calculation while cumprod(A,'omitnan') ignores them.

Examples

Cumulative Product of Symbolic Vector

Create a symbolic vector. Find the cumulative product of its elements.

syms x
A = (1:5)*x

A = $$\left(\begin{array}{ccccc}x& 2\hspace{0.17em}x& 3\hspace{0.17em}x& 4\hspace{0.17em}x& 5\hspace{0.17em}x\end{array}\right)$$

In the vector of cumulative products, element B(2) is the product of A(1) and A(2), while B(5) is the product of elements A(1) through A(5).

B = cumprod(A)

B = $$\left(\begin{array}{ccccc}x& 2\hspace{0.17em}{x}^2& 6\hspace{0.17em}{x}^3& 24\hspace{0.17em}{x}^4& 120\hspace{0.17em}{x}^5\end{array}\right)$$

Cumulative Product of Each Column and Row in Symbolic Matrix

Create a 3-by-3 symbolic matrix A whose all elements are x.

syms x
A = ones(3)*x

A = 
$$\left(\begin{array}{ccc}x& x& x\\ x& x& x\\ x& x& x\end{array}\right)$$

Compute the cumulative product of elements of A. By default, cumprod returns the cumulative product of each column.

B = cumprod(A)

B = 
$$\left(\begin{array}{ccc}x& x& x\\ x^2& x^2& x^2\\ x^3& x^3& x^3\end{array}\right)$$

To compute the cumulative product of each row, set the value of the dim option to 2.

B = cumprod(A,2)

B = 
$$\left(\begin{array}{ccc}x& x^2& x^3\\ x& x^2& x^3\\ x& x^2& x^3\end{array}\right)$$

Reverse Cumulative Product of 3-D Symbolic Array

Create a 3-by-3-by-2 symbolic array.

syms x y
A(:,:,1) = [x y 0; x 3 x*y; x 1/3 y];
A(:,:,2) = [x y 3; 3 x y; y 3 x];
A

A(:,:,1) = 
$$\left(\begin{array}{ccc}x& y& 0\\ x& 3& x\hspace{0.17em}y\\ x& \frac{1}{3}& y\end{array}\right)$$

A(:,:,2) = 
$$\left(\begin{array}{ccc}x& y& 3\\ 3& x& y\\ y& 3& x\end{array}\right)$$

Compute the cumulative product along the rows by specifying dim as 2. Specify the 'reverse' option to work from right to left in each row. The result is the same size as A.

B = cumprod(A,2,'reverse')

B(:,:,1) = 
$$\left(\begin{array}{ccc}0& 0& 0\\ 3\hspace{0.17em}{x}^2\hspace{0.17em}y& 3\hspace{0.17em}x\hspace{0.17em}y& x\hspace{0.17em}y\\ \frac{x\hspace{0.17em}y}{3}& \frac{y}{3}& y\end{array}\right)$$

B(:,:,2) = 
$$\left(\begin{array}{ccc}3\hspace{0.17em}x\hspace{0.17em}y& 3\hspace{0.17em}y& 3\\ 3\hspace{0.17em}x\hspace{0.17em}y& x\hspace{0.17em}y& y\\ 3\hspace{0.17em}x\hspace{0.17em}y& 3\hspace{0.17em}x& x\end{array}\right)$$

To compute the cumulative product along the third (page) dimension, specify dim as 3. Specify the 'reverse' option to work from the largest page index to the smallest page index.

B = cumprod(A,3,'reverse')

B(:,:,1) = 
$$\left(\begin{array}{ccc}{x}^2& y^2& 0\\ 3\hspace{0.17em}x& 3\hspace{0.17em}x& x\hspace{0.17em}{y}^2\\ x\hspace{0.17em}y& 1& x\hspace{0.17em}y\end{array}\right)$$

B(:,:,2) = 
$$\left(\begin{array}{ccc}x& y& 3\\ 3& x& y\\ y& 3& x\end{array}\right)$$

Symbolic Vector with NaN Values

Create a symbolic vector containing NaN values. Compute the cumulative products.

A = [sym('a') sym('b') 1 NaN 2]

A = $$\left(\begin{array}{ccccc}a& b& 1& \mathrm{NaN}& 2\end{array}\right)$$

B = cumprod(A)

B = $$\left(\begin{array}{ccccc}a& a\hspace{0.17em}b& a\hspace{0.17em}b& \mathrm{NaN}& \mathrm{NaN}\end{array}\right)$$

You can ignore NaN values in the cumulative product calculation using the 'omitnan' option.

B = cumprod(A,'omitnan')

B = $$\left(\begin{array}{ccccc}a& a\hspace{0.17em}b& a\hspace{0.17em}b& a\hspace{0.17em}b& 2\hspace{0.17em}a\hspace{0.17em}b\end{array}\right)$$

Input Arguments

A — Input array

symbolic vector | symbolic matrix | symbolic multidimensional array

Input array, specified as a symbolic vector, matrix, or multidimensional array.

dim — Dimension to operate along

positive integer scalar

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

Consider a two-dimensional input array, A.

• cumprod(A,1) works on successive elements in the columns of A and returns the cumulative product of each column.

• cumprod(A,2) works on successive elements in the rows of A and returns the cumulative product of each row.

cumprod returns A if dim is greater than ndims(A).

direction — Direction of cumulation

'forward' (default) | 'reverse'

Direction of cumulation, specified as 'forward' (default) or 'reverse'.

• 'forward' works from 1 to end of the active dimension.

• 'reverse' works from end to 1 of the active dimension.

Data Types: char

nanflag — NaN condition

'includenan' (default) | 'omitnan'

NaN condition, specified as:

• 'includenan' — Include NaN values from the input when computing the cumulative products, resulting in NaN values in the output.

• 'omitnan' — Ignore all NaN values in the input. The product of elements containing NaN values is the product of all non-NaN elements. If all elements are NaN, then cumprod returns 1.

Data Types: char

Output Arguments

B — Cumulative product array

vector | matrix | multidimensional array

Cumulative product array, returned as a vector, matrix, or multidimensional array of the same size as the input A.

More About

First Nonsingleton Dimension

The first nonsingleton dimension is the first dimension of an array whose size is not equal to 1.

For example:

• If X is a 1-by-n row vector, then the second dimension is the first nonsingleton dimension of X.

• If X is a 1-by-0-by-n empty array, then the second dimension is the first nonsingleton dimension of X.

• If X is a 1-by-1-by-3 array, then the third dimension is the first nonsingleton dimension of X.

Version History

Introduced in R2013b

R2020b: Ignore NaNs using 'omitnan'

cumprod can exclude NaNs when evaluating the cumulative product of an array that contains NaNs. You can use the option 'omitnan' to exclude NaNs and 'includenan' to include NaNs.

R2020b: Support for multidimensional arrays of symbolic expressions

cumprod accepts multidimensional arrays of symbolic expressions as their input arguments.