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 | NumericScalar | 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 effective rank after trailing singleton dimensions are ignored, with a minimum result of
2. - Character arrays, string arrays, logical arrays, complex arrays, and cell arrays all follow their MATLAB array shape metadata.
- GPU tensors report rank from handle shape metadata without gathering payloads; an absent shape is normalized as scalar metadata and returns
2. - All eight integer classes return a host double scalar and their payload storage is never read.
- 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 GpuTensorHandle.shape; no kernel launches, downloads, buffer allocations, or residency changes are required, including for integer payloads.
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?⌄
Yes. MATLAB ignores trailing singleton dimensions while retaining a minimum rank of two. A 2×3×1×1 value reports 2, while 10×1×1×4 reports 4 because its fourth dimension is nonsingleton.
How does ndims behave for GPU tensors?⌄
The runtime inspects shape metadata stored in the GPU tensor handle and does not download the payload. An absent shape is treated as scalar metadata and therefore reports 2.
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
Grouping
accumarray · combinations · discretize · findgroups · groupcounts · grp2idx · splitapply
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · toeplitz · 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.