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.
• gradient(F, hx, hy, ...) accepts one scalar spacing per output dimension. In v1, each spacing must be scalar.
• Interior points use central differences (f(i+1) - f(i-1)) / (2*h), while the first and last points use one-sided differences.
• 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, scalar-spacing gradients stay resident on the device. Complex GPU tensors and coordinate-vector spacing currently gather to the host.

Does RunMat run gradient on the GPU?

The WGPU backend implements gradient_dim, so scalar-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 gradient_dim, allowing provider-level parity tests without requiring a physical GPU.

Coordinate-vector spacing is intentionally out of scope for this version and falls back to host evaluation.

GPU memory and residency

Manual gpuArray promotion is optional. When a scalar-spacing gradient starts with GPU-resident data and the active provider implements gradient_dim, RunMat keeps the result on the device. If the provider lacks the hook, if spacing is specified with coordinate vectors, or if the input is complex GPU data, 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])

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