cummin — Compute cumulative minima (with optional indices) in MATLAB and RunMat.

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

Syntax

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

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

Inputs

Returns

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

Errors

How cummin works

• By default the running minimum follows the first non-singleton dimension. Use cummin(X, dim) to choose a dimension explicitly; if dim > ndims(X), the input is returned unchanged and the indices are ones.
• [Y, I] = cummin(X, ...) returns both the running minima (Y) and the indices of where those minima 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 minimum, 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 cummin on the GPU?

When the input already resides on the GPU, RunMat calls the acceleration provider's cummin_scan hook. Providers that implement this hook return GPU handles for both the running minima 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 cummin builtin preserves residency whenever the provider implements cummin_scan. If the hook is unavailable, RunMat gathers to the host transparently and still returns MATLAB-compatible minima 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 minima

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

Expected output:

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

Requesting running minima across rows

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

Expected output:

Y =
     4     2     2
     3     3     1
I =
     1     2     2
     1     1     3

Getting cumulative minima in reverse order

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

Expected output:

Y = [2 2 2 2]
I = [4 4 4 4]

Ignoring NaN values in running minima

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

Expected output:

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

Capturing running minima and indices on the GPU

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

Using cummin with coding agents

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

FAQ

Related Math functions

Open-source implementation

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

• View the source for cummin 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