minus — Compute element-wise subtraction in MATLAB and RunMat.
minus(A, B) (or A - B) subtracts corresponding elements of B from A. Implicit expansion and complex handling follow MATLAB semantics.
Syntax
C = minus(A, B)
C = minus(A, B, "like", prototype)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Left numeric/logical operand. |
B | Any | Yes | — | Right numeric/logical operand. |
like | StringScalar | Yes | — | Literal string "like". |
prototype | LikePrototype | Yes | — | Output class/device prototype. |
Returns
| Name | Type | Description |
|---|---|---|
C | NumericArray | Elementwise difference result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:minus:InvalidArgument | Optional arguments are malformed or unsupported. | minus: invalid argument |
RunMat:minus:InvalidInput | Operands or prototypes cannot be converted into supported numeric/logical forms. | minus: invalid input |
RunMat:minus:SizeMismatch | Operands are not broadcast-compatible. | minus: array sizes are not compatible for broadcasting |
RunMat:minus:Internal | Provider interaction, gather/upload, or internal tensor construction failed. | minus: internal error |
RunMat:minus:SparseSizeMismatch | Sparse operands cannot be implicitly expanded to a compatible result shape. | minus: sparse operand sizes are not compatible |
RunMat:minus:SparseUnsupportedOperand | Sparse arithmetic is requested with an unsupported operand class or residency. | minus: unsupported sparse arithmetic operand |
RunMat:minus:SparseDensifyTooLarge | A sparse operation would have to materialize a dense or fully populated sparse result beyond the runtime limit. | minus: sparse arithmetic result is too large to materialize |
RunMat:minus:SparseInternal | Sparse arithmetic storage construction or conversion failed unexpectedly. | minus: sparse arithmetic internal error |
How minus works
- 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 subtraction preserves the integer class. The other operand must use the same integer class or be scalar double; fractional results round, overflow saturates, and 64-bit integer/scalar-double arithmetic uses the extended-precision compatibility path.
- Sparse real matrices interoperate with sparse, dense, logical, character, scalar, and complex operands. Sparse-sparse subtraction preserves sparse storage; dense, nonzero scalar, and complex interop returns full real or complex storage when implicit zeros become nonzero.
- In RunMat compatibility mode, the RunMat-only optional
'like'prototype makes the output adopt the residency and complexity characteristics of the prototype. MATLAB-compatible mode rejects this extension before dispatch.
Does RunMat run minus on the GPU?
When a gpuArray provider is active:
1. If both operands are gpuArrays with identical shapes, RunMat dispatches to the provider's elem_sub hook, including for complex-interleaved resident handles. 2. If the left operand is a gpuArray and the right operand is a real 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 real scalar, RunMat calls scalar_rsub so the scalar subtraction also remains on the device. 4. For shape-compatible implicit expansion, RunMat first expands gpuArray operands on device with repmat and then dispatches elem_sub. 5. Unsupported shapes or 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.
GPU memory and residency
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.
Examples
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 3Subtracting 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.5Broadcasting 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 -27Subtracting complex numbers element-wise
z1 = [1+2i, 3-4i];
z2 = [2-1i, -1+1i];
diffz = minus(z1, z2)Expected output:
diffz =
-1 + 3i 4 - 5iSubtracting 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 27Using minus with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how minus changes the result.
Run a small minus example, explain the result, then change one input and compare the output.
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?⌄
Ordinary real inputs produce double and complex inputs produce complex double. Integer arithmetic preserves the integer class under MATLAB's same-class-or-scalar-double rules. Logical and character inputs are promoted to double.
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. Integer subtraction preserves the integer class, rounds fractional results, and saturates overflow. Inputs must use the same integer class or pair one integer operand with scalar double.
Can I mix complex and real operands?⌄
Absolutely. The result is complex, with broadcasting rules identical to MATLAB.
Does minus preserve sparse matrices?⌄
Sparse-sparse subtraction returns sparse storage, including scalar sparse expansion when the result fits the sparse materialization limit. Subtracting dense, complex, or nonzero full scalar operands returns full storage because implicit sparse zeros become stored nonzero values.
What about string arrays?⌄
String arrays are not numeric and therefore raise an error when passed to minus.
Related Math functions
Elementwise
abs · angle · bsxfun · complex · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log1p · log2 · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Optim
coneprog · fminbnd · fminunc · fsolve · fzero · integral · linprog · lsqcurvefit · lsqnonlin · optimoptions · optimset · quad · secondordercone
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how minus is executed, line by line, in Rust.
- View the source for minus 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.