RunMat
GitHub

View all functions

CategoryArray: Creation
GPUYes

What does the range function do in MATLAB / RunMat?

range(X) returns the span (maximum minus minimum) of the elements in X. For arrays, the calculation happens along the first non-singleton dimension unless you specify one. The output keeps MATLAB's column-major shape conventions.

How does the range function behave in MATLAB / RunMat?

  • Operates on scalars, vectors, matrices, and N-D tensors.
  • range(X) measures the spread along the first non-singleton dimension.
  • range(X, dim) targets a specific dimension.
  • range(X, vecdim) reduces across multiple dimensions at once.
  • range(X, 'all') collapses all elements to a single scalar result.
  • range(___) is equivalent to max(___) - min(___) over the requested slice.
  • vecdim accepts a row or column vector of positive integers; duplicate entries are ignored.
  • range(___, 'omitnan') ignores NaN values (resulting in NaN if a slice has no finite values).
  • range(___, 'includenan') (default) returns NaN for any slice containing NaN.
  • Works with gpuArray inputs; the runtime keeps residency on the GPU when provider hooks are available.

Examples of using the range function in MATLAB / RunMat

Measuring column-wise range of a matrix

A = [1 4 2; 3 7 5];
spread = range(A);

Expected output:

% Each column's maximum minus minimum
spread = [2 3 3];

Selecting a dimension explicitly

A = [1 4 2; 3 7 5];
row_spread = range(A, 2);

Expected output:

row_spread = [3; 4];

Collapsing all elements with 'all'

temperatures = [68 72 75; 70 74 78];
overall = range(temperatures, 'all');

Expected output:

overall = 10;

Ignoring NaNs when computing range

samples = [2 NaN 5; 4 6 NaN];
spread = range(samples, 1, 'omitnan');

Expected output:

spread = [2 0 0];

Keeping gpuArray results on the device

G = gpuArray([1 10 3; 2 8 4]);
column_spread = range(G);
gather(column_spread);

Expected behaviour:

ans =
     1     2     1

Handling higher-dimensional inputs

data = reshape(1:24, [3, 4, 2]);
slice_spread = range(data, [1 2]);

Expected output:

slice_spread(:,:,1) =
    11

slice_spread(:,:,2) =
    11

GPU residency in RunMat (Do I need gpuArray?)

You generally do not need to call gpuArray explicitly in RunMat. When the input is already on the GPU, the planner keeps the result on-device if the active provider exposes reduce_min, reduce_max, the corresponding *_dim reductions, and elementwise subtraction. Current providers specialise 2-D reductions; multi-axis reductions, tensors with more than two dimensions, or 'omitnan' requests gather back to the host for correctness. When a required hook is missing, RunMat gathers the data automatically, computes on the CPU, and returns a standard tensor.

FAQ

What does range(X) return for scalars?

The range of a scalar is always 0, because the maximum and minimum coincide.

How are NaN values treated by default?

By default ('includenan'), any slice containing NaN yields NaN. Use 'omitnan' to ignore them.

Can I supply multiple dimensions?

Yes. Pass a vector such as [1 3] to reduce across both the first and third dimensions simultaneously.

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

RunMat mirrors MATLAB: a size-1 dimension produces zeros (or NaN when the lone value is NaN).

Does range support integer and logical inputs?

Yes. The inputs are promoted to double precision internally, matching MATLAB semantics.

How does range interact with gpuArray?

The runtime asks the active provider for min/max reductions. When unavailable, it gathers the data and computes on the CPU.

Why is the output sometimes a scalar and sometimes a vector?

The output collapses the selected dimensions to size 1, leaving other dimensions unchanged. A single remaining element becomes a scalar.

How can I inspect the range across all elements quickly?

Use range(X, 'all') to flatten all dimensions into a single scalar spread.

See Also

max, min, sum, mean, gpuArray, gather

Source & Feedback