ndims — Return the MATLAB-visible rank of an array.
ndims reads shape metadata, ignores trailing singleton dimensions, and returns a host double scalar of at least two.
Syntax
n = ndims(A)Inputs
A- Type
Any- Required
- Yes
- Description
- Value whose MATLAB-visible dimensions are inspected.
Returns
n- Type
NumericScalar- Description
- MATLAB-visible rank of the input, with a minimum of two.
Errors
RunMat:ndims:InternalError- When
- Value or distributed shape metadata is invalid.
- Message
ndims: invalid shape metadata
RunMat:ndims:TooManyOutputs- When
- More than one output is requested.
- Message
ndims: too many output arguments
Visible rank
ndims(A) returns the MATLAB-visible rank of A as a double scalar. The result is at least 2, so scalars, row and column vectors, and matrices all return 2.
Trailing singleton dimensions do not increase visible rank. A 2-by-3-by-1-by-1 array returns 2; a 2-by-3-by-1-by-4 array returns 4 because the fourth dimension is nonsingleton.
Value classes and residency
Numeric, logical, character, string, cell, struct, object, sparse, and complex arrays all use their outer array dimensions. The stored element class and values do not affect the result.
gpuArray and distributed inputs use validated shape metadata. ndims does not launch a kernel, call a provider, allocate device storage, or transfer payload data. It returns one host double scalar and forms a fusion boundary.
Examples
Inspect a scalar
n = ndims(42)Expected output:
n = 2Inspect a matrix
A = rand(5, 3);
n = ndims(A)Expected output:
n = 2Inspect a three-dimensional array
A = rand(4, 5, 6);
n = ndims(A)Expected output:
n = 3Ignore trailing singleton dimensions
A = ones(2, 3, 1, 1);
n = ndims(A)Expected output:
n = 2Inspect a cell array
C = {1, 2, 3; 4, 5, 6};
n = ndims(C)Expected output:
n = 2Inspect a string array
S = ["alpha"; "beta"; "gamma"];
n = ndims(S)Expected output:
n = 2Inspect a resident N-D shape
G = gpuArray(ones(16, 32, 2));
n = ndims(G)Expected output:
n = 3Using 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 do scalars and vectors return 2?⌄
Their MATLAB-visible shapes are 1-by-1, 1-by-N, or N-by-1, and visible rank has a minimum of two.
Are trailing singleton dimensions counted?⌄
No. They are ignored. A later nonsingleton dimension remains visible and determines the rank.
Does ndims gather gpuArray data?⌄
No. The resident handle carries the required shape metadata.
Can ndims inspect cells, structs, and objects?⌄
Yes. It uses their outer MATLAB-visible array dimensions and does not inspect contents.
Do element classes change the result?⌄
No. Floating, integer, logical, complex, character, and string arrays all use the same shape rule.
Can ndims appear beside fused GPU work?⌄
Yes. It reads metadata and returns a host scalar at a fusion boundary without moving the input payload.
Related Array functions
Introspection
height · iscolumn · isempty · ismatrix · isrow · isscalar · isvector · length · numel · size · width
Accumulation
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 · shiftdim · squeeze · toeplitz · tril · triu · vertcat
Creation
colon · createArray · empty · eye · false · full · inf · int16.empty · int32.empty · int64.empty · int8.empty · linspace · logspace · magic · meshgrid · nan · ndgrid · nonzeros · ones · peaks · rand · randi · randn · randperm · range · sparse · spdiags · speye · spones · sprand · true · uint16.empty · uint32.empty · uint64.empty · uint8.empty · zeros
Combinatorics
Binning
Grouping
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.