RunMat
GitHub

View all functions

CategoryMath: Reduction
GPUYes

cumsum — Cumulative sum of scalars, vectors, matrices, or N-D tensors.

cumsum(X) computes the cumulative sum of the elements in X. The result has the same size as X and each element stores the running total along a chosen dimension.

How does the cumsum function behave in MATLAB / RunMat?

  • By default, the running total is taken along the first dimension whose length is greater than 1.
  • cumsum(X, dim) lets you pick the dimension explicitly; if dim > ndims(X), the input is returned unchanged.
  • Passing [] for the dimension argument keeps the default dimension (MATLAB uses this as a placeholder).
  • cumsum(..., "reverse") works from the end toward the beginning, whereas "forward" (default) works from start to finish.
  • cumsum(..., "omitnan") treats NaN values as missing. Leading NaN values yield zeros until a valid number appears.
  • Synonyms such as "omitmissing" / "includemissing" are also accepted for MATLAB compatibility.
  • The function supports real or complex scalars and dense tensors. Logical inputs are promoted to double precision.

GPU behavior

When a tensor already lives on the GPU, RunMat asks the active acceleration provider for a device-side prefix-sum implementation. The WGPU provider ships a native scan kernel; other providers may still fall back. If no hook is available, RunMat gathers the data to host memory, performs the cumulative sum on the CPU, and returns a dense tensor value. Residency metadata is cleared so later operations can re-promote the tensor when profitable.

GPU residency

Manual gpuArray calls are optional. RunMat promotes tensors automatically when the planner predicts a benefit, and it keeps fused expressions resident on the device. Explicit gpuArray is still supported for MATLAB compatibility or when you want to guarantee GPU residency before entering a critical loop.

Examples of using cumsum in MATLAB / RunMat

Running totals down each column (default dimension)

A = [1 2 3; 4 5 6];
columnTotals = cumsum(A)

Expected output:

columnTotals =
     1     2     3
     5     7     9

Tracking cumulative sums across rows

A = [1 2 3; 4 5 6];
rowTotals = cumsum(A, 2)

Expected output:

rowTotals =
     1     3     6
     4     9    15

Reversing the direction of accumulation

v = [1 3 5 7];
reverseTotals = cumsum(v, "reverse")

Expected output:

reverseTotals =
    16    15    12     7

Ignoring NaN values while accumulating

v = [2 NaN 5 NaN 1];
running = cumsum(v, "omitnan")

Expected output:

running =
     2     2     7     7     8

Computing a cumulative sum inside a GPU workflow

G = gpuArray(rand(1, 5));
totals = cumsum(G);
hostResult = gather(totals)

FAQ

Does cumsum change the size of the input?

No. The output is always the same size as the input tensor.

What happens if I request a dimension larger than ndims(X)?

The function returns X unchanged, matching MATLAB behaviour.

How are complex numbers handled?

cumsum accumulates the real and imaginary parts independently. NaN checks treat a complex number as missing if either part is NaN.

What does "omitnan" do for leading NaN values?

Leading NaN values contribute zeros so the running total remains 0 until a non-NaN value appears.

Does "reverse" affect which dimension is used?

No. Direction only decides whether accumulation walks from the start or from the end along the selected dimension.

Can I combine "reverse" and "omitnan"?

Yes. You can specify both options (in any order) and RunMat mirrors MATLAB’s results.

Does the GPU path respect "omitnan"?

If the active provider does not natively handle "omitnan", RunMat gathers back to host and computes there to preserve MATLAB semantics.

See also

sum, cumprod, diff, mean, gpuArray, gather

Source & Feedback