gradient — Compute numerical gradients in MATLAB and RunMat.

gradient(F) computes numerical derivatives using central differences in the interior and one-sided differences at boundaries. Default dimension behavior and multi-output ordering follow MATLAB semantics.

Syntax

G = gradient(F)
G = gradient(F, h)
[G1, G2, ...] = gradient(F)
[G1, G2, ...] = gradient(F, h1, h2, ...)

Inputs

Returns

Returned values from gradient depend on how many outputs the caller requests.

Errors

How gradient works

• gradient(F) chooses the first non-singleton dimension for vectors and returns the column-direction derivative for matrices.
• [FX, FY] = gradient(F) on a matrix returns FX for dimension 2 (across columns) and FY for dimension 1 (down rows), matching MATLAB.
• gradient(F, h) applies the same scalar spacing to every returned dimension. For vector inputs, h may be a coordinate vector with one point per element.
• gradient(F, hx, hy, ...) accepts one scalar or coordinate-vector spacing per output dimension, ordered as MATLAB returns outputs (x/columns first for matrices, then y/rows).
• Coordinate-vector spacings must be finite, match the corresponding dimension length, and avoid zero finite-difference denominators.
• With scalar spacing, interior points use central differences (f(i+1) - f(i-1)) / (2*h), while the first and last points use one-sided differences.
• With coordinate-vector spacing, denominators come from the supplied coordinates: boundary points use adjacent coordinate differences and interior points use x(i+1) - x(i-1).
• Real, logical, and scalar numeric inputs promote through the standard tensor conversion path. Complex host inputs are supported by differentiating the real and imaginary parts independently.
• When a GPU tensor is passed and the active provider implements gradient_dim or gradient_dim_with_coordinates, scalar and coordinate-vector spacing gradients stay resident on the device. Real and complex-interleaved GPU tensors are supported.

Does RunMat run gradient on the GPU?

The WGPU backend implements gradient_dim and gradient_dim_with_coordinates for real and complex-interleaved tensors, so scalar and coordinate-vector spacing gradients execute on the device and return GPU tensors for both single-output and multi-output calls.

The simple in-process provider also exposes real and complex gradient hooks, allowing provider-level parity tests without requiring a physical GPU.

Coordinate-vector spacing is validated with MATLAB-compatible denominator rules before the provider hook runs; unsupported providers fall back to host evaluation.

GPU memory and residency

Manual gpuArray promotion is optional. When a gradient starts with GPU-resident data and the active provider implements gradient_dim for scalar spacing or gradient_dim_with_coordinates for coordinate-vector spacing, RunMat keeps the result on the device. Complex-interleaved GPU tensors preserve complex residency. If the provider lacks the required hook, RunMat gathers to the host and preserves MATLAB-compatible results.

Examples

Differentiating a row vector

v = [1 4 9];
g = gradient(v)

Expected output:

g = [3 4 5]

Requesting both matrix gradient components

A = [1 2; 3 4];
[FX, FY] = gradient(A)

Expected output:

FX =
     1     1
     1     1

FY =
     2     2
     2     2

Using scalar spacing on GPU data

G = gpuArray(single([1 4 9]));
D = gradient(G, 2);
out = gather(D)

Expected output:

out = single([1.5 2.0 2.5])

Using nonuniform coordinate spacing

x = [0 1 3];
v = [1 4 9];
g = gradient(v, x)

Expected output:

g = [3.0000 2.6667 2.5000]

Feeding gradient into a vector-field plot

[X, Y] = meshgrid(linspace(-2, 2, 25), linspace(-2, 2, 25));
Z = X .* exp(-X.^2 - Y.^2);
[DX, DY] = gradient(Z, X(1,2)-X(1,1), Y(2,1)-Y(1,1));
quiver(X, Y, DX, DY)

Using gradient with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how gradient changes the result.

FAQ

Related Math functions

Open-source implementation

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

• View the source for gradient 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.

Getting started · Benchmarks · Pricing