RunMat
GitHub

View all functions

CategoryMath: Signal
GPUYes

What does the conv2 function do in MATLAB / RunMat?

conv2 performs two-dimensional linear convolution. By default it returns the full convolution (size(A) + size(B) - 1), but it can also return the same or valid regions so results match MATLAB exactly. The builtin accepts real or complex inputs, logical arrays (promoted to double), and the separable form conv2(hcol, hrow, A) that is common in image processing pipelines.

How does the conv2 function behave in MATLAB / RunMat?

  • conv2(A, B) returns the full 2-D convolution of A and B.
  • conv2(A, B, 'same') slices the central part of the full convolution so the output matches the shape of A.
  • conv2(A, B, 'valid') returns only those points where B overlaps A completely.
  • conv2(hcol, hrow, A) is syntactic sugar for conv2(hcol(:) * hrow(:)', A).
  • Scalars are treated as 1×1 matrices and preserve the orientation of the other input.
  • Empty inputs follow MATLAB’s rules: conv2([], X) and conv2(X, []) return empty matrices (or zero-sized slices for 'same').
  • Logical inputs are promoted to double precision before computation; complex inputs preserve their imaginary part throughout the convolution.

conv2 Function GPU Execution Behaviour

RunMat Accelerate keeps tensors on the GPU when the active provider implements a conv2d hook (the in-process provider uses the host implementation and returns a GPU handle; the WGPU backend will adopt a native kernel). When the hook is unavailable, RunMat gathers GPU inputs to the host, performs the convolution on the CPU, and returns a host tensor. Documentation and the GPU metadata make this fallback explicit so providers can add native implementations without changing this builtin.

Examples of using the conv2 function in MATLAB / RunMat

Smoothing an image patch with a 3×3 averaging kernel

A = [1 2 3; 4 5 6; 7 8 9];
h = ones(3) / 9;
smoothed = conv2(A, h, 'same');

Expected output:

smoothed =
    1.3333    2.3333    1.7778
    3.0000    5.0000    3.6667
    2.6667    4.3333    3.1111

Computing the full convolution of two small kernels

K1 = [1 2; 3 4];
K2 = [1 1; 1 1];
C = conv2(K1, K2);

Expected output:

C =
     1     3     2
     4    10     6
     3     7     4

Extracting the same-sized result to preserve dimensions

edge = conv2([1 2 3; 4 5 6; 7 8 9], [1 0 -1; 1 0 -1; 1 0 -1], 'same');

Expected output:

edge =
    -7    -4     7
   -15    -6    15
   -13    -4    13

Valid convolution for sliding-window statistics

block = magic(4);
kernel = ones(2);
valid = conv2(block, kernel, 'valid');

Expected output:

valid =
    34    26    34
    32    34    36
    34    42    34

Using the separable form with column and row vectors

hcol = [1; 2; 1];
hrow = [1 0 -1];
A = [3 4 5; 6 7 8; 9 10 11];
gx = conv2(hcol, hrow, A, 'same');

Expected output:

gx =
   -15    -6    15
   -28    -8    28
   -27    -6    27

Convolving gpuArray inputs with transparent fallbacks

G = gpuArray(rand(128, 128));
H = gpuArray([1 2 1; 0 0 0; -1 -2 -1]);
gx = conv2(G, H, 'same');
result = gather(gx);

The result remains on the GPU when the provider implements the conv2d hook. Otherwise RunMat gathers both inputs back to the host, executes the CPU algorithm, and returns a host tensor that matches MATLAB exactly.

FAQ

Does conv2 support the three MATLAB shape modes?

Yes. Pass 'full', 'same', or 'valid' as the final argument and RunMat will mirror MATLAB’s output sizes and edge handling precisely.

How do I use the separable form?

Call conv2(hcol, hrow, A) (optionally with a shape argument). RunMat converts the vectors into an outer-product kernel internally so it behaves exactly like MATLAB.

What happens if one input is empty?

An empty input produces an empty output (or a zero-sized slice for 'same'). This follows MATLAB’s behaviour and avoids surprising dimension growth.

Do logical inputs work?

Yes. Logical arrays are promoted to double precision before convolution so the result is numeric.

Will the result stay on the GPU?

If the active provider exposes the conv2d hook the result stays device-resident. Otherwise RunMat falls back to the CPU path and returns a host tensor; this fallback is documented so providers can add native kernels without breaking compatibility.

See Also

conv, filter2, imfilter, gpuArray, gather

Source & Feedback