RunMat
GitHub

View all functions

CategoryMath: Reduction
GPUYes

What does the max function do in MATLAB / RunMat?

max returns the largest values in its input while preserving MATLAB semantics for reductions, elementwise comparisons, NaN handling, complex magnitude comparisons, and linear indexing.

How does the max function behave in MATLAB / RunMat?

  • max(X) on an m × n array reduces along the first non-singleton dimension, returning a row vector of column-wise maxima and the corresponding indices (when requested).
  • max(X, [], dim) reduces along the specified dimension; max(X, [], vecdim) reduces along each dimension listed in vecdim.
  • max(X, [], 'all') collapses every element into a scalar and returns the linear index when two outputs are requested.
  • max(X, [], 'linear') is equivalent to 'all' but guarantees that the matching index is linear over X(:).
  • max(X, [], ..., 'omitnan') ignores NaN values inside each slice. If every element in a slice is NaN, the result for that slice is NaN and the index is NaN.
  • max(X, [], ..., 'includenan') (default) propagates NaN whenever a slice contains any NaN element, returning the index of the first NaN.
  • max(A, B) performs elementwise comparison using MATLAB's implicit expansion rules. The second output indicates whether the maximum came from A (index 1) or B (index 2).
  • Complex inputs follow MATLAB ordering: 'ComparisonMethod','auto' (default) compares magnitudes and breaks ties using phase angles, while 'real' compares real components first. 'abs' is an explicit alias for magnitude ordering on real and complex inputs.

max Function GPU Execution Behaviour

When RunMat Accelerate is active, tensors that already reside on the GPU stay on the device whenever the provider exposes reduce_max_dim (for dimension reductions) or reduce_max (for whole-array reductions). Requests that require omitnan, custom comparison modes, 'linear' indices, or complex arithmetic gather the data to the host, compute the MATLAB-compatible result, and return the output on the host. Elementwise max(A, B) currently executes on the host; the planner rematerializes tensors on the GPU when follow-on fused kernels make it profitable.

Examples of using the max function in MATLAB / RunMat

Finding column-wise maxima of a matrix

A = [3 1 5; 4 2 6];
[m, idx] = max(A);

Expected output:

m   = [4 2 6];
idx = [2 2 2];

Reducing along the second dimension

A = [3 1 5; 4 2 6];
[m, idx] = max(A, [], 2);

Expected output:

m   = [5; 6];
idx = [3; 3];

Collapsing all elements with linear indices

A = reshape(1:12, [3 4]);
[m, idx] = max(A, [], 'all');

Expected output:

m   = 12;
idx = 12;  % linear index into A(:)

Ignoring NaN values during reduction

values = [NaN 4 2; 3 NaN 1];
[m, idx] = max(values, [], 1, 'omitnan');

Expected output:

m   = [3 4 2];
idx = [2 1 1];

Elementwise maximum with broadcasting

A = [1 4 7];
B = [2; 3; 5];
[C, origin] = max(A, B);

Expected output:

C =
     2     4     7
     3     4     7
     5     5     7

origin =
     2     1     1
     2     1     1
     2     2     1

Comparing complex values by magnitude

Z = [1+2i, 2+1i, -2+2i];
M = max(Z);                         % magnitude ordering
R = max(Z, [], 'ComparisonMethod', 'real');

Expected output:

M = -2.0000 + 2.0000i
R = 2.0000 + 1.0000i

GPU residency in RunMat (Do I need gpuArray?)

You typically do not need to call gpuArray manually. The fusion planner keeps tensors on the GPU between compatible kernels. When a reduction is supported by the active provider, the maximum values and indices stay on device. If a provider lacks the necessary hook, RunMat gathers data to the host, computes the result, and returns host tensors—subsequent fused GPU kernels can re-upload data when profitable.

FAQ

Can I request the linear index of the global maximum?

Yes. Use either max(X, [], 'all') or max(X, [], 'linear'). Both return a scalar maximum and the linear index into X(:) when you request two outputs.

Does max support 'ComparisonMethod' for real and complex arrays?

Absolutely. 'auto' or 'abs' compare magnitudes; 'real' compares the real component first. The returned values always match MATLAB, including tie-breaking rules.

What happens when all elements are NaN and 'omitnan' is requested?

The value result is NaN and the index is NaN, matching MATLAB's behavior for empty slices.

Can I mix elementwise comparisons with dimension reductions?

No. max(A, B) performs elementwise comparisons only. Use max(A, [], dim) when you want reductions along specific dimensions.

Do GPU reductions support 'omitnan' or custom comparison methods?

Not yet. Those requests fall back to the host implementation, which still honors MATLAB semantics. The output remains a host tensor in that case.

Are logical and integer inputs supported?

Yes. Logical arrays are promoted to double precision, and integer inputs are converted to double before comparison, matching MATLAB's numeric tower.

See Also

min, sum, mean, gpuArray, gather

Source & Feedback