RunMat
GitHub

View all functions

CategoryMath: Signal
GPUYes

What does the conv function do in MATLAB / RunMat?

conv(a, b) computes the one-dimensional linear convolution of the vectors a and b. The default padding mode returns the full convolution (length(a) + length(b) - 1). Optional shape arguments ('same', 'valid') select MATLAB-compatible padding behaviour.

How does the conv function behave in MATLAB / RunMat?

  • Accepts real or complex scalars, vectors, or tensors that can be flattened column-major into a vector.
  • Keeps the orientation of the first input when returning row or column vectors ('same' and 'valid' honour this rule).
  • Supports the three MATLAB shape modes: 'full' (default), 'same', and 'valid'.
  • Returns empty outputs when either input is empty or when 'valid' is requested with insufficient overlap.
  • Logical inputs are promoted to double precision before the convolution.
  • GPU inputs are gathered automatically when the active provider lacks a native 1-D convolution kernel.

Examples of using the conv function in MATLAB / RunMat

Computing the full convolution of two row vectors

a = [1 2 3];
b = [1 1 1];
c = conv(a, b);

Expected output:

c = [1 3 6 5 3];

Keeping the same length as the first input

kernel = [1 0 -1];
signal = [3 4 5 6 7];
edge = conv(signal, kernel, 'same');

Expected output:

edge = [4 2 2 2 -6];

Valid convolution without zero padding

weights = [1 2 3 4];
window = [1 1 1];
valid = conv(weights, window, 'valid');

Expected output:

valid = [6 9];

Convolving column vectors

a = (1:3)';
b = [2; 0; -2];
c = conv(a, b);

Expected output:

c =
     2
     4
     4
     -4
     -6

Multiplying polynomials using convolution

p = [1 3 3 1];    % (x + 1)^3 coefficients
q = [1 -1];       % (x - 1)
coeff = conv(p, q);

Expected output:

coeff = [1 2 0 -2 -1];

Complex-valued convolution

t = 0:3;
sig = exp(1i * pi/4 * t);
filt = [1 2i];
resp = conv(sig, filt);

Expected output (RunMat prints complex numbers as a + bi):

resp =
   1.0000 + 1.0000i   1.4142 + 2.4142i   0.0000 + 3.4142i  -1.4142 + 2.4142i  -1.0000 + 1.0000i

Scaling a signal by a scalar

s = [4 5 6];
y = conv(2, s);

Expected output:

y = [8 10 12];

Using gpuArray inputs with automatic host fallback

g = gpuArray([1 2 3 4]);
h = gpuArray([1 0 -1]);
edge = conv(g, h, 'same');
result = gather(edge);

When the provider implements the conv1d hook (the in-process provider and the WGPU backend both do), the convolution executes without leaving the device and the result remains GPU-resident. When the hook is unavailable, RunMat gathers both arguments, performs the computation on the CPU, and returns a host tensor that matches MATLAB semantics.

FAQ

Does conv require row vectors?

No. conv accepts row vectors, column vectors, scalars, and tensors that can be flattened into a vector. The result preserves the orientation of the first input when that orientation is unambiguous.

What happens when one of the inputs is empty?

The result is an empty vector with an orientation derived from the non-empty input (or a 0×1 column vector when both inputs are empty), matching MATLAB's behaviour.

How is 'same' computed?

'same' returns the central portion of the full convolution whose length matches the first input. Internally RunMat performs a full convolution and slices the appropriate window.

When should I use 'valid'?

Use 'valid' when you only want results that do not rely on zero padding. This is common when sliding windows should fit completely inside the input without extending past the boundaries.

Does conv support single precision?

The host path computes in double precision. Provider implementations choose their native precision: the in-process provider mirrors double results, while the WGPU backend emits either f32 or f64 kernels depending on device support. Providers without a conv1d hook gather inputs back to the CPU to maintain MATLAB-compatible answers.

Will the result stay on the GPU?

Yes—provided the active provider exposes the conv1d hook (the in-process provider and WGPU backend do). Without that hook, RunMat gathers inputs, computes on the host, and returns a CPU tensor with the correct orientation.

Can I convolve matrices or higher-dimensional arrays?

conv treats inputs as vectors using MATLAB column-major order. For multi-dimensional convolution use the dedicated conv2 or convn builtins (planned).

How do I convolve with an impulse (delta) kernel?

Include a 1 followed by zeros in your kernel. The input will be preserved (with appropriate padding) because convolution with a delta function is an identity operation.

What about circular convolution?

Use cconv for circular convolution, or compute the FFT manually and multiply in the frequency domain before performing an inverse FFT.

Are there GPU-specific tuning knobs?

Not yet. Current providers choose kernel launch parameters automatically; user-facing tuning switches will arrive alongside future backend updates.

See Also

fft, ifft, fftshift, gpuArray, gather

Source & Feedback

  • Full source: crates/runmat-runtime/src/builtins/math/signal/conv.rs
  • Found an issue? Open a ticket with a minimal reproduction.