gradient — Numerical gradients using central differences with MATLAB-compatible output ordering.

gradient(F) computes numerical derivatives with central differences in the interior and one-sided differences at the boundaries. For matrices, a single output returns the derivative along columns, while multiple outputs follow MATLAB ordering: first columns, then rows, then higher dimensions.

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.

How RunMat runs 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)

FAQ

What finite-difference stencil does gradient use?

RunMat matches MATLAB's shape-preserving behavior: central differences in the interior and first-order one-sided differences at the boundaries.

Why does a matrix return the x-direction first?

MATLAB defines the first matrix output along dimension 2 (columns), then dimension 1 (rows). RunMat preserves that ordering so plotting workflows like quiver line up correctly.

Can I pass coordinate vectors for spacing?

Not in this version. gradient(F, X) and vector-valued hx, hy, ... are reserved for a follow-up implementation.

Does gradient support GPU arrays?

Yes for default spacing and scalar spacings. With an active provider such as WGPU, the scalar-spacing path stays on the GPU via the gradient_dim hook.

Do complex inputs work?

Yes on the host. Complex GPU tensors currently gather to the host before differencing.

Related functions to explore

These functions work well alongside gradient. Each page has runnable examples you can try in the browser.

diff, meshgrid, quiver, gpuArray, gather

Open-source implementation

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

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