RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

What does the reshape function do in MATLAB / RunMat?

reshape(A, newSize) returns the elements of A with a different dimensional layout while preserving column-major ordering. The total number of elements must remain unchanged.

How does the reshape function behave in MATLAB / RunMat?

  • Accepts either a size vector reshape(A, [m n …]) or individual dimensions reshape(A, m, n, …).
  • Exactly one dimension may be specified as []; RunMat infers its value from numel(A).
  • Dimensions must be nonnegative integers. Zero-sized dimensions are allowed when numel(A) == 0.
  • Works on numeric, logical, complex, string, char, GPU, and cell arrays (cell/char currently support up to 2-D).
  • Reshaping never copies data; it only reinterprets layout metadata.
  • Scalar inputs follow MATLAB semantics: reshape(5, 1, 1) yields the scalar 5, while larger shapes return dense arrays.

reshape Function GPU Execution Behavior

When the input lives on the GPU, RunMat asks the active acceleration provider to apply the reshape hook so the backend can update its residency metadata. No data transfers or kernel launches are needed, so gpuArray inputs stay on the device. Providers that do not override the hook fall back to updating the tensor handle directly, which is sufficient for the in-process reference backend.

Examples of using the reshape function in MATLAB / RunMat

Reshaping a row vector into a matrix

A = 1:12;
B = reshape(A, [3, 4]);

Expected output:

B =
    1     4     7    10
    2     5     8    11
    3     6     9    12

Using an automatically inferred dimension

A = 1:18;
B = reshape(A, 3, []);

Expected output:

size(B)  % => [3 6]

Reshaping into three dimensions

A = 1:24;
C = reshape(A, [2, 3, 4]);

Expected output:

size(C)  % => [2 3 4]

Reshaping logical arrays preserves type

mask = logical([1 0 1 0 1 0]);
grid = reshape(mask, 2, 3);

Expected output:

grid =
     1     1     1
     0     0     0

Reshaping GPU data without gathering

G = gpuArray(1:1000);
H = reshape(G, 10, 100);

Expected behavior: H stays on the GPU with shape [10 100], and no host copies occur.

Handling zero-sized dimensions

E = reshape([], 0, 3);

Expected output:

size(E)  % => [0 3]

FAQ

Can I reshape using a size vector or separate arguments?
Yes. reshape(A, [m n p]) and reshape(A, m, n, p) are equivalent.

How many automatic ([]) dimensions are allowed?
At most one. RunMat reports reshape: can only specify a single [] dimension when more are provided.

Does reshape copy data?
No. It only repackages metadata, so large arrays—including GPU arrays—are reshaped instantly.

Can I reshape empty arrays?
Yes. You can reshape to any layout whose product is zero. Automatic dimensions become zero when numel(A) == 0.

Why do char and cell arrays reject 3-D reshapes?
The current runtime stores char and cell arrays as 2-D matrices. Future releases will lift this restriction.

Does reshape change data ordering?
No. RunMat uses MATLAB's column-major ordering, so the memory layout is preserved exactly.

What happens if the dimension product mismatches numel(A)?
RunMat raises reshape: product of dimensions (X) must equal numel(A) (Y).

Is reshape compatible with complex inputs?
Yes. Complex scalars become complex tensors when the target shape has more than one element.

See Also

Source & Feedback

  • Full implementation: crates/runmat-runtime/src/builtins/array/shape/reshape.rs
  • Found a bug or behavioral difference? Open an issue.