cumulative_sum

cumulative_sum(x: array, /, *, axis: int | None = None, dtype: dtype | None = None, include_initial: bool = False) → array

Calculates the cumulative sum of elements in the input array x.

Parameters:

  • x (array) – input array. Should have one or more dimensions (axes). Should have a numeric data type.

  • axis (Optional[int]) –

    axis along which to compute the cumulative sum. A valid axis must be an integer on the interval [-N, N), where N is the number of axes in x. If an axis is specified as a negative integer, the function must determine the axis along which to perform the operation by counting backward from the last axis (where -1 refers to the last axis). If provided an invalid axis, the function must raise an exception.

    If x is a one-dimensional array, providing an axis must be optional; however, if x has more than one dimension, providing an axis must be required.

  • dtype (Optional[dtype]) –

    data type of the returned array. If None, the returned array must have the same data type as x, unless x has an integer data type supporting a smaller range of values than the default integer data type (e.g., x has an int16 or uint32 data type and the default integer data type is int64). In those latter cases:

    • if x has a signed integer data type (e.g., int16), the returned array must have the default integer data type.

    • if x has an unsigned integer data type (e.g., uint16), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is int32, the returned array must have a uint32 data type).

    If the data type (either specified or resolved) differs from the data type of x, the input array should be cast to the specified data type before computing the sum (rationale: the dtype keyword argument is intended to help prevent overflows). Default: None.

  • include_initial (bool) – boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value must be the additive identity (i.e., zero). Default: False.

Returns:

out (array) – an array containing the cumulative sums. The returned array must have a data type as described by the dtype parameter above.

Let M be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules:

  • if include_initial is True, the returned array must have the same shape as x, except the size of the axis along which to compute the cumulative sum must be M+1.

  • if include_initial is False, the returned array must have the same shape as x.

Notes

  • When x is a zero-dimensional array, behavior is unspecified and thus implementation-defined.

Special Cases

For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of add().

New in version 2023.12.

Changed in version 2024.12: Behavior when providing a zero-dimensional array is explicitly left unspecified.