conv2 — Two-dimensional convolution with MATLAB-compatible padding modes.

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.

Syntax

C = conv2(A, B)
C = conv2(u, v, A)
C = conv2(___, shape)

• A is the 2-D input matrix (real, complex, or logical; logicals are promoted to double).
• B is the 2-D convolution kernel. It is flipped along both axes before the sum-of-products, which is what makes the operation true convolution rather than correlation.
• conv2(u, v, A) is the separable form: u is a column vector applied down the rows of A and v is a row vector applied across the columns. This is equivalent to conv2(u(:) * v(:).', A) but runs as two 1-D passes, which is much faster whenever the effective kernel u*v' is rank-1 (box filters, Gaussians, Sobel components).
• shape selects the output region: 'full' (default) returns an array of size size(A) + size(B) - 1; 'same' slices the central portion so the output matches size(A); 'valid' returns only the fully-overlapping region of size size(A) - size(B) + 1 (empty when B is larger than A along any dimension).

How conv2 works

• 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.
• For even-sized kernels with 'same', alignment follows MATLAB's top-left convention in each even dimension.
• 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.

How RunMat runs conv2 on the GPU

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

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 =
    27    -6   -27
    28    -8   -28
    15    -6   -15

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)

How RunMat validates conv2

conv2 uses an in-repo implementation for both the direct (conv2(A, B)) and separable (conv2(u, v, A)) forms. The module-level tests cover 'full', 'same', and 'valid' shapes against reference outputs. The GPU path currently defers to the CPU implementation via the in-process provider and returns a GPU handle; a native WGPU conv2d kernel is tracked as follow-up.

• Implementation: crates/runmat-runtime/src/builtins/math/signal/conv2.rs
• Parity test: conv2 unit tests
• Tolerance: 1e-9 (f64), 1e-3 (f32)

See Correctness & Trust for the full methodology and coverage table.

FAQ

Related Math functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how conv2 works, line by line, in Rust.

• View conv2.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing