RunMat
GitHub

View all functions

CategoryArray: Creation
GPUYes

What does the meshgrid function do in MATLAB / RunMat?

meshgrid turns one-, two-, or three-dimensional vectors into coordinate arrays that span a rectangular grid, mirroring MathWorks MATLAB behaviour exactly. The first output replicates the x vector across rows, the second replicates the y vector across columns, and the optional third output expands a z vector across pages for volumetric grids.

How does the meshgrid function behave in MATLAB / RunMat?

  • meshgrid(x) is shorthand for [X, Y] = meshgrid(x, x). It produces square 2-D grids.
  • meshgrid(x, y) yields X of size length(y) × length(x) with rows copied from x, and Y of the same size with columns copied from y.
  • meshgrid(x, y, z) returns three outputs sized length(y) × length(x) × length(z), enabling 3-D volume visualisation.
  • Input vectors may be row or column vectors (or even scalars). Empty vectors propagate to empty grids of matching shape.
  • Complex inputs produce complex grids where each output shares the input’s complex values.
  • Supplying GPU vectors (or a 'like', gpuArray(...) prototype) keeps the outputs on the GPU when an acceleration provider is active. Without provider support, RunMat gathers inputs, materialises the grid on the host, and uploads the result transparently.
  • 'like', prototype matches both the residency (host or GPU) and numeric class (real or complex) of the prototype. Integer prototypes are promoted to double precision, consistent with MATLAB.

meshgrid Function GPU Execution Behaviour

  • When the active acceleration provider implements the custom meshgrid hook, RunMat allocates every coordinate tensor directly on the device so large grids avoid host round-trips entirely.
  • If the hook is missing (or errors), RunMat gathers the 1-D axes, materialises the grids once on the host, and uploads the outputs whenever GPU residency is requested, preserving observable semantics.
  • Complex-valued grids always materialise on the host today; when GPU residency is requested the runtime logs a trace warning and returns host complex tensors so callers still receive correct MATLAB-compatible results.

Examples of using the meshgrid function in MATLAB / RunMat

Generating a square 2-D grid from one vector

x = -2:2;
[X, Y] = meshgrid(x);

Expected output (X shown; Y mirrors the row/column relationship):

X =
    -2    -1     0     1     2
    -2    -1     0     1     2
    -2    -1     0     1     2
    -2    -1     0     1     2
    -2    -1     0     1     2

Building a rectangular grid from two different vectors

x = [0 0.5 1.0];
y = [10 20];
[X, Y] = meshgrid(x, y);

Expected output:

X =
         0    0.5000    1.0000
         0    0.5000    1.0000

Y =
    10    10    10
    20    20    20

Creating a volumetric grid for 3-D plotting

u = -1:1;
v = 2:4;
w = linspace(0, 1, 5);
[U, V, W] = meshgrid(u, v, w);

Expected output shapes:

size(U) == [3 3 5]
size(V) == [3 3 5]
size(W) == [3 3 5]

Matching an existing GPU prototype

gx = gpuArray(single(linspace(-pi, pi, 4)));
gy = gpuArray(single([-1 0 1]));
[Xg, Yg] = meshgrid(gx, gy);

Xg and Yg remain gpuArray values with single precision. Gathering them produces the same numeric data as the host result.

Using 'like' to copy residency from another array

proto = gpuArray.zeros(1, 1, 'double');
angles = linspace(0, 2*pi, 8);
radius = [0 1 2];
[X, Y] = meshgrid(angles, radius, 'like', proto);

Both X and Y stay on the GPU because the prototype is a gpuArray.

Complex inputs produce complex grids automatically

z = [1+1i, 2+4i];
[Zx, Zy] = meshgrid(z);

Zx and Zy are complex arrays whose imaginary parts match the source vector.

GPU residency in RunMat (Do I need gpuArray?)

You usually do not need to wrap vectors with gpuArray manually. When the active acceleration provider supports uploads, RunMat automatically constructs the grid on the host and keeps the outputs on the GPU. Supplying a 'like', gpuArray(...) prototype produces GPU outputs even when all inputs are host arrays. Until native provider hooks land, complex-valued grids remain host-side and emit a warning when GPU residency is requested.

FAQ

How many inputs can meshgrid accept?

One, two, or three numeric vectors. Use three inputs when you need volumetric (3-D) grids.

Can I request three outputs with only one or two inputs?

No. RunMat follows MATLAB and requires three input vectors when three outputs are requested.

Do row or column vectors behave differently?

No. Any vector shape (row, column, or scalar) is accepted. RunMat treats the linearised data identically and replicates it along the appropriate axes.

What happens with empty vectors?

Empty inputs propagate to empty outputs. For example, meshgrid([], 1:3) returns 0×3 grids for both outputs.

Can I use integer vectors?

Yes. Inputs are promoted to double precision internally so the outputs represent the exact same values as MATLAB.

Does meshgrid support complex numbers?

Absolutely. Any imaginary components propagate into the outputs. Complex grids currently stay on the host even if GPU residency is requested.

What does 'like' do?

It matches the numeric class and residency (host or GPU) of the prototype array. Supply a gpuArray prototype to keep the resulting grids on the GPU.

How can providers avoid the host fall-back?

Implement the meshgrid custom hook in the acceleration provider. RunMat will automatically dispatch to it once available.

Is the output always dense?

Yes. meshgrid produces dense arrays. Use ndgrid when you need permuted axes or higher-dimensional grids beyond three inputs.

What error do I get if I omit all inputs?

RunMat raises the MATLAB-compatible error meshgrid: at least one input vector is required.

See Also

linspace, zeros, ones, gpuArray, gather

Source & Feedback