.. _op_ai_onnx_CumSum:

CumSum
======

- **Domain**: ``ai.onnx``
- **Since version**: 14

Performs cumulative sum of the input elements along the given axis.
By default, it will do the sum inclusively meaning the first element is copied as is.
Through an ``exclusive`` attribute, this behavior can change to exclude the first element.
It can also perform summation in the opposite direction of the axis. For that, set ``reverse`` attribute to 1.

Example:

.. code-block::

    input_x = [1, 2, 3]
    axis=0
    output = [1, 3, 6]
    exclusive=1
    output = [0, 1, 3]
    exclusive=0
    reverse=1
    output = [6, 5, 3]
    exclusive=1
    reverse=1
    output = [5, 3, 0]


**Inputs**

- **x** (*T*): An input tensor that is to be processed.
- **axis** (*T2*): A 0-D tensor. Must be in the range [-rank(x), rank(x)-1]. Negative value means counting dimensions from the back.

**Outputs**

- **y** (*T*): Output tensor of the same type as 'x' with cumulative sums of the x's elements

**Attributes**

- **exclusive** (*int*): If set to 1 will return exclusive sum in which the top element is not included. In other terms, if set to 1, the j-th output element would be the sum of the first (j-1) elements. Otherwise, it would be the sum of the first j elements.
- **reverse** (*int*): If set to 1 will perform the sums in reverse direction.

**Type Constraints**

- **T**: Constrain input and output types to numeric tensors.
  Allowed types: tensor(bfloat16), tensor(double), tensor(float), tensor(float16), tensor(int32), tensor(int64), tensor(uint32), tensor(uint64).
- **T2**: axis tensor can be int32 or int64 only
  Allowed types: tensor(int32), tensor(int64).

Examples
--------

**test_cumsum_1d**

.. code-block:: text

    Node:
      CumSum(x, axis) -> (y)

.. code-block:: text

    Inputs:
      x: shape=(5,), dtype=float64
        [1., 2., 3., 4., 5.]
      axis: shape=(), dtype=int32
        0

    Outputs:
      y: shape=(5,), dtype=float64
        [ 1.,  3.,  6., 10., 15.]

**test_cumsum_1d_exclusive**

.. code-block:: text

    Node:
      CumSum(x, axis) -> (y)
      Attributes:
        exclusive = 1

.. code-block:: text

    Inputs:
      x: shape=(5,), dtype=float64
        [1., 2., 3., 4., 5.]
      axis: shape=(), dtype=int32
        0

    Outputs:
      y: shape=(5,), dtype=float64
        [ 0.,  1.,  3.,  6., 10.]

**test_cumsum_1d_int32_exclusive**

.. code-block:: text

    Node:
      CumSum(x, axis) -> (y)
      Attributes:
        exclusive = 1

.. code-block:: text

    Inputs:
      x: shape=(5,), dtype=int32
        [1, 2, 3, 4, 5]
      axis: shape=(), dtype=int32
        0

    Outputs:
      y: shape=(5,), dtype=int32
        [ 0,  1,  3,  6, 10]

**test_cumsum_1d_reverse**

.. code-block:: text

    Node:
      CumSum(x, axis) -> (y)
      Attributes:
        reverse = 1

.. code-block:: text

    Inputs:
      x: shape=(5,), dtype=float64
        [1., 2., 3., 4., 5.]
      axis: shape=(), dtype=int32
        0

    Outputs:
      y: shape=(5,), dtype=float64
        [15., 14., 12.,  9.,  5.]

**test_cumsum_1d_reverse_exclusive**

.. code-block:: text

    Node:
      CumSum(x, axis) -> (y)
      Attributes:
        exclusive = 1
        reverse = 1

.. code-block:: text

    Inputs:
      x: shape=(5,), dtype=float64
        [1., 2., 3., 4., 5.]
      axis: shape=(), dtype=int32
        0

    Outputs:
      y: shape=(5,), dtype=float64
        [14., 12.,  9.,  5.,  0.]

**test_cumsum_2d_axis_0**

.. code-block:: text

    Node:
      CumSum(x, axis) -> (y)

.. code-block:: text

    Inputs:
      x: shape=(2, 3), dtype=float64
        [[1., 2., 3.],
         [4., 5., 6.]]
      axis: shape=(), dtype=int32
        0

    Outputs:
      y: shape=(2, 3), dtype=float64
        [[1., 2., 3.],
         [5., 7., 9.]]

**test_cumsum_2d_axis_1**

.. code-block:: text

    Node:
      CumSum(x, axis) -> (y)

.. code-block:: text

    Inputs:
      x: shape=(2, 3), dtype=float64
        [[1., 2., 3.],
         [4., 5., 6.]]
      axis: shape=(), dtype=int32
        1

    Outputs:
      y: shape=(2, 3), dtype=float64
        [[ 1.,  3.,  6.],
         [ 4.,  9., 15.]]

**test_cumsum_2d_int32**

.. code-block:: text

    Node:
      CumSum(x, axis) -> (y)

.. code-block:: text

    Inputs:
      x: shape=(2, 3), dtype=int32
        [[1, 2, 3],
         [4, 5, 6]]
      axis: shape=(), dtype=int32
        0

    Outputs:
      y: shape=(2, 3), dtype=int32
        [[1, 2, 3],
         [5, 7, 9]]

**test_cumsum_2d_negative_axis**

.. code-block:: text

    Node:
      CumSum(x, axis) -> (y)

.. code-block:: text

    Inputs:
      x: shape=(2, 3), dtype=float64
        [[1., 2., 3.],
         [4., 5., 6.]]
      axis: shape=(), dtype=int64
        -1

    Outputs:
      y: shape=(2, 3), dtype=float64
        [[ 1.,  3.,  6.],
         [ 4.,  9., 15.]]

Differences with previous version (11)
--------------------------------------

**SchemaDiff**: ``CumSum`` (domain ``'ai.onnx'``)

* old version: 11
* new version: 14
* breaking: no

**Type constraints:**

* changed 'T': added types: ['tensor(bfloat16)', 'tensor(float16)']

Version History
---------------

- :doc:`Version 11 <CumSum-11>`