ndims — Return array dimensionality in MATLAB and RunMat.
ndims(A) returns the number of dimensions (rank) of A. Minimum-two-dimension behavior for scalar/vector/matrix inputs and higher-rank reporting follow MATLAB semantics.
Syntax
n = ndims(A)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input value to inspect. |
Returns
| Name | Type | Description |
|---|---|---|
n | IntegerScalar | Number of dimensions of input. |
How ndims works
- Scalars and vectors return
2, because MATLAB treats them as1×1or1×N. - Matrices return
2unless they have trailing dimensions beyond the second. - N-D arrays return the length of their dimension vector after trailing singleton dimensions are preserved.
- Character arrays, string arrays, logical arrays, complex arrays, and cell arrays all follow their MATLAB array shape metadata.
- GPU tensors report their rank without gathering when the provider populates shape metadata on the handle. When metadata is missing, RunMat downloads the tensor once to preserve correctness.
- Objects, scalars, and other non-array values return
2, consistent with MATLAB's scalar rules.
Does RunMat run ndims on the GPU?
ndims is a metadata query. When the input resides on the GPU, RunMat inspects the shape stored in GpuTensorHandle.shape. No kernels are launched, no buffers are allocated, and residency is not altered. If a provider leaves the shape empty, the runtime downloads the tensor a single time to reconstruct its dimensions before returning a host scalar. The builtin therefore preserves fusion pipelines while still providing MATLAB-compatible answers.
Examples
Checking how many dimensions a scalar has
n = ndims(42)Expected output:
n = 2Counting the dimensions of a matrix
A = rand(5, 3);
r = ndims(A)Expected output:
r = 2Detecting 3-D array dimensionality
V = rand(4, 5, 6);
r = ndims(V)Expected output:
r = 3Finding ndims for gpuArray data without gathering
G = gpuArray(ones(16, 32, 2));
r = ndims(G)Expected output:
r = 3Understanding ndims with cell arrays
C = {1, 2, 3; 4, 5, 6};
r = ndims(C)Expected output:
r = 2Verifying ndims on string arrays
S = ["alpha"; "beta"; "gamma"];
r = ndims(S)Expected output:
r = 2Using ndims with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how ndims changes the result.
Run a small ndims example, explain the result, then change one input and compare the output.
FAQ
Why does ndims return 2 for scalars and vectors?⌄
MATLAB treats scalars and vectors as 2-D arrays (1×1 or 1×N). RunMat mirrors this behaviour, so ndims(5) and ndims([1 2 3]) both return 2.
Does ndims ignore trailing singleton dimensions?⌄
No. MATLAB preserves trailing singletons when reporting the rank. If your tensor was explicitly created with size 10×1×1×4, ndims returns 4.
How does ndims behave for GPU tensors?⌄
The runtime inspects shape metadata stored in the GPU tensor handle. When the provider populates that field, no gathering occurs. If metadata is absent, RunMat downloads the tensor to keep the answer correct.
Can I call ndims on cell arrays and structs?⌄
Yes. ndims inspects the MATLAB array shape of the container, so cell arrays and struct arrays report their grid dimensions.
What about objects or scalars like strings and logical values?⌄
Objects and scalar values follow MATLAB scalar rules and return 2. Use specialised functions (like isobject) when you need more information about their type.
Does ndims participate in GPU fusion?⌄
No. ndims returns a host scalar immediately and performs no computation on the GPU. It is safe to use inside expressions that also run on the GPU because it does not allocate device memory.
Related Array functions
Shape
cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · tril · triu · vertcat
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how ndims is executed, line by line, in Rust.
- View the source for ndims 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.