RunMat
GitHub

View all functions

CategoryMath: Reduction
GPUYes

What does the cummin function do in MATLAB / RunMat?

cummin(X) computes the cumulative minimum of the elements in X along a chosen dimension. It also tracks where each running minimum occurs, mirroring MATLAB's two-output behaviour.

How does the cummin function behave in MATLAB / RunMat?

  • 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.

cummin Function GPU Execution Behaviour

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.

Examples of using the cummin function in MATLAB / RunMat

Tracking column-wise running minima

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

Expected output:

Y =
     4     2     1
     3     2     1
I =
     1     1     2
     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);

Behaviour: When the active provider supplies cummin_scan, Y and I stay resident on the GPU. Otherwise RunMat gathers G, computes the result on the host, and returns dense CPU tensors so downstream code still matches MATLAB's results.

GPU residency in RunMat (Do I need gpuArray?)

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.

FAQ

Does cummin always return indices?

Yes. The builtin produces MATLAB-compatible indices internally. When a call requests two outputs ([Y, I] = cummin(...)), I is surfaced directly. For single-output calls the indices remain available to the runtime for later retrieval.

How are complex numbers ordered?

Complex minima follow MATLAB's rules: values compare by magnitude, and ties break by phase angle. "omitnan" treats elements with NaN real or imaginary parts as missing.

What happens when all elements seen so far are NaN with "omitnan"?

The running minimum stays NaN and the corresponding index is NaN until a finite value is encountered. Once a finite value appears, subsequent NaNs leave the minimum and index unchanged.

Does the "reverse" option change the reported indices?

Indices are still reported using 1-based positions along the chosen dimension. "reverse" simply walks the dimension from end to start before writing the outputs.

What if the requested dimension exceeds ndims(X)?

The input is returned unchanged. Every index is 1, matching MATLAB's treatment of singleton trailing dimensions.

See Also

min, max, cumsum, cumprod, gpuArray, gather

Source & Feedback