RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the minus function do in MATLAB / RunMat?

minus(A, B) (or the operator form A - B) subtracts corresponding elements of B from A, honouring MATLAB's implicit expansion rules so that scalars and singleton dimensions broadcast automatically.

How does the minus function behave in MATLAB / RunMat?

  • Supports real, complex, logical, and character inputs; logical and character data are promoted to double precision before subtraction.
  • Implicit expansion works across any dimension, provided the non-singleton extents match. Size mismatches raise the standard MATLAB-compatible error message.
  • Complex operands follow MATLAB's analytic rule (a + ib) - (c + id) = (a - c) + i(b - d).
  • Empty dimensions propagate naturally—if either operand has a zero-sized dimension after broadcasting, the result is empty with the broadcasted shape.
  • Integer inputs promote to double precision before subtraction, mirroring MATLAB behaviour and keeping numeric tower rules consistent with other RunMat arithmetic builtins.
  • The optional 'like' prototype makes the output adopt the residency (host or GPU) and complexity characteristics of the prototype, which is particularly useful for keeping implicit-expansion expressions on the device.

minus Function GPU Execution Behaviour

When a gpuArray provider is active:

  1. If both operands are gpuArrays with identical shapes, RunMat dispatches to the provider's elem_sub hook.
  2. If the left operand is a gpuArray and the right operand is a scalar, RunMat calls scalar_sub to keep the computation on the device.
  3. If the right operand is a gpuArray and the left operand is a scalar, RunMat calls scalar_rsub so the scalar subtraction also remains on the device.
  4. Implicit-expansion workloads (e.g., mixing row and column vectors) or unsupported operand kinds gather transparently to host memory, compute the result with full MATLAB semantics, and return a host tensor unless a 'like' GPU prototype is supplied—in which case the runtime re-uploads the output to honour the residency request.

Examples of using the minus function in MATLAB / RunMat

Subtracting two matrices element-wise

A = [7 8 9; 4 5 6];
B = [1 2 3; 1 2 3];
D = minus(A, B);

Expected output:

D =
     6     6     6
     3     3     3

Subtracting a scalar from every matrix element

A = magic(3);
shifted = minus(A, 0.5);

Expected output:

shifted =
    7.5    0.5    5.5
    2.5    4.5    6.5
    3.5    8.5    1.5

Broadcasting a column minus a row vector

col = (1:3)';
row = [10 20 30];
M = minus(col, row);

Expected output:

M =
    -9   -19   -29
    -8   -18   -28
    -7   -17   -27

Subtracting complex numbers element-wise

z1 = [1+2i, 3-4i];
z2 = [2-1i, -1+1i];
diffz = minus(z1, z2);

Expected output:

diffz =
    -1 + 3i     4 - 5i

Subtracting from character codes

letters = 'DEF';
codes = minus(letters, 1);

Expected output:

codes = [67 68 69]

Keeping element-wise differences on the GPU with 'like'

proto = gpuArray.zeros(1, 1);
G1 = gpuArray([10 20 30]);
G2 = gpuArray([1 2 3]);
deviceDiff = minus(G1, G2, 'like', proto);
result = gather(deviceDiff);

Expected output:

deviceDiff =
  1x3 gpuArray
     9    18    27
result =
     9    18    27

GPU residency in RunMat (Do I need gpuArray?)

RunMat's auto-offload planner keeps tensors on the GPU whenever fused expressions benefit from device execution. Explicit gpuArray / gather calls remain supported for MATLAB code that manages residency manually. When the active provider lacks the kernels needed for a particular call (for example, implicit expansion between gpuArrays of different shapes), RunMat gathers back to the host, computes the MATLAB-accurate result, and resumes execution seamlessly.

FAQ

Does minus support MATLAB implicit expansion?

Yes. Any singleton dimensions expand automatically. If a dimension has incompatible non-singleton extents, minus raises the standard size-mismatch error.

What numeric type does minus return?

Results are double precision for real inputs and complex double when either operand is complex. Logical and character inputs are promoted to double before subtraction.

Can I subtract gpuArrays and host scalars?

Yes. RunMat keeps the computation on the GPU when the scalar is numeric. For other host operand types, the runtime gathers the gpuArray and computes on the CPU.

Does minus preserve gpuArray residency after a fallback?

When a fallback occurs (for example, implicit expansion that the provider does not implement), the resulting array stays on the host by default. Provide a 'like', gpuArray(...) prototype if you need the runtime to re-upload the final result automatically.

How can I force the result to stay on the GPU?

Provide a 'like' prototype: minus(A, B, 'like', gpuArray.zeros(1, 1)) keeps the result on the device even if one of the inputs originated on the host.

How are empty arrays handled?

Empty dimensions propagate. If either operand has an extent of zero in the broadcasted shape, the result is empty with that broadcasted shape.

Are integer inputs supported?

Yes. Integers promote to double precision during the subtraction, matching other RunMat arithmetic builtins.

Can I mix complex and real operands?

Absolutely. The result is complex, with broadcasting rules identical to MATLAB.

What about string arrays?

String arrays are not numeric and therefore raise an error when passed to minus.

See Also

plus, times, ldivide, rdivide, gpuArray, gather

Source & Feedback