cummax — Compute cumulative maxima (with optional indices) in MATLAB and RunMat.

cummax(X) computes running maxima along a chosen dimension. Optional second output returns indices of each running maximum, with behavior aligned to MATLAB and RunMat.

Syntax

M = cummax(A)
M = cummax(A, dim)
M = cummax(A, direction)
M = cummax(A, nanflag)
M = cummax(A, dim, direction)
M = cummax(A, direction, dim)

M = cummax(A)
M = cummax(A, dim)
M = cummax(A, direction)
M = cummax(A, nanflag)
M = cummax(A, dim, direction)
M = cummax(A, direction, dim)
M = cummax(A, dim, nanflag)
M = cummax(A, nanflag, dim)
M = cummax(A, direction, nanflag)
M = cummax(A, nanflag, direction)
M = cummax(A, dim, direction, nanflag)
M = cummax(A, dim, nanflag, direction)
M = cummax(A, direction, dim, nanflag)
M = cummax(A, direction, nanflag, dim)
M = cummax(A, nanflag, dim, direction)
M = cummax(A, nanflag, direction, dim)
[M, I] = cummax(A)
[M, I] = cummax(A, dim)
[M, I] = cummax(A, direction)
[M, I] = cummax(A, nanflag)
[M, I] = cummax(A, dim, direction)
[M, I] = cummax(A, direction, dim)
[M, I] = cummax(A, dim, nanflag)
[M, I] = cummax(A, nanflag, dim)
[M, I] = cummax(A, direction, nanflag)
[M, I] = cummax(A, nanflag, direction)
[M, I] = cummax(A, dim, direction, nanflag)
[M, I] = cummax(A, dim, nanflag, direction)
[M, I] = cummax(A, direction, dim, nanflag)
[M, I] = cummax(A, direction, nanflag, dim)
[M, I] = cummax(A, nanflag, dim, direction)
[M, I] = cummax(A, nanflag, direction, dim)

Inputs

Returns

Returned values from cummax depend on how many outputs the caller requests.

Errors

How cummax works

• By default the running maximum follows the first non-singleton dimension. Use cummax(X, dim) to choose a dimension explicitly; if dim > ndims(X), the input is returned unchanged and the indices are ones.
• [Y, I] = cummax(X, ...) returns both the running maxima (Y) and the indices of where those maxima were observed (I). Indices are one-based and match MATLAB exactly.
• Add "reverse" (or "forward") to control the scan direction. Reverse mode walks from the end of the chosen dimension back to the beginning.
• "omitnan" skips NaN values when choosing the running maximum, returning NaN only when every value seen so far is NaN. "includenan" (default) propagates NaN once one is encountered.
• Synonyms such as "omitmissing" / "includemissing" are accepted for MATLAB compatibility.
• Real and complex inputs are supported. Complex numbers are ordered using MATLAB's magnitude-and-angle rules.

Does RunMat run cummax on the GPU?

When the input already resides on the GPU, RunMat calls the acceleration provider's cummax_scan hook. Providers that implement this hook return GPU handles for both the running maxima and their indices. If the hook is missing—or if it rejects the requested options (such as "omitnan" or "reverse")—RunMat gathers the data to the host, computes the MATLAB-compatible result, and returns dense tensors on the CPU. Residency metadata is cleared so downstream kernels can re-promote values when profitable.

GPU memory and residency

Manual gpuArray calls are optional. The planner keeps tensors on the GPU when profitable, and the cummax builtin preserves residency whenever the provider implements cummax_scan. If the hook is unavailable, RunMat gathers to the host transparently and still returns MATLAB-compatible maxima and indices. You can still use gpuArray to match MATLAB scripts or force residency ahead of a tight GPU loop.

Examples

Tracking column-wise running maxima

A = [4 2 7; 3 5 1];
[Y, I] = cummax(A);
disp(Y);
disp(I)

Expected output:

Y =
     4     2     7
     4     5     7
I =
     1     1     1
     1     2     1

Requesting running maxima across rows

A = [4 2 7; 3 5 1];
[Y, I] = cummax(A, 2);
disp(Y);
disp(I)

Expected output:

Y =
     4     4     7
     3     5     5
I =
     1     1     3
     1     2     2

Getting cumulative maxima in reverse order

v = [8 3 6 2];
[Y, I] = cummax(v, "reverse")

Expected output:

Y = [8 6 6 2]
I = [1 3 3 4]

Ignoring NaN values in running maxima

v = [NaN 5 NaN 3];
[Y, I] = cummax(v, "omitnan")

Expected output:

Y = [NaN 5 5 5]
I = [NaN 2 2 2]

Capturing running maxima and indices on the GPU

G = gpuArray([3 1 4 1 5]);
[Y, I] = cummax(G);
hostY = gather(Y)
hostI = gather(I)

Expected output:

hostY = [3 3 4 4 5];
hostI = [1 1 3 3 5]

Using cummax with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how cummax changes the result.

FAQ

Related Math functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how cummax is executed, line by line, in Rust.

• View the source for cummax in Rust on GitHub
• Learn how the RunMat runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

• RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
• Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing